# Debugging and profiling

> Scripted runs, world dumps, the scheduler report, GPU profiles and crash reports.

## 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:

| 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_world` shows 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_report` tells you which systems take the time, and how well they spread over the lanes.
- `gpu_prof:3:out/prof` profiles 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.
