Fatshark Stingray Debugger
This extension makes Visual Studio Code into a full-featured code editing debugging environment for your Fatshark projects. You can connect the debugger to a running engine, launch a project, trigger breakpoints and step through your project's Lua code, view variable values, send commands to the engine, and more.
This extension is based on a fork of the Autodesk Interactive Debugger developed by Jonathan Schmidt.
Step 1. Install the extension
Bring up the Extensions view by clicking the Extensions icon in the Activity Bar on the left side of Visual Studio Code, or selecting View > Extensions (
For more about installing extensions, see the Visual Studio Code user guide.
Step 2. Open your project folder
Open your Fatshark project folder in Visual Studio Code. This will be your workspace, where Visual Studio Code will keep your debug configurations.
Select File > Open Folder (
You can make any folder on your computer your workspace, but using your project's resources folder has the advantage of keeping your debug configurations together with the project that you'll be using them with. It also makes the Lua files in your project easy to get to in the editor while you're working.
Step 3. Create your debug configurations
A debug configuration tells the Visual Studio Code debugger what it should do when you start debugging: whether it connect to a running process or launch a new process, and what settings and parameters it should use for the connection.
You can read some background about these configs here.
You'll have to create at least one new debug configuration in order to make the debugger able to attach to or launch the engine.
Attach to a running engine
You can make the Visual Studio Code debugger connect to a running instance of the Stingray engine. Use the following launch configuration:
Launch a project and attach
You can make the Visual Studio Code debugger launch the Autodesk Interactive engine with a specific project, and immediately attach itself to that instance of the engine. The engine will wait for the debugger to connect and start the debugging session before it runs any Lua initialization code.
Launching the game from the debugger like this makes it easy to trigger breakpoints in your initialization code:
To set this up, use a launch configuration like this:
You don't have to provide any command-line parameters. The debugger extension will set the ones it needs, like
Step 5. Start debugging!
If the debugger is able to connect to the game, it will show the Debug actions pane. You should now be able to open your project or editor script files and set up some breakpoints.
Set breakpoints, inspect and advance
You can set breakpoints in any Lua scripts from your project and from the core resources. Open the script file and click in the left margin next to a line of code:
Whenever the engine evaluates a line of code that has a breakpoint set, it pauses. While it's paused, you can:
Read console messages
Just like the Log Console in the Autodesk Interactive editor, the Debug Console in Visual Studio Code prints out all console messages sent by the connected engine:
If any of those messages contain ID strings known to the engine (e.g.
Send engine commands
You can send console commands to the engine from the Debug Console. Prefix the commands with
![engine commands](https://github.com/FatsharkStudiosAB/stingray-vscode-debugger/raw/master/gifs/engine commands.gif)
You can also send commands from the Command Palette. Open the Command Palette, type
Send engine scripts
Everything that you type in the Debug Console that is not prefixed with
Code editing features
This extension does more than just debugging: it also adds some extra features to the code editor that you'll find especially handy when you work with Autodesk Interactive projects.
Autodesk Interactive Lua API hovering support
Hover over any function from the Autodesk Interactive API to get the function's signature and brief description:
Stingray Lua API function signatures
You'll also be reminded of the signature and description as you type the opening bracket for a function:
Syntax highlighting for SJSON resources
The code editor shows appropriate syntax highlighting for Autodesk Interactive resource types that use [SJSON format], like .unit, .level, and .script_flow_nodes.