Authoring Lua Debugger

Lua VS Code Debugger

EmoTracker ships a built-in Debug Adapter Protocol (DAP) server that lets you debug your pack's Lua scripts directly from Visual Studio Code. You can set breakpoints, step through code, inspect locals and upvalues, catch Lua errors as they happen, and evaluate expressions in a REPL — all without modifying your pack files.

Prerequisites

• Visual Studio Code
• Node.js (for building the extension, v18 or later)
• npm (bundled with Node.js)

Step 1 — Install the VS Code extension

The debugger extension lives in the vscode-extensions/emotracker-lua-debug/ folder of the EmoTracker repository. Clone or download the repo if you haven't already.

cd vscode-extensions/emotracker-lua-debug
npm install
npm run compile

Then install it into VS Code using either method:

Option A — Install from folder (easier for development)

Open the VS Code command palette (Ctrl/Cmd + Shift + P) and run:

Developer: Install Extension from Location...

Select the vscode-extensions/emotracker-lua-debug/ folder.

Option B — Package as a VSIX and install

# From vscode-extensions/emotracker-lua-debug/
npx vsce package

This produces emotracker-lua-debug-x.x.x.vsix. Install it via:

• VS Code Extensions panel → ⋯ menu → Install from VSIX...

After installing, the extension registers the emotracker-lua debug type. You do not need to restart VS Code.

Step 2 — Launch EmoTracker in dev mode

The Lua debugger is only active when EmoTracker is started with the -dev flag. Without it, the DAP server does not start and VS Code cannot connect.

The easiest way is to use the pre-configured VS Code launch profile inside the EmoTracker repo:

1. Open D:\Code\EmoTracker-Community\EmoTracker in VS Code.
2. Go to Run & Debug (Ctrl/Cmd + Shift + D).
3. Select "Launch EmoTracker Avalonia (Dev-Debug)" from the dropdown and press F5.

Or launch from a terminal:

dotnet run --project EmoTracker/EmoTracker.csproj -- -dev

When the DAP server is ready you will see this in the developer terminal:

[LuaDbg] DAP server listening on port 27126

Port override: Set the EMOTRACKER_DAP_PORT environment variable to use a different port.

Step 3 — Attach VS Code to EmoTracker

Open your pack folder in VS Code (the folder that contains manifest.json). Then:

1. Go to Run & Debug (Ctrl/Cmd + Shift + D).
2. Click "create a launch.json file" if you don't have one, or open the existing .vscode/launch.json.
3. Add an attach configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "emotracker-lua",
      "request": "attach",
      "name": "Attach to EmoTracker (Lua)",
      "host": "localhost",
      "port": 27126
    }
  ]
}

4. Select "Attach to EmoTracker (Lua)" from the dropdown and press F5.

VS Code connects to the running EmoTracker instance. The debug toolbar appears and the status bar turns orange. You are now live.

Tip: You can attach and detach while EmoTracker is running. EmoTracker continues running normally when no debugger is attached — there is no overhead unless a client is connected.

Setting breakpoints

Open any .lua file from your pack in VS Code and click in the gutter to set a breakpoint (red dot). Paths are resolved relative to the pack's root folder.

Breakpoints take effect immediately — you do not need to reload the pack. If you have multiple tabs open with the same pack, breakpoints apply to all of them.

Debugging features

Stepping

When execution pauses at a breakpoint or on an error:

Action	Shortcut
Continue	F5
Step Over	F10
Step Into	F11
Step Out	Shift + F11
Pause all	Pause button in the debug toolbar

Variables

The Variables panel shows three sections while paused:

Section	Contents
Locals	Local variables in the current stack frame
Upvalues	Closure captures from enclosing scopes
Globals	The Lua global table

Tables expand lazily — click the arrow next to a table to explore its entries. Variables are read-only; you cannot modify values from the panel.

Call stack and threads

Each open EmoTracker tab that has an active Lua interpreter appears as a separate thread in the Call Stack panel. Switch between threads to inspect the state of different tabs. When one thread pauses, the others keep running unless you use the Pause All button.

Evaluate / REPL

While paused, open the Debug Console panel and type a Lua expression to evaluate it against the current frame's scope:

Tracker:FindObjectForCode("bow")

The REPL evaluates only while paused — it is not a live console during execution.

Break on Lua errors

Open the Breakpoints panel and check "Lua errors" to pause automatically whenever a Lua error propagates through a _safe_call boundary. This catches script errors without requiring you to know where they might occur.

Multi-state debugging

If you have multiple tabs open with the same (or different) packs, each tab's Lua interpreter registers as its own thread. You can:

• Switch threads to inspect state in a different tab
• Set breakpoints that fire only when a specific tab hits them (use conditional breakpoints based on variable values, since thread-scoped breakpoints are not yet supported)

Verbose DAP tracing

To log all DAP protocol messages to the developer terminal, set the environment variable EMOTRACKER_DAP_TRACE=1 before launching EmoTracker. In the EmoTracker repo's .vscode/launch.json, there is a commented-out "env" block in the Dev-Debug profile — uncomment it to enable tracing automatically.

Trace lines appear in the developer terminal prefixed with [LuaDbg].

Known limitations

• Conditional breakpoints are not supported.
• Set variable from the Variables panel is not implemented (inspection is read-only).
• Lua coroutines are not tracked as separate threads.
• Evaluate only works while paused, not during execution.

See also

• Developer Setup — tools and environment setup for pack authors
• Authoring Lua Scripts — the Lua scripting overview
• Authoring Lua — Standard Callbacks — the callback functions EmoTracker calls into your pack
• Multi-Tab and Window — running multiple packs simultaneously