VS Code DAP Debugger

The VS Code DAP debugger is a Professional tier feature. Today the gate is the LUAU_ENV_ENABLE_DEBUGGER compile-time flag — when present, --debug works on any tier. The licence gate ships in a future release.

Overview

codegen embeds the Roblox luau-debugger (vendored at vendor/luau-debugger/). When started with --debug, the engine spins up a DAP TCP server and blocks until a debugger attaches. You can then:

• Set breakpoints in .luau scripts (preamble, handler, grouping)
• Inspect the entity payload and any local variables
• Step through execution
• Watch the call stack

Setup

1. Install the LuaU VS Code extension

   Use the extension that ships with vendor/luau-debugger/extensions/vscode/. There is no codegen-specific VS Code extension. Any DAP-capable editor that speaks the same protocol works equivalently.

2. Add a launch configuration

   .vscode/launch.json

   {
     "version": "0.2.0",
     "configurations": [
       {
         "type": "luau",
         "request": "attach",
         "name": "attach to codegen",
         "address": "localhost",
         "port": 50001
       }
     ]
   }

   The default port is 50001. Match it with --debug-port if you need a different one.

3. Run codegen with the debugger flag

   codegen --debug \
           --debug-port 50001 \
           --debug-source-root "$PWD/.codegen/rules" \
           -i ./include \
           -r .codegen/rules \
           -a ToString

   --debug-source-root should be the absolute path to the rules root, so VS Code can map breakpoints to the on-disk script files. If omitted, the engine uses the absolute path of --rules-dir.

   The engine prints a “waiting for debugger” line and blocks.

4. Attach from VS Code

   Press F5 (or use the Run menu) with the launch configuration above active. Once attached, the engine resumes; execution pauses at any breakpoint you’ve set in a .luau script.

What’s available in the inspector

When paused inside a handler, expand the local that holds the decoded entity to navigate the AST:

local node = json.decode(input)  -- ← break after this line, expand `node`

The Variables panel shows the full table including _namespaces, _registryId, attributes, memberVariables, and so on. This is the fastest way to understand the exact JSON shape your rule receives.

Limitations

• The debugger attaches to a single rule run; it doesn’t keep a session across re-invocations.
• Hot-reload (editing the script while paused) isn’t supported. Restart the debug session after edits.
• The --debug-port is required for non-default ports; there’s no port discovery.
• Debugger support requires the binary to be built with LUAU_ENV_ENABLE_DEBUGGER. The default build profiles enable it; release builds may not.

Key Takeaways

• Use the luau DAP launch type with request: "attach"; there is no codegen-specific extension.
• The engine blocks at startup with --debug and resumes when the debugger attaches.
• --debug-source-root is the absolute rules root used for VS Code’s source mapping.
• Breakpoints work in handler, preamble, and grouping scripts.