Skip to content

Instantly share code, notes, and snippets.

@Norbyte

Norbyte/LSLib Compiler and Debugger.md

Last active January 23, 2024 02:34
Show Gist options
  • Save Norbyte/8b7eb35cd17f799ea113636b15e1f967 to your computer and use it in GitHub Desktop.
Save Norbyte/8b7eb35cd17f799ea113636b15e1f967 to your computer and use it in GitHub Desktop.
Download ZIP
LSLib Compiler and Debugger Quick Start Guide
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment