Debugging and profiling
Scripted runs
--commands runs a timed script inside your game: time:action:arguments, separated by ;, and always ending with quit. It's how you reproduce a bug the same way every time, and how an AI agent sees what your game is doing.
hz/hzbuild --commands "1:key_down:W;2:key_up:W;2.5:screenshot;3:quit" -- --offscreenThe ones you'll use most:
| Command | Does |
|---|---|
screenshot | saves out/screenshot_commands.png |
key_down:W, key_up:W | presses a key, by its display name (Space, Left Shift, Mouse Left) |
move_to_text:Play, touch_start, touch_end | clicks the UI element that says "Play" |
teleport:Player:0,2,10 | moves a named entity |
frame_entity:Boss | points the camera at it |
dump_entity:Player, dump_world | prints an entity's components, or every table and system |
ecs_report | time, rows and lanes per ECS system |
0:help prints every command your build knows, including the ones your own game registers. Add --fixed-dt to the game's arguments and every frame is exactly 1/60 s, so a script plays out the same on any machine.
When something's wrong
- A system doesn't run.
dump_worldshows how many entities each system matched. Zero usually means a missing component. - A hang. Almost always a
lane_sync()that only some lanes reach. Debug builds catch it and tell you where. - It's different every run. Try
-- --lanes 1. If the bug goes away, it's a race between lanes. - The GPU complains. Debug builds on macOS run with Metal validation, so GPU mistakes show up in the log.
Profiling
perf_stats_draw(in the template) is an overlay with frame time, CPU and GPU time.ecs_reporttells you which systems take the time, and how well they spread over the lanes.gpu_prof:3:out/profprofiles three frames of the GPU: every pass, every big draw and, on macOS, every shader.perf_cpu_scope_begin("name")and_end()time your own code in the overlay.
Profile release builds (--release). Debug builds are much slower and their numbers will mislead you.
Crashes
A crash writes a report, and the next launch sends it to us so engine crashes get fixed (kaigen telemetry crash-reports off turns that off). If you hit an engine bug you can't get past, hz/hzbuild report "what happened" sends us your description with the logs and versions (never your code) and gives you an id to mention when you talk to us.