Editing Modding/Using Visual Studio Code

While it is easily possible to make Lua mods for Desynced using any text editor, Visual Studio Code is the recommended editor for some additional features it offers for Lua programming. Besides quick code navigation it has Lua syntax highlighting, auto completion and code analytics which can help finding mistakes and other bugs. It also has a full Lua debugger with breakpoints and variable inspection as well as a debug console that connects to a running game while developing a mod.

== Setting up Visual Studio Code ==
If you don't have VS Code installed, you can download it for free at the [https://code.visualstudio.com/download official site]. It can be installed from just a ZIP file and then there also is a way to use it in [https://code.visualstudio.com/docs/editor/portable portable mode] so it doesn't mess with the system or multiple installations.

=== Workspace Folder ===
After opening VS Code for the first time for Desynced modding, you should open the "mods" folder. To find it, run the game and go to <code>Options</code> → <code>System</code> and then click the "Open Mods Folder". Alternatively you can browse to the game's installation directory and go into the <code>Desynced\Content\mods\</code> sub-directory.

=== Required Extensions ===
Next you should switch to the Extensions tab (by clicking the icon or by pressing <code>CTRL + SHIFT + X</code>) and install these two extensions for Lua editing:

* [https://marketplace.visualstudio.com/items?itemName=sumneko.lua Lua by sumneko] for code completion/navigation and other convenience features
* [https://marketplace.visualstudio.com/items?itemName=beamng.lrdb-beamng lrdb-beamng by BeamNG] for attaching the debugger and seeing logging in the editor

(Make sure to confirm the developer names before installing as there are many extensions named "Lua" or "lrdb").

==== Lua Language Server Setup ====
Alongside the [https://modding.desyncedgame.com/syntax.html Lua API documentation] the developers of Desynced offer a Lua Language Server definition file for download at the following link:

https://modding.desyncedgame.com/desynced-lls-library.lua

With the [https://marketplace.visualstudio.com/items?itemName=sumneko.lua Lua] extension installed, the easiest way to make use of it is by downloading the above file (desynced-lls-library.lua) into the root of the Desynced mods directory (which is the workspace folder that is opened in VS Code). The API names and documentations will then show up while writing code or when hovering the mouse over function names.

==== Debugging Setup ====
With the [https://marketplace.visualstudio.com/items?itemName=beamng.lrdb-beamng lrdb-beamng] extension installed, make sure to start the game with the command line argument <code>-moddev</code> and keep it running.

To attach the debugger, switch to the 'Run and Debug' tab in Visual Studio Code (menu 'View' -> 'Run' or by pressing <code>CTRL + SHIFT + D</code>). Click on the "create a launch.json" link and replace the content with the following:
<syntaxhighlight lang="json">{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lrdb",
            "request": "attach",
            "name": "Attach",
            "host": "localhost",
            "port": 21110,
            "sourceRoot": "${workspaceFolder}",
            "stopOnEntry": false,
        },
    ],
}</syntaxhighlight>
Again make sure that the workspace folder opened in VS Code matches your Desynced installation, it always needs to point to the top "mods" directory and not a specific mod directory inside of it. With the launch configuration saved, press F5 to attach the debugger to the game. If it doesn't end up connecting, open the "LUA REMOTE DEBUGGER - VMS" panel in the 'Run and Debug' tab of Visual Studio Code and try to double click the Desynced Lua VM which should be shown running on "localhost:21110".

Once connected, you'll have full access to breakpoints, code stepping, as well as accessing local and global variables and the watch window. Also it is recommended to open the Debug Console (menu 'View' -> 'Debug Console' or by pressing <code>CTRL + SHIFT + Y</code>) to have any logging or errors appear directly in Visual Studio Code. The debug console is interactive, too, so entering code into the input text box below the console will execute it in the game. This can be used to execute <code>Debug.Reload()</code> which will hot-reload the Lua code from inside the code editor (same as pressing F7 in the game).

To use breakpoints, make sure that the folder opened in Visual Studio Code is the top "mods" directory of Desynced and not a specific mod directory inside of it, as it needs to match the path defined in the "sourceRoot" field of the launch configuration.

=== Additional Customization ===

==== Syntax highlighting for UI layout strings ====
To make Visual Studio Code show syntax highlighting of Desynced UI layout strings you can install this tiny extension which will apply XML formatting for text inside multi-line Lua strings. This works because Desynced UI layout definitions are similar to XML documents. To install the extension after downloading it, switch to the Extensions tab (by clicking the icon or by pressing <code>CTRL + SHIFT + X</code>) and select the "Install from VSIX..." option inside the ⋯ menu in the top-right of the Extensions panel.

Download: https://github.com/StageGames/vscode-xml-in-lua/releases/download/1.0.0/stagegames.xml-in-lua-1.0.0.vsix

==== Highlight Status Bar While Debugging ====
To make it easier to know if your debugger is attached, you can make VS Code colorize the status bar in an orange tone. To do so, press <code>CTRL + SHIFT + P</code>, write ">workspace settings json", press enter and add the following rules to the settings file:
<syntaxhighlight lang="json">    "workbench.colorCustomizations": { "statusBar.background": "#007ACC", "statusBar.debuggingBackground": "#CA5100", },</syntaxhighlight>

==== Code Hot-Reload Hotkey ====
You can configure a custom hotkey to make the game hot-reload any code changes from within VS Code. To do so, press To do so, press <code>CTRL + SHIFT + P</code>, write ">keyboard shortcuts json" and select "Preferences: Open Keyboard Shortcuts (JSON)" and add the following entries to it:
<syntaxhighlight lang="json">[
    { "key": "ctrl+f7", "command": "workbench.debug.action.focusRepl", "when": "!inDebugRepl" },
    { "key": "ctrl+f7", "command": "workbench.action.debug.start", "when": "debuggersAvailable && debugState == 'inactive'" },
    { "key": "ctrl+f7", "command": "runCommands", "when": "inDebugRepl", "args": { "commands": [
                { "command": "workbench.action.files.saveAll" }, { "command": "workbench.debug.viewlet.action.reapplyBreakpointsAction"}, { "command": "cursorBottom" }, { "command": "cursorTopSelect" },
                { "command": "type", "args": { "text": "Debug.Reload()" } }, { "command": "repl.action.acceptInput" }, { "command": "workbench.action.focusActiveEditorGroup"} ] } },
]</syntaxhighlight>

With that in place, at any time you can hold CTRL then press F7 twice to make the game reload any changes made to Lua. 

==== Integrate with TortoiseSVN ====
If you use TortoiseSVN to manage software versioning of your Lua code you can add a few hotkeys to easily access common SVN functions. To do so, press <code>CTRL + SHIFT + P</code>, write ">keyboard shortcuts json" and select "Preferences: Open Keyboard Shortcuts (JSON)" and add the following entries to it:
<syntaxhighlight lang="json">[
    { "key": "ctrl+numpad1", "command": "workbench.action.terminal.sendSequence", "args": { "text": "&\"C:\\Program Files\\TortoiseSVN\\bin\\TortoiseProc.exe\" \"/command:diff\" \"/path:${file}\"\n" } },
    { "key": "ctrl+numpad2", "command": "workbench.action.terminal.sendSequence", "args": { "text": "&\"C:\\Program Files\\TortoiseSVN\\bin\\TortoiseProc.exe\" \"/command:log\" \"/path:${file}\"\n" } },
    { "key": "ctrl+numpad3", "command": "workbench.action.terminal.sendSequence", "args": { "text": "&\"C:\\Program Files\\TortoiseSVN\\bin\\TortoiseProc.exe\" \"/command:blame\" \"/path:${file}\"\n" } },
]</syntaxhighlight>

With these in place, the following hotkeys become available to VS Code while having a .lua file open:

* <code>CTRL + NUMPAD 1</code>: Open diff of the current file against the source repository
* <code>CTRL + NUMPAD 2</code>: Open the revision log of the current file
* <code>CTRL + NUMPAD 3</code>: Open the blame tool for the currently edited file

==== Better Diagnostics ====
To avoid the Lua extension in Visual Studio code reporting too many or too few problems, the settings can be further refined. In VS Code, press <code>CTRL + SHIFT + P</code>, write ">workspace settings json", press enter and append the following into the settings file:
<syntaxhighlight lang="json">{
    "Lua.diagnostics.disable": [
        "unbalanced-assignments",
        "cast-local-type",
        "need-check-nil",
        "duplicate-set-field",
        "undefined-field",
        "assign-type-mismatch",
    ],
    "Lua.diagnostics.severity": {
        "redundant-return": "Error",
        "unused-function": "Error",
        "empty-block": "Error",
        "trailing-space": "Error",
        "unreachable-code": "Error",
        "redundant-parameter": "Error",
        "missing-parameter": "Error",
        "unused-vararg": "Error",
    },
    "Lua.type.weakNilCheck": true,
    "Lua.type.weakUnionCheck": true,
    "files.associations": {
        "*.json": "jsonc",
    },
    "search.exclude": {
        "desynced-lls-library.lua": true,
        ".vscode": true,
    },
}</syntaxhighlight>

=== For Developers At Stage Games ===
When working with the internal code base at Stage Games, the Lua extension can get confused about custom pre-compiler directives. To make it ignore #if/#elif/#else/#endif in Lua code, a small modification of the Lua extension is needed. In VS Code, press <code>CTRL + SHIFT + P</code>, write ">open extensions folder" and press enter. Then browse into <code>sumneko.lua-VERSION-win32-x64/server/script/parser</code> and drag the file <code>compile.lua</code> into VS Code. Find the function <code>skipComment</code> near line 532 and change the first few lines of code to the following then save and restart VS Code:
<syntaxhighlight lang="lua">local function skipComment(isAction)
    local token = Tokens[Index + 1]
    if token == '--'
    or (
        token == '//'
        and (
            isAction
            or State.options.nonstandardSymbol['//']
        )
    ) or (
        token == '#' and (Tokens[Index + 3] == 'if' or Tokens[Index + 3] == 'elif' or Tokens[Index + 3] == 'else' or Tokens[Index + 3] == 'endif')
    ) then</syntaxhighlight>
When the extension is updated (automatically or manually) this change needs to get applied again.

{{ModdingNav}}