Norbyte/LSLib Compiler and Debugger.md

## LSLib Compiler and Debugger.md

      
      Raw
    
  
              LSLib Compiler and Debugger.md
            
          
    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 the Tester mod then open Divinity 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 command Install 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 the Compiler directory (eg. "C:\\...\\Dbg\\Compiler\\") in either your user settings or your workspace settings in VS Code.


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 and EXIT sections of goals, THEN sections of rules, and the IF 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