Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
LSLib Compiler and Debugger Quick Start Guide

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. You can either:

    • 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. You can simply copy them to your game directory or use the installation assistant.

  • If you have used the install command in the previous step, you've probably already setup the required files. You can re-run the debugger setup any time by pressing Ctrl+Shift+P in VS Code and executing the command Install LSLib Debugger for editor or game.
  • You can also copy the files manually to your game or editor directory:
    • If you'll be debugging using the game, extract the contents of the GameBackend folder to the Classic\bin\ directory of the game
    • If you'll be debugging using the editor, extract the contents of the EditorBackend folder to the root directory of the engine

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".
  • Start the game or the editor:
    • When debugging ingame, just start the game normally (either from Steam or directly using EoCApp.exe)
    • When debugging in the editor, the editor should be started using OsirisDebugLauncher.exe. Starting the editor directly will not load the debugger!
  • 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
You can’t perform that action at this time.