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.

Walk forward, look, quit
hz/hzbuild --commands "1:key_down:W;2:key_up:W;2.5:screenshot;3:quit" -- --offscreen

The ones you'll use most:

CommandDoes
screenshotsaves out/screenshot_commands.png
key_down:W, key_up:Wpresses a key, by its display name (Space, Left Shift, Mouse Left)
move_to_text:Play, touch_start, touch_endclicks the UI element that says "Play"
teleport:Player:0,2,10moves a named entity
frame_entity:Bosspoints the camera at it
dump_entity:Player, dump_worldprints an entity's components, or every table and system
ecs_reporttime, 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

Profiling

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.