[klimovich008]

Testing a change in the game means a new full build: a new work folder translates the game again, and a new game folder prepares every shader from cold, 69 minutes in all on an RX 9070 XT. Most of that is the same for every change. This adds a development tool that builds the game once as a base and each change as a small pack over it.

What changed

• scripts/dev_packs.py (new, development only):
  • base builds a checkout at a commit. --seed copies an older game folder's shader caches first, as an update keeps them.
  • pack builds a change. Commits, uncommitted edits and untracked files all count.
    • Renderer alone (RX_VK_ONLY, seconds): when every changed file is a renderer file the game isn't built from. Those files are found in the checkout from host/'s includes and build.py's dependencies.
    • Otherwise make_game.py, which builds both modules.
  • What a pack keeps:
    • A module when an object in its link list (objs.rsp, vk_objs.rsp) differs from the base's. Bytes can't decide this: nx2/version.py puts a fingerprint of every source into both modules.
    • Both modules when a build script, a non-translator data file under nx2/, or a non-C file changed.
    • Generated files that differ, such as the shader seed and the prompts. Files the base's own build made that the change no longer makes are removed.
  • rt makes a runtime: the base with romfs hard-linked and the other files copied, the packs' files over them. It runs a prepare when the shader translator or the seed changed. Two packs that bring the same file are refused, and so is a pack built on another base.
• docs/development.md: a new section, Testing a change against a base.
• AGENTS.md: one bullet pointing agents to it.
• Nothing players build changes. It calls make_game.py and build.py as they are; no build or CI file is touched.

Testing

• tests/test_dev_packs.py (no game):

  • the build route, and the renderer files the game reads;
  • that the translator list matches build.py's stamp, and that the version-stamped objects are build.py's;
  • that link-only inputs keep both modules;
  • the lift key's dependence on the folders;
  • generated files that change or are removed, and a clean output folder;
  • a runtime from packs, and every refusal by its own reason.
  • Negative controls: every rule above has a sabotaged variant of the script that fails the test.

• Ten review rounds with gpt-6.1-sol, every finding fixed; the last found none.

• End to end on Windows (Ryzen 7 5700X3D, RX 9070 XT), packs over a full build of 57ed3aa:

  Pack	Changed	Kept	Time
  host only	host/nvn_native.c	hookshot.exe	14 min first (one translation), 48 s later
  host + renderer	host/nvdrv.c, vk_memory.cpp	both	34 s
  renderer only	vk_replay.cpp	hookshot_vk.dll	16 s first, 2 s later
  runtime of two packs		exe from one, DLL from the other	3 min 51 s

  Each pack's modules are byte-identical to that change's own earlier full build, apart from 2 PE header bytes. The renderer-only route gives the same DLL as make_game.py for the same tree.

• Seeded base on main 4678050 from 57ed3aa's caches:

  • 52.6 min, against 69 min for 57ed3aa cold.
  • Shader programs: 290 s against 822 s. main changed the translator, so the program cache was rebuilt, but the driver's pipeline cache carried over.
  • Precompile: 258 s against 602 s.
  • Predicted pipelines: 1,790 s against 2,150 s.

• In the game: a runtime made by rt from two packs over 57ed3aa (the host-only pack's exe, with its new switches off, and the renderer-only pack's DLL):

  • The run: the standard Hyrule scene (32:9, unlocked frame rate, camera turning), 3 runs, RX 9070 XT, Windows 11.
  • Result: the game started and played the scene every time, at 40.4–41.9 fps. 57ed3aa's own runtime measured 39.8 fps on the same test that morning.
  • Not a measurement: n=1 after two warm-ups, and the game clock dipped to 0.94–0.98 in these runs, as it did in the base's own runs that day.
  • No tested-configurations row: this was a development runtime with unmerged changes, not a player build.

• Not tested: Linux. The module names there are hookshot and hookshot_vk.so, and RX_TARGET=windows uses the Windows names; neither pack nor rt has run there.

Related: the dev-loop proposal (#2636). This covers part of its "middle loop" without changing the build.

🤖 Generated with Claude Code

[klimovich008]

Thanks, all three are done in c3f666f:

1. Never leaves the PC. Testing a change against a base now says it plainly: a base, a pack and a runtime are built from the game (the pack's modules have the lifted game linked in, its files are generated from it, a runtime is a whole game folder), so they are never attached, uploaded or sent to a tester or the chat; what you share is the branch, and the tester builds their own. It links CONTRIBUTING.md's rule. The AGENTS.md bullet says the same in its last sentence.
2. rt and pack.json. Before anything is made, rt now refuses a pack whose files names anything but the two modules, and any generated or deleted path that is absolute or resolves (realpath) outside the runtime. test_guards has four refusal cases: an absolute path, ../x, romfs/../../x, and a module key ../x. Each checks that nothing was made and that the file outside is untouched.
3. AGENTS.md is down to three lines: the pointer, one shared base agreed before moving, development and A/B only, never send them.

The Linux line stays in the description.

[klimovich008]

Extra hardening of point 2 in ac5af7b and 1307585: rt now judges a pack path by its text first (no .., not rooted, no : stream names), then re-checks each destination where it is written, once the runtime exists, by file identity through links, so a link cloned from the base's romfs can't lead a write or delete outside the runtime; tests cover each case.

[Joey-Magnus]

I merged 1307585 into current main and ran tests/test_dev_packs.py, which passes. The two red jobs are not from this PR. One is test_release_scripts.py (test_nightly_two_runs_at_once_end_at_the_newer_commit), which is flaky. The other is test_pipeline_cache_save.py on Windows part 1, a timing wait on the in-play save. This PR only adds scripts/dev_packs.py, its test and docs, so a re-run should clear both.

hckrman101's points are all addressed. Docs and AGENTS.md now say plainly that bases, packs and runtimes never leave the PC. rt refuses absolute paths, .. paths and module keys other than the two modules, and re-checks each destination by file identity, and test_guards has a refusal case for each. The AGENTS.md bullet is down to three lines. I also read clear_output and the pack rmtree: both only work inside the dev folder, and the pack name is validated before the delete.

The one gap is Linux (hookshot/hookshot_vk.so), which the description already states. That's fine for a development tool.