bt-dap

bt-dap is the BT debugger adapter. Editors use it to set breakpoints, step through BT code and inspect variables. Studio, the VS Code extension and the JetBrains plugin set it up for you (see Editor integrations and Studio play and debug). This page is for connecting another editor that supports the Debug Adapter Protocol (DAP), such as Neovim (nvim-dap), Emacs (dap-mode) or Helix.

Setting it up

Configure your editor to start bt-dap and talk to it over standard input and output, with the debugger type bt:

bt-dap --runner /path/to/bt-run

--runner names the bt-run that runs your scripts. It defaults to the bt-run in the same folder as bt-dap, so you can leave it out when the two are installed together.

Debug a script

{ "type": "bt", "request": "launch", "program": "/opt/bt/bt-run",
  "args": ["main.bt", "input.txt"], "cwd": "/home/me/tool" }

program is bt-run; the first argument is a .bt file or a .ctbt file built with ctbt artifact --debug. A .bt file is compiled with debug information automatically; if it has errors, the launch fails with could not compile PATH: ... and nothing runs.

Key	Default	Description
program	required	bt-run, or a game or program built with the debug runtime (see below).
args	[]	Arguments. For bt-run, the script or .ctbt file comes first.
cwd	The adapter's folder	Working folder of the program.
stopOnEntry	true	Pause before the first line of the entry function (top-level variable initializers run first, without pausing). Set false to run until a breakpoint.

The program's output appears in the editor's debug console. Stopping the debug session stops the program.

Debug a running game

To debug a game outside Studio, the game must be built with the debugger included:

1. Set "bt_debug_runtime": true on the build target in your .ctproject, use code_mode source or bytecode (AOT-compiled code cannot be debugged), and build it.

2. Start the game with a port and a secret token, either through bt.debug in the manifest or with environment variables:

   BT_DEBUG_PORT=4711 BT_DEBUG_TOKEN=my-secret ./MyGame

   The game waits for the debugger before it runs (set BT_DEBUG_WAIT=0 to start without waiting).

3. Attach from the editor:

   { "type": "bt", "request": "attach", "port": 4711, "token": "my-secret" }

Key	Default	Description
port	required	The port the game was started with.
token	required	The token the game was started with (up to 64 characters).
stopOnEntry	true	Pause at the first line.

You can also launch a debug-runtime game directly by giving its executable as program. The debugger listens only on your own computer (127.0.0.1).

What you can do

Line breakpoints, continue, step over, step in, step out, pause, a thread per BT task, call stacks, local variables, and hovering a variable to see its value. In the debug console you can evaluate a local variable's name, or assign a number, boolean or string to a local (count = 3).

Errors

Message	What to do
launch refused: ...	program must be the bt-run next to bt-dap (or the one named by --runner) with a .bt or .ctbt file, or an executable built with the debug runtime. Plain release builds cannot be debugged.
could not compile PATH: ...	Fix the compile error shown.
could not launch or connect to debug target	The program did not start, exited at once, or was not built with debug information. Rebuild the .ctbt with --debug.
could not attach to BT debug agent	Check the port and token, and that the game is running with the debug runtime.
BT debugging requires an artifact built with --debug	Rebuild with ctbt artifact --debug.
v1 evaluation accepts a local name or scalar literal assignment	Only local names and simple assignments can be evaluated.