diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..13de2d69 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,16 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash|PowerShell", + "hooks": [ + { + "type": "command", + "shell": "bash", + "command": "grep -qiE \"taskkill[^|;&]*/IM[^|;&]*totk|Stop-Process[^|;&]*-Name[^|;&]*totk|pkill[^|;&]*totk|killall[^|;&]*totk\" && echo \"{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PreToolUse\\\",\\\"permissionDecision\\\":\\\"deny\\\",\\\"permissionDecisionReason\\\":\\\"Killing totk.exe by name stops other agents and benchmark runs. Stop only a totk.exe you started, by PID (taskkill //PID //F).\\\"}}\" || true" + } + ] + } + ] + } +} diff --git a/.claude/skills/private-build/SKILL.md b/.claude/skills/private-build/SKILL.md new file mode 100644 index 00000000..07aa7d4d --- /dev/null +++ b/.claude/skills/private-build/SKILL.md @@ -0,0 +1,55 @@ +--- +name: private-build +description: Fork a private build of the runtime to change and test it without touching runtime/ or other agents' builds, then hand back a diff. Use before editing runtime/ or tools/ code, building totk.exe, or cleaning up a finished build dir. +--- + +# Private build: fork, build, hand back, clean up + +Several agents change `runtime/` at once and the coordinator merges their diffs, so every change starts in a fork: +`build/v121-/`, where `` is a short name for your task. + +## 1. Fork + +Copy `runtime/` to `build/v121-/runtime-src` once and edit only there. For a `tools/` change, copy the file into +`build/v121-/` and run the copy. `generated/v121` and `recomp/` are shared: report a needed lifter change and leave +it unmade. + +## 2. Build + +``` +export PATH=/c/msys64/ucrt64/bin:$PATH && .venv/Scripts/python tools/build_game.py --runtime build/v121-/runtime-src --out build/v121- +``` + +The fork reuses `build/v121`'s generated objects: it hardlinks them into its `obj/` and compiles only `runtime/*.c`, so +a first build takes about 10 s. It does so when `build/v121` is up to date and every header the generated code includes +is byte-identical in your `runtime-src`. If you changed such a header (`cpu.h`, ...) or the main build is stale, it +prints `compiling all generated C: ` and rebuilds everything (about 200 s on every core). `--full-build` forces +that. A `.c` change is incremental either way. After every build check the exe's mtime: a failed build leaves the old +`totk.exe` in place, and you would test old code. + +Run the game with the `run-game` skill and the probes from the build dir: `totk.exe --probe-kernel`, `--probe-vkexec`, +`--probe-nvn-tex`, `--probe-shader` must pass before you hand back. + +## 3. Hand back + +A fix that costs frame time is not done: keep new work off per-draw and per-pixel paths unless the semantics need it, +and say in the report what the change costs per draw, shader or frame. The coordinator measures `fight.txt` with +`--quiet` before merging. + +A change on the render path also gets one look: a field `--shot` of your build next to one of `build/v121` at the same +frame. Runs diverge, so small differences prove nothing, but gross regressions show (grass gone, colours off, black +areas) and block the hand-back. + +Write `build/v121-/.diff` with `diff -u --strip-trailing-cr runtime/ build/v121-/runtime-src/` for +every changed file, against `runtime/` as it is just before you write it (others merge meanwhile). Keep LF line +endings. Read the diff's `-` lines: each must be a line you meant to change, not a merge you are reverting. + +Keep notes in `build/v121-/NOTES.md` as you go. When you stop unfinished, write `build/v121-/HANDOFF.md` +(under 80 lines): findings with paths, what is ruled out, the leading hypothesis, the exact next step, temporary debug +edits (file:line). + +## 4. Clean up + +After the coordinator merges the diff, or drops the task, the fork goes: copy `*.md`, `*.diff` and any helper scripts +to `build/archive/v121-/`, then delete `build/v121-/`. Forks of tasks waiting to be continued stay until +then. `build/v121` (the main build) and `build/v121-pf` (shared shader and pipeline caches) are never deleted. diff --git a/.claude/skills/run-game/SKILL.md b/.claude/skills/run-game/SKILL.md new file mode 100644 index 00000000..701a230e --- /dev/null +++ b/.claude/skills/run-game/SKILL.md @@ -0,0 +1,60 @@ +--- +name: run-game +description: 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 --save --frames N [--script tools/input/.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 `/logs/.log` and +prints `: rc=`. 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-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 + +- `--shot` builds pipelines synchronously: use it for pictures, never for timing. +- `--quiet` waits until no other `totk.exe` or `ninja.exe` runs. Use it for every timing you report. +- Input scripts: lines `