Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.8 KiB
name, description
| name | description |
|---|---|
| run-game | Run a TotK build into gameplay from a backed-up save. Use when you need the game in-world (screenshot, perf measurement, frame dump, scripted input) or need to pick a save scene. |
Run a build into gameplay
One command loads a save and plays scripted input; it never writes the user's profile (build/profile):
.venv/Scripts/python tools/run_game.py <build dir> --save <backup> --frames N [--script tools/input/<f>.txt] [--shot out.png] [--env K=V] [--quiet] [--tag name]
It copies the profile, swaps in the save from build/save-backup/, writes the log to <build dir>/logs/<tag>.log and
prints <log>: rc=<code>. The game window opens behind the user's windows without taking focus.
Saves
--save |
Scene after load_save.txt (gameplay from about frame 1500) |
|---|---|
user-save-2026-10-21-field |
Hyrule field, Link in tall grass |
user-save-2026-10-21-monsters |
Moblins and Zonai constructs attack at once; use with --script tools/input/fight.txt |
user-save-2026-10-21 |
Hyrule field facing the castle, rainy; distant sky over the castle |
user-save-2026-10-23-pillars |
Hyrule field by standing stone pillars, about 17:40, a Zonai construct beside Link; use with --script tools/input/backrun.txt (runs backward from 1550: phantom rocks, a one-frame glitch at about 1605) |
user-save-2026-10-24-brightbloom |
Cave, about 20:40: a Brightbloom plant at the lower left (its bulb floats beside the stem, build/v121-bloom/NOTES.md), teal Moblin and Bokoblin ahead or Zonai constructs (runs differ) |
user-save-2026-10-22-island |
Sky island edge; use with --script tools/input/island.txt (runs off, skydives, opens the paraglider with B at frame 1975; X does nothing in a dive) |
--frames counts presents. Pick 1500 + the frames you need in-world.
At most 3 runs go at once across all agents (TOTK_MAX_RUNS, lock files in build/run-slots/): more exhaust device
memory. run_game.py waits for a free slot, so start every game run through it; probes (--probe-*) run directly.
Options that change results
--shotbuilds pipelines synchronously: use it for pictures, never for timing.--quietwaits until no othertotk.exeorninja.exeruns. Use it for every timing you report.- Input scripts: lines
<frame> <button> [hold]or<frame> LSTICK|RSTICK x y [hold], names indocs/controls.md. A new script starts with the four A presses oftools/input/load_save.txt. The Purah Pad map opens with<frame> MINUS 4.
Recordings of the user's play
TOTK_INPUT_RECORD=<absolute path> writes the merged input as script lines; TOTK_SHOTS=lo-hi:step with
TOTK_SHOTS_DIR=<absolute path> saves 480x270 frames. The user's sessions live in build/recordings/ (<name>.txt +
<name>-shots/). Replay one with --script build/recordings/<name>.txt; runs can diverge (weather, positions), so check
the shots of your replay before relying on it.
Flight recorder
TOTK_FLIGHT=1 keeps the last 600 frames (TOTK_FLIGHT_FRAMES): interval, render-thread blocked time, event counts
and a 320x180 thumbnail each. F8 in the game window, a frame over TOTK_FLIGHT_SPIKE_MS (100; one dump per 10 s) or
TOTK_FLIGHT_AT=<frame>,... writes build/flight/<time>-f<frame>/ (frames.tsv, f<frame>.png) 30 frames later;
the log line flight: dump <dir> names it. python tools/flight_view.py <dir> lists the frames around the worst
interval and the counts that stand out, and writes contact.png. Costs 132 MB of host memory for the thumbnails.
Running totk.exe yourself
Set TOTK_ASSUME_FOCUS=1 (an unfocused window stalls the game), TOTK_INPUT=none and TOTK_BACKGROUND_WINDOW=1.
Other agents run the game at the same time: stop only a totk.exe you started, by PID.
Measuring, frame dumps and debugging: docs/agent-playbook.md.