Engine environment
Environment variables you can set when running a game (a built executable,
a game played from Studio, CTurtleHost or
bt-ui) to measure performance, capture frames, rule out
problems, or attach a debugger. Players never need them.
CT_FRAME_STATS=1 ./MyGame
CT_PROFILE_FRAMES=frames.csv CT_PROFILE_AUTO_QUIT_SECONDS=30 ./MyGame
On Windows (PowerShell): $env:CT_FRAME_STATS=1; .\MyGame.exe.
"On" below means any value that is not empty and does not start with 0.
Measuring performance
| Variable | Value | Effect |
|---|---|---|
CT_FRAME_STATS | any | Prints [frame] N frames avg X ms (F fps) worst Y ms once per second. Watch the worst time as well as the average: a good average can hide stutters. |
CT_PROFILE_FRAMES | file path | Records how long each part of every frame took (game update, ECS, UI, drawing, GPU passes) and writes it as a CSV file when the game quits. |
CT_PROFILE_AUTO_QUIT_SECONDS | seconds | Quits normally after this many seconds. Use with CT_PROFILE_FRAMES for repeatable measurements. |
BT_PROFILE_STARTUP | any | Prints how long loading and compiling BT scripts took at startup. |
BT_JIT_PERF_MAP | file path | Linux: writes a map of compiled BT functions so the perf profiler can show BT function names. Use /tmp/perf-PID.map for perf to find it. |
ECS_WORKERS | whole number, 1 or more | Number of background worker threads. Default: one fewer than the number of logical processors (at least 1). Lower it to see how the game runs on a machine with fewer cores. |
Ruling out problems
| Variable | Value | Effect |
|---|---|---|
DETERMINISTIC | on | Steps the game a fixed 1/60 second per frame instead of by real time, and makes physics repeatable. Use it to reproduce a bug the same way every run. |
BOX2D_SERIAL | on | Runs physics on one thread. If a physics problem goes away, it is related to multithreading. |
CT_DISABLE_RENDER | on | Starts with drawing turned off, so you can measure game logic on its own. Game code can turn drawing back on. |
Capturing frames
| Variable | Value | Effect |
|---|---|---|
CT_CAPTURE_FRAME | file path | Saves frame 60 as a PPM image. Useful for automated screenshots and visual checks. |
CT_CAPTURE_EVERY | whole number N | With CT_CAPTURE_FRAME, also saves every Nth frame after frame 60, as PATH.FRAME.ppm. |
Debugging
These work only in programs built with the debugger included: games built with
bt_debug_runtime, programs built with ctbt build --debug, and bt-run.
Editors set them for you when they launch a program; set them yourself to
attach to a game you started. See Debug a running game.
| Variable | Value | Effect |
|---|---|---|
BT_DEBUG_PORT | port number | Turns on the debugger, listening on 127.0.0.1 at this port. |
BT_DEBUG_TOKEN | text | Secret the debugger client must send to connect. |
BT_DEBUG_WAIT | 0 or other | Wait for the debugger to connect before running. Default: wait. 0 starts at once. |
BT_DEBUG_STOP_ON_ENTRY | 0 or other | Pause at the first line. Default: pause. 0 runs until a breakpoint. |
If the code was compiled without debug information, the program stops with
BT debugging requires an artifact built with --debug.