LSLib Compiler and Debugger
This package allows you to compile story scripts for Divinity Original Sins 2 from the command line and debug them both in the editor and in the game.
Quick start
Install VS Code
The debugger runs inside VS Code. Follow these steps to setup VS Code and the required extensions.
-
Install VS Code: https://code.visualstudio.com/
-
Install the Divinity Engine Script Support extension: https://marketplace.visualstudio.com/items?itemName=sebastian-lenz.divinity-vscode
-
Open your mod data folder in VS Code. Your mods data folder will be located at
.\Data\Mods\
inside your Original Sin 2 installation directory. (e.g. if you'll be editing theTester
mod then openDivinity Original Sin 2\Data\Mods\Tester_86cfadbc-81f7-4537-b5e3-540c8619c024
) -
Install LSLib Compiler and Debugger:
- Use the install command of the extension. Press
Ctrl+Shift+P
and search the commandInstall LSLib Compiler and Debugger
. The command will ask you for the preferred install location (select an empty path) and install the tools. - Download and extract the tools manually. Set the
divinity.compilerPath
configuration variable to the path of theCompiler
directory (eg."C:\\...\\Dbg\\Compiler\\"
) in either your user settings or your workspace settings in VS Code.
- Use the install command of the extension. Press
Prepare the game or the editor
The debugger needs additional files in order to be able to communicate with the game or editor.
- If you'll be debugging using the game, install the Script Extender to the
Divinity Original Sin 2\DefEd\bin\
directory of the game - If you'll be debugging using the editor, install the Script Extender to the root directory of the engine (
The Divinity Engine 2\DefEd
)
First run
You must add a task definition to your VS Code project. Press F5 to create the default task definition. VS Code will open the file launch.json
and create an entry with the title Attach to Story Server
.
Debug!
- The debugger only works with stories compiled with its own compiler, so you'll need to compile your story using the LSLib compiler. In VS Code, select "Terminal" > "Run Task..." or press
Ctrl+Shift+B
. From the menu that shows up, select the option "Compile". - When debugging, just start the game/editor normally (either from Steam or directly using EoCApp.exe)
- Now, you are ready to start the debugger. Head back to VS Code and press
F5
. The debugger will attach to the game or editor and you can place breakpoints in your code.
Usage Notes
- Standalone stories can be debugged both ingame and in the editor. Mods that are dependent on the main campaign can only be debugged in the editor.
- Adding/removing breakpoints, single stepping (step in/out/continue), rule variables and the call stack are completely supported
- Breakpoints are only validated after the mod was loaded in the game/editor; before loading the mod every breakpoint will be marked as invalid (gray circle instead of red)
- Breakpoints are only supported in
INIT
andEXIT
sections of goals,THEN
sections of rules, and theIF
section of rules after the second condition. (This means that in a rule you cannot add a breakpoint directly on the event or database that triggers the rule.) - Conditional breakpoints, function breakpoints, watchpoints are not supported in the current version