OpenTTD Development • Squirrel debugger support for OpenTTD (AI / GameScript) – prototype

For quite a long time, debugging AI / GameScripts in OpenTTD has mostly meant printing values and reading logs:

Code:

AILog.Info("value = " + value);

or similar approaches.

I experimented with integrating the Squirrel debugger (sqdbg) into OpenTTD, and it turns out it is possible to attach a real debugger to running AI / GameScript instances.

Current state

The prototype currently supports:

• attaching an external debugger
• breakpoints
• stepping
• inspecting variables
• works with both AI and GameScripts

Tested with VS Code using the sqdbg extension: https://github.com/samisalreadytaken/sqdbg-vs

How it works

Each Squirrel VM exposes a debug port.

Ports are assigned sequentially starting from:

Code:

2222

So typically:

Code:

GS -> 2222AI0 -> 2223AI1 -> 2224AI2 -> 2225...

Ports are printed to the console, so OpenTTD needs to be started with:

Code:

-d

Then you can attach the debugger to the port corresponding to the AI / GS instance.

Example workflow

• start OpenTTD with -d
• load a game with AI or GameScript
• check console output for assigned port
• attach debugger (e.g. from VS Code)
• set breakpoint
• execution stops at that point

Function breakpoints

Function name matching is currently limited.

There is no support for:

Code:

Class.MethodClass::Method

Only the function name itself is used:

Code:

Method

This means that if multiple classes define functions with the same name, function breakpoints may trigger in multiple places.

In such cases, regular line breakpoints are more reliable.

Downloads Windows x64 binary: https://github.com/PaSaSaP/OpenTTD-sqdb ... penttd.exe

Source code: https://github.com/PaSaSaP/OpenTTD-sqdbg-debugger

VS Code setup (sqdbg)

Example launch.json configuration:

Code:

{ "version": "0.2.0", "configurations": [ { "type": "squirrel", "request": "attach", "name": "Attach to OpenTTD", "port": 2222 } ]}

How to use

• Install the sqdbg VS Code extension: https://github.com/samisalreadytaken/sqdbg-vs
• Create or edit .vscode/launch.json in your project.
• Set the port to match the one printed by OpenTTD (requires running with -d).
• Start OpenTTD, load a game with AI / GameScript.
• In VS Code:
  • select "Attach to OpenTTD"
  • press Start Debugging (F5)
• Set breakpoints in .nut files and run the script.

Execution will pause when a breakpoint is hit.

Demo

openttd-sqdbg.gif

Notes

• based on OpenTTD 15.2
• currently implemented as a patched build
• each VM uses a separate port (no multiplexing)

Statistics: Posted by MustBe — 17 Mar 2026 19:50

---