# Agent playbook: running, measuring and debugging the game Read this before you run the game, take a frame dump or measure performance. This page holds the conventions; the `--help` of each tool holds its options. ## Work in a task worktree Start, build, hand back and clean up a task with the `private-build` skill (`.claude/skills/private-build/SKILL.md`): a git worktree on `task/` and a build dir `build/v121-`. The pipeline cache, `pipeline-keys.bin`, `shader-cache`, `shader-programs.bin` and `shader-answers.bin` live next to each `totk.exe`, so a task build starts cold: seed it by copying `build/v121`'s five before timing anything. A build seeded from an older one stalls on pipeline and shader builds, and its slow frames say nothing about the change. (Until 2026-10-22 every task build wrote into `build/v121`'s caches, and task builds broke each other's runs.) ## Running Run a build into gameplay with the `run-game` skill (`.claude/skills/run-game/SKILL.md`): `tools/run_game.py`, the save backups and their scenes, input scripts. `build/profile` is the user's real profile: never write it. Other agents run the game at the same time: stop only a `totk.exe` you started, by PID; `taskkill /IM totk.exe` closes every instance. ## Measuring Timings are only comparable on a quiet machine. Pass `--quiet` to take the machine-wide lock `build/.gpu-run.lock` (held until the game exits, freed by the OS if the caller dies, holder pid and build in the file), then wait until no other `totk.exe` or `ninja.exe` runs. The log's first and last lines record the count either way. - `--env TOTK_TRACE=perf,sched`, then `python tools/perf_summary.py `: fps, max frame and the render-thread buckets per 60 frames. Per-thread run, core, host, lock and addr shares come per 120 presents. A second `perf: frame N: gpu avg` line per window has the GPU busy time per frame (timestamp queries per submission part, `vk_sync.c`; upload batches not included), fence waits of the render thread and of other threads, VRAM use and budget (`VK_EXT_memory_budget`), process RAM and `bound: gpu|cpu|pace` (pace: the frame waited for pacing 15% of the time or more; gpu: the GPU was busy 80% of the interval or more). - The pool census (`mem: census`, `vk_memory.c` `vk_mem_census`) is logged at frame 1800, with `perf` every 1800 frames: pools by kind and flags, and the bytes bound or copied per frame by pool class since frame 1200. Also at frame 600. `mem: class` (once at start) says whether the GPU counts as uma or discrete and lists its heaps and types. - With `perf`, `mem: dirty` every 60 frames: what a VRAM mirror of the buffer-bound pools would upload (pages the CPU wrote per frame and per submit, eager and lazy, by pool class), FlushMappedRange calls and bytes, and the mirror size. The dirty count costs about 1.1 ms of CPU per frame on the submitting thread here (3 ms on an 8th-gen i7); `perf_summary.py` summarises it. - `TOTK_PROFILE= TOTK_PROFILE_FRAMES=lo-hi`: sampling profiler (`runtime/prof_win.c`), read with `tools/prof_report.py `. With `TOTK_PROFILE_RENDER=1` it samples the render thread only and keeps call chains: the report adds inclusive time per function and the exe callers of the driver and system DLLs. - `tools/regress.py --base build/v121-m4 [--routes fight,rock,island,field] [--repeat 3] [--cold] [--validation] [--out dir]`: runs the routes through `run_game.py --quiet`, scores logs and `TOTK_SHOTS` frames (`tools/regress_score.py`, tested by `tests/regress_score_test.py`) and prints median and worst per metric. Run the candidate alone and judge it against the targets: max fps, no slow frames (`perf: slow frame`), no black or flat frames, no new validation errors. `--base` (a diff with `ok`, `better`, `worse`) only when a question needs a side-by-side; do not rerun a base build by habit. Glitches are found by looking at the shots and dumps, not by the diff. `--cold` empties only the pipeline cache. Each route writes `//-worst.png` (the 6 worst frames) and `route_failed` marks a run that ended in game over, crashed or stopped early: its numbers do not count. One run takes 2 to 4 minutes. - Baselines (Ryzen 9 7900X, RX 9070, 1600x900, 60 fps patches and real-time step on, 2026-10-23): - field: 59.4 fps mean, 60 median, replay 9.5 ms per frame; - `fight.txt`: 59.1 fps mean, 60 median, replay 13.6 ms, 0 CPU-side slow frames; the slow frames left are pipeline and shader-translation waits. - `--validation` runs work in the world (1800 frames checked). The layer prints each message kind 10 times, so it gives no totals; the known messages left are in the backlog correctness queue, item 8. ## Frame dumps `TOTK_DUMP= TOTK_DUMP_DIR=build/captures/` writes per-pass PNGs, `passes.txt` and `images.txt` (`runtime/vk_dump.c`). `passes.txt` lists bound textures with swizzles, storage buffers with their c0 slots, and copies and clears. `TOTK_DUMP_BUF=addr:size[:off:stride:w:h]` dumps a guest buffer. - A draw's argument lines come before its pass header. - Pass numbers shift between runs. Find a pass by its draw count instead: the g-buffer pass has about 1990 draws. RenderDoc cannot capture: the driver hides `VK_EXT_external_memory_host`. ## Other GPUs The RX 9070 is the only GPU agents can run; the build also has to run on NVIDIA and older AMD (Vega, wave64 only). New Vulkan code queries the feature, extension, format or limit it uses and keeps a working path or a logged fallback when it is missing (`vk_pipeline.c` provoking vertex and subgroup size pinning are examples). Never hard-code what this GPU reports: alignments, subgroup size, depth formats, `maxPushDescriptors`. Numbers from this machine do not carry over. Measured on the user's other machines (2026-10-24/25, logs and analysis in `build/mem-plan.md`): - GTX 1050 Ti (4 GiB, 214 MiB BAR, no ReBAR; i7 8th-10th gen) and RTX 3090 Ti: GPU time 110-120 ms per frame in the world against 4.3 ms here, because the GPU reads imported host pools over PCIe. The VRAM mirror (cd6f490) brings the 1050 Ti to 10-11 ms; that machine is now CPU-bound at 25-45 fps (replay 25-30 ms per frame, backlog 0b). - The same write-watch scan costs about 3x the CPU time it costs here. - NVIDIA has no ASTC: first texture uploads decode on the CPU, 0.4-0.7 s load frames (backlog 5a.2). - `cannot alias its pool memory` fills its 16-line log limit on NVIDIA and on the RX 9070 alike (1920x1080, 1600x900, 800x450 render targets); a suspect for the black patches of backlog 0a (`build/alias-plan.md`). A run on another machine goes through the user: copy `build/release/TotK-perf-log.vbs` next to the `totk.exe` you hand over. It starts the game with `TOTK_TRACE=perf` and writes `logs\perf--