Skip to content

Debugging with VS Code

Jump to bottom
fabian-flassig edited this page Jul 31, 2026 · 1 revision

PYTHA contains a debug server for the Lua API. Together with the VS Code extension PYTHA Lua Support it lets you debug a plugin in the editor while it runs inside PYTHA: breakpoints, call stack, variable inspection, stepping and a Lua REPL.

The debugger attaches to a running PYTHA over a local TCP connection — VS Code never starts PYTHA itself. PYTHA stays open, and you can run the plugin as often as you like within one debug session.

Requirements

  • PYTHA with the Lua debug server (see below)
  • Visual Studio Code
  • The extension PYTHA Lua Support, installed from the Marketplace:
ext install pytha-3d-cad.pytha-lua-support

The extension provides autocomplete and the debugger in one package; see Home.

1. Enable the debug server in PYTHA

Open PYTHA's settings and go to the page Developer:

  • Switch on Enable Lua Debugger.
  • Lua Debugger Port sets the TCP port. The default is 4711; only change it if that port is already taken on your machine.

The server starts as soon as the setting is applied — no PYTHA restart is needed. Switching the setting off (or changing the port) stops and restarts it right away. The setting is persisted, so it stays on until you turn it off.

The server listens on localhost only, so it is not reachable from other machines.

2. Configure VS Code

Open the folder containing your plugin in VS Code.

If you kept the default port, no configuration is required. Otherwise set the port to the same value you configured in PYTHA:

// .vscode/settings.json
{
  "pytha-lua.port": 4711,
  "pytha-lua.host": "127.0.0.1"
}

A launch configuration is not required — the extension offers PYTHA Lua (attach) on its own. If you want one anyway (to pin a port per project, or to keep several configurations side by side), add it via Run → Add Configuration… → PYTHA Lua:

{
  "version": "0.2.0",
  "configurations": [
    { "type": "pytha-lua", "request": "attach", "name": "PYTHA Lua (attach)" }
  ]
}

A port or host given directly in the launch configuration takes precedence over the settings above.

3. Attach and debug

  1. Start PYTHA and load the project you want to work in.
  2. In VS Code, press F5 (or Run → Start Debugging) to attach. The status bar turns orange once the connection is established.
  3. Set breakpoints in your plugin's .lua files.
  4. Run the plugin in PYTHA. Execution stops at the first breakpoint that is hit.

The debug session stays attached across plugin runs, so you can start the plugin repeatedly without pressing F5 again. To detach, press Shift+F5 in VS Code.

Conditional breakpoints and logpoints

Right-click a breakpoint in the editor gutter and choose Edit Breakpoint…:

  • Expression — a Lua expression that is evaluated in the frame of the breakpoint every time the line is reached. Execution only stops if it is true, e.g. part_index > 20 or name == "Front".
  • Log Message — turns the breakpoint into a logpoint: execution never stops, instead the message is written to the Debug Console. Expressions in curly braces are evaluated and substituted, e.g. part {i} of {count}, type = {pytha.get_element_type(part)}.

Logpoints are the least intrusive way to trace a plugin, because they do not freeze PYTHA.

What you can do while stopped

  • Call stack — the Lua frames of the running plugin, with file and line.
  • Variables — locals and upvalues of the selected frame. Tables can be expanded, and values can be changed in place.
  • Watch and hover — evaluate any Lua expression in the context of the selected frame.
  • Debug Console — the same evaluation as a REPL, e.g. #pytha.enumerate_parts().
  • Stepping — step over, step into, step out, continue, and pause a running plugin.
  • Stop on error — an uncaught Lua error stops execution at the place where it was raised, with the error message shown, so the call stack and all locals are still intact.
  • print(...) — while a debugger is attached, print is available and writes to the Debug Console. It is disabled otherwise (see Lua Runtime).

Notes and limitations

  • Only plugins that are started while the debugger is attached can be debugged. Attach first, then run the plugin.
  • While execution is stopped, PYTHA's window is frozen and does not repaint — this is expected. It resumes on continue or step.
  • Only one debug session at a time is served, matching the single embedded Lua runtime.
  • Protected plugins (delivered in encrypted form) cannot be debugged.
  • The execution-time limit of the Lua runtime keeps running while you are attached, but the time spent stopped at a breakpoint does not count against it.
  • Breakpoints are matched against the file path of the loaded plugin source. Debug the files in the plugin folder PYTHA actually loads, not a copy elsewhere.

Troubleshooting

VS Code reports that the connection was refused. Check that Enable Lua Debugger is switched on in PYTHA, and that the port in PYTHA and the port in VS Code (pytha-lua.port or the launch configuration) are the same.

Breakpoints stay grey / are never hit. The plugin was already running when you attached, or PYTHA loads a different copy of the file. Detach, attach again, then start the plugin.

Nothing appears in the Debug Console. print is only installed when the debugger is attached at the moment the plugin starts. Attach before running the plugin.

Clone this wiki locally