WIP: feat(mods): the Modding API: TypeScript mods the game compiles and sandboxes, system mods, a Mods tab, hot reload, custom actors and in-game tests #1958

Draft
HumanBean wants to merge 589 commits from mod-api into main
Owner

Summary

Longshot gets a Modding API: mods written in TypeScript that change and add to the game, loaded and checked by the game
itself, with a permission prompt, a sandbox and a Mods tab to switch them. Until now a mod could only replace game files
(RomFS and ExeFS); with this, a mod can read and change the game as it runs, add content, and talk to other mods.

What a player gets:

  • The Mods tab (Insert menu): the list of mods; each opens its own page with its switch, its permissions and its
    settings. Safe start runs the game with only the built-in mods.
  • Built-in (system) mods that ship with the game: the mod inspector, full screen with the input while open (cards for
    the mods' time, faults and heap; the mods' table beside the chosen mod's graph, numbers, slow frame and log), and the
    Discord status. The engine has no Discord code: all of it is the system/discord mod over a generic longshot/ipc.
  • Hot reload, on by default: a mod added, changed or removed (by the launcher or by hand) while the game runs is
    started, reloaded or stopped without a restart.
  • Skip title screen hooked into the game: it presses A as each screen (the title, the file list, the load check)
    waits for a button, instead of on a timer; in play about 11 s after the first controller read on this PC.

What a mod author gets:

  • TypeScript 7 with no build step: the game compiles a mod's src/ itself (oxc, linked in, cached in
    modcache/js); longshot-mod check type-checks, pack packs src/, types writes a library's mod.d.ts.
  • The API (longshot/*): game state and flags, items and grants, rules (damage, actor life, rewards), actors (list,
    writes, events, bomb light), camera, input (filters, replays), audio, UI (HUD, windows), world shapes and effects, text,
    storage, settings, content (new actors, items, text, flags), calls between mods and to system mods (caller() says
    who), and native C/C++ mods built with the game (unsafe, marked as such).
  • Custom actors: copy an actor and change its components with types (longshot-mod types --game), attach scripted
    components (longshot/behaviour), copy and edit behaviour trees (values and links).
  • Spawning: actors.spawn/remove, over the game's own create path taken from #68 by mooki (credited; refused in a
    co-op room until #68 lands, then a shared-world event).
  • Attaching and answers: actors.attach binds an actor to another's bone through the game's ModelBind;
    actors.answer answers three of the trees' queries (isDead, isThrown, isPutAway) for chosen actors.
  • Tree nodes: content.tree adds nodes (a sequence, a command's behaviour) to a copied tree, checked against a
    schema built from the player's own game in modcache/; the tree writer was checked byte-exact on all 11,707 of the
    game's trees, locally.
  • Skins, models and animations: content.actor's skin swaps a copied model's textures for the mod's PNGs (made
    into the game's textures on the player's PC, with bc7enc, MIT, vendored); content.model checks a model a mod brings;
    a mod's clips join an actor's animations (longshot-mod anim from glTF, skeleton --game to rig against). No game
    data ships with a mod: models are copied from the player's game when the mod loads.
  • What a randomizer needs: content.read.placements (a map's placements, read from the player's game),
    content.change, rules.rewards (what events give), rules.skips (cutscenes by name), world.states,
    world.destinations/travel, player.setAge, dungeon items in items.*. The randomizer itself is its own PR on top
    of this one, #1959.
  • Windows and labels: a fullscreen Window (the whole screen under the game's title bar, never dragged or
    resized), and <World occlude="depth">: a label drawn in the scene by the world layer, each pixel tested against the
    game's depth, so a wall or a pillar cuts it at its edge (one 2048 x 1024 atlas of 64 labels, made with the first such
    label and let go after the last).
  • In-game tests: --mod-tests <folder> runs a mod's own tests in the real game (the same files as the fake game);
    dev.py game-tests runs tests/game-features/, headless unless --window.

This branch also carries snaildev99's ExeFS-patch and code-module work from #961, #984, #1036 and #1089 (their commits,
their authorship), which the API builds on; if snaildev99 agrees, this PR supersedes those four.

Read first: docs/modding/README.md and api-guide.md (for authors), docs/user/ "Using mods" (for players),
docs/dev/reference/mods.md and actors.md (for contributors); code: host/modapi/loader.c (start and the frame's
order), runtime.c (modules, budgets), perms.c, host/broker.c (the sandbox), modapi/schema/ (the API's source
of truth, generated into the C bindings, longshot.d.ts and the reference).

Overlaps: #1577 (dyst, a test switch that boots straight into a save) and #659 (NitnekLeBorgne, cancels the title
presses when the player takes over; also edits host/oot_autoload.c).

Testing

Tested: Linux (CachyOS, kernel 7.3.3), NVIDIA GeForce RTX 3090, driver 620.70.06, on the branch before its rebase
onto main: the in-game feature suite (dev.py game-tests, the kokiri-start save) in three runs.

  • The joined branch: 22 passed, 4 failed (teleport events, Link's life write, an item grant given every frame, the
    wallet's size), 40 skipped (fake-game-only, or a route of their own). All four fixed since; the grant one was a real
    bug (a bag given 428 times).
  • With spawn, attach and answers: a crash at the first frame from a use-after-free in the loader with more than 16 mods
    (fixed, with a test that crashed the same way); then 25 passed, 4 failed (the new feature mods' flags undeclared, and
    Link's life read back a frame early), both fixed since with game-free tests. Its next run (2026-11-20, a426bf10): 28
    passed, 1 failed (attach: the pot broke inside Link; the test now binds a Deku stick and keeps the pot 0.6 m clear,
    not run since). Seen in that run: spawn (an Octorok made in about 284 ms), Link's life written, answers reaching the
    trees, a ModelBind made.
  • The randomizer (#1959) on this API, headless (2026-11-21, a test seed): 77 of OoTR's 315 drops bound, a beatable seed,
    57 rewards set, 22 starting items; a seed in game mode failed before its fix (a partly bound dungeon's keys).
  • Seen working in the game: the title skip (each screen pressed about 0.3 s after it waited), Discord as a system mod
    from src/main.ts, actors, audio, camera, content, timers, input replay, rules, storage, HUD and windows, text,
    teleport. The game-free suite (run_all.py --strict) on the branch: every failure is one main has.

Still to test:

  • Linux, NVIDIA, this PR's head (rebased): dev.py game-tests --window, expecting the 4 fixes to hold and spawn's,
    attach's and the answers' game tests to pass or skip with a reason (by hand)
  • Linux, this PR's head: the Mods tab (switch, permissions, settings), Safe start, the inspector full screen (its
    frame, the mouse and the controller on it, Esc and B), hot reload of a mod added while the game runs (by hand)
  • Linux, this PR's head: skins, models and animations (tests/game-features/assets, red-cucco, puffed-cucco), new tree
    nodes (trees), placements; enemy-names with occlude="depth" in Kokiri Forest and at the Deku Tree, on the game's
    upscale and on DLSS (a label cut at a trunk's edge, no fringe, no stray picture) (by hand)
  • Windows, NVIDIA and AMD: the game starts with no mods and with the examples; the sandbox (AppContainer) and the broker
    (@Beanstalk start the game with no mods and with modapi/examples, check the log for the sandbox and mods lines)
  • Steam Deck: a start with mods, the Mods tab with a controller (@Beanstalk)
  • The launcher's side is its own PR (mods/launcher-pr on LongshotLauncher)

Measurements

TODO before ready: main against this PR with no mods (gate 5: a game with no mod pays nothing), fps and frame time in
the standard areas, two interleaved runs each; and the game's build time against main (the TypeScript compiler library
is linked in).

Risks

  • A game with no mod of the player's pays nothing for the API (gate 5, to be shown in Measurements), apart from two things it always has: the Discord system mod's runtime, and one idle lsmod-watch thread for hot reload (asleep, at most 0.1 s of CPU and 64 switches in a run; scripts/parity_gates.py checks it).
  • A mod runs sandboxed (Landlock and seccomp on Linux, AppContainer on Windows) with only the permissions the player
    granted; native mods are not sandboxed and are marked unsafe in the Mods tab.
  • Hot reload watches the mods folder (HOS_MODS_WATCH=0 turns it off). Safe start, or removing the mod, undoes any mod.
  • After updating: longshot_options.ini gains the Mods tab's rows; the Discord status's old switch is read once and
    carried into mods.json; modcache/ is new.
  • Size: the TypeScript compiler (oxc 0.157.0, vendored with its licences in third_party/oxc) adds about 4.5 MB.

Checklist

Ready for review

  • One topic, on current main; the title is a Conventional Commit. (One topic as the user asked: the Modding API, as one PR.)
  • Tested on my own PC, in the game for a change the game runs, as Testing says. (Before the rebase; the head still to run.)
  • mise run test passes (any failure that also fails on main is named). (Suite on the rebased head running.)
  • Measured against main, or Measurements says why there is nothing to measure. (TODO.)
  • No game files, build output or hand-edited generated files; third_party/ untouched; nothing GPL-incompatible. (third_party/oxc and third_party/oxc-runtime are added, all permissive and GPL-3-compatible, listed in PROVENANCE: to be checked in review.)

When it applies

  • A fix: a game-free test that fails on main and passes here.
  • A check under tests/ that reads changed source is updated, not weakened.
  • MKWVK_API_VERSION bumped (MkwVkHost or MkwVkRenderer in gpu/vk/vk_api.h changed). (42, on main's 41.)
  • Host code builds on Windows (llvm-mingw) and Linux, with UTF-8 paths. (Linux built; Windows not yet.)
  • Screenshots of the same spot on main and here, for a change that shows on screen. (The Mods tab and the inspector: TODO.)
  • Docs updated. (A docs pass against the code is next.)
  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.

Ready to merge

  • Everything in Still to test has run, its results in Tested.
  • Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers").
  • Approved in review, every comment answered.
  • CI passes on the head; on current main, measured again or a comment says why the numbers still hold.

🤖 Generated with Claude Code

https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt

## Summary Longshot gets a Modding API: mods written in TypeScript that change and add to the game, loaded and checked by the game itself, with a permission prompt, a sandbox and a Mods tab to switch them. Until now a mod could only replace game files (RomFS and ExeFS); with this, a mod can read and change the game as it runs, add content, and talk to other mods. What a player gets: - **The Mods tab** (Insert menu): the list of mods; each opens its own page with its switch, its permissions and its settings. Safe start runs the game with only the built-in mods. - **Built-in (system) mods** that ship with the game: the mod inspector, full screen with the input while open (cards for the mods' time, faults and heap; the mods' table beside the chosen mod's graph, numbers, slow frame and log), and the Discord status. The engine has no Discord code: all of it is the `system/discord` mod over a generic `longshot/ipc`. - **Hot reload, on by default**: a mod added, changed or removed (by the launcher or by hand) while the game runs is started, reloaded or stopped without a restart. - **Skip title screen hooked into the game**: it presses A as each screen (the title, the file list, the load check) waits for a button, instead of on a timer; in play about 11 s after the first controller read on this PC. What a mod author gets: - **TypeScript 7 with no build step**: the game compiles a mod's `src/` itself (oxc, linked in, cached in `modcache/js`); `longshot-mod check` type-checks, `pack` packs `src/`, `types` writes a library's `mod.d.ts`. - **The API** (`longshot/*`): game state and flags, items and grants, rules (damage, actor life, rewards), actors (list, writes, events, bomb light), camera, input (filters, replays), audio, UI (HUD, windows), world shapes and effects, text, storage, settings, content (new actors, items, text, flags), calls between mods and to system mods (`caller()` says who), and native C/C++ mods built with the game (unsafe, marked as such). - **Custom actors**: copy an actor and change its components with types (`longshot-mod types --game`), attach scripted components (`longshot/behaviour`), copy and edit behaviour trees (values and links). - **Spawning**: `actors.spawn`/`remove`, over the game's own create path taken from #68 by mooki (credited; refused in a co-op room until #68 lands, then a shared-world event). - **Attaching and answers**: `actors.attach` binds an actor to another's bone through the game's ModelBind; `actors.answer` answers three of the trees' queries (isDead, isThrown, isPutAway) for chosen actors. - **Tree nodes**: `content.tree` adds nodes (a sequence, a command's behaviour) to a copied tree, checked against a schema built from the player's own game in `modcache/`; the tree writer was checked byte-exact on all 11,707 of the game's trees, locally. - **Skins, models and animations**: `content.actor`'s `skin` swaps a copied model's textures for the mod's PNGs (made into the game's textures on the player's PC, with bc7enc, MIT, vendored); `content.model` checks a model a mod brings; a mod's clips join an actor's animations (`longshot-mod anim` from glTF, `skeleton --game` to rig against). No game data ships with a mod: models are copied from the player's game when the mod loads. - **What a randomizer needs**: `content.read.placements` (a map's placements, read from the player's game), `content.change`, `rules.rewards` (what events give), `rules.skips` (cutscenes by name), `world.states`, `world.destinations`/`travel`, `player.setAge`, dungeon items in `items.*`. The randomizer itself is its own PR on top of this one, #1959. - **Windows and labels**: a `fullscreen` Window (the whole screen under the game's title bar, never dragged or resized), and `<World occlude="depth">`: a label drawn in the scene by the world layer, each pixel tested against the game's depth, so a wall or a pillar cuts it at its edge (one 2048 x 1024 atlas of 64 labels, made with the first such label and let go after the last). - **In-game tests**: `--mod-tests <folder>` runs a mod's own tests in the real game (the same files as the fake game); `dev.py game-tests` runs `tests/game-features/`, headless unless `--window`. This branch also carries snaildev99's ExeFS-patch and code-module work from #961, #984, #1036 and #1089 (their commits, their authorship), which the API builds on; if snaildev99 agrees, this PR supersedes those four. Read first: `docs/modding/README.md` and `api-guide.md` (for authors), `docs/user/` "Using mods" (for players), `docs/dev/reference/mods.md` and `actors.md` (for contributors); code: `host/modapi/loader.c` (start and the frame's order), `runtime.c` (modules, budgets), `perms.c`, `host/broker.c` (the sandbox), `modapi/schema/` (the API's source of truth, generated into the C bindings, `longshot.d.ts` and the reference). Overlaps: #1577 (dyst, a test switch that boots straight into a save) and #659 (NitnekLeBorgne, cancels the title presses when the player takes over; also edits `host/oot_autoload.c`). ## Testing **Tested:** Linux (CachyOS, kernel 7.3.3), NVIDIA GeForce RTX 3090, driver 620.70.06, on the branch before its rebase onto main: the in-game feature suite (`dev.py game-tests`, the kokiri-start save) in three runs. - The joined branch: 22 passed, 4 failed (teleport events, Link's life write, an item grant given every frame, the wallet's size), 40 skipped (fake-game-only, or a route of their own). All four fixed since; the grant one was a real bug (a bag given 428 times). - With spawn, attach and answers: a crash at the first frame from a use-after-free in the loader with more than 16 mods (fixed, with a test that crashed the same way); then 25 passed, 4 failed (the new feature mods' flags undeclared, and Link's life read back a frame early), both fixed since with game-free tests. Its next run (2026-11-20, a426bf10): 28 passed, 1 failed (attach: the pot broke inside Link; the test now binds a Deku stick and keeps the pot 0.6 m clear, not run since). Seen in that run: spawn (an Octorok made in about 284 ms), Link's life written, answers reaching the trees, a ModelBind made. - The randomizer (#1959) on this API, headless (2026-11-21, a test seed): 77 of OoTR's 315 drops bound, a beatable seed, 57 rewards set, 22 starting items; a seed in game mode failed before its fix (a partly bound dungeon's keys). - Seen working in the game: the title skip (each screen pressed about 0.3 s after it waited), Discord as a system mod from `src/main.ts`, actors, audio, camera, content, timers, input replay, rules, storage, HUD and windows, text, teleport. The game-free suite (`run_all.py --strict`) on the branch: every failure is one main has. **Still to test:** - Linux, NVIDIA, this PR's head (rebased): `dev.py game-tests --window`, expecting the 4 fixes to hold and spawn's, attach's and the answers' game tests to pass or skip with a reason (by hand) - Linux, this PR's head: the Mods tab (switch, permissions, settings), Safe start, the inspector full screen (its frame, the mouse and the controller on it, Esc and B), hot reload of a mod added while the game runs (by hand) - Linux, this PR's head: skins, models and animations (tests/game-features/assets, red-cucco, puffed-cucco), new tree nodes (trees), placements; enemy-names with `occlude="depth"` in Kokiri Forest and at the Deku Tree, on the game's upscale and on DLSS (a label cut at a trunk's edge, no fringe, no stray picture) (by hand) - Windows, NVIDIA and AMD: the game starts with no mods and with the examples; the sandbox (AppContainer) and the broker (@Beanstalk start the game with no mods and with modapi/examples, check the log for the sandbox and mods lines) - Steam Deck: a start with mods, the Mods tab with a controller (@Beanstalk) - The launcher's side is its own PR (mods/launcher-pr on LongshotLauncher) ## Measurements TODO before ready: main against this PR with no mods (gate 5: a game with no mod pays nothing), fps and frame time in the standard areas, two interleaved runs each; and the game's build time against main (the TypeScript compiler library is linked in). ## Risks - A game with no mod of the player's pays nothing for the API (gate 5, to be shown in Measurements), apart from two things it always has: the Discord system mod's runtime, and one idle `lsmod-watch` thread for hot reload (asleep, at most 0.1 s of CPU and 64 switches in a run; `scripts/parity_gates.py` checks it). - A mod runs sandboxed (Landlock and seccomp on Linux, AppContainer on Windows) with only the permissions the player granted; native mods are not sandboxed and are marked unsafe in the Mods tab. - Hot reload watches the mods folder (`HOS_MODS_WATCH=0` turns it off). Safe start, or removing the mod, undoes any mod. - After updating: `longshot_options.ini` gains the Mods tab's rows; the Discord status's old switch is read once and carried into `mods.json`; `modcache/` is new. - Size: the TypeScript compiler (oxc 0.157.0, vendored with its licences in `third_party/oxc`) adds about 4.5 MB. ## Checklist ### Ready for review - [ ] One topic, on current `main`; the title is a Conventional Commit. (One topic as the user asked: the Modding API, as one PR.) - [ ] Tested on my own PC, in the game for a change the game runs, as Testing says. (Before the rebase; the head still to run.) - [ ] `mise run test` passes (any failure that also fails on `main` is named). (Suite on the rebased head running.) - [ ] Measured against `main`, or Measurements says why there is nothing to measure. (TODO.) - [ ] No game files, build output or hand-edited generated files; `third_party/` untouched; nothing GPL-incompatible. (`third_party/oxc` and `third_party/oxc-runtime` are added, all permissive and GPL-3-compatible, listed in PROVENANCE: to be checked in review.) ### When it applies - [ ] A fix: a game-free test that fails on `main` and passes here. - [x] A check under `tests/` that reads changed source is updated, not weakened. - [x] `MKWVK_API_VERSION` bumped (`MkwVkHost` or `MkwVkRenderer` in `gpu/vk/vk_api.h` changed). (42, on main's 41.) - [ ] Host code builds on Windows (llvm-mingw) and Linux, with UTF-8 paths. (Linux built; Windows not yet.) - [ ] Screenshots of the same spot on `main` and here, for a change that shows on screen. (The Mods tab and the inspector: TODO.) - [ ] Docs updated. (A docs pass against the code is next.) - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. ### Ready to merge - [ ] Everything in Still to test has run, its results in Tested. - [ ] Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers"). - [ ] Approved in review, every comment answered. - [ ] CI passes on the head; on current `main`, measured again or a comment says why the numbers still hold. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The lift makes BL a C call and RET a C return; a B to code that is no
function start becomes a goto. A mod's hook is often `bl hook` written over
one of the game's instructions, going back with `b <the call's next
instruction>` because its own calls have used up x30. On the console that B
is a return; translated, the hook's C function runs the rest of its caller
inside the call and then returns into the caller, which runs that rest again
with its frame gone (Character Select v0.1.2 crashed so, two calls up).

collect() now writes such a B as RET (make_returns, hooked_returns) when the
hook's routine (what is reached from the call's target, up to its returns and
up to the call's next instruction) was all written by the patches and is
entered from that one call alone: no other direct branch or call into it, no
instruction above it falling in, no unwind start, function symbol,
relocated pointer or ADR / ADRP+ADD address in it. Then the B goes exactly
where a return goes, whatever x30 holds. Otherwise the B stays and the file's
note says why it may not run as on the console (entered from elsewhere too,
it runs the game's own code, or the way back is conditional).

BlueShell rewrites every patched B to a patched BL's next instruction
(nx2/exefs_mods.py there); that also catches a routine entered with B that
goes back there, whose B is right as it is. The test has that case.

On the game's code, offline: Character Select v0.1.2's patch gets its two
B's back to main+C15C60 made returns (the hook's lifted walk: 30
instructions, before 78 that ran on into the caller); v0.2.1's, whose call
is a B since, is untouched. The check costs about 2 s when a mod has such a
hook and nothing otherwise.

apply() closes the JSON it reads.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
#134's test of the build's entry runs collect() with a fake Main, so that no game code is needed. The returns'
pass reads that Main's image; the test stubs make_returns too (no hooks there) and puts it back after.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The review of #960 (suggestion 1): Main.starts held the unwind starts, function
symbols and RELATIVE addends, but nx_image._entries also seeds ABS64-relocated
values and DT_INIT/DT_FINI. A hook routine one of those reaches is now left as
it is, with the "entered from elsewhere too" note.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Where two patch files write the same byte, the one lower in the list won,
and nobody was told. collect() now names every such place (overlaps): in the
build's log, and in both files' notes in exefs_patches.txt ("120 of its bytes
are taken by HUD lower in the list (main+...)" / "... written differently by
Characters higher in the list; this one's are used"), where the Mods tab can
show it.

The lower file now also wins where it writes the game's own byte back over a
higher file's change. Main.classify leaves out the bytes a file writes that
equal the game's, so such a byte was not applied and the higher file's byte
stayed: a mix of two mods' code that neither wrote. Those bytes are put back
into the lower file's writes, and a file that was "empty" (every byte the
game's) becomes code or data when it puts bytes back.

Modelled on a real case: two HUD mods put a stub inside the range a
character mod's patch writes. parse_file() is classify_file()'s parse, shared.

apply() closes the JSON it reads.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
exefs_patches.txt has a note for each patch file; the Mods tab showed it only
for a file that cannot be applied. It now also shows the first note of a file
built into the game (two mods writing one place, bytes left out of a
relocated word), as "ExeFS: <note>.". kind_note() reads the note for both and
drops a trailing \r (a list saved with Windows line ends).

tests/test_mods_sizes.py: a built file's note on the Mods tab.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The notes named a run of differing bytes as a place, so one stub came out as
three places where a byte in it happened to be the same in both mods. A run
now goes on over up to 3 bytes written alike (within an instruction): the
Rupee Counter's stub against Character Select's patch reads main+3C46740-3C46773
where it read three places.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The overlaps test now gives collect() its order in mods.json, the list the game and the build read, instead of
longshot_mods.txt, which is only read once to carry an older list over.

#134's test of the build's entry fakes Main and classify_file, so that no game code is needed. The overlaps pass
reads each applied file's bytes again with parse_file, which then asked the fake Main for a build id; the test
stubs parse_file too (no bytes written: no overlaps) and puts it back after.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The review of #961 (suggestion 2): exefs_said held 160 bytes of the first built
file's note, and the clash text came after the relocated-word note (and, with
#960, after the returns' notes), so it was the part cut. overlaps() now puts a
file's clash notes ahead of its other notes, and exefs_said is sized like the
tab's note line.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game loads each file inside an actor pack (Pack/Actor/x.pack.zs, a SARC
archive) as a resource of its own, in a heap sized by that file's own entry
in the resource size table, and the stock entries fit to the byte. The merge
sized loose files only (restbl.c said the packs are sized as a whole, which
is not so for this game: nearly every member has its own entry). A mod that
grows a file inside a pack and ships no table, or a stale one, kept the
game's entry: the file loads, the heap runs out for what is parsed out of
it, a loading thread fails on a null object and the game waits at a loading
screen for ever.

restbl.c gets restbl_sarc_each and restbl_pack_raise, after
valentderah/totk-pc-recomp runtime/restbl.c (MIT, the notice is in
restbl.h): a member that grew against the game's copy of the pack is raised
by restbl_grow, a member the game's copy lacks gets restbl_estimate, the
others are left alone. host/mods.c's fit_sizes calls it (pack_members) for
every pack a mod serves, reading both packs with host/zs.c, which already
decodes frames made with the game's dictionaries. A pack that cannot be read
is named in the log and its members keep their entries; the summary line
counts the members and packs raised, and up to 16 lines name them.

Measured on this game's own files (a local harness, nothing committed): the
nine packs of a character mod that grows the player's parameter files take
15 ms and raise 21 entries, among them the two whose growth once hung a
loading screen; 200 stock packs served unchanged take about 40 ms and raise
none.

tests/test_mods_packs.py checks restbl_pack_raise on made-up packs (grown,
equal, smaller, streamed, .zs and new members, a new pack, an entry already
larger, unreadable archives) and host/mods.c over a made-up game folder whose
packs use a trained dictionary as the game's do. It fails on the base (no
restbl_pack_raise; with it, the grown member keeps the game's entry) and
passes here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A run in the game crashed with the previous commit: a character mod whose
own size table was set back to the game's entries for the files inside its
packs (the case this branch is for) loaded the adult player's pack and its
loading thread failed on a null object, the heap of the player's
ControllerSetParam run out. That file had grown from 15,256 to 56,116 bytes
by 555 cloth reactions and options; growth in proportion gave 125,664.

What a BYML parameter file adds is mostly list elements, which the game
builds into objects that cost far more than their bytes. Least squares over
the game's own files: ControllerSetParam (5,602 files) 6,619 + 1.04 a byte +
60 to 180 an element of each list, at most 319 off; ClothParam (170 files)
4,653 + 1.90 a byte + 289 a mesh + 31 a collision shape, at most 784 off. For
the crashed file the fit asks about 178,600 (3.5 a byte grown). restbl_grow
now gives a grown .bgyml or .byml file at least 8 entry bytes for each byte it
grew, plus 4 KiB: twice the fits' need for such growth, and the rule the
character mod's own builder uses, whose entries for these files load in the
game (365,136 for the crashed file; the new rule gives 365,152). Other types
(.ainb and the physics binaries, about 1 a byte in the game's table) keep
the proportion. This applies to loose BYML files that grow too; it only
ever raises an entry.

The merge's log line now gives its time in parts (the mods' tables, the
files, the packs among them, writing): a start with the 1 GB character mod
took 7 to 9 s in the game where a harness over the same folder takes 250 ms
(tables 53, files 195 of which packs 10), and the next run should say which
part the game's seconds are.

tests/test_mods_packs.py adds a member of the crashed file's shape (made-up
sizes) that must get at least 8 a byte grown plus 4 KiB and more than twice
the proportion, and an .ainb member that keeps the proportion; it fails with
the previous commit's restbl.c and passes here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c now reads and writes its list through host/mods_list.c and asks host/options_path.c where the
settings file is. The test's host/mods.c fixture compiles mods_list.c with it, answers hos_options_file with
no settings file (so mods.json is the game folder's) and, on Linux, has a Sleep stand-in beside the pieces it
takes from the shim.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The review of #942 (suggestion 1): when the game's copy of a pack existed but
hos_zs_read failed on it (no dictionary, over PACK_MAX, no content size),
pack_members went on as if the game had no such pack and estimated every member
(10.7 times the size plus 8 KiB for a .bgyml). It now returns -1, as for a mod's
copy that cannot be read, and the log line names the copy that failed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A mod replaces whole files, and many of the game's files are SARC archives
of hundreds of small files (the actor packs, the layout archives, the text
archives). A mod that changes one of those small files ships the whole
archive, so two mods that changed different files inside one archive
clashed: the lowest mod's whole file won and the other's change was lost.

At the start, for every path several enabled mods have that is a SARC
archive of the game's in a .zs file, host/mods.c merge_archives now makes
one archive of the copies and serves it for that path:

- restbl_sarc_merge (host/restbl.c, beside the SARC reader the pack members'
  entries use) compares each copy with the game's own, member by member. A
  member comes from the mod whose copy differs from the game's for it, or
  that adds it; the lowest such mod where several do, as for whole files.
  A member of the game's is left out only when the lowest mod leaves it
  out (what that mod's file alone would do); a mod above leaving one out
  changes nothing. Two mods with the same bytes for a member do not clash.
  A name an archive holds several times (the layout archives hold each
  layout four times) is taken as one member, a member that is an archive
  itself is taken whole.
- A SARC archive does not say how its members are aligned. Each member
  keeps the alignment its own archive gave it: the largest power of two its
  offset there is a multiple of, from the archive's start and from its
  data's start, between 8 and 8 KiB. That is never less than it had.
- The archive goes to modcache/archives in the game folder as a frame of
  raw blocks (hos_zs_write, as the merged size table and the button
  prompts' files), with a record of what it was made of: a hash of every
  copy's bytes in the list's order and of the game's. A start whose record
  matches reads the copies' compressed bytes only and serves the archive
  made before; a changed copy, another order, a mod switched off or a
  damaged archive make it again. Mod files are only read.
- The size table follows by itself: fit_sizes sizes what is served, so the
  merged archive's own entry and, for a pack, its members' entries
  (restbl_pack_raise) come from the merged archive.
- The log names each merged archive with what each mod gave, and each
  member two mods changed with the mod that won it. The Mods tab's line of
  a mod says how many of its archives are served as one with other mods'
  copies and how many files inside them a lower mod takes; such an archive
  no longer counts as a file taken whole.
- Kept as before (the lowest mod's whole file): a file that is no archive
  (found from the first bytes of the game's copy, hos_zs_head, without
  decompressing it all), an archive the game lacks, a copy or a game file
  that cannot be read as a little-endian SARC archive with named members
  and the game's hash key (the log names the copy), an archive that would
  hold nothing of the mods above, and one that cannot be written.

The button prompts and the PC texts meet a merged archive as they meet any
mod's file: a mod's layout or text archive wins over theirs.

tests/test_mods_archives.py: restbl_sarc_merge alone on made-up archives
(different members, the same member, the same change, members added and
left out, three copies, names held four times, a nested archive, nothing to
make, nine unreadable archives, too many members, alignment kept), and
host/mods.c over folders with dictionary-compressed archives (what is
served, the log and the Mods tab's lines, the size table, the cache used
and made again, a mod switched off, the order changed, no mod or game file
written). tests/test_mods_packs.py's two mods on one pack now expect the
merged pack: the member only the upper mod grew is served, so its entry is
raised.

Not run in the game. Measured over the real game's files with a harness
(not committed): eight archives of a character mod and of a made-up second
mod, 21.9 MB decompressed, are merged in 126 to 168 ms at a first start and
checked in 10 ms at the next ones; the merged archives are 0.3 to 4.5%
larger than the larger copy (padding).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
An independent review of the previous commit found one crash, one way to
make Longshot write far more than it read, and a wrong number. Each fix has
a check in tests/test_mods_archives.py that fails on the previous commit.

- A member name is any bytes up to a NUL. The clashes were kept as text
  lines with the name in them and the log read the two copies' numbers
  back out of that text: a name with a line break made a line of its own,
  and the numbers on it indexed the copies' array (a read outside it; the
  game exited with an access violation at its first start with such a
  pack in two mods). The clashes are now an array of numbers and names,
  never parsed back; a name is kept without control characters and cut at
  160 bytes before it reaches the record or the log, so it cannot add a
  line to either; the record's numbers are range-checked where they are
  read and again where they are used.
- restbl_sarc_merge takes a limit and never returns an archive larger than
  it, nor larger than the game's archive and the copies together. A copy
  whose nodes share one member's bytes (300 nodes over one 64 KiB member:
  a file of a few KB) used to be written out node by node: 19 MiB here,
  up to 4 GiB a path by the old bounds. host/mods.c gives ARCHIVE_MAX (256
  MiB, which a typedef holds to PACK_MAX), so a merged pack is always one
  the size table's step can read back. Beyond the bound: the lowest mod's
  whole file, as before the merge, and a log line.
- An archive made before is served again only when the file has the size
  AND the hash its record gives (the record now holds both; its format is
  "longshot archive merge 2"). An archive damaged in place without a change
  of size was served again; now it is made again. So what is served is
  always an archive this code wrote whole. The record is written through
  <record>.new and a rename, with its writes checked.
- The data's first member no longer gets the largest alignment (8 KiB): its
  offset from the data's start is 0 and says nothing, so it keeps what its
  offset from the archive's start gave it, which is all its own archive
  gave it. Every merged archive's data used to start on a multiple of
  0x2000: about 8 KiB an archive, several times a small pack (median +256%
  over the game's packs laid out by the old rule). By the new rule: a pack
  +2.5% (median; +2.0% of all the packs' bytes; over 5% for 2,392 of 8,385,
  the most +129%), a layout archive +0.4%, a text archive +0.1%. The
  comment in restbl.c had "2 to 5%", which held for large archives only.
- Every copy whose change of a member is not what the archive gets has it
  counted as lost and named in the log (two mods with one change, a third
  with another: only the second was counted; a change the lowest mod makes
  too is not lost).
- A copy that cannot be decompressed (no size in its frame, a dictionary
  the game does not have) is said to be that, not "not an archive".
- docs/mods.md: the bound, that copies are compared with this game
  version's archive, and that the merged archive is a few percent larger
  and kept uncompressed.

tests/test_mods_archives.py: a member name with line breaks changed by two
mods (the game starts, one line in the log and the record, the record fits
at the next start); members that share bytes (alone and through
host/mods.c: nothing over 4 KB in modcache); the limit to the byte; a small
archive stays within 256 bytes of its members laid out afresh; the
alignment cap (0x2000, neither 0x1000 nor 0x4000); a name that does not end
inside the archive; a name above ASCII, merged and refused when hashed
another way than the game's; one name's nodes in their order with
different bytes; the game's own file changed (made again); an archive
damaged in place (made again); an archive that cannot be written (no
record that says it is not needed; made at the next start);
hos_mods_file. The folder checks that need no dictionary now run without
the zstandard package too.

Not run in the game, nor on Linux.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
host/mods.c now keeps its list in mods.json through host/mods_list.c: the archive test's fixture compiles
mods_list.c with it, answers hos_options_file with no settings file (so mods.json is the game folder's) and,
on Linux, has a Sleep stand-in beside the pieces it takes from the shim. The test switched a mod off and
changed the order by rewriting longshot_mods.txt between starts; the game reads that old file only once, so
it now writes mods.json for both.

#134's tests/test_mods_list.py builds host/mods.c with stand-ins for host/zs.c; the archive merge calls two
more of its functions (hos_zs_decode, hos_zs_head), so that fixture gets stand-ins for them too (no game
RomFS there: nothing is merged).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
main's players' guide (#1210, brought in line with #134 there) says what a player sees; this branch changes that, so the
guide's paragraph follows.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The review of #1089:
- merge_one looked for the game's copy with the mod's spelling, which Linux
  finds only in the game's own case: a mod that ships pack/actor/x.pack.zs was
  merged on Windows and not on Linux. game_file_cased tries game_case's
  spelling after the mod's, and game_case now runs on every system (host/posix's
  FindFirstFileA ignores case as Windows' does). pack_members finds the game's
  copy the same way.
- put() used realloc's result unchecked; with no memory the path is not
  merged and the lower mod's whole file is served, as before.
- the archive's path leaves room for ".txt.new": hos_zs_write writes through
  <path>.new in MAX_PATH, and a path of 256 to 259 characters cut that name to
  the path itself.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The launcher keeps one list per instance and names it at every start. When
HOS_MODS_LIST is set, host/mods.c state_file takes that file ahead of the
settings file's folder (HOS_OPTIONS_FILE's too). Nothing is carried into it
(not the game folder's mods.json, not longshot_mods.txt, which is left as it
is) and no note is left in modcache for the build: the launcher tells its
builds with make_game.py --mods.

It names a file the game writes, so longshot_env.txt cannot set it
(host/hos_main.c env_line_allowed), and it has its row in switches.def.
tests/test_mods_list.py checks where the list is read and written, that
nothing is carried or imported, and that no note is left.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Checked at the top of hos_mods_init: one log line ("mods: off for this start
(HOS_NO_MODS): ..."), no mod files and no cheats loaded, and the list neither
read nor written, so the Mods tab changes nothing and the next normal start is
as before. The ExeFS patches a build took are compiled into the game and stay;
the log line says so. A row in switches.def; tests/test_mods_list.py checks
the start, the log line and that the list is left as it is.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Spec 5.4: the build is given the list. With --mods, nx2/exefs_patches.py
list_file takes that file ahead of its other rules (HOS_OPTIONS_FILE, --user,
the game's note, the game folder), and collect reads neither the game folder's
mods.json nor longshot_mods.txt in its place, as the game started with
HOS_MODS_LIST carries nothing into its list. Without --mods the build finds
the list as before; taking no mods without it is a separate decision.
exefs_patches.py's own command line takes --mods too.

tests/test_mods_list.py: the build given the file the game was given with
HOS_MODS_LIST reads the same order, ahead of --user and HOS_OPTIONS_FILE, and
collect follows --mods.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The players' guide told them to set HOS_MODS in longshot_env.txt, which the
game refuses (host/hos_main.c env_line_allowed: a switch that names a folder
is taken from the environment only). docs/using-mods.md and docs/mods.md say so
now. docs/mods.md, docs/development.md (the mods.json paragraph and the
Running a test table) and the README's Mods section document HOS_MODS_LIST,
HOS_NO_MODS and make_game.py --mods.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Spec 5.5 and 8.4: a mod with code (ExeFS patch files, .ips and .pchtxt, and
code modules, exefs/subsdk*) is off until the player accepts its warning, and
again when its code changes. A mod without code is on when found, as before.

- host/mods.c code_hash: FNV-1a 64 over the mod's code files by their names'
  bytes (each as its name, a 0 byte, its size in 8 bytes little-endian, its
  bytes), "fnv1a64:<16 hex>". check_code, at the start after the list's
  switches: a mod whose entry's "accepted" is not that hash is off (the file's
  switch left as it is) and asks; the log names why.
- The Mods tab (API version 36, MkwVkHost.mod_code): On for a mod that asks
  opens its warning in the tab's help box instead (what it has, that its code
  runs with everything the game can do, that it can crash the game or damage a
  save, to trust where it came from, that it goes in at the next build). Enter
  accepts (mod_edit op 4): the mod is on and its hash is kept in its entry as
  "accepted"; Esc or Left leaves it off. The host refuses op 1 for a mod that
  asks.
- The migration from the builds before this: a mod whose entry has no
  "accepted" and whose every patch file, as it is now, the last build applied
  (exefs_patches.txt) is taken as accepted once, its hash kept and logged: its
  code runs in the game already.
- host/mods_list.c reads and writes a string key of an entry that it keeps as
  it is written, so "accepted" stays a key a reader that does not know it
  keeps.
- exefs_patches.txt's new kind "unaccepted" (the build, next commit) counts
  as waiting for a build.

Tests (written, not run): tests/test_mods_list.py (off when found, On refused,
Accept keeps the hash, a changed code file asks again and one that is not code
does not, the migration and its limits), tests/test_mods_menu.py (the warning,
Accept, the version 36 wiring), tests/test_mods_sizes.py's code mod accepted,
tests/test_hos_ab.py's table check past the new function.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
nx2/exefs_patches.py collect reads each entry's "accepted" (parse_entries;
parse_list and read_list keep their shape) and works out each mod's code_hash
as host/mods.c does. A mod whose code is not the accepted one is left out
whatever its switch: its patch files are "unaccepted" in exefs_patches.txt,
with why (not accepted yet, or changed since), and the game counts them as
waiting for a build. The migration is the game's: a mod whose entry has no
"accepted" and whose patch files the game folder's last build applied is
taken once (taken_before), and the game keeps its hash at its next start. A
list that is not a list takes nothing once, as in the game. --mods and the list
rules are as before. An accepted mod that is off is still not applied: making
it switchable at the start is #1036's.

make_game.py writes only the applied files into the patches JSON whose hash
is in the lift key, so mods that are off, left out or not accepted, and the
acceptance kept in mods.json, never change the key. A build that also listed patch files it did
not apply (a mod off, another version's, unsupported) is translated again once.

Tests (written, not run): tests/test_mods_list.py build_entry (the build's
hash is the game's, accepted mods taken, a new mod and a changed one left out
with their notes, exefs_patches.txt's line, the migration, the JSON's text),
tests/test_exefs_overlaps.py's list accepts its two mods.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/using-mods.md tells players that a mod with code is off when found, that
turning it on shows a warning and Enter accepts it, why (its code runs with
everything the game can do), that a change to its code asks again, and what
happens to code mods from an earlier version. docs/mods.md defines mods.json's
"accepted" field and its hash for the launcher, the migration rule, and the
warning for authors; the README's Mods section says it in short.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
make_game.py writes mods_switches=HOS_MODS_LIST,HOS_NO_MODS into the stamp it
writes for packaged tools (MODS_SWITCHES), after builder= and before the
addresses, the other lines as they were. The launcher sets those switches only
for a game folder that has the line; a folder without it was built by tools
from before them, which take no make_game.py --mods either. Documented beside
builder= in docs/development.md and in docs/mods.md; tests/test_mods_list.py
checks the list is exactly the two and that host/mods.c reads each.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The whole image was one executable region. The lift now writes each module's regions into gen/hos_image.c
(nx2/standalone.py regions: .text r-x and .rodata r-- as static code, .data with the .bss rw- as mutable code), and
host/hos_svc.c answers from that table. A mod's code module finds the game's main by walking these regions down
from its own, as it does on a console; with one region the walk met the loader and gave up. The SDK's own readers
(nn::ro's module header search, nn::diag's backtrace) get a module's start the same way.

HOS_QUERY_MEMORY_OLD=1 keeps the one region, for A/B. An address of the image that no region holds gets the whole
image as before. Stack, heap, system region and free memory are unchanged.

tests/test_query_memory.py runs the real code over a made-up image, with a module's walk to main and four broken
variants.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
nx2/exefs_modules.py collects exefs/subsdk0..9 of the mods that are on (host/mods.c's order and switches, as the
ExeFS patches), and nx2/image.py loads them after the game's last module: no address of the game moves, and the
game's own symbols are found first. The module is relocated, bound and translated with the game; its start routine
runs after the game's modules' (gen/hos_image.c, as for any module). It is part of the lift's key like the patches,
and gets a chunk of its own when chunk boundaries are kept, so the game's last chunk is not compiled again.

Taken: a module that only adds code and reaches the game through a patch file's stubs, the game's functions by
address and the system calls host/hos_svc.c has. Left out with a note in exefs_patches.txt: a module that holds a
system call that maps or makes code memory (it installs hooks by writing instructions while the game runs), one
with another system call the host lacks, one that imports a symbol the game does not have, a file that is no NSO,
and a replaced main, sdk or rtld.

main + each constant a module's code builds (MOVZ + MOVK) that is a code address of main becomes an extra entry:
a module jumps back into the middle of a game function after its patch's stub, and an indirect jump needs an entry.

tests/test_exefs_modules.py: made-up modules through the real image builder and lifter.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Co-Authored-By: Claude Fable 5.2 <[email protected]>
From a review of the branch.

A mod's file is from anywhere, and three things in one stopped the lift
or went wrong in the image where the mod should have been left out with
a note:
- a relocation of a kind hos/nx_image.py does not apply (TLSDESC, for
  one) raised SystemExit in the lift;
- a relocation that points outside the module died in the lift with a
  traceback, or, when it pointed into the next mod's module, was applied
  there;
- a header that asks for gigabytes of .bss was given its slot, and MOD0
  saying more .bss than the file's header made the image longer than its
  slot.
classify() now refuses these (malformed), and collect() does not load a
file whose header asks for more than 64 MB (header_refusal).

The constants taken for addresses of main were every MOVZ + MOVK pair in
the module, numbers it merely uses among them (a size, a serial speed),
and each such entry cuts a game function in two at that address (the
first part tail-calls the second: correct, a call slower there; the
docstring said 'a second translation', which is not what the lifter
does). Only a constant the code then adds to another register counts
now: an offset from an address, as the modules build them.

A missing import's name goes into the note as one line (a name with a
tab or a line break made a second line in exefs_patches.txt).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
nx2/exefs_modules.py still gave exefs_patches.ordered the game folder's longshot_mods.txt as the list. Since
#134 that argument is mods.json, so the old file was read as a list that is not one: every mod on, by name,
while the patch files followed mods.json. collect now finds the list as exefs_patches.collect does
(list_file, the old file, the game folder's mods.json beside it, nothing of the game folder's with
HOS_OPTIONS_FILE), says which list it read when a mod has a module, and takes the user folder:
nx2/make_game.py passes --user down as it does for the patch files, and the command line has --user.

The test checks that both collect calls give exefs_patches.ordered the same list, the old file and the one
beside it, with and without a user folder, and that a user folder's mods.json orders and switches modules.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
main's lift key takes only the environment it names now (LIFT_ENV_PREFIXES, LIFT_ENV_NAMES); before, every OOT_ variable was
in it, which is how the code modules' list got into the key. OOT_EXEFS_MODULES_SHA1 (the hash of the modules' JSON, which names
every module built in with its file's sha1) is one of LIFT_ENV_NAMES now: without it a build after a module was added, changed
or removed would keep the translation made without it, silently. OOT_EXEFS_MODULES names that JSON in the work folder (a path,
LIFT_PATH_ENV). tests/test_lift_cache.py checks both; the hash's case fails without the change.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
main's players' guide (#1210, brought in line with #134 there) says what a player sees; this branch changes that, so the
guide's paragraph follows.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Main's switch table holds the host's switches too now (67efc4d3) and
tests/test_switch_table.py asks for a row for every name the source reads;
this branch's svcQueryMemory switch had none.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
tests/test_query_memory.py's fixture names HOS_GUEST_SPACE and expects a free address to be answered as the
whole gap, as main's query_memory does since #1683; tests/test_query_memory_free.py's fixture stubs env_on and
image_region, which query_memory calls now (the image as one region there, as it expects).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The code modules came in from #984 before the warning (spec 5.5, 8.5 rule 1): exefs_modules.collect took
every module of a mod that is on, and a mod mods.json does not name is on, so a folder with exefs/subsdk7
dropped into mods/ put native code into the game at the next build with no warning shown. It also read the
list on its own and did not take make_game.py --mods, so with --mods modules and patch files could follow
two lists.

exefs_patches.mods_in_order is now the one rule both collect calls use (the review's suggestion: their
list, old-file and beside logic was copied line for line): the list (list_file, --user, --mods), the
order and switches (ordered) and the mods whose code is not the accepted one (code_hash against
"accepted", which already counts exefs/subsdk*; the migration, taken_before, never takes a mod with a
module). A module of such a mod is "unaccepted" in exefs_patches.txt with the same note as its patch
files (not accepted yet, or changed since), whatever its switch, and its file is not parsed. make_game.py
gives the modules --mods; exefs_modules.py takes --mods on its own command line too.

Tests (written, not run): tests/test_exefs_modules.py's mods are listed in mods.json with their code
accepted, a new mod and a changed one are "unaccepted" with their notes and their exefs_patches.txt line,
and the two collect calls give ordered the same list with --mods too, which the modules follow;
tests/test_mods_list.py checks make_game.py gives the modules --user and --mods.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The review of #984 (blocking 1, and the DT_INIT suggestion, asked for here): malformed() missed three
things a mod's file can hold, each of which got past classify:
- a .text whose start or size is not a multiple of 4: hos/nx_image.py's _entries unpacks .text as whole
  words (struct.unpack needs the exact length), so the lift stopped;
- .rodata or .data below .text or each other, or overlapping: nx2/standalone.py regions() stops the build
  with SystemExit when it writes hos_image.c's region table (that raise is now reached only by the game's
  own modules);
- a DT_INIT outside the module's .text, or not at an instruction: the host calls base + DT_INIT at every
  start, so the game crashed at every start instead of the module being left out.
Each is now refused in malformed() with a note in exefs_patches.txt. The order is checked before the
size check, which takes .data as the last segment.

tests/test_exefs_modules.py (written, not run): nso() places .rodata and .data where it is told, takes a
.text size and dynamic entries; one case each for a .text of 0xFFE bytes, .data below .rodata, .data
over .rodata's end, DT_INIT in .rodata and DT_INIT between instructions.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The review of #984 (blocking 2, spec 8.5 "bounded"): header_refusal capped what the NSO header asks for,
but nso.Nso then read more sizes from the module's own bytes before malformed() saw anything: MOD0's
bss_end grew the image to as much as 2 GB, a DT_SYMENT of 1 with SYMTAB..STRTAB across the image made
tens of millions of symbol dicts each with a name scan, and the relocation tables, DT_RELR's bitmaps,
DT_INIT_ARRAY and the unwind table were read by their own counts. The 64 MB cap was per module, with
any number of them; third_party/ cannot be changed.

nx2/exefs_modules.py parse() is nso.Nso with image_refusal() run on the loaded segments before its
_mod0 (nso2's, with DT_RELR) reads anything, raising Refused with why; the module is then left out with
that note. The bounds, each far above a mod's module of a few hundred KB (some 30 dynamic entries, a
few thousand symbols and relocations):
- the file: at most 64 MB (MAX_FILE), not read past that; the header's memory at most 64 MB, as before;
- MOD0's .bss end within the size the file's header gives (the 2 GB case);
- the dynamic section: its end mark within 512 entries and inside the module;
- symbols: 24-byte entries (DT_SYMENT), at most 65,536, the table inside the module, each name's 0
  within 16 KB and inside it;
- relocations: DT_RELA, DT_JMPREL and DT_RELR inside the module, DT_RELR at most 262,144 words, and
  at most 262,144 relocations in all with DT_RELR's bitmaps unpacked;
- DT_INIT_ARRAY at most 4,096 entries, inside the module; .eh_frame_hdr's table at most 262,144
  entries, inside it;
- all the modules one build parses: 128 MB together by their headers (MAX_TOTAL); the later ones in
  the list are left out, with a note that says so.
A module of a mod that is not accepted is not parsed at all (the previous commits). The lift's load()
parses the copies the same way, and the copies are the bytes collect read and checked, not the file
read again.

code_hash (nx2/exefs_patches.py and host/mods.c alike) does not read a code file over 64 MB
(CODE_FILE_MAX): the mod has no hash and is never accepted, and the warning says a file cannot be read
or is over 64 MB. The build read a whole file of any size to hash it before.

docs/mods.md states the bounds. tests/test_exefs_modules.py (written, not run): a module of each kind
above is refused with its note before the loader allocates or loops by it (some with a lowered bound),
a good one is parsed, the total and the file bounds in collect, a code file over the bound has no
hash. host/mods.c checked with cc -fsyntax-only (Linux).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A mod made for the console or an emulator may ship a compiled code module in
its exefs folder (subsdk0 to subsdk9, or the game's main, rtld or sdk replaced
whole). Longshot compiles the game's code ahead of time and runs no module,
so that part of the mod does nothing; until now the mod was listed on the
Mods tab and the module was left out without a word.

exefs_status now recognises such files by their names (exefs_module: the
console loader's module names, any case, no extension; main.npdm, .stub
files and other names are not modules), logs one line for each and counts
them. mod_text names them in the mod's detail line and says in its note that
they are not loaded, that the mod's patch files may do nothing without them
(a module's patches often only call into the module) and, for a mod with
nothing else, that it does nothing here. Patch-only and RomFS-only mods read
as before. README and docs/mods.md say the same.

tests/test_mods_modules.py builds host/mods.c as it is over made-up folders
(Windows' own file calls on Windows, host/posix's on Linux) and checks the log
lines and the two lines of six mods. It fails on the base and passes here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c now reads and writes its list through host/mods_list.c and asks host/options_path.c where the
settings file is. The test's fixture compiles mods_list.c with it, answers hos_options_file with no settings
file (so mods.json is the game folder's) and, on Linux, has a Sleep stand-in beside the pieces it takes from
the shim. The longshot_mods.txt it writes before the one start stays: a first start still reads the old file.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
#940's review (request changes): with #984 a mod's subsdk0..9 is built into the game or left out with
why, and the build writes a line for it into exefs_patches.txt (mod, file, FNV-1a 32, module |
unsupported | unaccepted, note), but the game never read that line back: #940's text said every
module "is not loaded: Longshot cannot run code modules", false for one that is built in, and a
mod with only a module showed nothing true about it.

host/mods.c exefs_status now looks each module file up in exefs_patches.txt as it looks up a patch
file (built_line, by name and hash) and the Mods tab and the log say:
- "module": built into the game (the detail line, "built into the game" or "some built into the
  game" as for patch files);
- "unsupported": left out by the build, with the line's note ("1 code module is left out by the
  build: <why>."), and only then "Its patch files may do nothing without it";
- no line, the mod on and accepted (or "unaccepted" in a build before it was accepted): not in
  the game yet, build again;
- no line and the mod off: not built in while it is off; the mod's code not accepted: the warning's
  note says so, and the module adds nothing of its own (its file is not read again when it could not
  be hashed).
A module line of a mod that is off, or gone, is counted in the log's "stay in it until it is built
again" line with the patch files, and an off mod's note says its code modules stay in the game
until it is built again. #940's name-only "cannot be loaded" text is kept for the game's own main,
rtld or sdk replaced whole (exefs_module 2), which the build never takes; "This mod does nothing
here" is said only when such a module or a left-out one is all the mod has.

The names in the detail line are as many as fit (96 bytes: the ten subsdk names do), and the rest
are counted ("and 4 more"): before, a later name was dropped while the count kept it (the review's
exefs_module_names[96] note; on a case-sensitive disk subsdk0 and SUBSDK0 are two files).

README's Mods section and docs/mods.md say this in #984's words instead of #940's "not loaded";
docs/using-mods.md says the tab gives the reason, and that a replaced main, sdk or rtld cannot be
loaded.

tests/test_mods_modules.py (written, not run) builds host/mods.c over mods whose code is accepted in
mods.json and a made-up exefs_patches.txt: a module built in, one left out beside a built patch, one
waiting with a replaced main, a patch-only and a RomFS-only mod, a replaced rtld switched off, a
built-in module switched off and one not built, a mod not accepted, one accepted since the build,
fourteen names in one mod, the log's lines and the stale count with a gone mod's module line.
host/mods.c checked with cc -fsyntax-only (Linux).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The branch mods/port-sites (no pull request of its own yet), as merged after the ones before it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The branch mods/atmosphere-patches (two commits, no pull request of its own yet), as merged after the ones before it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The branch mods/lift-key-bytes (no pull request of its own yet), as merged after the ones before it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A mod's ExeFS patches are written into the game's code before it is
translated, so a mod with patches that was switched on or off needed the
game built again, and until then the game ran half the mod: its code
without its files, or its files without its code.

Now the build takes the patches of every mod with code that is in the mods
folder, on or off, and translates the code they change both ways; the game
picks a version when it starts.

The build (nx2/exefs_switch.py, with exefs_patches.py collect and apply,
lift.py, chunks.py write and edit_c, build.py):
- each such mod is a switch, a byte of hos_patch_on[] (plan);
- the lift walks main with every switch on, as before. Each function that
  holds a word a switch wrote is walked again for every other state of the
  switches that touch it, over main as that state has it, with the same
  entries (analyse); a function is what the lift walks from an entry, so a
  code cave with branches, calls and adr needs no rule: it is part of the
  versions that reach it;
- the function as written gets one line at its top that tail calls the
  version for the state when its switches are not all on (dispatch). The
  other versions are in a64_switch.c, each under its function's own head
  with a #define around it, so the game's own edits of the lifted C
  (oot_patches.py, the page marks) are made in them as in the function;
- a64_switch.c also has the switches, their patch files (name and hash)
  and, for every byte a switch writes, the game's own and each mod's in
  the list's order;
- a switch that writes data a jump table is read from marks the jump, so
  its function is switched too;
- not switched, and built in or left out as before: a mod that changes a
  place where Longshot hooks the game's code; where more than two switches
  touch one function, the ones lowest in the list (the lift then builds
  them in for good, as applied or as left out); every mod with
  LONGSHOT_PATCH_SWITCH=0, the mods that are off with =on;
- the lift's key with switches is made of each file's bytes, its switch
  and whether its mod is on (names still left out).

The game (host/mod_switch.c, host/mods.c, hos_main.c): before any of the
game's code runs, mods.c is told which patch files are behind a switch; a
switch is on when a mod that is on has every file of it as built, under
any folder name; hos_patch_on[] is set and the game's memory written to
match (image.bin holds main as with every switch on). The Mods tab no
longer says of a switched mod that its patches stay in the game or wait
for a build. A mod added after the build, or a patch file edited since,
waits for a build as before.

tests/test_exefs_switch.py: a made-up main and made-up mods through the
build's own steps (collect, the lift's image, a64-kit's Lifter, install,
dispatch, write, and once chunks.write and edit_c), compiled and run in
every state of the switches against a small interpreter of the same
instructions: a cave with a conditional branch, a call and an adr; a mod
off at the build; two mods on one function; a third built in for good, on
and off; the plan's exceptions; the key; a jump table in data.
tests/test_mods_switch.py: host/mods.c and host/mod_switch.c over made-up
mods, the table made by exefs_switch.tables, and made-up memory: the
switches and every byte at three starts.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
An independent review of the switch found nine things the game round did
not meet. Each is answered here with a test that fails on the commit
before and passes now.

1. The lift's key did not cover what a64_switch.c carried (HIGH). The
   table named each switched file and the hash of its bytes; the key is
   made of the bytes the files write. A file saved again, renamed or
   encoded another way kept the key and the old table, so its switch
   stayed off for good while the Mods tab said "built into the game".
   a64_switch.c now has numbers and bytes only (what became of each switch
   of the plan, and the writes); which file is of which switch is in
   exefs_patches.txt ("code+switch<n>"), which every build writes, a
   switched mod that is off included, and host/mods.c reads it there.
2. Longshot's own edits of the lifted C and the line at a switched
   function's top (HIGH). The line was put in when the function was
   written, so an edit that puts a host call first in a function put it
   above the line, and the call ran again in the version the line left
   for; an edit that matches the head with the first instruction found
   nothing; and of several other versions under one head only the first
   was edited. The line now goes in after the edits: chunks.edit_c takes
   the lines out before its first pass and puts them in after its last
   (exefs_switch.strip_lines, add_lines; a64_switch.c records them), and
   each other version is edited by itself (exefs_switch.edit). Not the
   picking function of its own the review proposed: that needs the
   function as written under another symbol, a #define above it, and the
   lift's cuts of a file (chunks._cut, split_hot.py) are made at a
   function's head line, which would leave the #define in the piece before.
3. A function only the unpatched code calls was no entry (MEDIUM): the
   image takes its entries from main with every switch on, so the version
   with a mod off called code with no function and was written as a trap.
   The calls of the game's own words and of each switched mod's own words
   at every place such a mod writes are entries now (exefs_switch.entries,
   nx2/image.py), and so are the code addresses the game's own words form
   there with ADR (plain_image, nx2/lift.py). Where a version would still
   stop at code that is no function and the function as written would not,
   the function's switches are built in for good, with a line in the log:
   such a mod takes a build to switch, as before, and no state traps.
4. A mod that is off decided how a mod that is on was built (MEDIUM):
   make_returns saw the off mod's bytes in the on mod's hook routine and
   left its B where a build without the off mod writes a RET. Two switched
   mods of which one changes what make_returns writes for the other are no
   switches (exefs_switch.entangled, settled before the whole-list steps);
   built in or left out as they are at the build, the step sees exactly
   what the game has. A note about bytes a switched mod takes says "while
   that mod is on".
5. The cap's re-walk dropped the table of a jump another function shares
   (LOW): the table is kept unless the walk without the mod reads it again,
   and read again from the image without the mod when another function
   still holds the jump.
6. Two mods that ship the same patch file (LOW): each file is its own
   mod's by the list's line, so one mod's file is not counted for the
   other's switch.
7. The log said a deleted switched mod's code stays in the game (LOW): a
   switched file's line is not counted there; its switch is off.
8. Jump tables (LOW): the table check runs for every switch, not only
   those that write data, once with every switch off and then a switch at
   a time, each both ways (two mods on one table); a version's jump that
   its own code does not resolve has no targets left from the lift.
9. A mod that is off could stop the supported build (LOW): an output-size
   place that only a version with a mod off has counts as found, with a
   warning that the place is lost while that mod is on.

tests/test_exefs_switch.py is written again around the shapes the review
named, each run in every state against the interpreter: a function only
the unpatched code calls; Longshot's own head hooks on functions two mods
switch, through chunks.write and edit_c as the supported build runs them,
with the host calls counted; a hook's return with an off mod over its
routine; a left-out mod whose routine shared a jump; the hot file cut by
split_hot.py and the compile's cut of a giant; the kept translation for a
file saved again. tests/test_mods_switch.py: the list of a later build,
the same file in two mods, a deleted mod, a left-out mod's bytes, a write
outside the game's memory. Two of patch-build's tests read a line of the
list: its kind is "code+switch0" there now.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
main's host/mods.c asks texts.c for a path now (#604); the fixture builds mods.c without it, as it does without prompts.c.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The game reads the mods' order and switches from mods.json now and reads longshot_mods.txt only once, to carry an
older list over. The tests that switch mods between two starts, or give the build its order, write mods.json:
the switch test's fixture (which also links host/mods_list.c and has stand-ins for hos_options_file and, on Linux,
Sleep), the switch test's game folders, the atmosphere test's call of ordered() and the overlaps test.

The switch test also checks that the build's reading of that mods.json (ordered, a mod that is off listed too) is the
plan the fixture's switches are made from, so the build and the game number the switches from one list.

#134's test of the build's entry runs collect() with a fake Main; the passes after the classification on this branch
read its image, so the test stubs port_sites, parse_file and make_returns there (no bytes written) and puts them back.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Main now hashes only named variables into the lift's key. The switch's inputs
reach it through the patches' list: exefs_switch.plan runs in make_game.py
before the lift, and bytes_key (OOT_EXEFS_PATCHES_SHA1, named on #134) holds
which file is of which switch and whether a switched mod is on.
LONGSHOT_PATCH_SWITCH is read by a module the lift imports but only by the
plan, so it goes in LIFT_ENV_NOT_OUTPUT with why. A test through
make_game.lift_key: =0 against unset, an off mod joining or leaving the plan
(=on), a changed byte change the key; a renamed mod and the variable alone
do not.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
main's players' guide (#1210, brought in line with #134 there) says what a player sees; this branch changes that, so the
guide's paragraph follows.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The function as written (its chunk, or the hot file at -O2 in the profile's order) was the state with
every switch on, so a player with a code mod off ran the game's own version of each function it changes
from a64_switch.c, colder than a build without the mod (review of #1036, point 1). Now install() writes
each switched function in the state the mods are in at the build: where that state's code differs from
the lift's (every switch on), exefs_switch.written() puts that state's text in the chunk under the
function's own name and moves the lift's text into a64_switch.c as the version __s<every switch on>.
The line at the top leaves for another version when the switches are not in the state written.

Nothing the lift reads changes: it still walks main with every switch on, and the versions are the
same set. Which state is written is not in the lift's key: a kept translation is right for every state.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The lift's key with switches hashed each switched mod's on, its switch number and the list's order, so
switching a mod and then building for any reason, reordering two mods that do not overlap, or another
profile with the same code mods translated the whole game again (review of #1036, lift key; Modding
API spec 5.4: a build is keyed by the bytes its code mods apply, and profiles share it).

- exefs_switch.plan numbers the switches by what they write (the first byte each writes, then all of
  it), not by the list's place; Sets is by those numbers, which a64_switch.c's tables and
  exefs_patches.txt's +switch<n> use.
- exefs_patches.bytes_key (exefs-switch-2): each switch's writes by number, the bytes of the mods that
  are no switch, and the list's order only at a byte a switch and another file both write. No on.
- The one case a switched mod's state is in the translated code: a switch the lift built in for good
  (a third mod on one function, a version that would stop at code that is no function). make_game.py
  reads what the kept translation built in (exefs_switch.baked: a64_switch.c's plan) and translates
  again exactly when such a mod is in the other state now (rebuilt_for); a lift store copy that does not
  fit is not taken.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c checked each switched file's name and hash but not the order: with two switched mods that
write the same bytes (the usual clash, over the free space after the code) swapped in the list, the game
kept the build's winner in the memory and in the code's versions while the Mods tab showed the other
order (review of #1036, point 3; Modding API spec 5.4: a difference is "waits for a build", never a
silent mismatch). mod_switch.c now gives mods.c the build's bytes too: each place's writers are together
in the build's list order. switch_order() compares the two mods' places in the list now; when both are on
and swapped, the game keeps the build's order, and both mods' lines and the log name the other and whose
bytes the game has, until the next build.

a64_switch.c's places are offsets from main's guest address (hos_patch_base, 64-bit), not uint32_t
guest addresses (review nit).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
a64_switch.c got the default flags (-O1, no split_giants, no light passes by size) and mem_need counted
it at 400 MB, while a mod that touches a giant function puts up to three more copies of it in that one
file, compiled whole (review of #1036, point 2: f_81b8c000 is 4.79 MB of C; by mem_need's own rule three
copies need over 1.5 GB and minutes).

- exefs_switch.write puts the tables and the lines in a64_switch.c and the n-th other version of each
  switched function in a64_switch_<n>.c (at most three: CAP 2), so no file holds two versions of one
  function: a giant's versions compile side by side, and split_giants' pieces (static, named by the
  function's address) never meet another version's in one file. Files an earlier lift left go.
- nx2/build.py compiles a64_switch*.c with the chunks' flags (chunk_flags / lifted_flags over split_fl:
  giants cut into pieces, light passes by the largest function) and mem_need counts them as chunks
  (400 MB + 50 MB per MB of C + 250 MB per MB of the largest function).
- exefs_switch.edit edits every file; tests/test_exefs_switch.py's giant case cuts the versions too.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- nx2/guest_locals.py check_patched (#1576: no patched function has locals) read only code_*.c; a
  version in a64_switch*.c with a patch's mark and locals passed. It reads the versions' files too.
- exefs_switch.edit: an edit of nx2/oot_patches.py (or an output-size place) found in one version of a
  switched function, or in the function as written when this lift wrote it, and not in another, went
  unreported. Each such version and edit is printed: a switched mod changed the code the edit looks for,
  and in that state the game runs without it (review of #1036).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- A mod with a code module (exefs/subsdk*, #984) was switched like any other: its module is built in only
  when the mod is on at the build, and once in the game it starts with it whatever the switch says. So a
  module mod switched off still ran its start-up with its stubs off, and one built while off and switched
  on had its patches call a module that is not there (review of #1036, Neighbours). Gating the module's
  start on the switch would answer only the first; the safe rule is that such a mod is no switch:
  exefs_patches.collect bars it from exefs_switch.plan, so its patches and its module are built in or left
  out together as the mod is at the build, and switching it waits for a build.
- A mod that writes a word of one of the game's import stubs (PLT), or makes one, is barred too: the lift
  takes a stub as a call of its target wherever it is called, with no line of its own, so the stub kept
  the mod's change in every state while the host reported the mod as switched (review of #1036).
- A barred mod that is on has the reason in its files' note ("switched only by a build: ..."), which the
  Mods tab shows; plan keeps the kind "unaccepted" of a mod that is off and not accepted, so the list
  still names it with why (phase B's rule).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Phase B's rule (only a mod whose code the player accepted is built in or switched) missed the patch sets
of atmosphere/exefs_patches/<name>/: code_files and the host's code_hash read only <mod>/exefs, so a
patch set had no code, was never asked about, and its patches were taken unasked. Both sides now hash a
patch set's patch files in the folder itself (no modules there), and the migration (taken_before /
built_before) reads them there.

tests/test_exefs_switch.py, test_exefs_atmosphere.py and test_mods_switch.py came from before the
warning: their mods.json now accepts each mod's code (and a mod saved again asks again before its
switch is looked at); test_exefs_switch.py checks a mod not accepted is neither switched nor built in,
and that a mod with a code module is no switch through collect.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/mods.md has a section of its own for the switch: the state the game was built in is the one
compiled in the chunks and the hot file, the others in a64_switch_<n>.c; the lift's key holds no mod's
state and no list place of mods that do not meet (profiles share a translation); a translation again
exactly for a switch built in for good whose mod changed state; the mods that are no switch (a code
module, a hook site, an import stub, entangled hooks, past 64) and their note; two switched mods that
write the same bytes and are swapped wait for a build. A patch set's patch files are its code for
"accepted". The players' guide and the README say the same in short.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
"Restart needed: the mods" and "Restart to apply the mods?" read the same for
one mod or several, switched on or off, and the question put every changed
row into one sentence.

- The question counts what a restart applies ("Restart to apply 1 setting
  and 2 mods?") and lists it under that, a line each: the rows changed, the
  mods switched with their switch's word ("Character field swap (Off)"), the
  order when it changed. Eight lines at most; its window is as tall as its
  lines, and as before for one line and no list.
- The "Restart needed" line keeps the rows by name and groups the mods after
  them: one mod's switch by name, more as "2 mods"
  (menu_restart.h line_forms: the first form that fits the line).
- On the Mods tab the line is not shown while the selected mod's own
  switch, which its help says, is all that waits.
- menu_restart.h: mod_changes (what differs from the mods as the game
  started), list and line_forms, checked in tests/test_menu_restart.cpp;
  vk_menu.cpp keeps the mods as the game started before the Mods tab's
  first change. "the mods" stays for when they are not known.
- A mod switched since the start has the gold mark a changed row has, and
  its help says it takes effect after a restart.
- A mod's change is told to the restart state as set_row tells a row's:
  after Later, a mod switched again in the same visit to the menu is asked
  about at the next close.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
restart_values called mods_keep_start(), and restart_values runs on the draw
path (restart_pending in draw_options and draw_mods, inside menu_record,
without menu_mu), on the control bridge's thread (menu_setting_set -> set_row,
under menu_mu), from menu_tick and from menu_auto_for_gpu. Until the first
capture two of them could write mods_start at once and call host->mod_info,
which rewrites the host's notes, on two threads.

The start's list is now taken once, in restart_init (menu_init), before any
frame is drawn or the bridge sets a row: host/hos_main.c runs hos_mods_init
before hos_display_start, so the list is whole then. After it the draw path
and the bridge only read mods_start, as they read restart_state.start. The
call in menu_tick's Mods tab goes too.

tests/test_mods_menu.py: restart_init keeps the start, and nothing else calls
mods_keep_start; tests/test_menu_text_field.py's cut of restart_values
compiles again without a stub (it has none for mods_keep_start).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The review's suggestions on the restart texts:

- The "Restart needed" line: with mods switched and the order changed too, the
  order comes after them ("Music (Off), the mods' order", "2 mods, the mods'
  order"), where one mod and a new order read "1 mod" while the question
  listed the order. menu_restart.h mods_part, checked in
  tests/test_menu_restart.cpp.
- counted_mods has the third plural form counted_settings has (" mods (many)",
  for Russian and Polish at 5 and up), through one counted_text; a many form
  with no translation yet (the Mods tab's texts have none) is shown as the
  other form, never as its key.
- restart_line takes the caller's RestartTexts (which now carry restart_pending's
  bits): draw_mods asked the host for every mod twice a frame, through
  restart_texts and again inside restart_line.

tests/test_mods_menu.py follows: the line groups the mods with mods_part,
takes its texts from its caller, and the count's forms.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A restart switches a mod's files, its cheats and the ExeFS patches the build
made a switch (mod_switch.c), but not code that is not built into the game
yet (a mod accepted since the start, edited since the build, left out while
it was off) or code built in for good (a code module, patches the build could
not switch): that goes in or out at the next build. The restart texts said
"Randomizer (On)" for both.

- MkwVkHost.mod_build (API version 37; host/mods.c hos_mod_build): whether
  mod i, as it is switched now, has code a restart does not switch; on with
  patches or modules not in the game (or in another order than at the build
  with a mod writing the same bytes), off with code built in for good, as the
  tab's note says.
- menu_restart.h: a Mod's build flag; mod_changes says "<name> (On, its code
  needs a build)" for a switched one and counts them. Not switched, a mod
  that waits for a build is not listed (a restart does nothing for it); a
  mod whose warning waits is off and not switched, so not listed until it
  is accepted.
- The line counts them ("2 mods (1 needs a build)"); the question adds, when
  one is listed, that a mod's code that needs a build goes in or out when the
  game is built again and everything else applies at the restart.
- README's Mods paragraph and docs/using-mods.md say so.

Tests (written, not run): tests/test_menu_restart.cpp (the build flag in
mod_changes), tests/test_mods_switch.py (hos_mod_build for each made-up mod as
switched and switched the other way: switched patches need none either way;
edited or left-out ones need one to be on, built-in-for-good ones to be off),
tests/test_mods_menu.py (the API, the host's table and the menu's use).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A mod or a patch file named with a line feed and tabs ("x\nb_victim\tv.ips\t<fnv32>\tcode\tz.ips", possible
on Linux) made the build write a line that read as another mod's, and both readers (taken_before, built_before)
took the first line that matched: that mod's code was accepted at the next start without the warning.

- write_list leaves out the line of any file whose mod's or own name is not listable (a tab, a carriage return or
  a line feed in it, or not UTF-8), counts them in a comment and names them in the build's log; a note's breaks
  are spaces. The module entries go through the same list.
- Such a mod with code is never accepted, on both sides (code "unnamed"): mods.json could not keep its
  acceptance nor exefs_patches.txt its lines. hos_mod_code says why; the same holds for a mod whose folder's name
  is not UTF-8 (Linux), whose acceptance could not be saved and which was taken "once" at every start.
- exefs_patches.txt starts with "# exefs_patches.txt 2:" (LIST_HEADER); taken_before and built_before migrate
  only from a list without it, a build's from before, so the migration is one-time in fact. taken_before splits
  lines at line feeds alone, as the game does.

Test: tests/test_mods_list.py forged_lines (game and build, Linux names included).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c built_before took any kind that began with code or data (strncmp 4), so "code+switch<n>" and
"codex" migrated in the game and not in the build (nx2/exefs_patches.py taken_before required the word). Both
now take code, data or empty exactly, then a tab or the line's end; after the list header (the previous change)
the migration never reads a list of this branch, which is the only writer of "+switch", and both say so.

The build reads the list as the game does: under 16 MB, up to a NUL, lines at line feeds alone, the first line
for a file; a mod whose name starts with '#' (a comment line) is never taken, on either side.

Test: tests/test_mods_list.py migration_kinds (each kind, both line ends, first match, a '#' name).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods_list.c mods_list_mod_string takes an entry's first "accepted"; nx2/exefs_patches.py parse_entries took
dict(entry)'s, the last, so a list with both a stale and a current hash was accepted on one side and not on the
other. The build takes the first. A JSON null there was "no key" to the build (a migration) and "not a
string" to the game: both now take it as not a string, which matches no hash and is no migration.

Test: tests/test_mods_list.py accepted_twice (both orders, null and a number, with a list that would migrate).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c find_mods makes such a folder a mod of the usual layout (its code in its exefs folder, none when it
has none); nx2/exefs_patches.py patch_set made it a patch set whatever it held, so the build hashed and took its
loose patch files while the game hashed its exefs folder: the player's acceptance never matched, or the build
took code the game never asked about. patch_set has the game's condition now.

Test: tests/test_mods_list.py patch_sets (three layouts: the game's kept hash is the build's, and the build takes
what the game accepted).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The build read every patch file whole, unbounded, and FNV-1a'd it in pure Python, the files of mods it did not
take included, and read their code modules too; the game FNV-1a'd every patch file at every start, of any size,
when the mod's code could not be read. docs/mods.md says such a file "is not read".

- nx2/exefs_patches.py code_bytes: a code file read once for a build (keyed by path, size and time, emptied when
  collect starts), bounded by CODE_FILE_MAX. code_hash, taken_before, collect and nx2/exefs_modules.py collect take
  it, so the bytes the mod's hash is made of are the ones parsed and built in, and a file is read once whatever
  calls mods_in_order.
- A mod never accepted is hashed only for the migration from an old list; the files of a mod in asks are listed
  "unaccepted" without their FNV-1a and never opened; a module is read only when its mod is on and accepted.
- host/mods.c exefs_status does not read the patch files of a mod whose code is unreadable (or unnamed).

Test: tests/test_mods_list.py unread_files (a sparse 65 MB file, an unaccepted mod with a module: nothing of them
is opened by the build, the accepted mod's file once, and the game's log); the expected unaccepted lines in
tests/test_mods_list.py and tests/test_exefs_modules.py have no FNV-1a now.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Modding API spec 8.4: a code mod the last build did not take (new, edited since, or accepted since) is held back
whole until it is built in, since a mod with its files and without its code is a broken mod. The branch served
its RomFS and left the code for later ("On, its code needs a build").

host/mods.c: exefs_status runs before the files are indexed, and hold_back marks a mod that is on with a patch file
or code module not in the game as it is now: its RomFS files (and size table) are not indexed, its cheats are not
offered (hos_mod_cheats_dir), and its switch stays off. The Mods tab says it waits for a build; the restart texts
count it as before (hos_mod_build). A mod that cannot be switched and is turned off loses its files at once and the
tab says its code stays until the next build. The restart question says what applies when, both ways.

Docs: docs/mods.md (switching), docs/using-mods.md, README's Mods section.
Tests: tests/test_mods_list.py held_whole (held, built in, edited, off with code built in); the notes expected by
tests/test_mods_switch.py, tests/test_mods_modules.py and tests/test_mods_sizes.py (whose 01-first is all built
now, so its files are still served there).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Modding API spec 8.4: a patch that would break one of the engine's hooks means that mod is refused and named, not
the hook dropped. port_hooks (df36e979b) only named the place, and the lift then left Longshot's hook out
(widescreen, the field of view, the upscalers' camera jitter).

port_hooks now refuses each code or data file that changes such a place on this game version: "unsupported",
no writes, its note naming the place and the hook (and counting more), a log line a place. collect calls it right
after the files are classified, before the switches' plan, the overlaps and make_returns, so nothing applies or
weighs the refused bytes, and the lift finds the hooks' words as the game has them.

Docs: docs/mods.md, docs/using-mods.md, README's Mods section, nx2/exefs_switch.py's list of what is not switched.
Test: tests/test_exefs_port_hooks.py (the file refused with no writes and applied() empty, two places, refused
before the plan; what is not refused).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
exefs_switch.entangled compared the whole list only with one switched mod out at a time, and only the switched
mods' files. A hook whose way back (make_returns' RET) changes only when every other switched mod is out, the state
the game runs when that mod alone is on, was not found; nor a mod built in for good whose RET was decided with a
switched mod's bytes in the image, which the game runs with that mod off too.

entangled now compares every file that applies, and also each switched mod with all the others out, and all of
them out (for a built-in mod no single one explains). The switched mods whose absence changes a file are no
switches; a mod that is no switch already is not named. With one switched mod it compares too.

Test: tests/test_exefs_entangled.py (a stand-in make_returns: one out, all others out, a built-in mod, all out).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c switch_order told two switched mods that are on and swapped since the build, but the build's table
writes a mod built in for good among them too, in the build's order, and the game cannot follow a list that has
the switched mod and the built-in one the other way round either: it kept the build's order without a word.

The build marks the built-in file's line with the switch it meets and on which side (exefs_patches.overlaps:
"+over<n>", it was lower and its bytes win; "+under<n>", higher). switch_order compares that with the list now:
both on and swapped, both mods' lines say it waits for a build (whose bytes the game keeps), the log says so, and
hos_mod_build is true for both.

Tests: tests/test_exefs_overlaps.py (the marks, both sides, none for two switches or two built-in files);
tests/test_mods_switch.py (X built in for good above the switched A: said, hos_mod_build; in the build's order:
nothing).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A code module or a patch file applied for good that was edited after the build has no line with its new FNV-1a,
so host/mods.c counted it as "not in the game yet", or "not built in" while its mod was off or asked again,
though the version the build took runs until the next build; the restart texts said no build was needed to turn
such a mod off.

exefs_status looks for the file's line whatever its hash (old_line: a module, or code/data with no live switch)
before the warning and the switch: such a file counts as edited (exefs_old, module_old), waiting when its mod is
on, staying in the game when it is off (the log's count too). The tab says its old version stays until the game is
built again, never "not built in"; hos_mod_build is true for it either way.

Test: tests/test_mods_modules.py (a module edited, on and off; a patch file edited, off; hos_mod_build printed).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c exefs_status read every file of a patch set's folder (atmosphere/exefs_patches/<name>/) by the names of
an exefs folder: a subsdk file there was a module "not in the game yet", a main one "cannot be loaded", though a
patch set's code is its patch files alone (code_hash, and nx2/exefs_modules.py module_files, which reads exefs
folders only). It looks for modules in an exefs folder only now.

Test: tests/test_mods_list.py patch_set_modules (the game's and the build's hash agree, and no module is said).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
parse_ips expanded every RLE record (up to 65,535 bytes from 3 of the file) into the writes' dict before anything
checked where they land: a few hundred KB of runs made gigabytes. Given main's size (parse_file passes it), a run
past main, or records that together write more bytes than main has, stop the parse with a ValueError, and the file
is unsupported as one that writes outside main is. Without a size it parses as before.

Test: tests/test_exefs_patches.py (within main: the same; a run past it; 20,000 runs; classify_file says unsupported).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
OOT_EXEFS_MODULES_SHA1 was the SHA-1 of exefs_modules.json, which names each module's mod and file and carries its
note and FNV-1a: a renamed mod folder, or another note, translated the game again. exefs_modules.modules_key hashes
each built-in module's SHA-1 in order with the name the lift gives it (its copy, place and slot, which the image's
regions are named by) and nothing else, as exefs_patches.bytes_key does for the patch files.

Test: tests/test_exefs_lift_key.py test_modules_key (renamed, other notes, other kinds: the same key; other bytes or
order: another) and make_game.py's use of it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
svcQueryMemory answered an address of the image that no module region holds (between two modules, or after the
last one) as the whole image, one executable region: a module walking the regions, or the SDK's header search,
took unmapped memory for code. Such an address is free now, from the end of the region before it to the start of
the one after it, within the image. HOS_QUERY_MEMORY_OLD=1, or a build with no region table, answers as before.

Tests: tests/test_query_memory.py (the gap after the last module is free; a broken variant answering it as code
fails); tests/test_query_memory_free.py's fixture has an empty table, which keeps its one-region image.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game started with HOS_MODS_LIST (a launcher instance's list) left no note for the build, but left an older
one, from a start through a user folder, in place: a build without --mods then followed it and took the code mods
that other list accepted. note_state_file takes the note away when the list is named (and logs it), so such a
build reads the game folder's list. docs/mods.md and docs/development.md say that a builder for a launcher
instance must pass make_game.py --mods with the instance's list.

Test: tests/test_mods_list.py named_list (a note left by a start with another user folder is taken away).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Modding API spec 8.4 refuses the mod, not only the file that writes a hooked place (the previous change refused
the file alone, as its brief said).

- exefs_patches.port_hooks: every ExeFS patch file of such a mod is "unsupported" with no writes and f["hooked"],
  each note naming the place, its hook and the file that writes it; exefs_patches.txt writes the kind
  "unsupported+hooked". The refused mods are kept in hooked_mods, and nx2/exefs_modules.py collect refuses their
  code modules the same way (read for their FNV-1a only, never parsed).
- host/mods.c: a list line "+hooked" marks the mod; hold_back holds it back whole like an unbuilt mod (no RomFS
  files, size table or cheats, its switch off), the tab says "Left out: <the build's note>", and hos_mod_build
  stays 0 (a build would not change it).

Docs: docs/mods.md, docs/using-mods.md, README, nx2/exefs_switch.py.
Tests: tests/test_exefs_port_hooks.py (the whole mod refused, another mod kept, the list's kind, the modules' rule);
tests/test_mods_list.py hooked_whole (the build's module entry, the list, and the game holding the mod back).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A build from before this branch wrote names unescaped (a note's tabs as spaces), so a line with more than five
fields means a name held a tab, and such a name may have forged another mod's line. taken_before and built_before
(list_forged) migrate from no such list. A name with a line feed and no tab is not caught this way.

Test: tests/test_mods_list.py migration_kinds (a list with a six-field line is refused; a note with spaces is not).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Every lift writes a64_switch.c and nx2/build.py compiles it, and the
switched functions' versions as chunks (SWITCH_FILES in mem_need and
source_flags). test_mem_gate_leases cut mem_need without SWITCH_FILES,
test_a64_helper_build_flags' gen folder had no a64_switch.c, and
test_light_passes' switch-off case left out the versions its own
fixture writes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
dict(a, **b) takes string keys only; the writes are by offset.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
oot_patches.patch_file returns (text, counts, rows): the check of the
function as this lift wrote it took the text for the counts. The cut
test counts the versions that have a label to cut at: a version a
mod's patch makes straight code is left whole, as any small function.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
mod_text wrote the note with the detail line's bound, so every note was
cut at 320 bytes; a mod edited since the build, on, lost the line that
its old version stays. The note has room for what it can say at once.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
switch_order kept one other mod a mod: a switched mod that met another
switched mod and a built-in one, both in another order than at the
build, named only the last. Each pair is said, both ways, up to four a
mod (the rest counted).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
modcache/mods_json.txt was written only at a start that found the list
already there: the start whose change made it (the first switch or
move with --user) left no note, so a build that was not told the user
folder read the game folder's list until the next start. write_state
notes a list it makes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
code_hash read a mod's files in order and stopped at one over 64 MB:
the files before it were read for a hash that could only be
"unreadable". Their sizes are checked first, as no file of such a mod
is to be read.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Its checks after the note had not run since the switch: an accepted
mod that is off is built in behind its switch (kind code, off at the
start), not left out as "off"; the lift's key is bytes_key over what
the patches apply (lift_env), not the hash of a JSON of the applied
files; and a start with a mod that asks writes no mods.json, so the
forged-lines case takes away one that may not be there.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
On main, lift_key hashes a lift module by its code (code_prints), and
every module whole when one names a SOURCE_MARK that MARKS_NOT_OUTPUT
does not allow it. nx2/exefs_modules.py, a lift module since the code
modules, names __doc__ for argparse's description only, as
nx2/exefs_patches.py does: without its row a comment in any lift module
changed the key (tests/test_lift_cache.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The mods' files are indexed as layers of one view of the RomFS (host/romfs_layers.c, the Modding API spec's
file layers, section 4 and 6.1), which replaces host/mods.c's own index and its lookup: nn_fs.c asks
hos_romfs_resolve, prompts.c hos_romfs_file. The rule is the one before, last layer wins, and every layer's
copy of a path is kept under the served one, so merge_archives reads the copies from the layers instead of a
list of its own. The size table is served through the layers whatever they have (romfs_serve). With no mods
nothing is indexed or written (gate 5 of spec 16).

host/posix's FindFirstFileA now gives a file's last write as Windows does, which the layers keep beside each
copy for the merged-file cache that follows.

The checks that build host/mods.c over folders link the layers beside it (tests/mods_build.py names the files
once); tests/test_romfs_layers.py checks the layers alone.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The resource size table is still the game's with each mod's own table as a floor and every served file's
entry, pack members included, raised to fit; it is now kept with a record of what it was made of
(modcache/rsizetable.txt): this code's version, the game's and the prompts' tables, each mod's table and
each served file by its content hash. A start with the same files serves the table made before and reads
no file whole; a changed file, order or switch makes it again. This replaces the merge made at every start
(#134, #942).

host/modcache.c keeps the content hashes (modcache/hashes.txt), by each file's size and last write, so a
file is read whole once. The archives several mods have are keyed by the same hashes, not by reading every
copy at each start; their records' version goes to 3, so the archives made before are made once again.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A mod's folder named as an archive, romfs/<archive>.zs/<member path>, is that member's new bytes. It goes
into that archive, and into every pack of the game's that carries a member of the same path, since the
game loads a resource by its path once from whichever pack it reads first (Modding API spec 6.1). A
member new to the archive goes into it alone. The archive is the one the layers serve (the game's, a
mod's whole copy, or the archive made of several mods' copies); the mod lower in the list wins a member
two mods put in, and a whole copy lower in the list that changes the member wins over a member file
above it. The log names both and the Mods tab counts the members taken or unused.

The packs are written with restbl_sarc_put, a writer split out of #1089's restbl_sarc_merge (each member
keeps its archive's alignment, nodes sorted by hash, new names hashed by the archive's key), and kept in
modcache/files/ under the key of what they are made of, with modcache/members.txt for which game packs
carry which member paths: a start with the same files looks into no pack and writes nothing. Files no
mod that is on uses are removed, oldest first, once modcache/files/ holds more than 1 GiB.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A mod's patches/<path>.json beside its romfs sets, adds or removes keys of one BYML file (Modding API spec
6.1, parameter files): a file of the RomFS, or a member patched in every pack that carries it. The
patches of a file are applied in the list's order onto the file the layers serve (or the member a mod
puts in); two mods changing different keys both apply, and two setting one key to different values are a
conflict named in the log and on both mods' Mods tab lines ("Both A and B set Octorok's Life: B's is
used"), read from the ops alone. A mod lower in the list serving the whole file wins over the patches of
mods above it. An op that does not apply is left out and said; a file that is not a patch file is named
with its line and why.

The repo had no BYML writer: host/byml.c reads a document into a tree and writes it back (both byte
orders, versions 2 to 7, every node type the game's files use but aligned binaries), with bounds on
every offset, a depth limit and a node limit (a shared container is read as a copy each time). The patch
files are read by host/mod_patch.c's own strict JSON reader (UTF-8, depth and size limits). The patched
files are made in modcache/files/ by content, like the packs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/modcache.c over a made-up folder: a file's hash read once and kept by its size and last write, read
again when it is written; made files found by their key and note, not when changed in place; at the end
of a start the made files it did not use go oldest first over the cap, those it used stay, half-written
files and lone records always go; nothing written before a step asks.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A string of a patch file was given the rest of the file's bytes, never shrunk: a valid 1 MiB patch of
10,000 ops asked for gigabytes. Each string is now sized to its own text. A patch's target must be a path
inside the RomFS by nn_fs.c guest_path_ok's rule (no leading '/', no '.' or '..' part, no '\\' or ':').

host/byml.c also bounds the bytes it copies (strings, keys and binaries: 64 MiB in all), so one long
string referred to many times cannot ask for more, and reads a dictionary or hash map out of its keys'
order sorted (refusing a key twice): lookups by halves held only for sorted input, and writing a large
reversed one was quadratic.

mod_patch_touches, for which patch's value a conflict ends with (the next commit). Tests: a large valid
patch file, bad targets, the bytes' limit, a key twice, a large dictionary in reverse.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Against the archive made of several mods' copies, a member file was judged by the lowest copy even when
that copy left the member as the game has it: a mod above it that changed the member was overridden by
the member file's mod below it, or the member file lost and the log named the wrong mod. The layer that
changed a member is now the lowest copy whose member is not the game's (changer_of), for the member file,
its patches, the log and the made file's key (each copy's content and layer); the record keeps the layer
each part gave way to.

Also, from the review:
- an archive or a file where nothing needed making is kept as such (<name>.none), so the next start with
  the same files reads nothing;
- a conflict names the value used in the end, said once the patches are applied (an op of the lower mod
  that did not apply, a lower mod's whole file);
- the size table's key takes a mod's file by its path, size and last write, so a first start no longer
  reads every served file whole, and holds RESTBL_RULES, the sizing rules' version, bumped with them
  (tests/test_mods_packs.py ties it to the rules' text);
- modcache_stamp stats the exact path on Linux (host/posix's FindFirstFileA folds case and lists the
  whole folder);
- members and patches past what a made file's record holds are said in the log, not dropped silently;
- one mod's two folders with the same member: the winner by their paths, not by qsort's order;
- restbl_sarc_put leaves out a new member whose name's hash another member has.

Tests: a merged archive with a member file and a patch of it, a whole copy that leaves the member as it
is, the records of nothing to make, a hash taken, the rules' version.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The harness prints a "conflicts <n>" line beside each "conflict" line,
and the parser put the count where the list was.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A record's file was looked for by the path cut to the record name's
length less four, a path that is never there: every record went, and
with it every made file's next start.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
restbl_sarc_put refused a result larger than the archive and the
members together, but a member added takes a table entry and a name,
and every member's padding to its alignment can move: a member added
with its extension's 0x80 alignment refused the whole put.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Since #134, host/mods.c makes the size table from the game's (the
prompts' copy where there is one), each mod's table a floor and each
served file raised, and serves it from modcache/rsizetable.zs
(docs/modding/files.md). The routing cases still expected host/prompts.c
to merge the last mod's table into cache/prompts/rsizetable.mod.zs:
they check the made table now (two mods: both floors; no table of ours:
the game's; a grown or added file: its entry). A table that cannot be
read is still served as it is, as before.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
scripts/parity_gates.py plays one fixed scripted run through the control bridge
on two builds and compares them: gate 3 (behaviour: map, Link's age, life and
rupees exactly; position, facing and camera within a tolerance; changed flags'
values exactly), gate 4 (the save folders byte for byte, but caption.sav's date
and picture) and gate 5 (with no mods, no script runtime, merged-file cache,
broker or mod thread: a log, folder and /proc check). ab runs A, B and A again,
each a --mode shared job of the PC's queue, and measures the noise from the two
runs of A. A game run refuses to start outside a job or on a RAM file system.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/parity-gates.md: the scenario, what each gate compares and with what
tolerance and why, the noise, gate 5's log, folder, thread and process names
for the pieces still to come, the first runs that calibrate it, and the limits.
CONTRIBUTING.md lists it with the checks that need a run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review:
- SIGTERM (job_queue.py cancel) becomes KeyboardInterrupt: the run records why,
  quits its game and stops; ab passes it on to the queued run and waits.
- A value that is not a number never passes gate 3.
- A widened tolerance stops at a ceiling per checkpoint kind; two runs of A past
  it, or differing in an exact value, fail; noise of another scenario, of
  unfinished runs or with too many noisy flags or save bytes is not used.
- Gate 4 compares the save files copied and hashed before quit, needs a save
  the run wrote on both sides, and calls empty folders inconclusive.
- The second run of A reads the flags B saw change; a flag with a value on one
  side only is inconclusive, never a failure.
- Every exception is recorded in the result; both sides need every checkpoint;
  ab never passes a run that exited with an error.
- Run folders a1-/b-/a2-<label>; --name and --save may not leave their folder.
- Only --mode shared jobs, never on Windows; unreadable threads or children fail
  gate 5; run --dry-run prints its queue command; the caller's own HOS_, RX_,
  A64_ and OOT_ variables are dropped; encodings on every text open.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The language-neutral schema of the modding API (Modding API Spec 7.1, plan M4 piece 1),
as TOML in modapi/schema/: the global (has, apiVersion), log, game (state, version, the
frame and update events at the main thread's window acquire, plan S1), game.flags and
player read-only, with the permission, contexts, feature, phase and since of each.
Everything is 0.1.

modapi/generate.py checks it (names that work in JavaScript, Lua and C, every since 0.x,
no unknown keys) and writes, each naming the schema's SHA-256:
- host/modapi/longshot_api.h: the value model, tables, record descriptors and one
  thunk per function that checks context, permission, feature and arguments before it
  calls the service; no interpreter in it
- modapi/packages/api/longshot.d.ts (@longshot/api)
- the fake game's schema.json, the reference, the permission table and the generated
  blocks of the author's guide (docs/modding/)

tests/test_modapi_schema.py runs the generator's --check and compiles the header as C11
and C++17.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@longshot/mod-tools (Modding API Spec 13, plan M4 piece 2): the modding API with no
game behind it, implementing lib/schema.json and refusing to start when its services
do not match it. Each mod runs in its own node:vm realm with only the longshot global,
built there by a prelude from the schema (argument checks, on(), the language cuts of
7.2 and 12.3, frozen built-ins); only strings cross to the host. A test scripts the
game's state and steps frames, which fire each phase's events in order.

longshot-mod test runs a mod's test/*.test.js, each with a fresh fake game and
node:assert/strict. modapi/examples/heart-log is a small mod with its tests. Nothing in
it comes from the game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/modding/README.md says which kind of mod works today and which is a preview;
api-schema.md explains the layout and why, the schema's format, the C bindings, how
the fake game runs a mod, how to add to the API and where each later namespace slots
in. README.md points at it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- number is finite: lsapi_arg_number refuses NaN and the infinities (isfinite), and the
  schema says so (-0 may read back as 0).
- Every thunk checks the service's status (lsapi_done) and its result: ints within
  2^53, finite numbers, UTF-8 strings, enum indexes in range, records field by field
  (a generated lsapi_valid_<record>). A failure is the new InternalError, never a bad
  value handed to a script.
- The generator refuses names that clash once in C (fooBar and foo_bar, a has_ member,
  a type named like a built-in), C++ keywords, the names every JavaScript object already
  has (constructor, toJSON, then...), and type names that are taken or shadow a
  JavaScript global in longshot.d.ts.
- C strings escape control characters and trigraphs; doc comments escape */.
- --check (and so tests/test_modapi_schema.py) reads the fake game's services.js as text
  and fails when a schema function or event has no fake, with no Node needed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- Each mod's realm is created with vm.constants.DONT_CONTEXTIFY (a null-prototype object
  on older Node), so its global is not an object of the host's realm: a contextified {}
  let globalThis.constructor.constructor reach the host's Function and process.
- node:vm is still not a security boundary, and the docs now say so: the guide warns
  that the fake game runs a mod with Node's rights (test only mods you trust), and the
  sandbox it lists is the game's; prelude.js, fake-game.js and api-schema.md say the
  same.
- A call checks context, permission and feature before its arguments, as the C thunks
  do (a new bridge step); on() subscribes before it checks the listener.
- Strings with a lone surrogate are refused, log's parts included, as the C bindings'
  UTF-8 check refuses them; numbers must be finite (NaN and the infinities would cross
  as null); -0 is noted.
- The entry module and each round of listeners run with a time limit (2 s: an endless
  loop becomes a fault instead of a hang); a revoked permission or a removed feature
  stops its events; the fake's own result checks report InternalError.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- @longshot/mod-tools names @longshot/api as an optional peer instead of a dependency,
  so npm never fetches the unowned @longshot scope from the public registry; the guide
  shows both file: entries a mod needs until the packages are published.
- tests/test_modapi_schema.py runs longshot-mod test on modapi/examples/heart-log when
  Node 22 or later is on the PATH, and says it skipped otherwise. A schema function
  without its fake already fails without Node, in the generator's --check.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The release's amalgamated miniz.c and miniz.h and its LICENSE, unmodified, with the
upstream archive's and each file's SHA-256 in PROVENANCE.md (spike S10's answer).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mod_archive.c opens an archive through miniz's reader over its own read callback and
checks it whole before anything is unpacked: one disk; stored or deflate only; names UTF-8
(bit 11 or the 0x7075 extra field) or ASCII; no absolute names, drive letters, ':', backslashes,
empty, '.' or '..' parts, control characters, Windows device names or characters, trailing dots
or spaces, combining marks; no links or special files; no duplicates once case is folded, no
file that is also a folder; local and central names equal; entries sorted by local offset do not
overlap and end before the central directory; caps on entries, unpacked size and ratio; no
archive inside the archive, by name and by its first bytes. It unpacks into a fresh folder with
exclusive, no-follow creation and renames it to the package's SHA-256.

nx2/build.py compiles third_party/miniz (reader and inflate only) and gives host/mod_archive.c
its header. tests/test_mod_archive.py makes the archives it checks with zipfile and by hand.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mod_json.c is a strict JSON reader (RFC 8259, UTF-8 checked, no duplicate keys, no lone
surrogates): main has none to share. host/mod_manifest.c checks every field of section 5.2:
owner/name ids, major.minor.patch versions, the API version, entry, game builds, known
permissions and net origins, Factorio-style dependencies with version ranges, requires, claims,
multiplayer (state.write and items.grant cannot be local), saves, settings, replaces.

host/mod_resolve.c decides in steps that each judge every mod at once: pick versions (pinned or
newest), check API, Longshot, game build and features, drop mods whose dependencies fail in
rounds, then incompatible and claimed mods, then cycles; the order is dependencies first, then
the list's order. The launcher implements the same steps in C# against the shared vectors in
tests/mod_vectors, which tests/test_mod_manifest.py runs here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/modding/manifest.md: every field with its type and default, three example manifests, ids,
versions, the dependency notation, permissions, why a manifest is refused, the resolver's steps
with worked examples, and the reason codes. docs/modding/packages.md: how to pack a .lsmod or
.zip on each system, every check of the archive reader with its exact message and what to do,
and where unpacked mods go. docs/mods.md links them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The release's LICENSE has CRLF line endings, and the repository's * text=auto eol=lf could
check it out with LF and change its bytes. A .gitattributes of ours marks it -text, as
third_party/crt_shaders does; PROVENANCE.md names it as local and has the new tree-sha256.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A Zip64 extra field can give an entry 2^64-1 compressed bytes; miniz does not hold that to the
file, and the entry's end wrapped past zero, defeating the overlap and ratio checks. An entry
now cannot claim more than the file holds, and its end is computed without overflow.

The end of central directory record this reader checks must be the only one whose comment ends
the file, its central directory must end right before it (miniz takes bytes between as data
put before the archive and shifts every read by them), and miniz must have found the same
central directory, entry count and start offset.

Also: parts like a Windows 8.3 short name (PROGRA~1) are refused; an empty cache path is
refused and a drive root (C:\) keeps its separator; the final rename on Windows is tried again
on a transient denial; the header says why its narrower case folding fails safe. Tests: a
Zip64 size of 2^64-1, two end records, a fake one in the comment, bytes before the end record,
the entry, total-size and name-length limits (a limits mode in the driver), 50000 and 50001
entries, a 0x7075 field with the wrong CRC, short names. packages.md lists the new refusals.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
mod.json's reader compared each key with every earlier one, and the manifest each list entry
with every earlier one: a 1 MiB file of a hundred thousand keys took seconds at start. Both now
sort and compare neighbours, and an object or array of more than 4096 values is refused.
mod_json.h no longer claims mods_list.c's rules for duplicate keys, which it does not share.

tests/test_mod_manifest.py reads manifests of thousands of keys and claims, with and without a
duplicate, within a time bound. Two resolver vectors (a cycle of optional dependencies only, a
conflict that stays off when the other mod goes off too) and manifest.md say both rules.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The guide said the fake game has no time limits, but a round of listeners that runs over 2 s becomes a
Timeout fault (as docs/modding/api-schema.md says). It named new FakeGame({ strict: false }) without
saying how a test reaches it when longshot-mod test hands it a strict game: game.constructor with the
game's modDir and manifest, which index.d.ts now declares.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
longshot.game.on("no-such-event") said: has no event no-such-event (it has "frame", "update"). A
name with spaces or an empty one read as nothing at all.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
speedrun-timer counts time with frame and gives it to an area in update, logging a split per area and
the run's summary at the title screen. flag-tracker follows made-up flags with exists and get and falls
back when has() says the build cannot read them. misbehaving (a test mod, never to be published) breaks
each rule the fake game enforces, and its tests check each fault by name and the 3-in-a-minute stop.
heart-log gets the README the others have. Each runs with longshot-mod test, using only API 0.1.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
modapi/examples/lib-and-dependent: local/example-lib and local/example-dependent (>= 1.1.0), with
manifest variants the resolver must refuse or reorder: a library too old or pinned below the bound,
missing or off, an optional dependency, an incompatible rival, a cycle, and the cycle broken with ~.
Eleven resolve.json cases are built from those files, and tests/test_mod_examples.py checks they still
match them, packs both mods into .lsmod archives with zipfile, and has host/mod_archive.c take them
(and host/mod_manifest.c their mod.json) and refuse copies with a .. name or a name twice. API 0.1
has no calls between mods, so the dependency is shown at the manifest level only.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/modding/examples.md lists the five examples, what each shows, the command that runs its tests, and
what API 0.1 lacked while writing them; the index and the guide link it. tests/test_modapi_schema.py
runs longshot-mod test in every folder of modapi/examples with a mod.json, when Node 22 is there.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game services' first two pieces (Modding API plan, M3 piece 1), as a refactor: the same behaviour,
the old paths deleted.

- host/game/game.c game_call: the one way host code calls the game's functions. The Debug tab's
  pouch, clock and teleport calls (host/hos_main.c) each looked a function up, copied the context,
  set the stack and arguments and called it; they call game_call now. A guest thread that gave its
  virtual core up takes one back for the call and gives it up again (hos_vcore_held, new in
  host/hos_thread.c); a thread that is not a guest thread is refused. hos_call_guest
  (host/hos_hostcall.c), which nothing called, is deleted.
- host/game/flags.c: the one reader and writer of GameDataMgr. host/hos_main.c called the game's
  getters (f_8022d9c0, f_80cd0ea0) for Bools and String64s and walked the Bool table itself for
  writes; host/oot_state_tap.c read every container directly; host/oot_voice.c walked the Enum
  container a third way. All read through flags.c now: the state tap's bounded reader, moved, with
  the getters' layout (the Bool getter reads the entries flags.c reads). GameDataMgr's slot is in
  host/game/flags.h alone.
- nx2/build.py compiles host/game/*.c (objects host_game_<name>.o).

Two edges differ: a String64 is read up to 64 bytes (the getter path copied up to the caller's
buffer, 80), and the Voice Language option's entry index past the count reads as no option (the
game reads the first entry there).

Tests: tests/test_game_flags.py (flags.c over a synthetic GameDataMgr); the state tap, song
inventory, teleport minimap, perf pose, heart containers, voice option and HLE stats checks follow
the code to its new place.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The frame phase scheduler (Modding API plan, M3 piece 2; the interface script runtimes code
against, host/game/phases.h), with nothing added to it yet.

- host/game/phases.c: callbacks added to a phase run in order (by order, ties by add order),
  each called with the frame. A fixed table under one small lock, never held over a callback; no
  allocation; a run with nothing added is one relaxed atomic load and a return. A remove waits until
  the callback has returned, unless it is the callback's own thread; an add during a run counts from
  the next run.
- GAME_PHASE_ACQUIRE runs first in host/nn_vi.c hos_vi_native_acquire, the main thread's window
  acquire: once a frame in every state (spike S1), where the console blocks for a free texture and
  the pacing sleeps (outside the game's locks as far as is known; the present is not), before the
  pacing's early
  returns and its sleep (a callback's time comes out of the frame's wait), with the virtual core
  given up (nvnWindowAcquireTexture). The frame is the count of acquisitions before it.

Tests: tests/test_game_phases.py builds phases.c alone with tests/game_phases_test.c (order, adds
and removes inside a callback and from other threads while one runs, a full table, stale handles,
three threads churning against a running phase) and checks the empty run and the hook's place in
the source.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The control bridge's mem_read, mem_read_many and mem_write were served in the controller's read
(hos_control_input from host/nn_hid.c npad_states), which the game also makes from its job
workers in the middle of a frame (spike S1, wiki Modding-API-Plan): a read could mix two frames'
memory and a write could land while the frame's jobs ran, against docs/control.md's promise of one
frame's memory and writes between frames.

They are served in the frame phase GAME_PHASE_ACQUIRE now, at order 10 (hos_control_mem_phase,
added by hos_control_start only when HOS_CONTROL_MEM is on): the main thread, between its frames,
in every state. The bridge's presses stay in the controller's read. A request the game takes no
frame for replies timeout with "the game did not reach its next frame in time".

docs/control.md says where the requests are served, what between frames does and does not mean
(the background threads run on; the job workers having joined is not proven), and what changed;
and that input frames are counted in presents, not controller reads.

Tests: tests/control_test.c's stand-in game runs the phase before its controller read, and a
memory request with the phase held times out though the controller is read;
tests/test_game_phases.py checks in the source that the service is added at order 10 and is gone
from the controller's read.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game services' fourth piece (Modding API plan, M3 piece 4), for their first users, the script runtime's
game.state() and player.state() (API schema 0.1: the example mods heart-log, speedrun-timer and flag-tracker).

- host/game/state.c game_state_read: the mode (title, loading, play, paused, movie), the map (the game's own name),
  Link's age, loading, paused, an event playing and a movie playing, and game_state_features. The mode from what the
  host already knew: the flags (Sequence_CurrentBanc, _IsLoadingBanc, _IsChildhood), EventMgr's event (+104), the
  movie pacing's last movie update (host/nn_vi.c hos_movie_playing, now fps_refresh's too) and when Link was last
  updated, with the host's own times (250 ms: play, as hos_oot_player_seen; 90 s: a map loaded, as the Discord
  status). Paused is inferred (Link's update stopped). The time of day is absent: the host reads no clock.
- host/game/player.c game_player_read: present, position, facing, life, max life, rupees, and game_player_features.
  Link's actor is the one his update hands it (game_player_seen, from hos_oot_lift_player after its checks; this
  replaces hos_main.c's flight_player_seen, which hos_oot_player_seen(_ns) now read), used only within 250 ms and while
  his vtable and his movement's back pointer still name him; the position finite and within 1e6 m. Velocity and the
  wallet are absent: the host reads neither.
- Both read with game_peek (host/game/flags.c's bounded reader, now shared), no lock, no allocation, no game call;
  state.h and player.h say what may be mid-update at the acquire phase (spike S1) and how each read is kept safe.
- host/oot_state_tap.c reads the map, load, age, event, position, facing, life and rupees through them: its own
  reader, its copies of the flags' hashes, EventMgr's slot, Link's position offset and the facing's turn are gone.
  The position is now also refused past 1e6 m.
- docs/development.md: Game services, the services and their guarantees.

No guest address is new: each is one hos_main.c or the tap read before.

Tests: tests/test_game_state.py builds state.c and player.c with tests/game_state_test.c over made-up guest memory (the
features, every mode and its edges, Link's checks, unreadable fields left out) and checks in the source that the
services hold no address the host did not use, that Link's update hands them his actor and that the tap keeps no copy;
tests/test_oot_state_tap.py compiles the services with the sampler and reads the marks from them. Not run here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review of the first three commits:
- game_call put the whole context back after the call, poll too: a virtual-core request another thread wrote to
  c->poll during the call (hos_thread.c vc_acquire's kick, set only while vc_kick was clear) was lost, and the thread
  holding the core was never asked again. Every register is put back but poll, never written whole; poll is set again
  when a request was pending before the call or still stands after it (hos_vcore_kicked, new in host/hos_thread.c).
- A context that is not the caller's own (hos_ctx: the thread's, or the fiber's it runs) is refused.
- The refusal's log names its real reason: a negative count and arguments counted but not given were logged as
  "more than 8 arguments".
- game.h: a thread that gave its core up must not call while holding a lock a core-holding thread may wait on.
- hos_thread.c: hos_vcore_held moved above hos_vcore_checkpoint's comment, which it had split from its function.

Tests: tests/test_game_call.py builds game.c with tests/game_call_test.c (stub virtual-core calls logging their order, a
callee recording what it saw): back, the call, away for a thread without its core and neither for one with it; the
stack aligned down to 16, LR 0, x0..x7, *ret the callee's x0, the context put back; poll kept; every refusal calling
nothing. And hos_vcore_held, away and back cut from hos_thread.c: cores off, not a guest thread, held, away, escaped,
escaped then away. Not run here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review of the first three commits:
- phases.h: a guest thread holding a core must not remove a callback that may be running (the callback may wait for a
  core while the remove waits for it); game_phase_on_thread is 0 until the phase first ran with a callback added.
- phases.c: _Static_assert that a handle's low 8 bits can name every phase's slot.
- nn_vi.c: the acquire's comment said `until` is fixed before the callbacks; it is computed after them, from values only
  the present writes, which a callback cannot move.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review: hos_control_start added the acquire phase that serves guest memory after hos_control_serve had
started the bridge's thread, so a request could come before the phase that answers it. The phase is added first (when
HOS_CONTROL_MEM is ro or rw), removed again when the bridge cannot serve; a full phase table leaves the bridge without
guest memory (its requests answer unavailable) instead of turning the level off after the thread started.

Tests: tests/test_game_phases.py builds hos_control_start, cut from control.c, with stand-ins and checks the phase is
added at order 10 before the serve, only with guest memory on, removed when not served, and the full-table case; the
source check now asks for the add before the serve. Not run here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review: nx2/entry_hooks.py and nx2/standalone.py read only host/*.c for ENTRY_HOOK_SYM, imp_ and HLE()
definitions, while nx2/build.py compiles host/game/*.c too: one defined there would have been compiled but not hooked.
Both read host/*.c and host/game/*.c now (host/posix, Linux's Win32 stand-ins, has none). No file in host/game/ has one
today.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review:
- hos_main.c oot_map_refresh ignored game_flag_bool's result: the game's getter it called before wrote 0 for a flag
  not found, so the load and the age read 0 (not loading, the adult); they kept their defaults (the child) since the
  flags service. They read 0 again.
- tests/game_flags_test.c: a slot rewritten between game_flag_slot's two reads of it (its second read sees another
  entry) reads -1, with no key or value; tests/test_game_flags.py's hos_guest_range calls a hook of the test's for it.
  Not run here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The interpreter's sources only (quickjs.c and what it includes, libregexp, libunicode, dtoa, cutils.h, list.h, the
c-atomics header and LICENSE), unmodified, from the v0.18.0 tag's archive (sha256 28bcd89a...ff9f1dd, checked; the
copy compared with it byte for byte by check_third_party.py --upstream). Not quickjs-libc, qjs or qjsc. MIT.

nx2/build.py compiles its four sources with upstream's definitions, as a third-party part (so the release's
third_party_objects set carries it), and compiles host/modapi/*.c with its headers. Nothing of it runs without a
script mod (gate 5).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/modapi/runtime.c: a runtime per mod (JS_NewRuntime2 with an allocator that charges one counter per mod: 64 MB,
workers to share it), its context with the language and nothing of a host (no performance, atob, DOMException), an
interrupt handler on the clock (a callback is stopped at the first check past 5 ms; time in native code is counted as a
fault when it returns), unhandled rejections tracked, out of memory uncatchable (QuickJS-ng 0.18). Faults (a throw, an
interrupt, out of memory, a rejection nothing handled, an overrun) are counted: 3 in a minute stop the mod for the
session. 2 ms of a mod's script in a frame is warned about, 8 ms faults; 4 ms of all mods is warned about. Modules
are read as source from the mod's own folder only, by relative path; never bytecode.

host/modapi/bindings.c: longshot built from the generated tables (one copy of them: LSAPI_IMPLEMENTATION), every value
converted to the value model and back (strings, ints, numbers, booleans, null, bytes, handles, records with optional
fields and fields a build lacks; anything else as the fake game's display text), errors named as the API's,
lsapi_host_* (grants, features with their namespaces, events in load order, one callback at a time, each with its own
payload), on()/off(), and the prelude: eval and the Function constructors gone (stubs that throw), SharedArrayBuffer
and Atomics deleted, every built-in and longshot frozen.

host/modapi/services.c: has, the log (100 lines a second, one line each), game.version, the features this host has.
host/modapi/services_game.c: game.state, game.flags and player wait for M3's services: absent until then.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/modapi/loader.c with host/mods.c: a folder holding mod.json, or a .lsmod (or a .zip with mod.json at its root),
anywhere a mod may be, is one row of the Mods tab under its manifest's id, off until mods.json turns it on. The
resolver decides what loads against mods.json's order and switches (pinned versions too), this release, API 0.1, the
game's build and its features; a folder wins over a package of its id. A mod with a script starts only when every
permission it requires is granted in mods.json's "granted" list for it (the game-drawn prompt is a later piece); else
the log and the Mods tab say which are missing. Packages are unpacked into modcache/packages/<sha256> (checked
against the mod.json read before; stale .unpack-* folders swept: mod_archive_sweep). Runtimes are made at the first
acquire phase, on the game's main thread (game_phase_add orders 100 and 110), and frame and update are delivered
there to subscribers in load order; a stopped mod's subscriptions and runtime are disposed at the phase's end.

With no manifest mod the loader is never called: no runtime, no thread, no modcache folder, no line of its own (gate 5).
No hot reload yet: a switch applies at the next start.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
tests/test_modrt.py builds tests/modrt_test.c (a stub host, frame phases and a scripted game in services_game.c's
place) with the runtime and drives it: the prelude's cuts and freeze, imports (relative only, no escape, no links, no
bytecode), budgets (an endless loop, uncatchable interrupt, native overrun, a mod's frame, the warning), faults (3 in
a minute stop, 3 in two do not), out of memory uncatchable and the heap given back, unhandled rejections, the log's
limit, every kind of the value model both ways, records and missing features, errors by name, events and off(), and
the loader over folders and packages made in the test (gate 5, grants, the resolver, a folder over a package, a broken
mod.json, a package changed before its unpack, the stale unpack swept). modapi/examples/heart-log runs through the
loader with the scenarios of its own fake-game tests. Written, not run here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
game.flags.get and .exists hash the game's own flag name as the game does and read it through host/game/flags.h, the
one reader of GameDataMgr: a Bool reads 0 or 1, an Int, Enum or UInt its value; before GameDataMgr exists, get throws
UnknownName and exists says false. The features game.flags, .get and .exists are on. Longshot's flag name list, which
the API's docs promise, does not exist yet: any name the game has is a flag.

Depends on M3's host/game/flags.h and flags.c (bookmark mods/core); on this branch only the stand-in header is there,
so this commit is the one to keep or drop together with that dependency.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
QuickJS-ng 0.18 does not ask the interrupt handler inside native builtins, and several are reachable without
allocating:
- Array.prototype's methods walk ToLength(this.length) in C (join, reverse, copyWithin, splice, shift, unshift,
  slice, concat...): `join.call({length: 2**53-1})` froze the main thread for ever. The prelude now wraps each method
  to refuse a length above 2^22 (no array a mod's heap holds is longer), reading a length it would read twice (an
  accessor, an inherited one) once and handing the method a stand-in, refusing such objects for the mutating methods;
  concat checks its spreadable arguments too; flat and flatMap are JavaScript, so nested sparse arrays are interrupted.
- import() read and compiled a file in a native job, uncached on failure: refused now, always (the spec's modules are
  static imports; the fake game refuses it too). The deadline is also looked at between promise jobs: what is left
  stays queued and the call is a fault.
- Error.prepareStackTrace and Error.stackTraceLimit are accessors that Object.freeze leaves working (a mod's function
  ran inside the engine's error paths and got the frames' functions; the old limit leaked): fixed as plain values.
- BigInt maths near the engine's million bits takes seconds in C: not capped, a fault when it returns (documented).

Also: subscriptions reuse the slots off() frees and the 1,024 bound counts stored slots, ids are never 0 nor a live
one's, and one made during a round of events waits for the next; a Uint8Array argument is copied before later
arguments run the script's code; lsapi_result is zeroed before each call; the heap counter is charged our header and
an estimate of the C library's per allocation; unhandled rejections are attributed to the call they happen in and at
most 32 are kept (the rest counted); log lines lose C1 controls, NEL, line separators and direction overrides.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
part_ok refuses COM¹-³ and LPT¹-³ (Windows devices too); a module file is opened O_NONBLOCK and refused unless it is
a regular file (a FIFO no longer holds the open); the mods that start are started one a frame, in load order, instead
of every entry module in the first frame; of two folders with one id the first is kept whatever their versions, so the
folder host/mods.c serves files from is the one whose script runs. modrt_broken() tells host/mods.c a mod.json that
cannot be read.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c named a folder holding mod.json by its manifest id while nx2/exefs_patches.py still named it
local/<folder> and took a mod the list does not name as on: such a mod's exefs patches were built into the game with
no grant, even while it was off. Now neither applies the exefs patches or the cheats of a folder with mod.json
(exefs_patches.py leaves the folder out with what is below it; cheats.c gets no cheats folder for it): a manifest mod's
code is the unsafe tier's, behind its own grant. A folder whose mod.json cannot be read keeps its romfs served as an
emulator mod's, with a line in the log. docs/modding/manifest.md says so; tests/test_exefs_patches.py has such a folder.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
tests/test_modrt.py: Array.prototype methods over a huge length refused (an accessor's length read once, mutating
methods refuse it, concat's arguments, flat over a sparse 2^32 - 1 interrupted) and ordinary use kept; import()
refused; Error.prepareStackTrace and stackTraceLimit fixed; the normalizer's own .. guard; COM¹; a FIFO; deep recursion
caught and as a fault; a huge BigInt's text a fault; promise jobs out of time; off() frees slots and 1,024 at once;
a buffer detached while arguments are converted; log lines' controls and overrides; one entry module a frame.
Written, not run here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The hook compiler of the Modding API plan's M2, piece 1: one table of hook sites per game build
(game/<build id>/sites.toml), read and checked whole by nx2/hooks.py; each site found in main's code by
a signature of masked instruction words, exactly once or the build stops naming the site; and its hook
recorded where the lifter's emit picks it up (the kit's Lifter.after after a plain instruction, or
Lifter.site_entry, which a wrapper of emit_function puts first in the function, before its locals).
Nothing matches the lifted text. The host gives each site a flag byte and a callback slot
(host/game/sites.def, sites.c), so a dormant site is one byte load and a predicted branch.

The supported build's table is present and has no sites: the lift writes what it wrote before (parity
gate 1). A vslot kind (a vtable slot, data per build: the plan's S3) is in the format and stops the
lift as not implemented. The tables' hash is in the lift key; the builder package and the AppImage
carry game/; host/game/*.c is compiled.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The first feature moved from a text patch over the lifted C to the site table (the Modding API
plan's M2, piece 2). The site is after f_80b1e140+0x74, the load of a text pane's letter count
(signature: that ldrh, the cbz on it and the next tbnz, branch targets masked), with
host/oot_text_step.c's hos_text_letter_step as the engine's subscriber, on from the start.

The callback is the patch's C on the same registers: s0 times hos_text_scale when it is not 1, then
hos_oot_text_pane with x19. The patch ran after the count's test (cbz w9 to the return); the hook
runs before it, after the load, and the callback makes the same test itself, so it does nothing
when the game would return; the test reads only w9, which nothing in the callback writes. The
function keeps its registers in the context, now through the splice (guest_locals keep_spliced)
where it was through the patch's addresses. patch_text_speed and its constants are deleted.

tests/test_text_speed.py runs the old patch's C and the new hook with the callback, each in its
place, over counts, scales and times, and compares the whole guest context and the Text size calls.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/hooks.md: the format (with the Text speed site as the example), signatures and their masks, what
a table may hold under the rule that no game data leaves the PC, how a site is resolved and placed,
why a build stops there and what to do, adding a site or converting a text patch (with the parity
gates), and what a site costs at play and at build time. The development guide's layout names game/
and host/game/.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The site forms M2's conversions need beyond entry and after:
- entry with can_return: if (on && fn(c)) return;, as nx2/entry_hooks.py's hooks;
- return: the function lifted as f_1<address> under a wrapper f_<address> that calls it and then the hook, so
  every way out (ret, tail call, indirect jump) runs it and the body keeps its locals;
- before: before the instruction at offset, of any kind, after its label;
- replace: if (on) fn(c); else { the instruction }, a plain instruction only;
- branch: before a conditional branch, a non-zero answer takes it.
before, replace and branch are emitted by lines of nx2/fastfp.py's copy of the kit's emit_function tagged
"# (hooks)" (tests/test_fastfp_override.py takes both tags out before comparing with the kit), from
Lifter.site_before, site_replace and site_branch, sent to the emit's processes with the others. Every
callback is int fn(Ctx *): only can_return and branch read the answer (hos_text_letter_step returns 0).

Inline data rules (rule = mul_f32, scale_f32, note_u64): the compiler's own C inlined at the site,
reading a host value named in host/game/sites.def (HOS_VALUE, the feature's own variable): one load and
a predicted branch when off, no call. The host fills a value with one atomic store and a table by
publishing a new one with one pointer exchange, the old kept until a quiescent point
(host/game/sites.c hos_value_set, hos_table_publish, hos_tables_quiesce): no lock on the game's side.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
M2 piece 5. nx2/hooks.py patch_clashes(build_id, code, base, files) checks each patch file's writes on
their own against main's code as shipped: a write into a word a site is found by (its signature) or
hooked at (its point; the function's first word for entry and return), or one that makes the site's
signature match a second place, is a clash. nx2/exefs_patches.py collect refuses such a file (kind
"refused", the note naming the site), which apply() then leaves out and exefs_patches.txt and the Mods
tab report as cannot be applied; the other files apply and the build goes on. Files that stop a site
only together still stop the lift, whose message now says to turn the code mods off to tell.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The new-game opening's three text patches (nx2/oot_patches.py patch_opening) are the sites
opening.request, opening.timeline and opening.skipQuery: the entries of f_80d9a820, f_83b5bfb0 (can
return) and f_80de6cb0 (can return), with host/oot_sites.c's callbacks over hos_oot_opening.

Identity: the patches put hos_oot_opening(c, 0); and if (hos_oot_opening(c, k)) return; first in each
function; the hooks are first too, before anything of the function (its locals now load after them),
the flag on from the start, the callback that very call with its answer. The functions no longer
named by nx2/oot_patches.py may now get locals (nx2/ran_funcs.txt): only their bodies' C changes, not
what they do. patch_opening, its constants and its count are deleted.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
f_80bc72d0's text patch (if (hos_oot_trace_save(c)) return; first in the function: the save request
trace and the Insert menu's Transition autosave) is the site save.request, the function's entry with
can_return, its callback host/oot_sites.c's hos_site_save_request over hos_oot_trace_save.

Identity: the same call, first in the function, returning when it answers non-zero (it has set x0 to
0); what it reads (x1, x2, x30 and the stack at sp + 24) is the context as the caller left it, before
any of the function's locals are loaded, as before.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The four turn-speed functions' text patch (nx2/oot_patches.py patch_camera_speed: s0 times
hos_camera_scale in place of each return;) is four sites at = "return": camera.yawSpeed and
camera.pitchSpeed (f_80643f10, f_80643b60) and their level-2 pair (f_82ea21f0, f_82ea2220), with
host/oot_sites.c's hos_site_camera_turn_speed.

Identity: each function has one way out, its ret (no tail call, no indirect jump: read in the lifted
C), and the patch scaled s0 there after the epilogue; the return wrapper scales it after the function
has returned, with the same C (two volatile reads of hos_camera_scale, s0 written with the rest of v0
zeroed). The registers are the same when the caller gets them back. The functions' bodies may now get
locals (no longer named by the patches); the wrapper adds one call, which the compiler may inline.
tests/test_camera_speed.py runs the patch's C and the callback side by side.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
f_80825aa0's text patch (nx2/oot_patches.py patch_dynres: the config flag's test widened to
if (hos_fixed_resolution || !(w8 & 1)) goto fixed; hos_dynres_runs++;, and hos_fixed_scale_bits in place of
the fixed path's 1.0) is three sites with host/oot_sites.c's callbacks:
- dynres.fixedPath, a branch site before the tbz at +0x130: taken while hos_fixed_resolution is set;
- dynres.dynamicFrame, before the cmp at +0x134, which only the tbz's fall-through reaches (no label):
  hos_dynres_runs++;
- dynres.fixedScale, a replace site on mov w9, #0x3f800000 at +0x980: w9 = hos_fixed_scale_bits.

Identity: the patch's widened test is the branch site's test followed by the tbz's own; the count runs on
the same path, after the test; w9 gets the same value (one volatile read, the upper half cleared as
the mov's own second line does). The function keeps its registers in the context, as it did for the
patch. tests/test_dynres_sites.py runs the patch's C and the emitted hooks side by side.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The engine's two step divides' text patch (nx2/oot_patches.py patch_frame_seconds: base * the frame's
seconds in place of the quotient while host/nn_vi.c gives them, and hos_step_probe = x19) is three
sites with inline rules, no callback: frame.stepDivide (mul_f32 after fdiv s8, s1, s0 at
f_80706be0+0xe4), frame.globalStepDivide (mul_f32 after fdiv s0, s1, s0 at f_83b6ea90+0x68) and
frame.stepProbe (note_u64, x19 into hos_step_probe, after the first). host/game/sites.def names
host/nn_vi.c's own variables as the rules' values (HOS_VALUE frame.seconds, frame.stepObject): the host
side is unchanged.

Identity: the patch let the divide run (its flags as before) and replaced the quotient with base *
seconds read once from hos_frame_seconds_bits, base the dividend's register; the rule runs after the
divide with the same arithmetic on the same register (s1 is not the divide's destination in either
function), writing the result with the rest of v0 zeroed as the divide did. Expected cost: as the patch's,
one volatile load and a predicted branch at 60 fps or below, a multiply above; no call. The report's
"both or neither" rule and its unpatching go: the two sites are placed together or the lift stops.
The hook no longer depends on the divide's text, so the hot list's float-call rewrite cannot lose it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The acquire phase is the main thread's alone: the game's background threads run through it and the job
workers' join there is not proven (spike S1), so a hook on another thread may hold the old table at that
point. Each table counts its readers (hos_table_enter / hos_table_leave, for the first template that
reads one), and hos_tables_reclaim (was hos_tables_quiesce) frees a retired table once its count is seen
at 0 after the exchange. hos_table_publish calls it, and the first retirement adds it to the acquire
phase at order 20 (the engine's range); with no table replaced nothing is added (parity gate 5).
docs/hooks.md has the argument.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
services_game.c maps the schema's GameState and Player onto host/game/state.h and player.h: each field's
feature is on when the service says this build provides that field, and a field the service could not
read this time is nothing (a T? field) or 0. timeOfDay, vel and wallet have no service field, so their
features stay absent. Player's other fields are 0 while Link is not present, as the schema says; map is
the game's own name until Longshot's name list exists.

The schema put the wallet under player.rupees, which the game has while the wallet's size is not read:
wallet is a feature of its own now (player.wallet), regenerated. The dependent example shows the wallet
only where the build has it, with a test for a build without it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The runtime's lines all begin "script runtime:" (started, did not start, faults, budgets), it makes no
thread of its own (scripts run on the main thread at the acquire phase), and it unpacks packages into
modcache/packages, beside host/mods.c's size table and list note: the modcache row named only M5's
merged files. The names themselves already matched; no runtime change.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/, host/game/, host/modapi/ and host/posix compile into one folder of objects, named host_<file>.o,
host_game_<file>.o and host_modapi_<file>.o: host/game_x.c and host/game/x.c (or host/x.c and
host/posix/x.c) would be one object and the link would miss one. None clash today; the build now stops
naming both instead. The entry hooks' and HLE functions' scans read host/modapi/ too, which every
standalone build compiles (nothing there defines one yet). The joined lists build each file once on
both platforms, and miniz and QuickJS-ng are in nx2/third_party_objects.py's SOURCES.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/development.md's layout had game/ and host/game/ but not host/modapi/ or modapi/, nor miniz and
QuickJS-ng among third_party/. host/game/ is described the same way there and in nx2/build.py: the
Modding API's core below the script runtime (the game services, the frame phases, the hook sites' host
side). docs/modding/README.md said script mods do not run in the game yet, which M4 changed, and now
links docs/hooks.md for people working on Longshot.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The hook site callbacks became int (an entry that can return, a branch) after the text.letterStep site
was written, and the two checks still cut "void hos_text_letter_step(", which no source has: both would
stop on the missing marker. sites.h and docs/hooks.md said the sites' several subscribers come with the
script runtime, which is in without them: they come with the API's hook namespaces.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
An API feature's name is dotted parts, each starting with a lower-case letter, then letters of either case, digits
and _: a record field's feature is its record's path in the API's own names. A part starting with a capital is still
refused. Two vectors, valid and refused; the launcher's resolver takes the same rule when it next syncs the vectors.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The modding API reshaped before more namespaces are built on it (nothing is published, so 0.1 changes in place):

- Modules, no global. A script imports "longshot" (version, has, the error classes, the shared types),
  "longshot/game" (state, frame, update, flags), "longshot/player" (state) and "longshot/log"; each has named
  exports and a default, its frozen namespace object. Export lists are fixed per API version: a member a build
  lacks is there and throws NotAvailableError. "longshot/ui", "longshot/ui/jsx-runtime", "longshot/storage" and
  "longshot/worker" are reserved (refused naming why). The schema maps namespaces to modules ([[module]], a
  namespace's module key or its top-level name's); longshot.d.ts is one declare module per module. The runtime
  makes C modules (JS_NewCModule) from the frozen API objects; the fake game a vm.SyntheticModule per specifier.
- version is one frozen record { api, longshot, gameBuild } (was apiVersion and game.version()).
- Events are values: frame and update are Event<Frame> objects whose on(listener, options) returns a Subscription
  with off() and [Symbol.dispose] (the same function). Both carry { frame, dt }; frame needs no permission.
  on()'s options record (SubscribeOptions) has no field yet: an unknown one is an ArgumentError.
- Errors are classes made in each mod's realm: LongshotError extends Error; ArgumentError, ContextError,
  PermissionError (permission), NotAvailableError (feature), UnknownNameError (list, value), LimitError, HostError
  (was InternalError, which QuickJS-ng's own error collides with). The schema stays name-based with fields.
- log never throws: past 100 lines a second they are dropped and counted, and said once the second is over.
- player.state() is PlayerState | null; a field whose feature a build lacks reads null, never 0. game.state() and
  player.state() return frozen records carrying their frame, the same object within a frame. Opt<F, T> types such
  fields; longshot-mod types writes a mod's longshot-env.d.ts from its requires to drop the null.
- has() takes the closed feature list (a schema type, feature): any other name is an ArgumentError. Field features
  are named by record path (player.state.life, game.state.timeOfDay).
- Names and units: position/velocity, PlayerState, maxRupees (its own feature), flags.has; units in the schema
  ([[unit]]: QuarterHearts, Seconds, Hours).

The C side keeps every safety property (the prelude's cuts, the freeze, the array-length guards, no import(), the
budgets and faults); the examples, the guide, the API schema page, the reference and the tests follow.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The `storage` namespace of the Modding API (spec 9.5, 9.6; plan M6 piece 3): storage.global, storage.profile and
storage.save, each with get, set, remove, keys, used, schema and setSchema, and storage.save.slot. Values are
structured: JSON's data within api.toml's new [value] limits (64 deep, 256 KB), refused with where they fail rather
than changed. New permission `storage` (low), new error NewerData.

- The generator: structured `value` parameters and results (LSAPI_V_JSON, checked by the generated lsapi_json_scan),
  list results of scalars (LSAPI_V_LIST), `Value` in longshot.d.ts, a Values section in the reference.
- The adapter (bindings.c): a script's value to JSON text with every refusal named, JSON and lists back to the script,
  and a service's own error (NewerData) thrown under its name.
- The host (host/modapi/storage.c): one JSON file a mod and a scope under <user>/modstore (format 1, the mod's version
  and its schema number), written whole by one writer thread from snapshots of immutable entries; quotas 16 MB global,
  4 MB a profile, 4 MB a slot, 8192 keys, checked before anything changes. A newer version's data is refused and kept;
  a file that is not one is kept aside as .bad. storage.save is held in memory and follows the game's save moments:
  taken at the save request (hos_oot_trace_save), committed when the game has written the slot's progress.sav,
  reloaded when the game reads it, deleted with the slot (host/nn_fs.c), emptied on the title screen when game.state
  exists. The profile is keyed by HOS_MODS_LIST (new switch row) until profiles exist.
- The fake game: lib/storage.js, with saveGame, loadSlot, reload, copySlot, deleteSlot, storedData, seedStorage and
  storageSnapshot for tests.
- The example save-tally (all three scopes, a migration), its fake-game tests, and tests/test_modstore.py (the C side
  with the stub host, save-tally in the real runtime); the harnesses of three tests that compile cut source get
  stand-ins for the new calls.
- docs/modding/storage.md for authors: scopes, quotas, when save data commits, reloads, migration, the files, what the
  launcher must do, and what a game run must confirm.

Not run: no tests, builds or game (generate.py --check, node --check and cc -fsyntax-only only).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The storage branch on the reshaped API. The generator gains [[interface]] (types.toml): functions written once and
bound by every namespace that says implements = "Store", each binding a plain object (a Lua table) with its own paths
and features, one C service per function told which binding was called (lsapi_impl_store_get(ctx, binding, ...)), one
TypeScript interface, and the reference listing it once.

- longshot/storage is no longer reserved: global, profile and save, each a Store (get, has, set, remove, keys,
  usedBytes, dataVersion, setDataVersion: schema()/setSchema() and used() renamed; has new), values typed Value
- save.slot(), and the event save.loaded ({ slot: number | null }) when a slot's data becomes current: fired between
  frame and update (update is order 2 now), so a mod migrates there and its update sees the result
- QuotaError (scope) and NewerDataError (scope, version) are classes; services set an error's fields
  (modrt_error_fields)
- the files' "schema" is "dataVersion"; the name global is kept and why is written down (Lua 5.5, LUA_COMPAT_GLOBAL)
- save-tally migrates at start and at save.loaded; test_modstore, storage.md and the guide follow

Co-Authored-By: Claude Opus 5.5 <[email protected]>
game.flags.set, player.setLife and player.setRupees (spec 9.2, 9.3, 12.4; plan M7 piece 1). The permission
state.write (medium: "Can change your game and what gets saved") and the error Denied join api.toml.

The rules are one table, game.flags.toml's [[writable]] (bool 0..1, int 32 bits), [[deny]] (Sequence_IsChildhood,
Sequence_IsLoadingBanc, MapIconDeactivateByAreaActor, PlayerStatus.MaxLife, OptionData.VoiceLanguage, each with its
reason) and [[range]] (PlayerStatus.Life 0..MaxLife, PlayerStatus.CurrentRupee 0..999). The generator checks them and
puts them into longshot_api.h (lsapi_flag_kinds, _deny, _ranges), the fake game's schema.json and the reference's
Writes, so the game and the fake game cannot drift.

host/modapi/writes.c applies them in one order (acquire phase, deny by hash, play only, the flag, its kind, its
value; refused, never clamped) and keeps a trace of every attempt (the first taken write of a mod logged at info, the
rest at debug, the last 64 for dev mode). The game's half is services_game.c over host/game: a switch through the
game's own Bool setter (new host/game/flag_set.c, game_call, the setter hos_main.c's teleport already uses, which
queues the save's copy), a counter in place (flags.c game_flag_set_int). No new guest address.

The fake game applies the same tables (lib/services.js writeFlag), records game.writes, reads Link's flags from
setPlayer and takes setFlag(name, value, { kind }). tests/modrt_test.c gets the scripted game's half and a trace
command; tests/test_modrt.py checks the deny list, kinds, ranges, play only, the permission, a missing feature, a
write the game does not take, the trace, and that every denied or ranged name hashes to a flag the host's source
knows. Not run here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/modding/writes.md: what a mod may write, the flags it may not and why, the ranges, the order of the checks, what
a write means for a save (kept by the next save, no undo, the save's format unchanged), the trace, what is not
written (Link's position: no safe way to move him; velocity, the wallet, heart containers) and what a game run still
has to check. modapi/examples/rupee-rain: a debug mod that rains rupees up to 999 while its switch is on, clamping
before it writes and waiting outside play, with its fake-game tests. misbehaving gets five refused writes. The
README, examples, api-schema and development pages say where writes are.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The writes branch on the reshaped API, and the write semantics decided: a write is checked at the call and made after
the frame's update listeners (modrt_writes_apply; the fake game's _applyWrites), in call order, so reads within a frame
see the frame's snapshot and writes take effect by the next frame.

- game.flags.set(name, value): boolean, and player.set({ life?, rupees? }): boolean (all or nothing), replacing
  setLife/setRupees; outside play (or before the game's flags exist) a write returns false and writes nothing
- the deny list and a kind no mod writes throw WriteRefusedError (fields flag and reason: deny, kind; "flag", not
  "name", which is the error class's own); a value outside its kind or range is ArgumentError, never clamped
- the generator takes record parameters: an options record with fields, handed over by name (LSAPI_V_FIELDS) and
  checked by a generated lsapi_arg_rec_<record>; lsapi_function.record_args; PlayerChanges is the first
- the one schema table of kinds, deny list and ranges stays; player.set's record must hold exactly the ranges' fields
- rupee-rain and misbehaving, their tests, test_modrt's writes, writes.md and the guide follow

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game runs JavaScript only (spec 7.2), so a mod written in TypeScript is compiled before it reaches it:

- build: src/**/*.ts and .mts to dist/ as ES modules, one per file, relative imports as written (naming the built
  .js), nothing bundled; then the built modules are linked (not run) as the game links them, so an import of a file
  the build did not make, or of a name nothing exports, fails here. --check compares dist/ with a fresh build.
- The compiler: the mod's own typescript (transpileModule, file by file, target from its tsconfig.json, ES2023 by
  default), else Node's module.stripTypeScriptTypes (22.13+/23.2+; erasable syntax only, refusing enums, namespaces
  and parameter properties with a message), else exit 77 saying what to install. No dependency added, nothing
  downloaded.
- test: .test.ts files and the mod's src/ are compiled on the fly with the same compiler (in memory; node:module
  register hooks for the tests, lib/compile.js in the fake game, which runs a TypeScript mod's entry from src/).
  JavaScript mods are unchanged.
- check: mod.json and its entry, then tsc --noEmit with the mod's typescript.
- pack: builds, then packs mod.json, dist/ and the mod's other files (not src/ unless --with-source, tests, npm or
  TypeScript files) into <owner>.<name>_<version>.lsmod, checking every name against host/mod_archive.c's rules
  (docs/modding/packages.md) and the entry's presence first; a plain zip with no time stamps.
- index.d.ts: Assert and Tests types (export default {...} satisfies Tests) so TypeScript tests need no @types/node,
  a Manifest type, and no /// reference to @longshot/api (npm links file: dependencies, and it is not found from
  the link's real folder); the mod's tsconfig brings the global in.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
heart-log, speedrun-timer, flag-tracker and lib-and-dependent's two mods are TypeScript now, behaviour unchanged:
src/main.ts (lib: src/format.ts too, imported as ./format.js), test/*.test.ts (export default {...} satisfies Tests),
the recommended tsconfig.json (ES2023, NodeNext, moduleDetection force, strict, isolatedModules,
verbatimModuleSyntax, erasableSyntaxOnly, types @longshot/api), typescript 6.0.3 beside the two file: packages in
package.json, and "entry": "dist/main.js". tsc 6.0.3 checks all five with no error.

dist/ is committed where a check needs a runnable file with no compiler: heart-log (tests/test_modrt.py runs it in
the real runtime, now as dist/main.js) and lib-and-dependent's two (tests/test_mod_examples.py packs them, now with
what longshot-mod pack packs: mod.json, dist/, the README). Each built file's first line says it is built from src/;
they are typescript 6.0.3's output through longshot-mod's compile step. tests/test_modapi_schema.py runs
longshot-mod build --check on those, and treats exit 77 (TypeScript, no compiler) as a skip. speedrun-timer and
flag-tracker ignore dist/.

misbehaving stays plain JavaScript on purpose: it passes the API wrong types, which TypeScript would mark, and it
shows a mod with no build (its README says so).

The resolver's example cases in tests/mod_vectors/resolve.json and lib-and-dependent's variants say
"entry": "dist/main.js", as the manifests they must equal.

docs: scripting.md's getting started is TypeScript (layout, manifest, tsconfig and package.json, building, the
compiler order) with a short Plain JavaScript section, and the dev loop lists build, test, check and pack;
examples.md and the modding README follow.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The TypeScript branch on the reshaped API.

- heart-log, speedrun-timer, flag-tracker and lib-and-dependent's two mods in TypeScript import the API's modules
  (import { update } from "longshot/game"; import player from "longshot/player"...), subscribe through event objects
  and handle the nullable fields (player.state() null without Link; a field's feature in requires drops its null)
- longshot-mod build and check write longshot-env.d.ts from mod.json's requires (as longshot-mod types does) before
  they compile or type-check; the examples' tsconfig.json includes it, .gitignore and pack leave it out
- the build's link step knows the API's modules by their export lists (lib/schema.json), so a name a module does not
  export, or a module this API version does not have, fails at the build
- dist/ rebuilt for heart-log and lib-and-dependent with typescript 6.0.3 (longshot-mod build); every TypeScript
  example type-checks with tsc --noEmit
- the guide's TypeScript settings, packages.md and examples.md follow

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Modding API plan M4 piece 7 (spec section 11), the host's and the renderer's side of the UI contract:

- host/modapi/ui.c, ui.h: each mod's retained tree in an arena of its own (a node pool, an id index, its mounts), given back
  with the mod (modrt_destroy). A batch of ops (create, set, text, insert, remove, mount, unmount, slot) is applied with an
  undo journal: an op that breaks a rule or a cap rolls the whole batch back, and the refusal is a fault (modrt_fault).
  The closed element list and each element's props (style tokens, no CSS), the contract's caps (4096 nodes, 4096 ops,
  4 KiB text, 8 KiB props, depth 64, 4 windows, 8 HUD roots) and the host's own (1 MiB a batch, 16 slot fills, 64 slots).
  Surfaces: HUD roots by region, windows (a window the player closes is hidden at once), the settings page, and slots
  that other mods fill, composed in load order. One immutable snapshot (gpu/vk/modui_snapshot.h) built after the reap
  at the acquire phase and handed over by an atomic exchange; events from the renderer queued and delivered to the
  owning mod's sink before the frame event. commit(ops) and onEvents(fn) for the JS side's longshot/ui
  (modui_js_define), not in the API schema yet.
- gpu/vk/vk_api.h: MKWVK_API_VERSION 38 (after the code mods' 36 and 37), MkwVkHost.ui_snapshot and ui_post (host/rx_backend.c).
- gpu/vk/modui_layout.cpp: the flex subset (gap, padding, grow, width, height, align, justify, wrap) in the 1920x1080
  virtual space, scaled ultrawide-aware as host/hos_wide_ui.c places the HUD; the HUD's 3x3 regions; navigation by place.
- gpu/vk/vk_modui.cpp: the HUD over the game, windows with the game's title bar, the Insert menu's look (rows, cells,
  buttons, help box, prompt strip), focus from layout with keys, controller and mouse, scrolling, text entry, key
  binding; events posted back. A focused window holds the game's input back (option 1) and takes its keys before the
  menu (menu_tick); nothing drawn and no ImGui frame for it without a mod UI. modui_draw_settings for the Mods tab.
- docs/dev/reference/architecture.md, Mod UI in the renderer: the renderer's rules for it.
- Tests (written, not run here): tests/test_modui.py (the host's side built alone, and the wiring),
  tests/test_modui_layout.py (layout on synthetic trees); test_hos_ab.py and test_modrt.py follow the table and ui.c.

Not yet: Image, Icon and Canvas keep their place and draw nothing of the mod's; World is refused; the HUD is not hidden
with the game's; the Mods tab's call to the settings page; the UI's permissions.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/modding/ui.md: the ops and events, the host's entry points, the caps, the elements and their props as implemented,
layout and the virtual space, the surfaces and the HUD's regions, slots across mods, the snapshot's handoff, where it is
wired and what is not there yet. Linked from docs/modding/README.md and the layout table of docs/development.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The authors' guide to longshot/ui takes docs/modding/ui.md (the JS side, joined next): the channel's doc for
contributors, and every comment and refusal that cites it, name ui-channel.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The Modding API spec's 11, decided: the reconciler is JavaScript run inside each mod's own runtime, shipped by the
host as the modules "longshot/ui" and "longshot/ui/jsx-runtime" (no longer reserved); the host composes mods.

- modapi/ui/runtime.js, one function expression called with the UI channel's native part (commit, onEvents; and
  requestFlush, settings when the host has them) and the mod's own longshot/game and longshot objects. A fiber per
  element; function components re-render on their state, a useGame value, a setting, or props that changed
  (shallowly); children matched by key, else by place; the difference emitted as the contract's ops (set with only
  the props that changed, inserts by a right-to-left walk that keeps what is already in order, removes of the top
  host nodes only); handlers kept in the mod ("onPress": true is sent); events mapped back by node id. At most one
  commit a frame, at the end of the update round (requestFlush; a promise job until the host has it). Hooks:
  useState, useReducer, useRef, useMemo, useEffect (after the commit, cleanups on change and unmount), useGame
  (selectors read at update, shallow compare), useSetting, useEvent (event values of the reshaped API), useFrame. The
  game's events are subscribed only while a hook needs them: an idle tree costs nothing a frame. A component that
  throws is a fault naming it (and its owners), and takes its mount down; a refused batch makes it send its trees again.
  Elements are typed components (Row ... Window, SettingsPage, World stub, Canvas place only, Slot); mount() with a
  disposable handle (update, open, close, isOpen, unmount, Symbol.dispose); a slot filled with surface "slot".
- The schema: a [[module]] may be js + types, JavaScript the host ships with hand-written declarations
  (modapi/ui/longshot-ui.d.ts, included in longshot.d.ts: elements as components, props per element, empty
  JSX.IntrinsicElements). generate.py makes host/modapi/ui_js.h (a C string naming the source's sha256) and the fake
  game's lib/ui-runtime.js from the source; lsapi_module gains js.
- The host: host/modapi/ui_module.c evaluates the source at the mod's first import of either module and bindings.c
  makes C modules of what it returns, as for schema namespaces.

Tests (written, not run here): tests/test_modrt.py imports both modules in the real runtime, checks they are made and
frozen, a Hud mounts without a fault, and a component that throws is a fault naming it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- lib/fake-ui.js applies a mod's batches with the game's host's rules (host/modapi/ui.c on mods/ui: its element list,
  props_table, ops, mount and slot rules, caps): a batch it refuses is refused whole and is a fault, as in the game.
- game.ui reads the tree (text, find/findAll/query by text, RegExp or fields, hud, window, windows, settingsPage,
  fills, mounts, toString, commits, lastBatch, refused) and acts as the player (press, change, submit, focus, blur,
  layout, close): each an event the mod gets at its next frame, refused when the game could not send it (no handler,
  disabled, on the HUD, in a closed window).
- The reconciler is the game's own source (lib/ui-runtime.js), evaluated in the mod's realm at its first import; the
  prelude makes its native part there (commit, onEvents, requestFlush, settings). Events are delivered before the
  frame event, the batch after the update event.
- Declared settings (mod.json "settings"): game.setSetting as the player, game.setting to read; useSetting's set.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- docs/modding/ui.md: a first HUD in TSX (tsconfig with jsxImportSource "longshot/ui") and in plain JavaScript with
  h(), the components and elements and their props, keys, surfaces and mount()'s handle, slots, the hooks and their
  rules, style tokens and layout, performance (an idle tree costs nothing; one batch a frame), errors, limits, testing
  in the fake game, and how it works. The host side's channel page is linked as ui-channel.md.
- modapi/examples/link-hud: Link's hearts and rupees on the HUD through useGame, and a window with a List and a Button,
  in TSX (src/main.tsx, compiled to main.js by TypeScript 6.0.3 with no error); its tests read the HUD and the window,
  check that an idle frame sends nothing and a change sends one op, press, choose and close.
- modapi/examples/ui-cases: a test mod with one case per rule of the reconciler (keys that move without being made
  again, effects and cleanups, a component that throws, hooks out of order, useFrame, useGame, useSetting, a slot, text
  input and a list, a refused batch), picked by a setting.

Tests written, not run here (tests/test_modapi_schema.py runs every example's).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The JS side's reconciler meets the UI host side (host/modapi/ui.c) in place of the stand-in it was written against.
native.requestFlush(fn) is the host's now, as the fake game's: fn is called once, in load order, at the end of the
frame's update round (modui_update_end: after the update event's listeners, before the frame's writes are made and
the snapshot is built), under the callback budget; asked again before then, the newest fn is called, still once; asked
while it runs (an effect that sets state), it is the next frame's. Without it the reconciler committed from a promise
job.

The direct runs of tests/modrt_test.c step the UI as the loader does, and test_modrt.py checks the order (a render
at the end of each update round, an effect's state the next frame's). test_modui.py cuts the joined loader (the frame's
payload, modrt_frame_begin first) and checks requestFlush's place. The channel's doc says requestFlush, and what is
left: the UI's permissions and the settings registry (useSetting throws NotAvailableError in the game until the
settings service).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Spike S2 of the Modding API plan, read from the game's code on this PC: every add to the pouch found
passes through f_8112d570 with the game's own reason (the play report pouch_content_change sits there);
songs are IsGet flags, rupees and hearts are Link's; a checked place is a Bool64bitKey flag by its
placement id, whose setter was not found, so checks are a comparison of that container between frames.
docs/items.md has the evidence, what is covered and what is not, and the game run that confirms it.

Three sites: items.pouchAdd and items.pouchAdded (the add's entry and return), save.load (the sequence's
load of the save data), each resolving once. host/game/items.c records the adds from the game's threads
and hands them, the checks, the songs, a save and a load over at the acquire phase; it gives an item
through OneShotAddOrRemovePouchContent, the Debug tab's call, whose addresses move here from
host/hos_main.c. The save requests let through are told to it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The items namespace of API 0.1 (modapi/schema/items.toml): items.checked (a place checked: map/id, and
whether the game resets it) and items.granted (an item reached the inventory: the game's actor name, the
count, the game's reason, and the mod and key of a mod's grant), both fired after update from the item
service; items.grant(item, count, key), items.pending() and items.held(item), with the permissions
items.read and items.grant.

host/modapi/items.c keeps each mod's grants in longshot_mod_items.txt in the user folder: queued, given
(since the game's last save: a load or a new start queues it again) or saved (a key stays known for ever).
One grant a frame goes to a running mod that holds items.grant, in play only.

The schema keeps API 0.1's shape (longshot.items.on("checked"), errors by name); the reshape into modules
with event objects and error classes maps each [[event]] and throws name one to one. grant answers
queued/known rather than a Promise, and takes scalars rather than an options record, until the bindings
have both. The fake game scripts checks, items, saves and loads; tests/test_game_items.py checks the
service and the queue with made-up guest memory and a scripted service.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
item-tracker logs checks and items with the game's names and reasons, and what Link holds at the start;
check-gift gives a bomb for each place checked, once a place by its key, again after a load before a
save: a multiworld client's core. Both with their tests in the fake game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The items namespace joins the API's modules: `import { checked, granted, grant, pending, held } from
"longshot/items"`, its events values with on() (order 3 and 4, after storage.save.loaded and update, fired from
modrt_items_frame after update and before the UI's flush), its errors the classes (UnknownNameError with the list
"items", ArgumentError, LimitError).

grant takes an options record, GrantOptions { count?, key? }, as the spec has it; the record itself may be left out
(grant(item): one, no key). The generator learns that: the last parameter, when it is an options record, may be
`optional = true`; its thunk takes argc N-1 and hands the service a record with no field (lsapi_no_fields), the C
adapter drops a trailing undefined record, the fake game's prelude does the same, and TypeScript sees options?. A key
given is 1 to 200 bytes (empty is ArgumentError: leave it out). grant still answers "queued" or "known" at once:
the generator has no asynchronous call yet, so no Promise; the mod hears its grant arrive through granted.

The fake game's items join its save slots: saveGame(slot) keeps the grants given so far, loadSlot and reload give
back those given since (its own saveGame/loadSave are gone). item-tracker and check-gift import their modules; their
tests use loadSlot and PermissionError. tests/test_modrt.py checks the options record left out, undefined and given;
modapi_items_test.c the defaults.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The launcher's Browse installs a portal mod into mods/<owner>/<name>/ with its mod.json, and names it owner/name in
mods.json. The loader now holds a folder to its id's path: a folder with mod.json inside a folder of the mods folder
is its manifest's id (checked by the manifest's id rules) when its path ends in <owner>/<name> of that id
(mods/<owner>/<name>/, or deeper, as emulators keep folders of folders); one that does not is refused with the reason
("its folder mods/o/renamed is not where its id o/original goes"), under local/ and its path, and nothing of it is
served (modrt_broken stays for an unreadable mod.json, whose romfs folder is still an emulator mod's). A folder
directly in mods/ (mods/<name>/, no owner folder) may hold any id, as a mod being made sits; a folder without mod.json
is local/ and its path, as before.

tests/test_modrt.py: placed, deeper, directly in mods/, renamed and elsewhere. manifest.md (Ids), packages.md, mods.md
and the author's guide say where a folder goes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From writing the sample mods (modapi/samples/README.md's awkward list):

- has(name) answers false for a name that is no feature of this API version, where it threw ArgumentError: a mod
  built for a newer API must not throw on an older game, it asks. The types keep the closed Feature union (this
  version's names, so TypeScript still catches a typo); at run time any text is taken (lsapi_arg_feature gives
  LSAPI_FEATURE_NONE, which lsapi_impl_has answers false; the fake game's values.js the same). A non-string is still
  ArgumentError. misbehaving's unknown-feature case now logs false; test_modrt.py checks it.
- useGame(selector, isEqual?): the value is compared shallowly by default, Object.is or, for two plain objects or two
  arrays, their own keys' values one level deep (a class instance or a Map is compared by identity, no longer by its
  empty key list); isEqual(previous, next) decides instead when given. ui-cases' purse and tens cases test both.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
prelude_src ended in a call, `})(globalThis)`, so JS_Eval ran it at once with no modules and no error spec, and every
modrt_create failed with "the prelude failed: TypeError". It is the function now, as ui_js.h's source is, and
modrt_prelude calls it. test_modrt.py's first check is that a mod starts and logs, and stops the run when not.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
game_items_give wrote a song's IsGet flag with game_flag_set_bool, the live byte only: the save's copy never had it,
so the next load took the song away while the grant counted as given. It is game_flag_set_bool_queued now, as
writes.c's switches are (the live value and the save's copy, at the game's next update); the grant's tag waits in
song_tag until the poll sees the flag set, which reports it then (song_was is no longer set before the setter has
applied). A second grant of the song before that is taken without a report; a load before it clears the tag (the
grant's queue gives it again). game_items_test.c stubs the setter's queue and the game's update and checks the save's
copy.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
modrt_items_parse_line read the escaped key with %602s into 602 bytes: the 603rd, the NUL, went past it. The buffer is
604 bytes and the width 603, so a key longer than the longest (200 bytes escaped: 600 characters) is seen and refused
rather than cut to fit and read as another key. modapi_items_test.c reads the longest back and refuses one byte more.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
commit skipped the write for a playthrough whose storage.save the mod never touched, and for a newer version's data,
leaving whatever the slot held: another playthrough's file, read back at that slot's next load. A skipped commit now
queues a JOB_DELETE_FILE for the mod's file of that slot, in order with the writer's other jobs (a later write of the
same file stays after it; peek_queue sees the file as gone). A newer version's data saved to the slot it was read from
is kept as before; saved to another slot, that slot keeps none of the mod's data (said in the log). The fake game's
storage matches. test_modstore.py: a quiet mod's new game over an old slot, and a newer version's data saved elsewhere.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Nested Rows that overflow measured each child again at a narrower width at every level: some 2^depth text measures a
present, on the thread that presents and under its lock. Layout now asks a MeasureMemo first, by (node, max_w, max_h):
a node d levels down is asked about at most d + 1 rooms, so the calls grow with nodes times depth. vk_modui.cpp keeps
one memo for the HUD and windows and one for the settings page across presents, while the key (the snapshot's serial,
the text's scale, the tabs shown) is the same; placing is then one walk. Tabs' measure clamps the selection as place
does, so it measures the tab shown. test_modui_layout.py: 24 nested overflowing Rows within nodes squared measures, none
again on the next layout with the same memo; a Tabs selection past its last tab.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
QuickJS-ng's interrupt and out-of-memory skip catch and finally, so a flush cut there left `flushing` (and a render's
`current`) set for good: request() and flush() returned at once, and the UI never changed again. Now:

- request() is not guarded by `flushing` (a request during a flush is the next frame's at the host anyway);
- flush() entered with `flushing` set treats the last one as cut short (cutShort): its ops, effects and errors are
  dropped, nothing of the fibers is trusted (a render may have stopped half way), each root's tree is made again from
  its element, and resync is set;
- a resync starts its batch with a new op, ["reset"], which removes every node of the mod's on the host (ui.c
  op_reset, journaled like the others; the fake game's UI the same), so it never needs to know which roots the host
  kept from a batch whose answer it did not see (cut after native.commit). committedRoots is gone;
- the host's callbacks (update, frame, events) clear a stale `current`, so hooks and mount() are not refused after it.

ui-cases' hang case: a render stopped by the time limit, then the next press resets the host and renders anew.
modui_test.c: reset, refused with a later op on a removed node (nothing changed), its ids free after it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
MODUI_OPS was 4,096, as MODUI_NODES was, and mod_json's arrays stopped at 4,096 values too, while a tree sent whole (a
resync) takes some 3 ops a node: a mod near its node cap could never send its tree again, and resynced forever. The
nodes are the spec's 12.6 number now, 2,000 (a string's Text counts); the ops 4 a node and some (8,192), and the batch is
read with mod_json_parse_members, a per-parse cap of values in one array or object, so mod.json keeps its 4,096. The fake
game's caps match; ui-channel.md and ui.md say both, and that a tree with long texts can still pass the 1 MiB batch.
modui_test.c: the caps from their macros, and a full tree (a Hud and 1,999 Texts made, given text, inserted, mounted)
in one batch.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The launcher leaves out of Browse and installs the mods whose manifest's api this game would turn off. The build writes
mods_api= beside version= and source=, from host/modapi/longshot_api.h's LSAPI_VERSION (the schema's version, the API
compiled in); a folder built without the header has no such line. docs/mods.md says so; tests/test_mods_api_stamp.py
checks the version read, its absence, and where the stamp writes it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- json_value: json_string's failure on a key past LSAPI_VALUE_BYTES came back as -1, "an exception is pending" when
  none was: the call failed without its reason. json_string now answers -2 for that (json_put said why), and a key's
  -2 is a refusal: ArgumentError, "more than 262144 bytes". test_modstore.py sets a 300 KB key.
- The results cached per frame are keyed on modrt_frame_no, which only on_frame advanced; a round where on_update came
  without it (frame's skipped) handed out the earlier frame's state(). on_update advances it too.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c calls the loader (modrt_found, _broken, _listed, _resolve, _loads, _start, _tab) since script mods came,
and test_mods_list.py, test_mods_size_table.py and test_mods_sizes.py build it without host/modapi/: they could not
link. tests/modrt_stub.py holds stubs of the seven, a game where nothing is a manifest mod; the first two link them as
a file of their own, test_mods_sizes.py puts them ahead of its cut of mods.c. (test_fs_links.py cuts index_romfs only,
and no other check links mods.c.)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- ui.c: the slots a removed subtree declares leave nslots in the batch that removes them (a batch may remove one and
  declare another at the cap), and come back when the batch is refused (rollback's U_REMOVE); slot_release no longer
  counts a removed node's twice at keep.
- ui.c: a Window's `id` prop passes name_ok, as mount's opts.id does (it is the window's key); the fake game's UI too.
- ui.c js_sink: an event's payload was leaked when its array could not be made; each value is now freed where its
  Define did not take it.
- ui.c journal_mount: the strdup copies of the old strings were dead work (every caller sets or clears the mount
  whole) and are gone.
- ui_module.c: native has no prototype, and the reconciler reads settings and requestFlush only as its own properties
  (the fake game's native the same), so a mod's Object.prototype.settings is never taken for the host's.
- runtime.js: a Text's lone surrogates and NULs become U+FFFD (wellFormed) rather than a refused batch and a fault.
- loader.c: with no mod running, on_update still calls modui_frame_end, so the snapshots the renderer gives back after
  the last mod is reaped are freed (one load when there are none).

Tests: modui_test.c the slots' cap across a remove, a refused remove and a reset, and a Window's id; test_modrt.py a
Text with lone surrogates and a NUL costs no fault; test_modui.py the loader's free with no mod running.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- modui_tick: a snapshot gone (NULL) after one lets go of the old one's state (by_key, scroll, tabs, the windows, the
  focus) and of the mouse, so a new mod UI is adopted afresh and the pointer is the game's again.
- adopt: the scroll offsets, tabs and layout sizes of nodes no longer in the snapshot are let go: those maps never grow
  past the mods' nodes.
- A scroll offset is clamped to what the Scroll (or a window's body) holds past its view where it is stored, by the
  wheel and by the focus kept in view, not only at layout: scrolling back after the end moves at once.
- The mouse finds a control in its clipped rectangle (Focusable.hit), never where a Scroll hides it; the keyboard and
  the D-pad still reach it (and bring it into view).
- A List posts CHANGE only when its selection moves, not each time the pointer passes over the selected item.
- A HUD root is placed at most its cell's width, its own width or not.
- GetAsyncKeyState is read only while a window of the game's process is in front (the menu's test), so Enter, Esc or
  Shift held in another program is not the game's.

test_modui.py checks each in the source.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
hos_fs_wait_writes flushed host/modapi/storage.c first and waited for the game's open write after, so a save and quit
had the mods' storage flushed before the game's save had finished: the slot-written moment it notes came too late for
that flush, and storage.save was not committed to the slot just saved. The wait for the game's write comes first now,
then modstore_flush (which acts on the notes it finds). test_close_waits_for_save.py: the flush after the wait.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- load_file reads the file's "format" before judging its shape (format_of): a newer format's file whose shape this
  reader does not know is refused as newer (NewerDataError) and kept where it is, never put aside as .bad.
- The loader attaches storage only for a mod granted `storage`: a store reads three scopes' files and follows the
  save moments, for nothing in a mod that cannot call it.
- do_get handed the adapter a pointer into the store's entry after letting the lock go; the value is copied under the
  lock into a buffer of the API's thread, kept until its next get.
- A file named from an id whose part before its first '.' is a Windows device (con, prn, aux, nul, com1-9, lpt1-9:
  "nul.dev~m.json" opens NUL there) gets '_' first, which no id begins with.

test_modstore.py: a newer format with an unknown shape refused and kept, and a device's name.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- The grants' file is written once a frame at most, at the end of modrt_items_frame when anything changed, not once a
  grant (journal_dirty).
- A mod keeps at most 16,384 grants with a key; past it a keyed grant is LimitError, said once in the log. The file's
  read cap covers GRANTS_MAX lines of the longest; a file past it is read up to the cap, said as an error, and not
  written over this session, so the keys not read are never lost.
- A full pouch: game_items_give answers GAME_ITEMS_FULL when the action ran and no add of its tag happened (seen while
  the add site is on); the grant stays queued and is tried again 300 frames later, said once, instead of being taken
  as given.
- A grant with no key that a save request drops keeps its tag in a ring of 64, so its add reported after the save
  still names its mod in granted.

modapi_items_test.c: the file written at the frame's end, a full pouch's wait and retry, a saved grant's add naming its
mod. docs/modding/items.md and docs/items.md say the wait and the cap.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
modrt_writes_apply made every queued write, even of a mod stopped after its call (its third fault in the same frame),
and with no mod running at all; and player.set's life was checked against Link's heart containers at the call only,
though a write of the same frame may lower them. Now a write whose mod is stopped, gone or whose entry failed is not
made (WriteRefusedError in the trace), the queue is dropped when no mod runs, and a range with a bound (max_flag) is
checked again when the write is made. ModRtWrite keeps the whole id (136 bytes), which the apply finds its mod by.
test_modrt.py: a mod stopped in the frame of its write.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- modui_test.c: a refused batch puts back an existing node's text, its place (moved under another parent) and its
  mount (a HUD unmounted, a window mounted); the slot fills' cap; a stopped mod's batch refused with no fault.
- test_modui.py builds modui_test with -fsanitize=address,undefined where the compiler has it (leaks not checked: the
  test keeps its mods), so a snapshot freed while the renderer holds it, or a rollback that writes past a node, fails.
- test_modstore.py: the writer's queue keeps a write after a delete of its folder after it (not folded into the write
  before), and a slot read while its delete waits is empty (peek_queue).
(The Tabs clamp is test_modui_layout.py's, the slots' and depth's caps modui_test.c's already.)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A key with a lone surrogate came back in the ArgumentError's message as its WTF-8 bytes, so the message itself held a lone
surrogate and the mod's own log.info of it was refused (and stopped the script); it is written as its escape now (\udc00),
and a key's 40 bytes are never cut inside a character. A path past 100 bytes (a value nested 65 deep) filled the 200-byte
message before its reason: it is shortened to its first 40 and last 50 bytes. (tests/test_modstore.py's values)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
<Badge>{n} rupees</Badge> made two Texts ("5", " rupees"), so the Badge's label was not "5 rupees" (link-hud's tests and
docs/modding/ui.md's own example): strings and numbers next to each other in one list of children are one string now.
A flush an interrupt cut short was only noticed at the next flush, which a press that sets the state already set never
asked for, so the UI stayed as the cut flush left it (ui-cases' hang test): the update, the frame and the events now ask
for a flush while one was cut short. Generated: host/modapi/ui_js.h, modapi/packages/mod-tools/lib/ui-runtime.js.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
nx2/build.py reads both (the mods' package reader, the script runtime) and stopped at FileNotFoundError on miniz.h from the
AppImage's tree (tests/test_appimage_player_build.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- mod_resolve_test reads the vectors file with a larger cap than MOD_JSON_MEMBERS: the large cases it holds must reach
  mod_manifest_parse, which refuses them, not stop the file's own parse (test_mod_manifest.py exited 2).
- test_mod_archive.py sets an entry's flags after zipfile writes it (writestr resets flag_bits: the encrypted case was not).
- test_modstore.py: the schema's path built before %, and a TOML line-ending backslash joined before the quota is looked for.
- modui_test: insert's fourth argument is the node before which (0: last), not an index.
- test_modrt.py: longshot's exports now include NewerDataError, QuotaError and WriteRefusedError; the stopped-write script
  imported player twice (a SyntaxError, so nothing ran).
- test_hooks.py: "before" is a valid at now (an unknown one is refused); an inline rule site has no HOS_SITE line, and its
  value's HOS_VALUE line is checked instead.
- misbehaving's stop test: an unknown feature is false, not a fault, since has() changed: a missing argument instead.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- test_fps_overlay_order.py: menu_record draws the mods' UI (modui_shown, modui_draw): stubs, and the cases with it on.
- test_menu_text_field.py: the cut of rx_backend.c holds the mods' UI declarations: their structs declared ahead.
- test_teleport_minimap_flag.py: game_call takes only the calling thread's context and keeps Ctx's poll: the stand-in's
  hos_ctx is main's context, its Ctx has poll, and hos_vcore_kicked.
- test_vk_pgo.py: appimage.sh copies game/ too (the hook sites' tables).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The manifest reader takes a mod's "settings" (Modding API spec 11.5): toggle, choice, slider, number, text,
keybind and color, each with its id, label, help, scope (global, profile or save), restart, a text's secret, and
its type's own fields and default, checked by the rules the launcher and the fake game keep too. A setting that
breaks one refuses the manifest, naming it. "author" is read for the Mods tab. tests/mod_vectors/manifest.json
holds the cases; docs/modding/manifest.md the fields.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The rest of milestone M4's script runtime (spec 9.2, 11.5, 12.4, 12.8):

- longshot/settings: get, set and changed over the mod's declared settings, kept in a store of their own beside its
  data in each setting's scope; a stored value that is not one of the setting's any more reads as its default.
  longshot/ui's useSetting is the same service.
- longshot/permissions: has, request (a Promise<boolean> the player's answer settles) and changed. The grants are
  kept in mods.json "granted"; a mod turned on in the Mods tab, one waiting for its permissions and a new version
  asking for more wait for the prompt (perms.c). ui.hud, ui.window and ui.settings are the UI's surfaces'
  permissions, checked at mount.
- longshot/time after and every in real time, game.after in game time: callbacks the host keeps, fired at the
  acquire phase after frame and storage.save.loaded, before update.
- longshot/dev: keep and reloading, and with HOS_MODS_DEV=1 a watcher that reloads a folder mod when its files
  change (dev.c), with the per-mod numbers the dev overlay shows.

The generator gains callback parameters, subscription results, async functions (settled at a serial point, their
continuations under the resuming callback's budget), a hand-written TypeScript signature, mod-scoped events and
permissions checked by the host; docs/modding/api-schema.md has them, with the Lua mapping (a coroutine's yield).
The fake game does all of it (lib/settings.js reads settings by the reader's rules; answer(), hotReload(), timers on
its clocks), and longshot-mod types writes ModSettings from mod.json.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
MkwVkHost version 39 (gpu/vk/modpage.h): the Mods tab lists, under each script mod, its declared settings drawn
with the menu's own cells (a toggle's halves, a choice's arrows, a slider, a number, a text field, a color, a
keybind that waits for a key; Delete its default; a save's setting only with a playthrough open), the line that
opens its own SettingsPage (modui_draw_settings, its controls given the menu's keys by modui_settings_input), and
its permissions, the optional ones switchable. The help box has its author and its script's frame time.

The permission prompt is page 6: it opens the menu above everything a mod can draw, Not now first, answered only
by the player's keys, mouse and controller. In dev mode (HOS_MODS_DEV=1) F8 shows the dev overlay (each mod's
frame time, heap, subscriptions, faults and last fault) and Shift+F8 reloads the folder mods.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/modding/settings.md: declaring settings, each type's fields and values, the key and button names, get, set
and changed, the ModSettings types, the scopes, and the Mods tab's rows. docs/modding/dev.md: HOS_MODS_DEV's hot
reload, dev.keep, the dev overlay and the timers. ui.md and ui-channel.md: a surface's permission at mount, and a
settings page in the Mods tab.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A TypeScript example of every setting type read and heard through longshot/settings (typed by longshot-mod
types), ui.hud asked for with permissions.request when the player turns its badge on, time.every and game.after,
and dev.keep across a hot reload; its tests run in the fake game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
find_next left ftLastWriteTime, ftLastAccessTime and ftCreationTime zero, so dev mode's watcher (host/modapi/dev.c,
which hashes path, size and time of writing) missed a Linux rebuild that wrote a file of the same size. They are filled
from stat as FILETIME (100 ns ticks from 1601), as Windows gives them. tests/test_posix_find_times.py sees a same-size
rewrite ten seconds on.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- A start (and a dev-mode reload) takes its grants from host/modapi/perms.c as they are now, masked by the manifest:
  a permission taken back or granted in the Mods tab since the list was read counts, and a required one missing
  makes it wait for the prompt again.
- The prompt has a serial (MkwVkModPrompt.serial); mod_prompt_answer(serial, allow) ignores an answer for a prompt
  that went in between. Its keys are a rule of their own (prompt_keys): nothing for 0.75 s and until every key,
  button and mouse button is up, fresh presses only (no repeats, nothing scripted, no tab keys), a move and a
  confirm in one tick take the move. A mod has 4 prompts waiting at most (32 in all), and a full queue is logged as
  such; an ENABLE allowed starts a mod that waits after Not now.
- Dev mode: a reload waits for a second walk that finds the same files; a watched mod that failed or stopped stays
  watched and starts again at its next change; Shift+F8 reloads every watched mod; the entry's own src/ is
  watched; what a dev.reloading listener writes is dropped; dev.keep is reentrant; log.debug shows in dev mode.
- A UI surface's permission taken back hides its mounts from the next snapshot. At most 64 Promise settlements
  (2 ms) a frame, all mods together. The Mods tab keeps its selection by line, asks a second Enter before granting
  an optional permission, types a secret as stars and does not open a text longer than its field. A stopped mod's
  settings store is made with its manifest's version, and no save is open before the title screen. json_number
  writes the shortest round-trip text.
- Tests: tests/test_modrt.py check_perms (request, answer, a serial that is not the one waiting, a declined
  request, a prompt gone with its mod, settings set and refused, a secret never logged, a value out of a new range,
  a reload after a grant taken back and given), tests/test_mod_prompt_keys.py (the prompt's rule, cut and run), and
  source checks in tests/test_mod_settings.py.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
settings.changed comes after update in the frame a setting changed: update had already told
at the new amount, and changed's reset made it tell again the next frame. The alarm now keeps
the amount it told about. settings.md says so for authors.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Without the flag the fake game's cases never started, so each case failed before it ran.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
modrt_test's step now calls the timers, settings.changed, permissions.changed and the Promises in
the loader's order: without them no timer fired. Its UI cases grant ui.hud, which a Hud's mount
needs now. longshot/game's exports have game.after. A mod that waits for a grant hooks the
phases for the prompt, so 'nothing runs' checks that the mod does not run, not that no phase was hooked.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/game/pad.c records the player's read in host/nn_hid.c npad_states and applies what mods set there (a replacement,
consumed buttons, timed presses); host/game/camera.c records the gameplay view in hos_oot_free_view and the angle in
hos_oot_fov, and puts a mod's view and field of view in their place. A mod's rumble plays over the game's
(host/pad_sdl.c). With no mod, each hook is one relaxed load.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The schema gains handles (an object a call gives the mod, with methods and events, released by its release or a using
block), filters (spec 8.2: a draft of a record chained in load order, an exclusive one under its claim) and plain record
parameters (a Vec3). longshot/input: actions from keybind settings, pad.state, pad.intercept (exclusive: the claim
input.pad), press, rumble, pointer.capture. longshot/camera: state and override (the claim camera). game.pause and
longshot/ui's hideGameHud have their shape, absent in the game until a safe point is known. A minimal run-time claims
registry names the holder in ClaimError and in the Mods tab. The fake game does all of it (game.input, game.camera).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
A press can be set back (a stopped mod's), and the last one's end makes the hook one load again; what the acquire phase
sets lapses 250 ms after it was set; a torn read says so (the caller keeps the last); a mod's rumble is one word, and can
be ended; while a mod's pointer capture applies the game's mouse look (nn_hid.c mouse_stick, mouse_native.c) leaves the
mouse's motion. tests/game_pad_test.c checks them, and the records and replacements under threads.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review of mods/input: the game's reads (pad, camera) are watched while a running mod holds input or
camera permissions (modrt_input_settle: at a mod's start, after each reap, with no mod left), so the first pad.state() and
camera.state() see them and the last mod's stop gives the game its own read, its mouse and nothing watched; a stopped
mod's presses and rumble are taken back; a draft is read back from own data properties only (no getter, Proxy or array)
under a deadline of its own, and cancel() is the draft's; a released handle's subscriptions go (fake game too); consume
drops a chord only while the chord holds the action; input.action needs input.read, 16 a mod, chords in any case;
camera override values bounded; CameraState.fov null when unknown; torn reads keep the last.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The docs and the schema say draft.cancel() gives the game nothing this frame: every button up, the sticks at rest. The
runtime handed its game side a pad that was also disconnected; host/modapi/services_input.c marks a replacement connected
whatever it is given, so the game saw the same, but the record the runtime publishes (and tests/modrt_test.c prints) said
otherwise. tests/test_modrt.py's "a cancelled draft gives the game nothing".

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Its update listener needed state.read, which its manifest does not ask for: the mod stopped at load in the fake game, and
would in the game. Turbo only counts time, the game's frame event's work (Needs no permission); test_modapi_schema's
examples in the fake game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A forward declaration of game_in_front made "static int game_in_front(" appear twice in host/nn_hid.c, and the checks that
cut it (tests/srccut.py's block, as test_input_background does) stop on a marker that is not unique. The script mods' key
read now sits after the function it calls.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
npad_states now calls game_pad_hook, and mouse_stick and hos_mouse_camera ask game_pointer_held (host/game/pad.h): the
checks that compile them gave neither, and stopped at the compile. test_input_background stands in a hook with no mod;
test_mouse_stick and test_mouse_native also check that while a mod's pointer capture has the mouse, its motion is left to
the mod (the stick at rest, the camera's angles kept, the motion not taken).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The checks were written before they ran, and five were wrong rather than the runtime:
- modules: longshot/game now has pause, and longshot ClaimError and StaleHandleError (this branch's schema);
- the old draft's cancel() read the "infinite" run's lines (whose draft is refused, so the player's A alone) instead of
  the traps run's own;
- the override's CAMERA lines counted the CAMERA watch line before them;
- pad.state() alone, under input.read only, listened on game.update, which needs state.read: on frame now;
- the Mods tab's claims mods ran game.update with camera.write alone: state.read added to their manifests and grants.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The schema names the camera's permission camera.write (spec 12.4's camera.control, named as state.write is), but mod.json's
reader still knew only camera.control: every mod asking for camera.write, photo-mode among them, was refused as "not a
permission" and never loaded. tests/test_modrt.py's Mods tab claims found it; test_mod_manifest now checks that mod.json
takes every permission modapi/schema/api.toml has.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Research (docs/actors.md): f_804bd8c0, the life component's apply of a hit, writes every GameActor's
life with two compare-and-swaps (the Debug tab's Damage taken places); the life component holds the
actor's type name, its life and maximum (QueryActorLife reads them there); GameActor's method
f_82c3d740 runs each actor's frame. The source's kind is read but unconfirmed; the attacker, a safe
write point and spawning were not found.

- nx2/hooks.py: the first templates over a table (life_rules_hit, life_rules): a relaxed load of the
  pointer while off, the reader count and the host's C (hos_rules_life) while a table is published; a
  rule's value may name a HOS_TABLE line
- game/<build>/sites.toml: rules.lifeHit, rules.lifeWrite (inline table rules) and actors.update (an
  event at GameActor's method's entry, off until watched)
- host/game/rules.c: the table, its publishing and the rules' arithmetic (scales in load order, then
  adds, then the clamp; never a heal)
- host/game/actors.c: a lock-free record of the actors updated, and the acquire phase's list with
  spawned, removed and died
- tests: test_game_rules.py (the arithmetic and the emitted C over made-up life components),
  test_hooks.py (a table rule; the repository check knows inline rules have no slot)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The API grammar grows what the two need (docs/modding/api-schema.md):
- [[handle]] types (Actor, Rule): lsapi_handle with its type, checked by the thunks; a function with
  method = true is also a method of its first parameter's handle, dispose = true its [Symbol.dispose];
  one frozen prototype per type in the bindings and the fake game's prelude
- list<Record> results (snapshots, frozen each and all)
- options records inside options records (a rule's where, and its damage)
- [[event]] filter = <options record>: on(listener, filter?) gets only the payloads equal to every
  field given, checked at on() and compared at each fire

longshot/rules: rules.damageTaken.add and rules.damageDealt.add (the interface DamageRules) take a
DamageRule value (scale, add, min, max, where: target, sourceKind, damage) and return a Rule;
rules.remove (rule.remove(), using). host/modapi/rules.c keeps the running mods' rules and, after
update and the writes, publishes one table in load order when something changed. where.source (the
attacker's type) and rules.rewards are left for later: the game's side was not found.

longshot/actors: list(filter?), info(actor), alive(actor), and removed, spawned and died filtered by
type, over the actor service, watched only while a running mod holds actors.read (a new permission).
actors.write is left out: no safe write point was found.

The fake game deals hits as the game does (damage(), rules) and places actors (setActor,
removeActor); tests/test_modrt.py runs both in the real runtime with a scripted game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
damage-tuner sets damageTaken and damageDealt rules from three declared settings (useSetting, with its
defaults on a build without mods' settings), with a where on the source's kind and the hit's size,
and replaces its Rule handles when a setting changes. enemy-hud lists the enemies around Link with
their health on the HUD from actors.list() in useGame, counts died once, and hears one type through a
filtered spawned. Both are plain JavaScript with tests in the fake game (damage, rules, setActor).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From a cold review, checked against the image:
- sourceKind reads +0x1370 bit 0, this frame's hit's (set on the path that registers hits, before the
  write); +0x18b8 is its copy, written after the write at +0x1188 (the last hit's at the write)
- the Debug tab's guard (patch_life) scales the hit the rules made: hos_rules_life keeps it per thread,
  hos_rules_hit gives it once for the same write, x9 otherwise and never changed (a failed swap
  recomputes w12 from w9 at +0x410); oot_damage leaves a hit of 0 (the game's clamp) alone
- the template tests next < old before the table's pointer: the first swap runs every frame for every
  actor with a life, a hit of 0 most frames; a hit of 0 is never ruled
- rules.lifeWrite is gone: +0x610 and +0x14a4 add to a life (heals; they lower one only to clamp it to
  its maximum), and f_82e68030 lowers the maximum and clamps the life: no rule applies there
- an unreadable type leaves the write as the game had it (never taken for another actor)
- docs: the hit is max(raw, 0) (bic at +0x3fc), the other life writes, the composition
- tests: fixtures from literal offsets; hit 0, the clamp, heals, retries, the ruled hit handed over once;
  test_rules_debug_damage.py runs the rule and patch_life's guard together over Half to Quadruple with
  scale, add, min and max, protection, and retries

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From a cold review:
- another actor at a known address (components or life component at other addresses, another type, a
  type readable for the first time, a dead actor alive again) is the old one removed and a new one
  spawned with a new generation: no handle, key or death carries over
- events are kept until the poll's list is whole, then fired removed, spawned, died
- the list finds actors by address in a hash, not a scan; a frame whose record overflowed removes
  none, and past 1,024 actors the list keeps the ones it has (said once)
- a filter field may name an optional payload field (lsapi_filter_field.payload_has_offset): a payload
  without it never matches
- ActorFilter gains key (one actor's events); test_modrt.py checks a two-field filter
- game_actors_test.c: same-type reuse, dead then alive, a type readable late, the events' order with the
  whole list seen by a listener

Co-Authored-By: Claude Opus 5.5 <[email protected]>
useGame hears longshot/game's update, and update.on() needs state.read (docs/modding/ui.md): with actors.read alone the
HUD threw a PermissionError at its first render, so four of its five tests failed (tests/test_modapi_schema.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The script logs "- " + an empty join + " 0" when no actor is listed yet, so the line is "list 1 0 true -  0": the host
was right, the expected line was not.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The input and rules work each brought a [[handle]] grammar: input's release
and [[handle.function]], rules' bare handle with method = true and
dispose = true. They are one now: a [[handle]] may have its own methods and
events, a namespace's function with method = true is also its method, and
release names the method (its own, or a module's) that ends it and is its
[Symbol.dispose]. A handle with release is a mod's resource whose other
members throw StaleHandleError once released; one without is a game
object's, whose methods answer null or false when the game no longer has
it. dispose = true is gone (Rule's release is remove). Documented in
docs/modding/api-schema.md#handles.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
input and together each brought ClaimError (and host/modapi/claims.c, the
same file in both, kept once with one set of declarations in
modrt_internal.h and one modrt_claim_declarer in loader.c); api.toml's
[[error]] list is the one place the lsapi_status order is written: the
base ones, then ClaimError, StaleHandleError, ModCallError, NetError,
NewerDataError, QuotaError, WriteRefusedError, LimitError, HostError. The
generated files follow (python -I modapi/generate.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The generator carries both sets: callback and subscription types, async
results, hand-written ts signatures, events of scope "mod" and a
permission's host key (settings), and JavaScript modules beyond
longshot/ui's, a module's permissions and features, and the together
source (mods together). Its header lists together_js.h and
together-runtime.js, and api-schema.md says how a permission's users (a
member, a JavaScript module, or its host) are checked.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/modapi/loader.c's on_frame and on_update hold every branch's step in
one order: the save moments and the prompt's answers, the start queue (load
order), the frame's begin, the UI's events and the settled Promises,
frame, storage.save.loaded and the timers; then update, the items', the
actors', settings.changed and permissions.changed, input settled to the
mods, mods together, the UI's batch, the writes, the rules' table,
dev.reloading and the reloads, the reap, input settled again and the UI's
snapshot. docs/modding/api-schema.md's "The frame's order" lists it;
tests/modrt_test.c's step() runs a direct mod's frame the same way (the
items' and dev's steps were missing there), and the fake game's frames()
follows it for every mod.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
scripting.md's "Coming later" names what the four branches brought (settings,
the prompt, timers, dev mode, input, the camera, rules, actors, mods
together, the network, workers) and what is still to come; api-schema.md's
status and its table of later namespaces say In for each, with their guides.
README.md and examples.md were merged with each branch's copy (eighteen
examples, eight in TypeScript; every permission an example uses).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- An action's key and a chosen button are the keybind setting's value now
  that settings keeps one (settings.c modrt_setting_keybind; the fake
  input reads lib/settings.js's), the manifest's "pad" chord beside it.
- loader.c grants_now counts a granted net:<origin> as can_start does.
- The adapter's handle_object takes a handle of no schema type as the bare
  object it was; the fake game's values take a handle as its id or as
  {$handle, id, generation}; schema.json's functions say method and
  dispose again (rule.remove() on the prototype).
- A hot reload in the fake game restarts that mod alone.
- enemy-hud asks for ui.hud, which its Hud needs since mount() checks it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- test_mod_manifest: ui.<surface> and net:<origin> are permissions the
  manifest takes by their pattern (permission_known), not by the list.
- test_mod_settings: settings.changed is order 8, permissions.changed 9 and
  dev.reloading 13 in the joined frame (after the actors' and input's).
- test_modrt: the consumer's keybind has a label and a lower-case id, as a
  manifest's settings must since the settings work.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The player camera's update's text patch (nx2/oot_patches.py patch_mouse_camera: hos_mouse_camera(c->x[0]);
first in f_80644c80) is the site camera.update, the function's entry, its callback host/oot_sites.c's
hos_site_mouse_camera over hos_mouse_camera. The signature (5 words at +0x30: the frame's set-up and the
loads of the camera's x0 and x1) finds it once in the supported build.

Identity: the same call with the same x0, first in the function, before any of its locals are loaded;
the callback answers 0 and the update runs on, as after the patch's call. f_80644c80 stays in the context
for the camera centering's text patch, which is still there. patch_mouse_camera and its report entry are
deleted. tests/sitecheck.py is the converted features' shared check of their sites (the table, the host
slot, the callback, the patch gone); tests/test_mouse_native.py uses it.

Gates: gate 1 (code parity: nx2/test_leaf.py with the table, f_80644c80's C differs by the hook alone) and
gate 3 (behaviour: the mouse turns the camera in a scripted run with Mouse camera on) need a lift and a
game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The menus' two text patches (nx2/oot_patches.py patch_menu_focus and patch_menu_tick: hos_oot_menu_focus(c, x0,
x1, x30) first in f_802ed660, a menu screen's handler of a pane getting the focus, and hos_oot_menu_tick(c, x0)
first in f_802f1380, every menu screen's update) are the sites menu.focus and menu.update, the functions'
entries, with host/oot_sites.c's callbacks over host/oot_menu.c.

Identity: the same calls with the same registers (x30 is the caller's return address at the entry, as at the
patch's first line), before anything of the functions; the callbacks answer 0 and the functions run on. Both
functions may now get locals (no longer named by nx2/oot_patches.py): only their bodies' C changes. The patches,
their constants and their report entries are deleted; tests/test_menu_hooks.py checks the sites.

Gates: gate 1 (nx2/test_leaf.py with the table: the two functions differ by their hooks and locals) and gate 3
(a scripted run through the pause menu with the mouse: focus follows the pointer, toggles clear on Linux) need a
lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The button prompts' three text patches (nx2/oot_patches.py patch_text_draw, patch_text_layout and patch_glyph:
hos_prompts_text_draw(x0), hos_prompts_text_layout(x0) and hos_prompts_glyph(x1) first in f_8152b670, a text
box's draw, f_8152aec0, its layout, and f_81680c60, FreeType's ft_smooth_render) are the sites text.boxDraw,
text.boxLayout and font.glyphRender, the functions' entries, with host/oot_sites.c's callbacks over
host/prompts.c.

Identity: the same calls with the same registers, before anything of the functions; the callbacks answer 0
and the functions run on. The functions may now get locals: only their bodies' C changes. The patches, the
helper they shared (_hook_head), their constants and report entries are deleted; tests/test_menu_hooks.py
checks the five entry sites (the menus' two and these three) through tests/sitecheck.py.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (a run that changes the controller while a text
box shows: its prompts are redrawn for the new pad) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The two text patches of the native zstd decodes (nx2/oot_patches.py patch_zstd_stream and patch_zstd_frames:
if (hos_zstd_stream(c)) return; first in f_80115c80, the game's stream decode of one chunk, and the same with
hos_zstd_frames first in f_8010b380, the resource loaders' whole-buffer decode) are the sites zstd.stream and
zstd.frames, the functions' entries with can_return, with host/oot_sites.c's callbacks answering what
host/hos_zstd.c answers.

Identity: the same calls, first in the functions, before any of their locals are loaded; an answer of 1
(the host did the call, x0 its result) returns at once, 0 (the switch off, or a stream the host cannot take)
runs the function as lifted. HOS_NATIVE_ZSTD and HOS_NATIVE_ZSTD_FRAMES still decide inside the host
functions. Both functions may now get locals. tests/test_native_zstd.py checks the sites.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (a load through two areas and a cutscene, with
both switches on and off: the same frames decoded, docs/tested's zstd runs repeated) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The cloth solve job's text patch (nx2/oot_patches.py patch_cloth_solve: if (!hos_oot_cloth_solve(the frame
step at 0x84d61fc8)) { x0 = 0; return; } first in f_81b47080) is the site cloth.solve, the job's entry with
can_return, its callback host/oot_sites.c's hos_site_cloth_solve: it reads the step as the patch did and
answers 1, x0 = 0, for a frame the gate holds.

Identity: the same call with the same word read, before the job saves anything (its first line, the
prologue's store, comes after the entry hook as it came after the patch); a held frame returns with x0 = 0
and the stack pointer as given. tests/test_oot_cloth_60.py builds the job with the emitted hook and with the
patch's line side by side and checks they solve and hold the same frames in every case (240, 144, 120, 60 and
30 fps, a cap of 60, a step of 0 and NaN, a load), for HOS_FPS_CLOTH_60 unset, 1 and 0. The patch, its
constants and its report line are deleted; the job may now get locals.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Zora's Domain near King Zora at a cap of 240 with
HOS_FPS_CLOTH_60=1: the cloth solved some 60 times a second, HOS_FPS_LOG's counts as on main) need a lift and a
game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The movie player's text patch (nx2/oot_patches.py patch_movie_frames: the count's add at f_83b7c710, +760 of the
player, made _b=hos_movie_frames(x20) in place of 1) is the site movie.frameCount, a replace site on that add
(add w8, w8, #1 at +0xb8), its callback host/oot_sites.c's hos_site_movie_frame_count:
w8 = (uint32_t)(w8 + hos_movie_frames(x20)).

Identity: the same call, once an update, on the same path, and the same 32-bit sum into w8 before the store;
with the site off the add runs as the game has it. The player's other branch (+0x1f8, the same three
instructions) is left as the patch left it: the signature takes the load, the add, the store and the branch
after them, which only the first branch has. tests/test_movie_frame_count.py builds the update with the
emitted hook and with the patch's add side by side: both pass the checks at 120, 240 and 40 fps, several
movies and more players than places; the hook switched off fails them, as the game's own count does. The
patch, its constants and its report entry are deleted; f_83b7c710 may now get locals.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (the Deku Tree's movie and a cutscene with one at a
cap of 120: narration and rumble with the picture, HOS_FPS_MOVIE=0 the game's own count) need a lift and a
game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The scene format's text patch (nx2/oot_patches.py patch_scene_format: f_80672260's mov w9, #0x1a, the
R11G11B10F choice, made w9 = hos_scene_rgba16f ? 0x2c : 0x1a) is the site render.sceneFormat, a replace site on
that mov (+0xec), its callback host/oot_sites.c's hos_site_scene_format setting w9 the same way.

Identity: w9 gets the same value (one volatile read), on the same path, before the same csel; with the site
off the mov runs as the game has it. The signature covers the pick (mov w10, #0x2c; the flags' orr and test;
the mov; the csel), which the patch matched as text. tests/test_scene_format.py builds the pick with the
emitted hook and with the patch's lines side by side: the same registers and flags for every flag and
setting. The patch, its constants and its report entry are deleted; f_80672260 may now get locals.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Native HDR with PsychoV35: the scene buffer made
RGBA16F, Vanilla: R11G11B10F, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The life write's text patch (nx2/oot_patches.py patch_life: a guard before each of f_804bd8c0's two
compare-and-swaps of an actor's life, which hands a lowering of the player's own life to hos_oot_damage) is
the sites player.lifeHit and player.lifeWrite, before the cas at +0x438 and +0x610, with host/oot_sites.c's
callbacks over one guard (life_write): x9 is the hit at the first, the difference at the second, as the
patch had them.

Identity: the same test (w12 below w11, the actor the player, x13 its life field) and the same call into
w12, before the same instruction on every way into it (the patch's text went after any label of the cas,
as a before site does); the hit is computed before the test now, from the same registers, which nothing
changes in between. The signatures take each cas with the instructions that set its registers, which the
patch's count of the cas text stood for. tests/test_oot_damage.py runs each hook as emitted and the patch's
guard side by side on copies of every case: the same registers. The patch and its constants and report
entry are deleted (LIFE_BUILD_ID stays: it names the supported build for the other patches).

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Damage taken Half and Quadruple, heart protection,
a hit from an enemy and a fall, on a fixed save: the life as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The flight's two text patches (nx2/oot_patches.py patch_movement: hos_oot_lift_player(c, x19) before
f_82c415e0's test of the actor's flag byte, and hos_oot_flight_pose(c, x19, x25) after its label L_82c41778;
patch_flight_rotation: hos_oot_flight_rotation(c, x0, x1) before f_806d2530's call of the controller's virtual
method) are the sites player.update (+0x14c), player.pose (+0x198) and player.flightRotation (+0x94), all
before sites, with host/oot_sites.c's callbacks.

Identity: the same calls with the same registers, at the same points: a before site's C goes after the
instruction's label and before its own C, where the patches put theirs (the tbnz has no label; +0x198 is
the label both paths reach, as L_82c41778 was; the blr's C follows). hos_oot_lift_player is also Link's
update for the state tap and the player service, so tests/test_oot_state_tap.py now finds it through the
site. tests/test_player_update_sites.py checks the three sites. The patches and their constants and report
entries are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (the Debug tab's flight on a fixed save: Link lifted,
turned and posed as on main; the control bridge's player state each frame) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The free camera's text patch (nx2/oot_patches.py patch_view: hos_oot_free_view(c, x20) after f_804e48c0's label
L_804e5068, the head of its loop over a camera's views, with or without the interrupt poll after the label) is
the site camera.view, before the instruction at +0x7a8, with host/oot_sites.c's callback.

Identity: the same call with the same register, after the label and before the instruction's C, on the loop's
entry and each time round, as the patch's text after the label ran. The site is placed by the address, so the
two forms of the label's line the patch looked for (nx2/poll.py's poll before or after) no longer matter.
tests/test_free_view_anchor.py checks the site and where the emit puts a before site's C. The patch and its
constants and report entry are deleted. (The lift reports the site as in a loop: it ran there before too.)

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (the Debug tab's free camera moved on a fixed save: the
view as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Movement speed's text patch (nx2/oot_patches.py patch_cct_speed: hos_oot_cct_speed(c, x0, per_second) after
four anchors) is four sites with host/oot_sites.c's two callbacks: player.speedMove and player.speedMoveOther,
after f_809552f0's two loads of the controller (ldr x0, [x8, #8] at +0x134 and +0x1ec, a frame's speed);
player.speedSet, the setter f_80559df0's entry; player.speedSetComponent, after f_80964bf0's first load
(+0x0; the last two a second's speed).

Identity: the same call with the same registers at each place: the patch's text followed the label and the load
at the first two (an after site follows the load), was first in the setter (its entry), and followed the
component's load. The setter's code is in the game twice (0x827abdd0's copy runs into more code); its
signature ends with the padding after this copy, which makes it unique. tests/test_movement_speed.py checks the
four sites and their units; its host and menu checks are as before. The patch, SPEED_PLACES and the report's
count are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Movement speed 2x on a fixed save: Link's run, a
swim and a ledge climb as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The horse jump's text patch (nx2/oot_patches.py patch_horse_jump: if (hos_oot_horse_whole_step(s10, the time
object's slot)) goto L_82c5ae48; between f_82c59eb0's test of its step against 1 and its b.pl to that label) is
the site horse.jumpStep, a branch site on that b.pl (+0xf70), its callback host/oot_sites.c's
hos_site_horse_jump_step answering the host's test.

Identity: the patch's line went to the b.pl's own target before the b.pl's own test; a branch site takes the
branch on a non-zero answer and runs the branch's test otherwise, at the same place, with the same call and
registers. The signature takes the fmov of 1.0, the fcmp and the b.pl, which the patch matched as text.
tests/test_horse_jump_step.py builds the update with the emitted hook and with the patch's line side by side:
both keep the game's blend frames at 70 to 240 fps and take the game's own test elsewhere; the update without
the hook, or with its flag off, fails the 120 fps check. The patch, its constants and report line are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Epona over a fence at Lon Lon Ranch at a cap of 120:
she jumps it, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The texture compaction's text patch (nx2/oot_patches.py patch_tex_compact: f_80797240's test of its flag bit 1,
if (!bit1) goto past the ask, widened to if (!bit1 || !hos_oot_tex_compact_due()) goto) is the site
texture.compactAsk, a branch site on that tbz (+0x38), its callback host/oot_sites.c's
hos_site_tex_compact_ask: bit 1 set and the host saying not now takes the branch; otherwise the tbz's own test.

Identity: the branch is taken exactly when !bit1 || !due, and the host is asked only when bit 1 is set, as the
patch's || did. tests/test_tex_compact.py builds the step with the emitted hook and with the patch's line side by
side: for every flag and answer the same way out and the same asks. The patch, its constants, its report line and
its paragraph in the module's notes are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (standing in Castle Town's market with
HOS_TEX_COMPACT_MS unset, 0 and off: the rounds the log counts as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The solver steps' text patch (nx2/oot_patches.py patch_solver_steps: x1 = hos_oot_solver_steps(x1, s0, s1)
between the cut of frame step * steps a frame (fcvtzs w1, s0) and its store at +712, in f_838ceb80 and
f_838cfc10) is the sites physics.solverSteps and physics.solverStepsOther, after each fcvtzs (+0x74, +0x110),
with host/oot_sites.c's one callback.

Identity: the same call with the same registers right after the cut, before the store, as the patch's line
was; x1 gets the 32-bit answer zero-extended as before. The signatures take each update's loads of the step
and the steps a frame, the fmadd, the cut and the store (the first loads through x25, the second x19), which
the patch matched as the cut and the store. tests/test_high_fps_fixes.py builds each site's hook as emitted and
the patch's line side by side: the same registers and the same stored count for every input. The patch, its
constants and its report line are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Link on a moving platform, the Deku Tree's and the
Forest Temple's elevators, at a cap of 144: he stays on, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The three text patches of the sound job above 60 fps (nx2/oot_patches.py patch_sound_job: the gate first in
f_80435300 and its phase 0's step through hos_oot_sound_step; patch_bgm_time: f_83373400's step and seconds
through the host; patch_bgm_flags: hos_oot_bgm_begin first in f_83373400 and its four reads of the battle
manager's change flags through hos_oot_bgm_flags) are eight sites with host/oot_sites.c's callbacks:
sound.job (the job's entry, can_return: held when the gate says so), sound.jobStep (after its ldr s0 at +0x34),
music.update (the update's entry), music.time (after its ldr s9 at +0x48: s8 and s9 the host's) and
music.changeFlags, changeFlags1, changeFlags2 and changeFlags6 (after each ldrb w8, [x26, #0x898], named by
the bit each tests).

Identity: the same calls with the same arguments, in the same order, at the same points: the gate first and a
held job returning before anything of it; each load's value through the host right after the load, as the
patches' lines that wrapped the load; the seconds given the step as read from guest memory, as the patch
re-read it. tests/test_high_fps_fixes.py builds the job and the update with the emitted hooks and with the
patches' lines side by side, over stand-ins that log every call to the host: the same registers and the
same calls, for each phase, gate answer and flag byte; its clock and flags checks run on the emitted hooks.
(Its flags check also gets stand-ins for HOS_HEAP_BASE and hos_guest_range, which host/oot_high_fps.c's
hos_oot_note_link reads and the check's world lacked.) The patches, their constants and report lines are
deleted; SOUND_SLOT stays for the floor carry and the driven target.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (at a cap of 144: a dozen loading zones with sounds
and music playing on, and a fight's music ending after it, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The driven target's text patch (nx2/oot_patches.py patch_drive_target: hos_oot_drive_target(x20, the body,
the time object's slot) between f_804f5030's load of the body (ldr x23 or x24, [x20, #0xf0]) and its reads of
the target, at the path's two copies) is the sites physics.driveTarget (+0x1b4) and physics.driveTargetOther
(+0xe6c), after each load, with host/oot_sites.c's callbacks.

Identity: the same call with the same registers right after the body's load and before the target's reads,
where the patch's line went (the patch matched the load and the reads as one text, so no label lies between
them). The signatures take the load and the two reads; the function's third load of x23 from +0xf0 (+0x500),
which the patch did not match either, reads other fields after it. tests/test_drive_target.py builds the
update with the emitted hooks and with the patch's lines side by side: both pass every climb check at 60 to
240 fps; the update without the hooks, or with their flags off, fails the 120 fps check. The patch, its
constants and its report line are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Link's pull-up onto a ledge at a cap of 120: he
gets up, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The cloth time's text patch (nx2/oot_patches.py patch_cloth_time: f_81b3aa48's load of its step context's time,
ldr d0, [x22, #8], with its low half made hos_oot_cloth_seconds(the time, the frame step at 0x84d61fc8)) is the
site cloth.time, after that load (+0x220), its callback host/oot_sites.c's hos_site_cloth_time.

Identity: the same call with the same values (the time as loaded, the step read from the same word), the low
half replaced and the high half kept, before the fdiv that reads s0, as the patch's rewritten load did.
tests/test_oot_cloth_time.py builds the setup with the emitted hook and with the patch's load side by side: the
same frame data for every step, scale and HOS_FPS_CLOTH value. The patch, its constants and its report line
are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Link's cap at a cap of 20: it swings and settles as
on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The whole frames' text patch (nx2/oot_patches.py patch_whole_frames: seven cuts of the frame step to a whole
number, fcvtzs or fcvtzu of s0, made hos_frame_whole(the counter's key, s0), the water's
hos_frame_whole_times(x21, s0, w8) with w8 then 1) is seven replace sites on those cuts, frame.wholePickup
(f_80a87e50+0x4b0), frame.wholeWater (f_800672e0+0x318), frame.wholeTimeOfDay (f_803edf70+0x50),
frame.wholeScarecrowPlay (f_832b32b0+0x160), frame.wholeScarecrowRecord (f_832b6840+0x2c8),
frame.wholeScarecrowLast (f_832b2690+0x38) and frame.wholeFloorWeb (f_80652cb0+0x50), with host/oot_sites.c's
callbacks (the two that share a key share one).

Identity: each callback writes the cut's register with the call the patch's line made, with the same key and
the same bits of s0 (the water's substeps register set to 1 after, as before); with a site off the cut runs as
the game has it. Each signature takes the cut with the lines the patch matched it by (the time of day's with its
store to +60, which leaves its other cut at +0x1f0 the game's; the recording's with its add of x10, which
leaves the mode-13 cut's add of x12 alone; the water's with the substeps' load). tests/whole_sites.py emits the
seven hooks into authored lifted C as the lift does, and the text patch's lines for comparison:
tests/test_frame_whole.py runs every site both ways over stand-ins that log each call (the same registers and
calls; off, the game's own cut), and the scarecrow, water and floor web checks run their behaviour with the hooks
and with the patch's lines. The patch, WHOLE_SITES and its report line are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (at a cap of 144: the pick-up indicator after a
rupee, the ripples in Zora's Domain, the time of day in Hyrule Field, Scarecrow's Song recorded and played, the
Deku Tree's web landed on: as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The fixed scale's text patch (nx2/oot_patches.py fixed_scale: after f_831f3200's label L_831f3efc, a recompute of
the 3D's scale asked for on the fixed path while +0xe5c is not the chosen one; after its load of the override
flags at L_831f3f08, hos_res_module = x20 and their bits 3/4 cleared on the fixed path) is the sites
render.fixedScaleApply, before the instruction at +0xcfc (that label's), and render.fixedScaleFlags, after the
load at +0xd08, with host/oot_sites.c's callbacks doing what the patch's lines did.

Identity: the same reads of guest memory and of the host's values, the same float arithmetic and the same
writes of w8, x8 and hos_res_module, at the same points (a before site's C follows the label, on every way into
it, as the patch's text did; the after site follows the load). One signature, the update of +0xe2c and the load
and test of the flags, places both. tests/test_fixed_scale_sites.py builds the block with the emitted hooks and
with the patch's lines side by side: the same registers, memory and hos_res_module for the fixed path on and
off, scales chosen and not, a 0 at +0xe50 and every flag. The patch, its constants, its report entry and its
paragraph in the module's notes are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Resolution at 50%, 75% and 100% on the fixed path,
docked and handheld: the 3D at the chosen size, no targets remade each frame, as on main) need a lift and a game
run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Three changes of control flow the text patches still made, as forms of the site table (docs/hooks.md, Forms):
- allow: the conditional branch at the offset is taken only when its own test holds and the callback, asked
  only then, answers non-zero: the branch's own if, its test and its goto kept inside the site's
  (if (<test> && on && fn(c)) <goto>), for a patch's narrowed condition (if (cond && host) goto);
- jump: before the instruction at the offset, as before, a non-zero answer jumps to the instruction at a new
  key, to, in the same function, which place() makes a label of every function the code is lifted in. The
  lift's flow analysis does not see that edge, so such a function keeps every flag store (site_keep_flags);
- replace on a call (bl, blr): the hook sets x30 to the return address and the callback makes the call itself
  (a64_lookup, a64_icall) when it wants it, as a wrapper of the callee; with the site off the call is lifted
  as before.

The reader checks the forms and to; place() records them (Lifter.site_allow, site_jump, site_keep_flags), one
before or jump site per instruction and one branch or allow per branch; nx2/fastfp.py's copy of the kit's emit
gets them in lines tagged (hooks); chunks.EMIT_TABLES sends the new tables to the emit's processes;
patch_clashes guards a jump's target. tests/test_hooks.py reads and places them and checks their C;
tests/test_hooks_emit.py emits each through the real emit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The camera centering's text patch (nx2/oot_patches.py patch_camera_centering: if (hos_disable_camera_centering())
{ x25 = x26; goto L_80645ad8; } on the fall-through of f_80644c80's b.ne at L_8064720c, the follow camera's
movement yaw) is the site camera.followYaw, a jump site before +0x2590 to +0xe58, its callback
host/oot_sites.c's hos_site_camera_follow_yaw: with the row on, x25 = x26 and the answer 1.

Identity: the same call at the same point (+0x2590 is the b.ne's fall-through and no label: nothing else reaches
it, so a before site there runs only where the patch's line ran), the same register written, the same label
jumped to. The function keeps every flag store now (the jump's edge, which the flow analysis does not see); the
patch's goto was not seen either, so this keeps more, never less. The signature takes the b.ne, the call the
movement path starts with and its x25 = x26. tests/test_camera_centering.py checks the site and runs a block
with the emitted hook and one with the patch's line, row off and on: the same way out, the same registers. The
patch, CAM_HEAD and its report entry are deleted: f_80644c80 is no longer named by nx2/oot_patches.py.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (walking with the row on and off on a fixed save:
the yaw follows Link's movement only with it off, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The floor carry's text patch (nx2/oot_patches.py patch_floor_carry: each of three update modules' b.gt to the
tenth of a floor's velocity, after its test of the physics' 1/dt against 100, made
if ((n == v) && !z && hos_oot_floor_carry_slow(s0, the time object's slot)) goto) is the sites
physics.floorCarry (f_80159dc0+0x2b0), physics.floorCarryOther (f_8015d490+0x280) and physics.floorCarryThird
(f_838baa40+0x1ec), allow sites on those b.gt, with host/oot_sites.c's one callback.

Identity: the branch is taken exactly when its own test holds and then the host answers non-zero, the host
asked only then, as the patch's && had it; the same call with the same s0 and slot. The signatures take each
module's load of 1/dt, the 100, the fcmp and the b.gt (the last two with the instructions after, which tell
them apart), which the patch matched as text. tests/test_floor_carry_step.py builds the updates with the
branches as the emit makes them around the allow sites and with the patch's branches side by side: both pass
every case; without the hooks, or with their flags off, the 120 fps check fails. The patch, its constants, its
report line and SOUND_SLOT (no patch names the time object's slot now) are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (on the Shadow Temple's barge at a cap of 144: Link and
the enemies ride it, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The voice option's text patch (nx2/oot_patches.py patch_voice_option: f_80a9ca30's call of f_80a9d1c0, "was the
option written?", made hos_oot_voice_option(c, f_80a9d1c0) after x30 = its return address) is the site
options.voiceWritten, a replace site on that bl (+0x68), its callback host/oot_sites.c's hos_site_voice_written:
hos_oot_voice_option(c, a64_lookup(0x80a9d1c0)).

Identity: the hook sets x30 to the call's return address, as the patch's line kept it, and the callback calls
the same wrapper with the game's function, found by its guest address instead of named in the lifted file (the
same function; a lookup once an update); with the site off the call is the game's own. The signature takes the
option's hash, the manager's load, the bl and the test of its answer. tests/test_oot_voice_option.py builds the
update with the emitted hook and with the patch's call side by side, over host/oot_voice.c and the flags service
as they are: both apply the saved choice once, follow writes and leave other questions to the game, and with
HOS_VOICE_OPTION_FOLLOW=0 both are the game's alone. The patch, its constants, its report entry and its paragraph
in the module's notes are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Japanese voices saved, a restart, Link's voice in a
cutscene in Japanese, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The heap retry's text patch (nx2/oot_patches.py patch_heap_retry: f_804566e0's two calls of f_80522050, its GPU
memory, made hos_oot_gpu_alloc(c, f_80522050), and its two tryAllocs, blr x8, wrapped in a refusal test and a
retry in the heap's parents for a null) is four replace sites on those calls: heap.gpuAlloc (+0x838),
heap.gpuAllocOther (+0x9b4), heap.cpuAlloc (+0x22c) and heap.cpuAllocOther (+0x6c0), with host/oot_sites.c's two
callbacks: hos_site_gpu_alloc, hos_oot_gpu_alloc with the game's function by a64_lookup; hos_site_heap_alloc, the
patch's lines with the call through a64_icall and the return address from x30.

Identity: the same calls with the same arguments in the same order, the same registers after; x30 is the call's
return address (set by the hook as the patch's lines set it), except under the test switch
HOS_GPU_ALLOC_TEST_FAIL, where the patch made no call and left x30 as it was and the hook leaves it as a call
would (nothing after a call reads x30 but as a call's). Each signature takes the call with the lines that set its
arguments; f_80522050's other callers stay as they are. tests/test_oot_heap_retry.py builds the four places with
the emitted hooks and with the patch's lines side by side over stand-ins that log every call (the same calls,
arguments and registers, for a refusal or not and a null or not), and its checks of the host's retries are as
before. The patch, its constants, its report check and its paragraph in the module's notes are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (a save loaded with HOS_GPU_ALLOC_TEST_FAIL=2: two
refusals made by the retry, the model drawn, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The song cue's text patch (nx2/oot_patches.py patch_song_cue: x0 = hos_oot_song_cue(site, x0) after
f_832b2af0's and f_832b2dc0's calls of f_832b7b50, the note flag's question) is the sites song.noteCue
(f_832b2af0+0x194) and song.noteCueOther (f_832b2dc0+0x114), before sites on the instruction after each call,
with host/oot_sites.c's callbacks (site 0 and 1).

Identity: C after a call is C before the next instruction when nothing else reaches it: neither return address
is a label in the lifted C (read in a lift of the supported build), so each hook runs exactly where the patch's
line ran, with the same call and register. The signatures take the call with the instructions around it.
tests/test_song_note_cue.py builds the playbacks with the emitted hooks and with the patch's lines side by side:
both pass every case at 60 to 240 fps; without the hooks, or with their flags off, the 120 fps check fails. (Its
world also gets stand-ins for what host/oot_high_fps.c now reads that it lacked: HOS_HEAP_BASE, hos_guest_range,
getenv's header and env_value_off.) The patch, its constants and its report line are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Zelda's Lullaby played at a cap of 144: its notes
shown one at a time with the melody, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The ocarina wait's text patch (nx2/oot_patches.py patch_ocarina_wait: lines in the note-wait action's start
f_828a9190 and tick f_828a9280 that set hos_oc_wait, hos_oc_last_kind and hos_oc_beat) is seven sites with
host/oot_sites.c's callbacks: ocarina.waitStart (after the start's load of the input kind, +0x48),
ocarina.waitTick (before the tick's running test, +0x1c: cleared, or re-armed and the beat stamped),
ocarina.waitMode, ocarina.waitContext and ocarina.waitOwner (before the three gates' branches, +0x4c, +0x60,
+0x98: cleared when they refuse), ocarina.waitDone (after the done store, +0x108) and ocarina.waitReset (before
the instruction after the input reset's call, +0x164, which nothing else reaches).

Identity: each callback writes the host's three words as the patch's lines did, from the same registers, at the
same points: the patch's lines inside a branch's block (taken) or after it (not taken) become a test of the
branch's own condition just before it (nothing lies between; the flags are in the context, as for every site
inside a function), and its line after the reset's call is the before site after the call. The signatures take
each place with what tells it from the game's many like it. tests/test_ocarina_wait.py builds both functions
with the emitted hooks and with the patch's edits side by side and runs them over every input kind, flag byte,
mode, context and owner: the same wait, kind, beat and registers. The patch, its constants, its report entry and
its paragraph in the module's notes are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (the ocarina played with the note controls, a song
lesson, a dialogue that takes the buttons, Scarecrow's Song: the pads swapped exactly while the game waits for
notes, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The loop step's and the loop pose's text patches (nx2/oot_patches.py patch_loop_steps: in f_802cfca0's two
multiplies of the step, s8, by the speed, the multiply's own copy of the step made hos_loop_step's;
patch_loop_pose: in f_80944aa0's store of a skeleton's time, the stored value made hos_loop_pose's) are three
pairs of sites with host/oot_sites.c's callbacks: anim.loopStep and anim.loopStepDone (before and after the
fmul at +0x164), anim.loopStepOther and anim.loopStepOtherDone (+0x530), anim.loopPose and anim.loopPoseDone
(before and after the str s0 at f_80944aa0+0x3b0). The before site swaps the host's value into the register
the instruction reads, the instruction runs as the game has it, and the after site puts the game's register
back (kept in a thread-local slot between the two, which run one right after the other).

Identity: the patch fed the host's value to the multiply (and its sign for the zero, computed from it) and to
the store without changing the register; here the multiply and the store read it from the register for one
instruction and the register is the game's again after it: the same product, the same stored word, the same
registers after. No new form was needed. tests/test_loop_step.py builds the updates with the emitted pairs and
with the patch's lines side by side: both keep a loop of one frame on one phase; without the hooks, or with
them off, the check fails. The patches, their constants and their lines in patch_file are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (the frozen Zoras in adult Zora's Domain at a cap of
165: they stand still, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The saved turn rate's text patch (nx2/oot_patches.py patch_turn_rate: in f_8263e8e0, the steering update, the
two multiplies of the saved rate's bounds by the step made divides while 0 < step < 1) is two replace sites on
those fmuls, steer.rateLower (+0x238, fmul s1, s0, s1) and steer.rateUpper (+0x23c, fmul s0, s0, s8), with
host/oot_sites.c's callbacks: the step's bits tested as the patch tested them (no host float compare, no guest
flag changed), then the divide or the game's multiply.

Identity: the same operands, the same choice, the same result register (its upper half cleared, as a64_vset64
does). The patch called the lift's fast helpers (a64_fpx_div32_div32, a64_fpx_mul32_fma32), which give the
exact helpers' value and FPSR when they can and call them otherwise; the callbacks call the exact helpers
(recomp_fpe_div32, recomp_fpe_fma32) directly: the same value and FPSR bits, a little slower on a path run once
an update per steering actor. The signature takes both multiplies with the instructions around them.
tests/test_saved_turn_rate.py builds the update with the emitted hooks and with the patch's arithmetic side by
side: both pass every step, sign and limit; without the hooks, or with them off, the short-step check fails.
The patch, its constants, its report entry and the report's last warning list are deleted.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Gohma at a cap of 144: she leaves the ceiling for
her next point, as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The barrier wait's text patch (nx2/oot_patches.py patch_barrier_wait: the 20 us sleeps of three parallel-for
jobs, f_800998a0, f_800738e0 and f_8007e200, made hos_oot_barrier_wait with the game's sleep behind it, and each
atomic OR into a polled mask word followed by hos_oot_barrier_wake) is five replace sites on the sleeps' calls
(barrier.sleepClaim, sleepGather, sleepDone, sleepOther, sleepThird) and seven after sites on the ORs' ldset
(barrier.orClaim, orClaimOther, orGather, orDone, orOther, orOtherSecond, orThird), with host/oot_sites.c's
callbacks: each sleep's the patch's wait with the same words, read only when the switch is on, and the game's
sleep (a64_lookup of SleepThread as the lift calls it, x30 set) when it is off or the wait answers 0; each OR's
the wake of its job block, the register the OR's address was made from.

Identity: the same calls with the same arguments in the same order, the same registers and memory: the patch
woke _a - off, the OR's address less the word's offset, which is the base register the signature's add made it
from (each OR's signature takes its add, so the offset and the register are the code's). The patch hooked a
function only where all its places and marks were found, at all of them; here every site resolves exactly once
or the build stops, so a sleep never waits for a wake that is not there. Its marks (where the loops load the
words the waits are told) were read in the supported build's code, as the patch's comment did; the table's
comment keeps them. tests/test_oot_barrier.py keeps its runs of the host's protocol and its broken variants;
the patch's checks are replaced by a side-by-side run of each of the twelve places with the emitted hook and
with the patch's text over stand-ins that log every call, the switch on or off and the wait yes or no, and three
broken callbacks that must fail it. patch_file and report are kept, empty, for nx2/chunks.py and the output
size; tests/test_patch_hooks_defined.py reads the output size's declarations, the patches' last.

Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Castle Town's market on 4 cores, HOS_OOT_BARRIER_WAIT
unset and 0: the barrier: log lines count waits moved and woken, frame time as on main) need a lift and a game run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/hooks.md's Not yet list names the swap of an instruction's operand done with a before and an after site at
one instruction (anim.loop*) as a form to come, and the output size's edits, the last text patch, with why they
stay one for now.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
nx2/fastfp.py's site_keep_flags test and allow site test ended in a longer comment, "# (hooks: ...)", which
tests/test_fastfp_override.py does not count as tagged: it would find the copy's untagged lines differ from the
kit's emit_function. Both end in "# (hooks)" now, their explanations on comment lines of their own, tagged
the same. The copy's untagged lines read the same as the kit's (compared by reading both, nothing run).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
anim.loop* were three before/after pairs sharing one thread-local slot: the before site swapped the host's
step (s8) or time (s0) into the register, the after site put the game's back. With each half's flag of its own,
a half turned off, or a flag stored between the two, could leave the host's value in the register or restore a
register from another pair's save. The pairs are gone: anim.loopStep and anim.loopStepOther replace the two
fmuls, their callback the multiply with the host's step through the runtime's exact float helper
(recomp_fpe_fma32, as steer.rate* do), and anim.loopPose replaces the str s0, its callback storing the host's
time through recomp_store32 (which marks its page). s8 and s0 are never changed; each site is one flag.

Identity: the text patch fed the host's step to the multiply's own copy of the operand (its zero's sign from it)
and the host's time to the store's, leaving the registers as they were: the same here. tests/test_loop_step.py
adds a side-by-side run of each place alone, hooked and as the patch had it, from random contexts and memory:
the whole context (every register, s8 and s0 among them, and FPSR) and memory must match, so a callback that
left a register changed fails. docs/hooks.md's Not yet entry says so.

Gates: as before, gate 1 and gate 3 (the frozen Zoras at a cap of 165).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review of mods/hooks2:
- A replaced bl now tells its callback the callee: the hook stores the function the lift calls there (past any PLT
  stub; Lifter.callee) in hos_site_callee (host/game/sites.c, per thread) before the callback, which calls
  a64_lookup(hos_site_callee). The voice option's, the GPU memory's and the job barriers' sleeps' callbacks no longer
  write 0x80a9d1c0, 0x80522050 or 0x85106220. A bl to a function the lift does not call plainly (no entry, or a setjmp
  owner) cannot be replaced: the lift stops.
- The global slots the callbacks read (the time object's pointer, the cloth's clock) are named once in
  host/oot_sites.c, in a block for build e0f3ccfa; tests/sitecheck.py's callback() cuts it with each callback, and
  tests/test_oot_cloth_60.py uses it. docs/hooks.md says a callback naming an address belongs to one build.
- A site may carry guards: words elsewhere in its function, checked where its signature puts the function, which stop
  the build as a missing signature does (and which the mods' ExeFS patch check keeps as it keeps the signature's). The
  five barrier sleeps guard what their waits are told: the loop heads' loads of the polled words, the stack slots and
  the frame slot of the full mask, as the deleted patch's marks did.
- place(): a branch site where an allow is is refused in either order (and two branch sites at one branch); a jump
  whose code is lifted in a function without its target is refused, not left without its label there; a jump back is
  reported as a loop; a before site after a call on a label is reported with a warning. docs/hooks.md says what stacks
  at one instruction as the code does.
- The table gets back steer.rateLower, which the previous commit cut by mistake with the loop sites' rows (its
  HOS_SITE line and callback stayed; nothing resolved it).

tests/test_hooks.py: guards read, met and missed; the refusals above; the loop report and the warning; the replaced
call's callee through a PLT stub. tests/test_hooks_emit.py, test_oot_voice_option.py (which now also checks x30 is the
call's return address when the game's function runs), test_oot_heap_retry.py and test_oot_barrier.py pass the callee.
Written and syntax-checked only; nothing run. All 95 sites resolve exactly once against the local image, guards
included.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
tests/test_hooks.py checked that each table row has its HOS_SITE line in host/game/sites.def, not the other way: an
engine callback whose row was gone (steer.rateLower, cut by mistake in an earlier commit of this branch and put back
since) linked, resolved nothing and placed no hook, and no check saw it. Each HOS_SITE_ENGINE line's site must now be a
row of a build's table. A plain HOS_SITE line, a slot for a mod's callback, is not required to have one yet. Written
and compiled only; read against the current table and sites.def by hand: all 92 engine lines have their row.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
nx2/texture_index.py walks every **/*.bntx.zs of the RomFS (the game's zs dictionary) and writes texture_index.txt into the
game folder: each BRTI's file, name, format, size, levels, kind, data offset, image size and the renderer's shape-free
signature of its data. make_game.py runs it after the button prompts, kept when the RomFS did not change; it is made from
the game and stays in the game folder. --list shows a texture pack's author the names to use (mise run texture-names),
--check-log is spike S5's check against RX_VK_LOG_TEX_HASH logs. No full XXH64 of the whole game here: in Python it would
add minutes to every build; the host computes it for the replaced textures only.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/png_decode.c reads a mod's own PNG into RGBA8: every colour type and bit depth, tRNS, not interlaced, every chunk's CRC
checked, the image data inflated into exactly the bytes the header says, a side capped by the caller. No new library: miniz is
in the executable already (MINIZ_HOST). tests/test_png_decode.py: good images against pixels made there, thirty malformed
files refused with their reason, and random damage under the sanitizers.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A manifest mod that lists gfx.textures and has a textures/ folder is a pack: each PNG names a game texture
(textures/<name>.png, or textures/<file>/<name>.png), resolved against the player's own texture_index.txt. For each one the
file the game is served is read, the texture found by name and its size, signature and full XXH64 taken (the renderer's
numbers, in C), cached in modcache/texture_hashes.txt by the file's size and time. The renderer gets them through MkwVkHost
version 40 (texture_replacement, texture_replacement_image, texture_replacement_free); the loader gives a content mod's
folder (modrt_content_root, a package unpacked then). With no pack nothing is read.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
gpu/vk/texture_pack.h has the rules: at a texture's first whole upload, the shape-free signature for each replaced size near
the storage's, and only on a candidate the full XXH64 (an ASTC texture's blocks_hash as it is); on a hit the pack's image,
decoded by the host on a thread of its own and given its own chain of levels, is what a sampled view of the whole texture
uses. The game's image stays for copies, render passes and storage views, and the override goes when the GPU writes the
texture or its storage is uploaded again. One image per hash, unused ones kept up to 512 MB. With no pack nothing runs.
RX_VK_LOG_TEX_HASH logs each first upload's L.size, hash and signature for spike S5's check; RX_VK_TEX_PACKS=0 turns packs
off for an A/B. docs/design.md section 14 has the rules, with doc: anchors on the functions behind them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/modding/textures.md: what a pack is, the two name forms and how to list the names from your own game, what the images
may be, what can and cannot be replaced, two packs on one texture, and what the log says when a texture is not replaced
(with the unverified part, spike S5, and the run that settles it). The modding index and the manifest's permissions point
to it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review of mods/gfx:
- The override's swizzle is the descriptor's and the view's (an X format's alpha one), taken before the 5-5-5 formats' R/B
  swap and RX_VK_9E5_SWAP, which are the game's own image's storage: an RGB5A1 texture's replacement drew red as blue. A
  channel the game's format lacks reads as it would (G, B zero, A one: R8, RG8, BC4, BC5, BC1 RGB, R5G6B5). ASTC formats a
  GPU samples itself are UNORM or sRGB kinds too (pack_format, pack_components).
- An upload after the first looks the texture up again (pack_reupload): the override stays with the same bytes, goes with
  others, comes with another replaced texture's; it was dropped for good at any re-upload.
- The draws' resolved views go stale by a pack generation of their own (texture_pack_generation, checked in
  texture_view_of), not destroy_gen, which the upscalers read as a texture gone, so a decode finishing no longer trips them.
- In a parallel replay an image is sampled only by the segment whose uploads filled it and later ones.
- Pack images count in total_bytes while held; at most 64 MB of them go to the GPU a frame; the decode thread is
  lsmod-texdec, made in pack_on with no lock held.
- tests/test_texture_pack.py cuts pack_attach, pack_detach, pack_format and pack_components out of vk_texture.cpp and runs
  them: the detach's stale views and last_value, a failed image never attached, the swizzle and channels per format.
- RX_VK_LOG_TEX_HASH also logs the replaced sizes the slack reaches, for --check-log; its row says the lines are game data's
  hashes. design.md section 14 says all of it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The build decompressed every .bntx.zs (about 20 GB) on every player's build for an index only texture packs use. Now
host/texture_packs.c makes modcache/texture_index.txt at the first start with a pack on, reading each file's first 16 KB
decompressed (more for an archive of many textures: hos_zs_read_prefix, a stream decode in host/zs.c), logs how long it
took, and makes it again only when a RomFS folder's time changed (the index keeps them). nx2/texture_index.py writes the
same file the same way for --list (mise run texture-names) and computes signatures only for --check-log; make_game.py no
longer runs it. The host's walks are bounded (folders), a path too long is said, and the hash cache is searched sorted.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Its inflated rows are twice an 8-bit image's: at 8192 x 8192 RGBA the decode held about 768 MB at once. Refused at its
header, with the reason. miniz's provenance names host/png_decode.c as its second user.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
"texture packs:" joins RESERVED_LOG (host/texture_packs.c, the renderer's "vk: texture packs:"), and docs/parity-gates.md
says what texture packs start: nothing with no mods, the lsmod-texdec thread with a pack on.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The join of the hook conversions with the damage rules: patch_life, which asked hos_rules_hit for the hit to scale, is a
site now (player.lifeHit), and its callback scaled the game's x9. host/oot_sites.c hos_site_life_hit passes
hos_rules_hit(c->x[19], (uint32_t)c->x[11], (uint32_t)c->x[9]) instead, as patch_life did; rules.lifeHit moves ahead of
player.lifeHit in game/e0f3ccfa/sites.toml, since several before sites at one instruction run in the table's order, so
the rule changes w12 first and the Debug tab's Damage taken scales the ruled hit.

tests/test_rules_debug_damage.py follows the hook path: it checks the two are before the same instruction, the rule
first in the table, the callback's hit, and compiles the rule's line and the site's hook as the lift emits them with the
callback cut from host/oot_sites.c over host/game/rules.c and host/oot_damage.c. The comments and docs/actors.md that
named patch_life name the site.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The decision of 2026-11-19 on hook shapes: on a worker thread a branch, allow or jump site, or an entry that can return,
is an engine feature's (a HOS_SITE_ENGINE line in host/game/sites.def) or an inline data rule, never a callback a mod's
service sets (a HOS_SITE line); scripts reach such a place only through data rules or filters on the serial thread.

nx2/hooks.py check_site takes the engine's site names (engine_sites(), read from host/game/sites.def by load()) and
refuses such a site that is not one, naming the site and the two ways a mod has; a table read without the host's list
(parse_table's tests of made-up tables) is not checked for it. docs/hooks.md says who may change the outcome. Every row
of game/e0f3ccfa/sites.toml keeps the rule already: its outcome-changing worker sites are all the engine's.
tests/test_hooks.py checks the forms, the threads, the list and the supported table.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The texture packs came at API version 36 on their branch; joined after the code mods (36, 37), the script mods' UI (38)
and pages (39) their three MkwVkHost functions are version 40's (the bump is in the joined feat(mods) commit).
tests/test_texture_pack.py checks the version and that they are MkwVkHost's last three after mod_reload, and
host/rx_backend.c's vk_host's after modrt_reload, in place of 'version 36'; tests/test_modui.py's check of version 39's
functions allows version 40's after them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
An allow site's hook was if (<the branch's test> && on && fn(c)) <its goto>: with its flag off the branch was never
taken, so a dormant allow site changed the game, where every other form off is the game as shipped (a replace site
off runs the instruction itself). It is if (<the test> && (!on || fn(c))) now: the callback, asked only when the
test holds, may still keep the branch from being taken while the site is on. tests/test_floor_carry_step.py's
negative control (the hooks off fail the 120 fps check, as the updates without them do) passes again;
tests/test_hooks.py's expected C follows, and docs/hooks.md's forms table and nx2/hooks.py's notes say so.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- tests/test_loop_step.py: the authored update's second multiply is fmul s1, s8, s0, as anim.loopStepOther's
  signature (1e200901) and its callback have it, not s2: the hooked update wrote s1 and the advance read the stale
  s2, failing three checks in the second mode. The update hands s1 to the advance.
- tests/test_oot_voice_option.py: the two direct calls of hos_oot_voice_option set x30 to the call's return address,
  as the site's hook does before its callback; the game's stand-in checks it.
- tests/test_song_note_cue.py, tests/test_high_fps_fixes.py: a stand-in for hos_step_probe (host/nn_vi.c), which
  host/oot_high_fps.c's cloth solve reads; the fixtures compile that file whole and did not link.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The reason a PNG is refused goes to the host's log and the Mods tab; for a wrong CRC or an unknown critical chunk it
printed the chunk's four type bytes as they were, so a damaged file put arbitrary bytes (not UTF-8) there, and
tests/test_png_decode.py's run of damaged files stopped on decoding them. Each byte that is not an ASCII letter is
'?' now. The check reads the decoder's output as bytes and fails on anything but ASCII.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- tests/modrt_stub.py: host/mods.c starts the texture packs (hos_texture_packs_start) with the manifest mods that
  load; the stub, with none that load, never calls it, but the checks that build mods.c without the runtime
  (tests/test_mods_list.py, tests/test_mods_size_table.py, tests/test_mods_sizes.py) did not link or compile.
- tests/test_texture_pack.py: a stand-in for hos_zs_read_prefix (host/zs.c), which host/texture_packs.c's index reads
  call since the index is made at the first start.
- tests/test_texture_pack.cpp: an empty storage compared with texture_ahead's signature through a readable pointer:
  an empty vector's data() may be null, which texture_ahead takes for storage it cannot read (0), not 0 bytes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/rx_backend.c's cut that tests/test_menu_text_field.py compiles declares hos_texture_replacement, whose
MkwVkTextureReplacement (gpu/vk/vk_api.h, version 40) the fixture did not declare, as it does the mods' page types.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A replace site's callback does the instruction's work, or a call's, in its place: it changes the game's outcome as a
branch, allow or jump site does. check_site's rule on worker threads (OUTCOME_FORMS) takes it in: an engine feature's
site (HOS_SITE_ENGINE) or an inline data rule only, never a mod's callback. Every replace row of game/e0f3ccfa/sites.toml
is an engine feature's already (the frame counters, the heap retries, the Voice Language option, the loop and steering
steps, the barriers, the scene format, the movie's frames). docs/hooks.md says which forms are checked; tests/test_hooks.py
refuses a mod-callback replace site there and keeps return, after and before open.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
They were MkwVkHost's last two at version 38; version 39's script mod pages and 40's texture packs follow them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
perms.c kept bits: the prompt's yes to a net:<origin> set LSAPI_PERM_NET_ORIGIN and wrote the template's name
"net:<origin>" to mods.json, while the loader matched origins against mods.json's "granted" list alone, so an origin
granted in the prompt or the Mods tab never reached the mod, and a reload lost even mods.json's (the last start's origins
went to the runtime it made).

- host/modapi/perms.c keeps each mod's granted origins as strings, "net:<origin>" normalized (bnet_origin_of), at most
  64 (the manifest's cap): read from mods.json's list, added by the prompt (a REQUEST's one origin, by its index in
  optionalPermissions; an ENABLE's, START's or UPDATE's required origins not granted, each named in the prompt), switched
  in the Mods tab (optional ones), and written to mods.json with the bits. A running mod's origins change with them
  (permissions.changed fires with the origin's name) and the network engine gets its grant again (modnet_regrant: a
  grant replaces the last, and the engine closes what it no longer covers). has() and request() take origins; a
  request turned down is not asked again this session, as for a bit. modrt_perms_origin answers the loader.
- host/modapi/loader.c asks perms.c for an origin (row_granted) and makes a row's origins again at every start
  (grants_now), so a reload starts with the origins of now.
- tests/test_mods_together.py check_net_grants: a request granted in the prompt (saved, the Mods tab shows it, the
  fetch reaches the engine's side), the reload keeping it, taken back in the Mods tab (saved, refused with
  PermissionError, the reload without it); a required origin granted in the start's prompt; mods.json's :443 the same
  origin. tests/modrt_test.c's noengine keeps the engine off (bnet_link_open wrapped at the link) so an allowed fetch is
  NetError and nothing reaches the network. docs/modding/net.md says how origins are granted and taken back.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The gates were written against the main before #1802, which removed scripts/job_queue.py and scripts/dev_build.py for
scripts/dev.py. parity_gates.py puts each game run in `dev.py queue run parity-<name> --mode shared --`, says so when it
refuses a run outside the queue, and takes the RAM file system check from scripts/devtools/common.py (on_ram, the
queue's own). docs/parity-gates.md builds the two game folders with `dev.py rt`, cancels with `dev.py queue cancel` and
links the developer pages where #1802 moved them; tests/test_parity_gates.py expects the new command.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
#1802 laid the docs out as docs/dev (with its reference pages) for people working on Longshot and docs/user for players.
The script API's pages for contributors, written before it beside the old ones, go to docs/dev/reference: hooks.md,
parity-gates.md, camera.md, items.md, actors.md and broker-net.md, and input.md as mods-input.md (main's input.md is the
input feature's page), listed in docs/dev/README.md. Every path to them in code, checks, schema and pages follows, and
every link to a page #1802 moved or merged (design.md: the architecture page; development.md: developing.md; mods.md,
control.md, using-mods.md, saves.md: their new places). The schema's own texts changed, so modapi/generate.py wrote its
files again.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Two places where the code mods' lift (M0) met the script API's hook sites:

- nx2/chunks.py edit_c told nx2/exefs_switch.py edit whether the step divides' text patch was in every file
  (oot_patches.STEP_SITES, the report's both or neither). The script API made those divides the hook sites
  frame.stepDivide and frame.globalStepDivide, placed together or the lift stops, and took STEP_SITES away: a build with
  a switched mod stopped there (tests/test_exefs_switch.py). The versions are emitted by the kit's emit_function, which
  nx2/hooks.py install() wraps, so they carry the sites as the function does: stepped is always true now.
- nx2/hooks.py names __doc__ for its command line (main.__doc__), which code_prints took for a module that may read
  another's text, so every lift module was hashed whole and a comment changed the lift's key
  (tests/test_lift_cache.py). It joins MARKS_NOT_OUTPUT, as nx2/exefs_modules.py did.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- tests/test_mods_archives.py, test_mods_modules.py, test_mods_packs.py and test_mods_switch.py (and test_mod_patch.py
  and test_mods_members.py, which build with the first) cut host/posix/win32_posix.c's find_next, which gives a file's
  times through filetime_of since the script API's dev reload needed them: the helper is in their cut lists, as the
  API's own checks had it.
- tests/test_mods_list.py's stand-in build (no game code) also stands in for exefs_patches.refuse_site_clashes, which
  looks the hook sites up in main's code.
- gpu/vk/vk_menu.cpp: the Mods tab's keys run mods_tick unless a mod's own page is open, written without a nested
  "} else {", so tests/test_mods_menu.py's cut of the tab's branch (to its first "} else {") still holds the restart
  state's note after it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
tests/test_exefs_switch.py's finding 2 checked that Longshot's own edits of the lifted C (nx2/oot_patches.py's menus'
update and movement speed) run once a call in every state of two switched mods. The script API made those edits hook
sites (nx2/hooks.py) and took them out of oot_patches.py, so the check now places three sites the same way (an entry
site on the menus' update, an after site in each speed function) before the switches are made, as nx2/lift.py calls
hooks.apply before exefs_switch.install, and asks the same: each hook runs once a call in every state (the program's
counts), the function as written dispatches to its version before its own hook, and each of the three other versions
has the hook. case() takes the placement and the counts it expects.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
host/mods.c calls the loader (host/modapi/) and the texture packs' start since the script API: the code mods' and file
layers' checks that build it over made-up folders (test_mods_archives, _members, _modules, _packs, _switch,
test_mod_patch) could not link. mods_build.copy_host, the one list of what such a build links beside mods.c, writes
tests/modrt_stub.py's stand-ins as modrt_stub.c with the host's files, so every one of them links them;
test_mods_list.py and test_mods_size_table.py, which wrote their own, take them from there. test_mods_list.py's
build_entry, which has no game code, stands in for refuse_site_clashes as for the other passes over main's image.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/dev/reference/mods.md: a script mod's entry keeps its grants (granted) as a code mod's keeps its acceptance
(accepted), in the same entry, each side keeping the keys it does not write; a script mod brings no code by the
emulator path, in the game and the build, so the two gates never meet in one mod; the Mods tab turns each on only
past its own gate; HOS_NO_MODS starts neither.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
damage-tuner, rupee-rain, misbehaving (state.write) and check-gift (items.grant) had no "multiplayer", so "local":
host/mod_manifest.c refuses such a mod (damage-tuner was refused in the game). The fake game's manifest check
(lib/together.js manifestProblems) now refuses it as the game does, so a mod's tests say so first.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
hos_oot_free_view records the 12 floats at view+8 once the game, the free camera or a mod's override wrote them
(game_camera_matrix_hook), while a mod holds state.read, camera.write or ui.hud. host/modapi/camera.c
modrt_camera_project takes a world point through it (the eye and target's matrix when none is recorded), the
projection's recorded vertical angle and the cameras' ratio (hos_wide_ratio, 16:9) to the picture's fractions and the
1920x1080 virtual space, with its depth and whether it is on the screen; actors.c gives an actor's position by its
handle. The matrix's eye is checked against the recorded eye once a run (a log line says a mismatch).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
<World at offset maxDistance fade> (spec 10.2/11.4) is a fifth surface, mounted with ["mount", id, "world", opts]
under ui.hud: at a point {x, y, z} or an actor {actor: {id, generation}}, at most 64 a mod, display only. At the
acquire phase, on the main thread, ui.c world_resolve reads each actor's position (actors.c) and projects the point
through the frame's recorded view (camera.c modrt_camera_project); a World surface of the snapshot carries its fx, fy,
depth, alpha and visible (hidden behind the camera, off the picture, past maxDistance, its actor gone, no view). A
snapshot of moved points only keeps the trees' layout serial (MkwVkUiSnapshot.layout, snapshot version 2), so the
renderer keeps its measures and its node state. vk_modui draws them over the picture as the present places it, under
the HUD, farther first, faded, never focusable.

The reconciler's World turns an Actor handle (native.actorRef), an actor's snapshot or event, its key or a position
into the wire's at; ui.project(position) gives {x, y, visible} or null (state.read). The d.ts, the fake game (a
projection through its camera, game.ui.worlds()) and the docs follow.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A World root a label, following the enemy's actor (the game places it each frame), for the enemies within 25 m of
Link: mounted as an enemy comes near, unmounted as it goes, sent again only when its health changes. The name is the
type's words (Enemy_Peahat_Larva: "Peahat Larva"), a small table for a few. Plain JavaScript, tests in the fake game.
enemy-hud and the docs point to it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
link-hud's first flush took 11.5 ms in the game, a fault. It sends 26 ops (806 bytes of JSON: 11 creates, 4 texts, 9
inserts, 2 mounts, measured in the fake game), so the batch is not what costs: the reconciler's code runs for the first
time, with every tree the mod mounted as it started. That first flush now has MODUI_FIRST_FLUSH_NS (50 ms) and its time
is taken out of the frame's script time, as the entry module's is; a first render over 2 ms is logged with the time the
host spent applying its batch, so a run says what dominates. tests/test_modrt.py runs link-hud in the real runtime.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
test_modui.py's check that the let-go snapshots are freed before the frame's end returns cut up to that return, which
is "if (!dirty && !moved) return;" now (World points moved are a snapshot too); test_modrt.py's World check read the
printed fy where it meant fx.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
A mod window opened with { open: true } took the focus at once (the host's default focus: 1), so on the title
screen it held back all of the game's input; and its close box answered the mouse only while it had the focus and
the window's thread had been told to let the mouse go.

The mouse, as it was:
- the close box's hit rectangle (close_box) was set only for the focused window, so an unfocused window (after the
  Insert menu, or another window) could not be closed or focused by a click at all;
- a click reaches the renderer only while the window's thread thinks a menu has the mouse (WM_APP + 8). The Insert
  menu (vk_menu.cpp, told) and the mod windows (vk_modui.cpp, released) each posted that one flag from their own
  memory, so closing the menu over a focused window let the mouse go and took it back in turn;
- with no menu open, a click on Linux captured the mouse for the game (display_sdl.c) and on Windows went to the
  game's own menu (the title screen) or a capture: an unfocused window could never get a click;
- windows were placed by their place in the drawing order, so a window brought to the front moved under the cursor.

Now:
- the host mounts a window unfocused unless its mod passes focus: true; the renderer gives the focus on opening only
  then. A click on a window gives it the focus, its close box closes it (focused or not), a click outside every window
  gives the input back to the game (the window stays open, dimmed);
- closing (close box, Esc, the controller's back) hides the window in the renderer at once; the host marks the mount
  closed when the event arrives and drops any later event of that window's nodes, and a second close; the reconciler
  marks the handle closed (isOpen false) before onClose runs, as a notice;
- the window frames and the click test are modui::window_frame and modui::window_at (modui_layout), with a cascade
  place kept from each window's first opening; the close box's hit area is the title bar's height square;
- the menu tells the window's thread to let the mouse go for both (now_open || modui_window_focused()), from one place;
- the renderer tells the window's thread where the windows are (MKWVK_UI_RECT_MSG, WM_APP + 13, fractions of the
  window; not part of MkwVkHost, no version), and a click there with no menu open is published to the renderer instead
  of capturing the mouse or reaching the game's menu (display.c, display_sdl.c, display_pointer.h);
- the fake game keeps a focused window (game.ui.click, clickOutside, focused): the game reads nothing and no key
  reaches an action meanwhile, as option 1 in the game.

Tests: test_modui_layout (the frames and the hits), modui_test.c (unfocused by default, nothing after a close, one
notice), test_modui (the wiring), display_pointer_test (a click on a mod window with no menu open, Linux and Windows).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The example's window was mounted with { open: true } and took the game's input from the start (the title screen
included). It now starts closed and a keybind setting ("rupee_log", F7, "Show the rupee log") opens and closes it
through longshot/input's action (permission input.read); opened, it leaves the game its input until the player clicks
it. onClose only logs: the player's close has hidden it already, and the handle says closed, so the key opens it again.

docs/modding/ui.md: Windows and the game's input (the focus, closing, the example); the fake game's click,
clickOutside and focused. Its tests: closed at the start, the key opens and closes it, the game keeps its input until a
click and gets it back by a click outside, changes listed while closed, the player's close. test_modrt runs it through
the loader (its setting declared from mod.json for the action).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
An actor caught half built or half torn down has garbage in its pointers
(0xFFFFFFFFFFFFFFFF, which crashed a spawner that walked the same list).
game_peek_at(base, off) refuses a sum that would wrap; the actor service
(read_actor), the type reader (game_life_type) and the life rule's reads
(hos_rules_life) offset every pointer they took from the game with it.
tests/game_actors_test.c: actors with such pointers and a garbled name are
listed with no type and no life.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A List's ListItem compared its props by identity, so a selector that
makes its items anew each update rendered every row every frame (some
30 us a row in QuickJS: a 200-row HUD was past the 5 ms a flush may).
sameItem compares the item's own fields (shallowEqual), the render, and
the index unless render takes the item alone. In the C harness: a 20-row
HUD with one row changed a frame 624 -> 210 us, a 200-row list turned by
one a frame 3.8 -> 1.3 ms, a 200-row one with one change 5 ms (faulted)
-> 1.5 ms.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Budgets (host/modapi/runtime.c, modrt_internal.h): every budget (5 ms a
callback, 2 and 8 ms a mod's frame, 4 ms all mods, 1 s the entry) counts
the thread's CPU time (Linux CLOCK_THREAD_CPUTIME_ID; Windows
QueryThreadCycleTime scaled by the TSC's rate, measured once in 2 ms),
not the wall clock: a loaded or swapping PC no longer faults and stops
mods. The wall clock is a hard cap for real hangs (10x the budget, at
least 50 ms a callback), in the interrupt handler and when native code
returns. A callback that faulted for its time is not faulted again for
its frame's 8 ms (one stall cost two of the three strikes).

Where the time went (ModRtCost): counters while a mod's callbacks run
(the API's calls by name, the result's script value included; longshot/ui
commit; major page faults on Linux, RUSAGE_THREAD), said only in a
warning or a fault: its CPU and wall time, the API's sum and costliest
call, the collector, its own JavaScript, the page faults. The collector
of a mod's runtime runs at the frame's end, timed, when the heap grew by
half (QuickJS-ng's own moved up to a net, counted when it runs inside a
callback); its time is in the frame's warning, never a fault.

actors.list(filter) takes an ActorQuery: type, typePrefix, key, near
{ position, within }, nearest, limit, answered in C before any object is
made. The frame's snapshots are made once for all mods, each answer is
kept for the frame by its fields, and its number (lsapi_ctx.result_key)
lets the adapter give the same frozen array again (MODRT_KEYED). The fake
game answers the same, with the same errors and the same array. The
generator names a C field near_ (C_MACROS): windows.h defines near away.
In the C harness with 500 actors: the old enemy-names pattern (list() and
filter in JS) 690 us a frame, the filtered list 53 us; enemy-hud's 637 ->
134 us.

tests/test_modrt.py: CPU time spun and wall time waited in native code,
the hard cap, one fault a slow moment, the breakdown's parts, the queries
and their errors, the same array, 500 actors; List rows. tests/modrt_test.c:
spin:<ms>, positions, actors <n>, cost and uicost (ui.c's ModUiCost:
stringify, parse, apply, snapshot builds).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
enemy-names: list({ typePrefix: "Enemy_", near: { position, within: 25 },
nearest: true, limit: 32 }), the host choosing the 32 nearest enemies
before any object is made (was every actor, filtered and sorted in JS:
its update listener faulted at 14.8 ms in a game run). enemy-hud:
list({ typePrefix: "Enemy_" }). A fake-game test of 40 enemies among 300
other actors: 32 labels, enemies only. In the fake game with 500 actors,
enemy-names' frame 9.7 -> 5.0 ms (the fake game's own work included).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A new module, longshot/lifecycle, with one event: stopping (order 14 of the acquire phase, after dev.reloading),
{ reason: "disabled" | "dependency", mod }, fired when the player turns the mod off in the Mods tab while the game
runs, or turns off a mod it needs. Not fired for a fault stop, a dev-mode reload or the game's quit. The fake game
models it: game.turnOff({ reason, mod }) fires it and stops the mod (its listener's writes not made), game.turnOn()
runs its entry module afresh with storage and settings kept. docs/modding/lifecycle.md says what a mod meets when it
is turned off mid-game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A manifest mod that is a script and nothing else (no romfs or patches folder, no texture pack, not needed by a mod
that has those) is live: hos_mod_edit keeps its switch in mods.json as before, then modrt_switch hands it to the
loader, which applies it at the next acquire phase (switch_frame, after the reloads): the resolver runs again over the
mods as they run; a running mod that is off now, or needs one that is, gets lifecycle.stopping (dependents first) and
is stopped and reaped that frame as a fault stop is; a mod turned on that loads beside every running mod is prepared as
at the start (grants, the prompt, the unpack) and starts at the next frame, and one that does not stays on, says why,
and starts once that changes. A waiting mod turned off has its prompts withdrawn. A mod stopped by its faults can be
started again (modrt_restart). state_key leaves a live mod's switch out, so a restart is never asked for it.

MkwVkHost version 41: mod_live, mod_dependents and mod_restart; MkwVkModPage gains status, live and can_restart. The
script runtime's check drives it: off and on at run time, a library's dependents stopped first and back by themselves,
the ENABLE prompt then the start from nothing hooked, mods with files and what they need left as the start made them,
Start again after a fault stop, a waiting mod's prompt withdrawn, and an incompatible mod refused until the other is off.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A script mod's line says its switch applies at once and is never in the restart's list or mark (menu_restart.h
Mod::live); every other mod's says "Takes effect when you restart", or "Needs a rebuild" for code that waits for a
build, and Restart now appears under the mods while such a switch waits (the restart question's Restart now). Off for a
mod that running mods need names them first, and Left again within 5 s turns them all off. A mod stopped by its faults
has a Start again line. Its page's state is the host's, live. docs/user/using-mods.md says which mods switch when.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A system mod is a script mod in modapi/system/<name>/, installed by every build into the game folder's
system_mods/<name>/ (nx2/make_game.py ship_system_mods, nx2/system_mods.py) with the id system/<name>. It loads before
the player's mods, cannot be moved or uninstalled, is granted what its manifest lists with no prompt, and may hold the
system-only permissions mods.inspect and mods.control (modapi/schema/api.toml, system = true).

Trust is the build's: modapi/generate.py compiles the name and tree hash of each system mod's shipped files into the
game (host/modapi/system_mods.h); host/modapi/system.c trusts an installed folder only when its files hash to it, and
checks again before each start. A folder copied into system_mods/ is never read, a changed one never loads, a system/
id in mods/ is refused by the manifest reader, and a mod the player installs that lists a system-only permission never
starts. Faults on a system mod are logged as errors.

longshot/mods gains inspect() (one frozen snapshot a frame, from counters the frame's end keeps anyway), logs(),
restart(), setEnabled() and reload() for system mods (host/modapi/inspect.c), with the fake game's side
(game.modStats, game.controls). The Mods tab groups system mods under Built in. The first system mod,
system/mod-inspector, opens on F8 (the dev overlay gives F8 up to it) with every mod's state, time, budget, graph,
faults, heap, subscriptions, UI and claims, the selected mod's log, and Restart, Turn off/on and Reload; and a corner
line, mods: 1.2 ms, 0 faults. docs/modding/system-mods.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A write to an actor is never made from the main thread: the game updates each actor on its job threads through the
acquire phase. The mods' writes are checked and queued at the call, handed to the actor service after every update
listener, and published as one table (actors.writes); the inline site actors.write, at the entry of GameActor's
per-frame method f_82c3d740 (where actors.update records), makes the actor's write there, on its own thread, before
that frame's hits: the life with a compare-and-swap as the game's own writes of it, held to the maximum; the position
through the character controller's own method (f_806d2530 at vtable +0xe8, what OneShotPhysicsCctChangePosition and
the Debug tab's flight call), with game_call. Each write is taken once (a ticket per entry carrying its table's epoch),
merged per actor, and dropped after three frames its actor does not take. One relaxed load while nothing is pending.

longshot/actors' setLife (1 to maxLife; not Link's, not a defeated actor's) and setPosition (an actor with a character
controller) answer a bool at the call, under the new permission actors.write (high, in words). The fake game applies
them after the frame's writes (actorWrites; setActor's movable); the pack-heal example; tests/game_actor_writes_test.c
over made-up actors with the site's C as emitted; tests/test_modrt.py's checks at the call.

docs/dev/reference/actors.md has the research: where the write is safe, and spawning: the game's create
(f_80392a70, ExecuteGenericRequestCreateActor's) is asynchronous and its request and actor link are the caller's to
keep and release across frames, the actor holders create only what the owner declared; not built, with what a spike
needs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The reward a chest holds is the actor the game creates from the chest's placement (its dynamic parameter
Drop__DropActor, or Drop__OverwriteDropActor), read by f_80bf1c00 into the drop's record as the chest's actor is
created. Two inline table rules (reward_rules_drop), just after the reader's two calls (rewards.drop in f_82f145e0,
rewards.dropOther in f_82f162f0), write a reward's item in place of the name when the dropping actor's placement id
([actor + 0x3d8] + 0x88, the key QueryActorGetIsRespawn looks up in the Bool64bitKey flags the checks scan) has one.
One relaxed load while no reward is published.

rules.rewards.add({ where: { location }, give: { item } }) of longshot/rules (state.write) keeps the rewards beside the
damage rules (host/modapi/rules.c), its first takes the claim items.rewards and its last gives it back; the table is
published at the rules' point after the frame's writes. The fake game's dropFor() and rewards; the chest-swap example;
tests/test_game_rewards.py over made-up drops; docs/dev/reference/items.md says what was read and what a run confirms.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The actor service reads more of each listed actor at its poll, each where the game's own event queries read it on build
e0f3ccfa: the 3x3 rotation by rows at +0x328 (QueryActorGetRotationFromActorLink, QueryActorGetForwardDir), the scale
at +0x34c (ExecuteActorChangeScale), the main rigid body's linear velocity (components +0x50 -> +0x20 -> +0x190, +0xe0:
QueryPhysicsGetActorVelocity), the character controller's ground state (QueryPhysicsCctIsOnGround's chain), the model
controller's shown byte (components +0x260, +0xe5: OneShotSetModelVisible) and the liftable component's state
(components +0x2c0, +0x28 and +0x2c: QueryLiftableIsBindState and the others). A liftable's change since the poll before
is reported once the list is whole: lifted, thrown (with the velocity of the throw, +0x17c), dropped (put, or fell).
Polled, not a site: nothing new runs with no mod watching.

The writes gain rotation, velocity and shown, made at the actor's own update as life and position are, each through the
game's own setter: the controller's rotation (+0x110, f_806d8910, OneShotCctChangeRotation's) and velocity (+0x78,
f_80559cd0, ExecutePhysicsCctSetLinearVelocityMps's) methods; for a physics object without a controller, its rigid
body's transform (f_806d21c0, OneShotPhysicsRigidBodyChangePositionAndRotation's, given the whole 3x4 with the actor's
frame rotation or position: setPosition now moves such objects too) and velocity (f_8014dbe0,
OneShotPhysicsRigidBodySetVelocityMps's); the shown byte and its change bit as OneShotSetModelVisible sets them.

Every pointer the service follows is checked by game_actor_ptr_ok first (the pointer alone, never a sum that can wrap),
as a half-built or torn actor's are anything: the life write checked only that its parameter's pointer was not 0, so a
0xffffffffffffffff there would have written near guest address 0. tests/game_actor_fields_test.c reads such actors and
the new fields; tests/game_actor_writes_test.c the new writes. docs/dev/reference/actors.md has the research, with the
notes the person you work for shared (build 1.1.1) and which of their items were re-verified here, and what a run
confirms.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
longshot/actors' ActorInfo gains rotation (a Rotation: yaw, pitch and roll in degrees, made from the game's 3x3; 0 faces
+z, 90 +x), scale, velocity and speed (metres a second), onGround, visible and lift (a LiftState), each null when the
actor lacks it or it could not be read, never 0. setRotation, setVelocity and setVisible (actors.write) answer a bool at
the call, checked (finite; 3,600 degrees, 100 m/s on an axis) and queued as setLife and setPosition are; the told text
of actors.write says what it now allows. The events lifted, thrown and dropped (ActorLiftEvent, ActorFilter) fire after
died, so the acquire phase's later events move up three (settings.changed 11 to dev.reloading 16). player.set is
unchanged: Link is an actor, and the actors' writes reach him.

The fake game places actors with the new fields (setActor's rotation, scale, velocity, onGround, visible, lift,
thrownVelocity, body) and fires the liftables' events from lift's changes; tests/test_modrt.py checks the fields, the
calls' checks, the writes handed over and the events in the real runtime; the spin-lift example turns Octoroks to face
Link, makes a throw fly higher and logs lifting. docs/modding/actors.md has a table of the fields with their units and
how sure each is, the rotation's convention, lifting, and the writes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
actorsw's game_actor_ptr_ok and the budgets' game_peek_at did the same job. game_peek_at
stays (host/game/flags.c), over game_guest_at, which the actor service's writes take; the
actor walk's ptr_at offsets through it and keeps only the 8-byte alignment of a pointer.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
modrt_test's "surfaces" lists the last UI snapshot's surfaces. The check drives link-hud as the game starts it
(its keybind setting's default from mod.json), holds F7 in the fake keyboard, and reads the window in and out
of the snapshot. It passes on mods/stack: the F7 that did nothing in play3.log was not this path (the mod had
been stopped by its budget faults, play3.log:4032).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
"mods: local/link-hud: action rupee_log on key F7 and pad L+R" when a mod makes an action (on key, on pad, or on
no key and no pad), and "action rupee_log pressed, its first time (by key F7)" once an action: the next run where
a key seems to do nothing says whether it reached the mod. (play3.log had neither, and the F7 that did nothing came
after local/link-hud was stopped by 3 budget faults in a minute, play3.log:4032.)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
draw_node in gpu/vk/vk_modui.cpp grouped MKWVK_UI_WORLD with Canvas and Spacer, the leaves that draw nothing, so no World
root ever showed its label: enemy-names ran a whole session in the game with its labels mounted and none drawn. The
check cuts draw_node and asks that the World branch reach draw_children. Fails here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A World root is a container since e1a620b6 (modui_layout.cpp leaf() leaves it out, and lays its children out), but
draw_node still had it with the leaves that draw nothing (Canvas, Spacer), left from when it was a place holder: the
renderer placed each World root over its point, measured its label, and drew none of it. It is drawn as the other
surfaces' roots are now, through the default branch.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
While any World root exists, world_resolve logs "mods: world: N roots, V visible; hidden: B behind, O off screen, F far,
G gone, W no view (the view: ...)" once a second, each hidden root counted by its first reason, and camera.c says what
the frame's view was made from (the game's matrix, or the eye and target and why) or why there was none
(modrt_camera_view_said). A run where labels do not show says where they went. tests/modui_test.c checks the counts
and the second between lines; docs/modding/ui.md shows the line.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Labels over enemies showed through walls. At the frame's gameplay upscale, where the scene's depth is whole (vk_draw.cpp
world_depth_at before any upscaler takes the dispatch, vk_temporal.cpp temporal_world_depth with the camera the chain takes,
engine or not), the recording copies five depth texels around each visible World root's point into a 10 KB mapped buffer
(vk_world_depth.cpp). A later present reads a copy only once vk_timeline_completed() has passed its recording: no wait is
added anywhere, and a frame with every copy in flight goes untested. Each tap goes back to a distance through the scene's
own projection (world_depth.h, fsr3_math.h's d = a + b / v) and is compared with the root's depth along the view from
host/modapi/camera.c modrt_camera_project, with a bias of 0.25 m + 2%.

A World's occlude prop (or its mount's opts): "hide" (the default, or true), "fade" (dimmed to 0.3) or "none" (or false).
The share of taps shown scales the root's alpha, eased over about 0.1 s; a new root fades in once its first copy is read.
The renderer tells the host when a root goes behind or comes out (MKWVK_UI_EVENT_OCCLUDED, never the mod's), and the
mods: world: line counts them (N occluded). MkwVkUiSurface.occlude: snapshot version 3. With no World root that asks, each
place that would test is one relaxed load (architecture.md, Mod UI in the renderer, rule 5).

tests/world_depth_test.cpp (via tests/test_world_depth.py) runs the depth math, the formats, the taps, the modes and the
copies' ring, and checks the wiring; tests/modui_test.c the prop, the opts and the event's count. The fake game takes
occlude (lib/fake-ui.js). docs/modding/ui.md and ui-channel.md say how it behaves.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
world.ray(from, to) -> RayHit? ({hit, position, normal?, distance}) against the game's own collision: the schema
(modapi/schema/world.toml, RayHit in types.toml), its bindings, the reference and the d.ts made by generate.py. No game
build answers it yet: services_game.c says false for world and world.ray, so a call throws NotAvailableError naming
world.ray, and a mod written against it loads everywhere and works on the first build that answers. host/modapi/world.c's
own answer, reached only by a stand-in game, is null.

A read of the lifted code found the game's synchronous collision-query executor (it reaches Havok's hknpWorld::castRay
through the physics manager's world). But it takes the physics world's lock, and whether the main thread may take that
lock at the acquire phase has not been shown by a run; nor which filter preset is the scenery alone.
docs/dev/reference/world.md says what a build needs before has("world.ray") says true.

The fake game matches: world.ray absent unless a test gives a world (game.allowRay(cast)). tests/test_modrt.py checks the
export, has() and the error; tests/mod_settings_fake.mjs the fake's absence and a hit against a test's floor, and a World's
occlude as the host takes it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
"enemies: listed L, near N, labels M" by log.info (it shows outside dev mode), with "(no position for Link)" when
player.state() has none, timed by the update's dt. tests/test_modrt.py runs the mod through the loader in the real
runtime: a label over an enemy shown on the view, its line, the host's World line shown and with no gameplay view, no
fault; its fake-game test checks the line.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
game.pause() asks the game's own pause manager (the one its pause menu, loads and events ask, f_80b1b980 and
f_80b1ba70) for DebugPause, the developers' pause type: the actors, effects, sound, timers, events and the UI's
update stop, and the 3D is still drawn. It stops the camera manager too, which would leave a mod's override
nothing to write into, so the camera's row is cleared in DebugPause's mask before the request and set again after
the release. Counted over every mod (no claim, 32 at once), given back by release, the mod's stop or the last
holder; ContextError outside play and paused. While held, state().mode reads paused, so after()'s game time stands
still.

hideGameHud() hides the game's Layer2D through its own event action OneShotSetLayerVisible, kept hidden if the game
shows it meanwhile and put back as the game last had it. longshot/ui gets native.hideGameHud only on the build
whose layers Longshot knows; it needs camera.write.

host/game/pause.c is the game's half (no hook site; nothing runs while no mod holds either), host/modapi/camera.c
counts the holders, ui_module.c gives the native. The fake game pauses and hides by default, as the game build does,
and refuses the pause outside play; the photo mode uses both, guarded for a build without them. The findings, what
was ruled out (the frame step's zero step, GamePause, a renderer-side hide) and what a game run must confirm are in
docs/dev/reference/camera.md. Checks: tests/test_game_pause.py over made-up guest memory, and the script runtime's
pause and HUD cases in tests/test_modrt.py.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The holder logged after p.release(), and the release prints the game's PAUSE off within the call, so the log line
came after it and the check failed though the game was let go at the right holder. The code is right; the check
now logs first.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Image src is a PNG of the mod's folder, read and decoded on a host thread (host/modapi/ui_images.c,
png_decode.c), capped (2048 px a side, 4 MiB an image, 16 MiB and 64 files a mod), shared by every node
naming it and held by the snapshots that list it; the renderer uploads each once through Dear ImGui's
texture path (vk_imgui.cpp user_texture) and gives it back when no snapshot names it. fit, tint, width/height.
Icon draws one of 30 built-in vector icons (gpu/vk/modui_icons.cpp). Canvas onDraw(d) records rect, line,
circle, path, text, image, clip and measure when it renders; the list is sent as a new "draw" op only when it
changed, checked and capped by the host (10,000 commands a canvas, 20,000 a mod), and drawn into ImGui's
draw list in the canvas's box. MKWVK_UI_SNAPSHOT_VERSION 2 (MkwVkHost unchanged). The fake game checks and
reads the same (game.ui.canvas(), image(), images()); ui-cases gains the canvas and picture cases.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A script mod's own GLSL fragment shader over the picture (Modding API spec 10.3), with the permission
gfx.shader (medium): gfx.effect({ shader, at, params }) gives an Effect handle with set(params),
setEnabled(on), info() and release().

- The effect template, checked on the SPIR-V (gpu/vk/fx_spirv.h, plain C): one fragment main, the picture
  at set 0 binding 0, uv, one vec4 output, a push-constant params block read by name; no buffers, storage
  images, discard, atomics, barriers or specialization constants; counted loops only (1,024 turns through
  nesting and calls), no recursion, back edges only from a loop's continue block. The host checks it at
  the call (an ArgumentError saying why) and the renderer again before any driver sees it.
- longshot-mod shaders compiles each .glsl with the pinned glslang (-V -g -S frag); -g keeps the source,
  which the host compares with the shipped .glsl. The game never compiles GLSL.
- The host's list (host/modapi/gfx.c) and the renderer's passes (gpu/vk/vk_effects.cpp, shaders/fx_*):
  beforeUpscale on the gameplay upscale's input, afterUpscale and beforeHud on its output on every
  upscaler path, before frame generation's HUD-less copy; per-effect GPU timestamps, stopped over 2 ms
  (RX_VK_FX_BUDGET_US); RX_VK_FX=0 for an A/B. With no effect: fx_generation answers 0, nothing runs.
- Render-target recipes (host/modapi/recipes.c): a gfx.textures mod's recipe.json sizes the renderer's own
  scalable targets (gpu/vk/mod_gfx.h: sunShadow, the Shadow resolution row's sizes) where the row is Auto.
- MkwVkHost version 41 (fx_generation, fx_list, fx_code, fx_note, gfx_recipe): MKWVK_API_VERSION 40 -> 41.
- The fake game's longshot/gfx (lib/fake-gfx.js), the example sepia-photo, docs/modding/gfx.md, the
  architecture's rules, gate 5's reserved names, tests/test_gfx_effects.py.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
textures/<name>.ktx2 is named as a PNG is: the 8-bit uncompressed formats (R8 to B8G8R8A8, UNORM or sRGB),
no supercompression, one 2D image, its first level read and the rest made by the renderer as for a PNG
(host/ktx2_decode.c). Basis Universal, BC and ASTC blocks, supercompression, 16-bit and float are refused
with the reason in the log; BC kept as BC with the file's own levels needs an upload path of its own.
A gfx.textures mod with a recipe.json and no textures folder is not told it lacks one. textures.md
documents KTX2 and render-target recipes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
test_gfx_effects.py's mod imported LimitError twice (API_IMPORTS has it), so it never started and the
generation never moved; test_texture_pack.py builds host/ktx2_decode.c beside texture_packs.c; the
text field's host fixture declares MkwVkEffect, which rx_backend.c's version 41 declarations name.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
gfx.effect and Effect.set took { amount: [1] } for a float param, as the fake game did: a float now
takes a number alone and a vector a list of exactly its size, else ArgumentError (param "amount" is a
number), in the host (host/modapi/gfx.c apply_params) and the fake game (lib/fake-gfx.js) alike.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A small process (the same executable, `--broker`) that holds what a
confined game may not: Discord's local socket (relayed frame by frame,
the handshake and SET_ACTIVITY only), sending a crash report (to the
stamp's address it reads itself, https, no redirect, 3 a run), opening
https links under the crash window's issue address and Longshot's pages
and folders or text files under logs/ and bug-reports/, and moving the
crash window's helper into a systemd scope of its own. Framed messages
over SOCK_SEQPACKET channels, at most 16 KiB, fds beside them; a
malformed frame loses its channel. The crash window's helper gets a
channel of its own (LONGSHOT_BROKER_FD), and a restart hands the
game's down. Nothing starts it yet: the sandbox does, next.

Rules in docs/design.md section 14; tests/test_broker_frame.py checks
the framing, the Discord checks and the opening rule.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
At its start, before SDL, the sound or Vulkan start a thread, the game
starts the broker and then confines itself, for every player: read the
game folder and the system, write the user folder, the game folder's
cache/ logs/ bug-reports/ modcache/ user/ and the drivers' shader
caches, devices with their ioctls, nothing else of the home folder; on
ABI 9 only the Wayland, X11, PipeWire and PulseAudio sockets (not the
session bus). A seccomp filter (TSYNC) allows only AF_UNIX and
AF_NETLINK sockets and refuses io_uring, on every kernel. The log says
every rule, what stays open on this kernel's ABI, and whether it was
confined. A failure confines less and never stops a start;
HOS_SANDBOX=0 turns it off, =strict refuses to start unconfined.

Windows: a stub and the AppContainer design (host/sandbox_windows.c).
docs/sandbox.md for players and contributors; tests/test_sandbox_linux.py
checks the ABI plan, the rules on made-up folders and the filter with
a BPF interpreter of its own.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review of mods/sandbox:
- host/json_keys.h: a strict JSON reader that decodes top-level keys, so
  a second "cmd" by any spelling ("\u0063md") or a trailing document is
  refused; the handshake must be exactly v and client_id, and the first
  application id is pinned for the broker's life.
- own_scope serves the game (the broker's parent) and processes it
  started, by /proc's parent chain, at most four scopes a run.
- The broker starts without LD_PRELOAD and sets PR_SET_DUMPABLE 0.
- Discord streams are non-blocking; a zero-length datagram ends the
  channel and its fd is closed; logs/ and bug-reports/ are made before
  the broker realpaths them.
- hos_broker_adopted: a restart's broker, so the sandbox is not applied
  a second time.
- HOS_BROKER_TEST: tests/test_broker_frame.py now builds host/broker.c
  and drives open_thing, crash_send and own_scope with the programs only
  recorded, plus the JSON reader and the policy helpers.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From the cold review of mods/sandbox:
- When (decided for now, pending the owner, spec gate 16.5): unset,
  only while a script mod is on (a mod.json with a runtime, enabled in
  mods.json); HOS_SANDBOX=1 always, 0 never, strict as before. It is
  refused from longshot_env.txt, so a confined run cannot turn the next
  run's sandbox off.
- The user folder is listed, not written: only its save/, temp/, cache/
  and nfc/ are; the launcher's launcher/ is neither read nor written.
  ~/.local/share/longshot is never given whole (nfc/ written, ngx/ read).
- The game folder is never written whole: its cache/, logs/,
  bug-reports/, modcache/, perf_pending/, perf_sent/ and user/ are; the
  settings file, mods.json and language.txt are single files written in
  place, made first when missing (hos_language_txt_ensure).
- /dev by class with ioctls (dri, input, snd, bus/usb, dma_heap, NVIDIA's
  and hidraw nodes, udmabuf); /dev/null and the random devices without;
  never a tty or /dev/uinput.
- A socket right a kernel refuses on a file skips that socket alone.
- Abstract sockets scoped from ABI 9 only (obs-vkcapture below it);
  what stays open on every ABI (X11's XTEST, PulseAudio's module
  loading, PipeWire's streams, the kernel) is logged and documented.
- PULSE_SERVER and PIPEWIRE_REMOTE paths, /dev/log, nvidia-persistenced;
  Steam's client and runtime folders and STEAM_FOSSILIZE_DUMP_PATH; the
  Vulkan drivers' library folders (relative ones too); MangoHud's and
  vkBasalt's settings; AMDVLK's cache; a private /tmp as TMPDIR;
  diagnostic switches' folders from the real environment, never the
  home or above; RX_VK_DLSS_DIR only when it holds DLSS's runtime.
- A restart's broker: confined already, not a second Landlock layer;
  seccomp's TSYNC refusal is logged and falls back.
- tests/test_sandbox_linux.py builds host/sandbox_linux.c over a
  stand-in kernel that refuses what Landlock refuses, over a launcher
  layout and an installed bin/ layout.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
sandbox_linux.c gives the folder /proc/self/exe is in read and run (the
executable's folder). The driver was built at the top of the temporary
folder the cases' made-up homes and launcher folders are made in, so that
rule covered all of them and the check that ~/.ssh and launcher/ are not
read failed. The driver now lives in exe/, beside the cases, as a real
executable's folder is beside the home.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
tests/test_msvc_oldnames.py reads #ifndef __linux__ ... #else as code the
Windows build compiles, so broker.c's Linux body (lseek, getpid) counted as
legacy names in the MSVC build. The Linux body is now under #ifdef
__linux__ and the stubs in its #else, which the check reads right.

tests/test_restart_log.py cuts relaunch() out of hos_relaunch.c, which now
hands the broker's channel on through hos_broker_exec_env: the harness gets
a stand-in that passes the environment on as it is.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The broker hands the game a net channel of its own (BROKER_NET_CHANNEL, one at a
time, the game's channel only) and runs broker_net_serve on it on a thread of its
own. hos_broker_launch routes every link through it (bnet_use_broker), so a run
the sandbox set out to confine never runs the engine itself: with no broker a
mod's connection is unavailable. Without the sandbox the in-process engine runs
as before. Every check the engine makes (grants, origins, the address rule and
its pinning, redirects, limits) is the same code on either side.

The game's end of the channel never blocks: what the socket cannot take now is
kept in order and sent at the next call, up to 16 MiB; the broker's end waits at
most 10 s for a game that does not read. A frame that could not go ends the link.

Tests: the link through bnet_use_broker to an engine in a child process over a
real socket pair, the game's end with nobody reading, and the broker's handler.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The broker owns a socket in the user's runtime folder (BROKER_DBUS_PROXY) and the
game is pointed at it before it confines itself (DBUS_SESSION_BUS_ADDRESS; a
Landlock rule for that socket alone). Each connection gets one of the broker's
own to the real session bus, and only a short list goes through: Hello once and
first, org.freedesktop.ScreenSaver Inhibit/UnInhibit, the portal's Inhibit and
its Request's Close, and gamemode's RegisterGame/UnregisterGame for the game's
own process. Anything else is answered AccessDenied by the filter; from the bus
only the replies to calls let through come back. No signals are subscribed, no
names owned, no file descriptors passed.

host/dbus_proxy.h reads the D-Bus wire format with strict bounds (the game's side
is untrusted), the list, both sides of EXTERNAL authentication and the bus's
address; host/broker_dbus.c is the socket and its loop.

Tests: the parser on malformed, truncated and bit-flipped messages (under the
sanitizers where the compiler has them), the list, the error, the authentication,
and the filter between a stand-in bus and a client.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A confined run has no network and cannot write Downloads or start the desktop's
programs, so both went nowhere under the sandbox. Now:

- BROKER_PERF_SEND: the summary's file posted with the system's curl to the
  stamp's perf_reports= address, read by the broker itself (https only, no
  redirect, 1 MiB, one at a time, 64 a run), on a side channel of the game's so
  its own channel is not held while curl waits;
- BROKER_SAVE_DOWNLOAD: the zip handed over as a memory file and saved under a
  name of Longshot's only, in the Downloads folder user-dirs.dirs names (else
  ~/Downloads, else the home folder), never over a link, then the folder opened;
  the issue is opened through BROKER_OPEN.

MkwVkHost gains broker_perf_send, broker_save_download and broker_open:
MKWVK_API_VERSION 40 -> 41. Each says -1 with no broker, and the renderer then
does it itself as before. The checks that found version 40's functions at the
table's end find them by position after version 39's now.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
host/broker_windows.c serves host/broker_frame.h's messages, one to a message of a
message-mode pipe, from the sandbox's outer process: a stream or a channel it makes is
duplicated into the client (its value in the reply), the crash report is named by its path
and opened as the client. Only a client in the job and the AppContainer is served.
BROKER_NET_CHANNEL (7) is the net engine's channel: Windows serves it with
broker_net_serve_handle; Linux's broker answers it has none until the network join.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
While a script mod is on (HOS_SANDBOX as on Linux), Windows' main() starts the game again
inside the Longshot.Game AppContainer (PROC_THREAD_ATTRIBUTE_SECURITY_CAPABILITIES, no
capability: no network), suspended and in a KILL_ON_JOB_CLOSE job, after granting the
container's SID the game folder (read) and the game's own folders, the user folder's, the
drivers' shader caches and the three settings files (write) with SetNamedSecurityInfoW. The
grants it added are recorded in the user folder's sandbox_grants.txt; --sandbox-revoke
takes them back. The first process stays outside as the broker and ends with the game's
exit code. Any failure runs the game unconfined with a log line, strict refuses.
host/sandbox_win_plan.h holds the decisions as plain C; tests/test_sandbox_windows.py
builds them on the host and reads the sources. Not run on Windows yet: the docs list what
a run must confirm.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
M11 of the Modding API plan, the run-time half. The raw permissions are in the schema with their prompt words:
memory.read, memory.write and hooks.unsafe of risk unsafe, romfs.read high; the manifest's rule that raw game data
(romfs.read, memory.read) is never held with net: or session stays as it was, and now has users.

- longshot/memory (host/modapi/memory.c): read(address, length) a frozen ArrayBuffer copy, write(address, data) queued
  and made after update with the flags' writes, regions(). Every range is checked against the game's memory map at the
  call, wholly in one part (host/hos_mem.c hos_mem_part: the image's segments by their permissions, the heap, the
  regions); Longshot's own objects and unmapped ranges are refused (MemoryError, reason and address), and writes into the
  game's code or read-only data too: the deny list's rule taken to memory. 64 writes and 256 KB a frame for a mod.
- longshot/romfs: read(path, { offset, length }) and size(path) of the file the game is served (the RomFS layers, then
  the dump's folder), paths checked, 4 MiB a read.
- longshot/hooks (host/modapi/hooks.c over host/game/modsites.c's slots): listen(site, fn), sites(), setValue(site, v) for
  a mod's own sites as mod_sites.txt says the game was built with them. A listener runs only at a serial site reached on
  the main thread while no script runs (an event frozen, a filter's sealed draft written back to the registers and its
  answer the site's); every other visit is recorded and told at the next frame (256 a frame); a data rule's value is
  the slot's, back to 0 when the mod stops. The Mods tab's line says "Unsafe" for a manifest with an unsafe permission,
  and the loader holds back a mod host/mods.c names (modrt_hold).
- The generator's bytes parameters and results (an ArrayBuffer or a Uint8Array in, copied; a frozen ArrayBuffer out),
  in the C bindings, the adapter, the types and the fake game.
- The fake game (lib/fake-unsafe.js): game.memory, game.romfs, game.sites with reach() and notBuilt().
- The example memory-viewer, docs/modding/unsafe.md for players and authors, and tests/test_modrt.py check_unsafe.

Nothing runs with no mod using it: no thread, no read of mod_sites.txt, the slots off.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
M11 of the Modding API plan, the build's half. A manifest mod with the permission hooks.unsafe declares sites of its own
in a sites.toml beside its mod.json: the rows of the game's own tables (docs/dev/reference/hooks.md), found by their
signatures and hooked by the same compiler (nx2/mod_sites.py, after nx2/hooks.py's table in the lift).

- The mods' rules (check_mod_site): no function, value, kind or module; `builds` maps build ids to the function in each
  (checked where the player's build is listed, and picking among several places); the forms entry, return, after,
  before, branch and allow; a worker site is an event or a data rule (mul_f32, scale_f32 over its slot's value), never
  a filter, a branch, an allow or a can_return; arguments named, at most 8; 32 sites a mod.
- Found by signature in any game version; one site not found, or found several times and not settled, leaves its whole
  mod out ("not available for your game version"), not the build. A mod is placed whole or not at all: the lift's
  tables are put back when one of its sites does not fit.
- A mod's site is a slot of host/game/modsites.h (256): the hook tests hos_modsite_on[k] and calls hos_modsite_call(c, k);
  a mod's data rule reads hos_modsite_value[k]. The engine's sites are emitted as before.
- Code, as M0 has it: host/mods.c hashes a manifest mod's sites.toml (nx2/mod_sites.py code_hash the same), the mod is off
  until the player accepts its warning, the build takes it only as accepted (on or off), and the game holds it back
  whole while it was not built with the sites as they are now ("waits for a build"; hos_mod_build says a build is
  needed). The lift's key holds OOT_MOD_SITES_SHA1, the taken mods' ids, hashes and tables; none taken, nothing changes.
- mod_sites.txt (the image folder, then the game folder with the mods the build left out) says what happened, a line a
  site, and is what host/modapi/hooks.c reads.
- python -I nx2/mod_sites.py <mod folder> checks a table and finds it in an image on this PC without a lift.
- The example site-event (a worker event site at the entry of the text panes' letter step, found by two instruction
  words, with builds), tests/test_mod_sites.py (the rules, one signature in two made-up game versions, builds, the emit,
  a mod placed whole or not at all, the list, collect and the key, the host's register reads and writes), and the
  contributors' and players' docs.

Not built yet: longshot-mod sites port, a packaged mod's sites.toml, placing mods' new code in free space (M11 piece 4).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The unsafe tier's strongest step (Modding API spec 8.6, new; plan M11). A manifest mod folder with native/ sources and
"native": {"entry", "std"} in mod.json, holding the permission native, is compiled on the player's PC by the game's own
compiler, target and CPU level into mods_native/<owner>__<name>.so (.dll) beside the game, never into the game.

- The ABI: modapi/native/longshot_native.h, C, usable from C++, versioned (LSN_API_VERSION 1.0). The mod exports
  lsn_mod_main through LSN_MOD_MAIN, which answers its version to a first call with NULLs: another major, or a newer minor,
  is refused before its code sees the table. The table: mod_id, mod_dir, log; on_frame, on_update, on_shutdown; export_fn;
  listen_site, listen_own_site and site_name, site_reg, site_nargs, site_arg, site_writable, site_set_arg, site_answer;
  mem_read, mem_write (one part of the map, never wrapping, never code or read-only data); setting_json.
- The build (nx2/native_mods.py, called by nx2/make_game.py once the game folder holds the new game): each accepted mod's
  .c/.cc/.cpp/.cxx compiled with -O2 -fvisibility=hidden, only modapi/native/ and its own native/ on the include path, an
  undefined symbol failing the link, C++ runtimes static. One mod that fails is left out alone with the compiler's first
  error lines; a library built from the same code and commands is kept. native_mods.txt beside the game says what.
- Accepted as code: host/mods.c hashes a manifest mod's code files (native/ and sites.toml, manifest_code_hash; nx2/mod_sites.py
  code_hash the same; a mod with sites.toml alone hashes as before), off until the player accepts its own warning, held
  back whole while its library is not built from its code as it is now.
- The load (host/modapi/native.c over host/modapi/native_core.c): after the resolver, before any script, each native mod
  that loads is opened (dlopen; LoadLibraryExW with the UTF-8 path made wide) and its entry called; frame and update at
  orders 101 and 111 of the acquire phase, right after the scripts'; shutdown callbacks at exit. Each callback is timed and
  warned about past the script budgets (5 ms, 2 ms a frame). The Mods tab's switch stops and resumes its callbacks at once.
- Sites: a named site is tapped (host/game/sites.c hos_site_tap: a dispatcher told before the site's own callback, whose
  answer stands; read-only, any thread); a mod's own site is given to its native listener (host/modapi/hooks.c), written back
  and answered only at a serial site reached on the main thread (host/game/modsites.c hands it the visit's context).
- longshot/native (modapi/schema/native.toml): call(name, args), the mod's own functions or "<owner>/<name>:<fn>" of a
  dependency, values as JSON's plain data without objects; a failure is a ModCallError. The fake game's game.native
  (lib/fake-native.js) stands in for the C.
- The example native-hello (a C entry that logs, counts frames, hears actors.update and exports add(), and a script that
  calls it), docs/modding/native.md, and tests/test_native_mods.py: the example's exports, one failure left out alone, the
  game's hash against the build's, the real loader over a fake table (version refusal, frames, the switch, values both
  ways, refusals, memory ranges with wrapping, shutdown), and the loader and the example compiled for Windows with
  llvm-mingw.

Not built yet: native code in a packed .lsmod, the launcher's own prompt for native, storage through the table.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Three more kinds of typed patch file beside "ops" (host/mod_patch.h), the ones the
content stage needs and a mod may ship too:

- "rows": rows of a data table (the RSDB tables: an array of dictionaries sorted
  by __RowId, or the column "column" names). add puts a row in at its sorted place,
  whole or copied from another key with paths set or added (a copied ActorName that
  names the row copied names the new one); set changes a path inside a row; remove.
- "placements": a map's placed actors by their 64-bit Hash ("0x..."). add
  appends one with its Hash and Phive/Placement/ID as uint64, its Translate, Rotate
  and Scale as floats and its SRTHash as a uint; set and remove by hash.
- "texts": labels of a message file inside a language's text archive. A bounded
  MSBT reader and writer of Longshot's own (host/mod_text.c: LBL1 and TXT2, labels
  in their hash slots, UTF-8 or UTF-16; a file with another section is not
  written); set adds or replaces a label's plain text, remove takes it out; the
  archive written again with restbl_sarc_put.

Each op has a path made of its key, so conflicts are found and named as for keys,
and only between patches of one kind (and one message file).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Modding API spec 6.2, milestone M5 piece 6. mod.json's "content" names a module run
once while the game starts, before its first file is opened (hos_mods_init), in a
runtime of its own: context "content" (api.toml), importing only longshot,
longshot/log, longshot/content and the mod's files. longshot/content's item, actor,
model, place and text (content.toml; their shapes as TypeScript in the namespace's
new ts_types) declare; the host makes the game's own kinds of files of them on the
player's PC (host/mod_content.c), served through the RomFS layers as the mod's own:

- a new actor: a copy of the pack of the actor it copies, as the layers serve it,
  with a new ActorParam whose $parent is the copied one and its changed components
  under the new name (host/mod_content_pack.c, made in the merged-file step,
  romfs_content_pack), and copies of its ActorInfo and GameActorInfo rows;
- an item: an actor, its PouchActorInfo row, and its name, description and get
  message in every language's ActorMsg/PouchContent.msbt;
- a model: the mod's own .bfres.zs and .bntx.zs files at Model/ and Tex/;
- a placement: added to Banc/<map>/<map>_<age>_<layer>.bcett.byml.zs;
- texts by label in every language's archive.

Mod-owned names: a mod's word is M and the FNV-1a 32 of its id, a new actor
<category>_<word>_<id>, a placement's id the FNV-1a 64 of its mod, map file and id:
the same on every start and PC, and no game name has that form. Cached by content in
modcache/content/ (the plan by the mod's script files, the outputs by the plan); the
new packs in modcache/files/ by what they copy; the size table follows by itself.
The permission content.add (medium), which also keeps a mod off "local"
multiplayer; a mod with content and no entry loads with its content only.
items.grant, items.held and actors.list take "owner/name:id" (":id" the mod's own).
A text archive's patches build on host/texts.c's PC wording.

The fake game runs the content module too (lib/fake-content.js, the same rules
written again; game.content: names, outputs, problems against a fake RomFS), and
tests/mod_vectors/content.json holds both sides to the same results and files
(tests/test_mod_content.py, with the rows, placements, texts and pack builder on
made-up files). Research and what a game run has to confirm:
docs/dev/reference/content.md; authors: docs/modding/content.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The content stage's example (docs/modding/content.md): content.js declares Rupee7, a
copy of the blue rupee worth seven (its bundle of green ones) in the purple rupee's
colour frame, named in three languages, and LuckyPot, a copy of the game's pot,
placed in Kokiri Forest for the child to drop it; main.js grants one by its id,
items.grant(":Rupee7", { key: "welcome" }). Its tests read game.content's names,
packs, rows, texts and placement, and the grant, in the fake game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
mapLoading and mapLoaded (the load flag and the map, polled at the acquire phase), saveWriting (the
save manager's request, at the site save.request) and flagChanged (the flags some listener names, read
once a frame: no writer hooked) over a new game service, host/game/watch.c, fired by
host/modapi/game_events.c after dev.reloading (orders 20 to 23). Nothing is read while no running mod
granted state.read listens (gate 5).

flagChanged is a watched event: an [[event]]'s new filter_required makes on() need its filter, in the
host and the fake game; the service refuses an unknown name or a 257th flag at on().

textShown is a filter of the schema and the fake game (showText, allowTextShown); absent in the game,
whose point where a message box takes its text is not found (docs/dev/reference/game-events.md).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
mapLoading and mapLoaded (the map left, a load's time), saveWriting (the maps since the last save),
flagChanged on two flags named one listener each, with a name the build lacks refused at on(), and the
textShown filter where the build has it and the optional state.write is granted; tested in the fake
game with setState, enterMap, saveGame, setFlag and showText.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
third_party/stb_vorbis (nothings/stb 033efa1b, unmodified, public domain or MIT) with its PROVENANCE.md. nx2/build.py compiles it once (STB_VORBIS_NO_STDIO, STB_VORBIS_NO_PUSHDATA_API) and keys host/modapi/audio_mix.c's object on it; the third-party objects set and the AppImage carry it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The schema's module longshot/audio (permission audio): audio.load(path) gives a Sound (a mod's resource, StaleHandleError once released), whose play, playAt(position) and playOn(actor) give a Voice (a handle that ends: playing(), stop(), setVolume, setPan, setPitch, moveTo answer false after). host/modapi/audio.c is the services and the placed voices, heard from the camera each frame after the writes; host/modapi/audio_mix.c decodes on its own thread (lsmod-audio, made at the first load), holds the voices and mixes them in host/nn_audio.c's mixer after the game's frame and before the player's Volume, through a limiter; one atomic load while nothing plays (gate 5). Limits: 64 sounds, 32 voices and 32 MB decoded a mod, 128 voices in all, 16 MB a file. A mod asking for audio gets a Sound volume row on its page in the Mods tab (settings.c, kept as $soundVolume). The fake game records plays (game.audio). Tests: tests/modaudio_test.c with tests/test_mod_audio.py (decoding, mixer, limiter, limits, release, the mixing point), test_modrt.py check_audio (the API in the real runtime). Docs: docs/modding/audio.md, docs/dev/reference/mods-audio.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
longshot/audio's example: chime.ogg on actors.died, placed on the actor (playOn), and ping.wav on a keybind; its tests read game.audio.plays and the voices' side and gain. docs/modding/examples.md lists it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The joined branches each bumped the renderer's interface on their own (36 to 41). Against main's 35
they are one change: MKWVK_API_VERSION is 36, every gate on a host's version and every check that
named 37 to 41 now names 36, and the menu's check of an older host turns the live switch's functions
off rather than naming a version between.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The branches numbered their events apart: actorsw moved settings to reloading up by three (11 to 16),
toggle put lifecycle.stopping at 14 and the game's moments came at 20 to 23. One sequence now, as the
host fires them: ... dev.reloading 16, lifecycle.stopping 17 (the Mods tab's switches), then the
game's moments mapLoading 18, mapLoaded 19, saveWriting 20 and flagChanged 21, after the switches.
The fake game's late events start at 18; the loader's and the docs' order notes follow.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
mods/tools kept a copy of mod_sites' format checks for a branch without mods/unsafe. Both are here:
mod_sites_port.read_table is mod_sites.parse_mod_table, so the port takes only what the build
takes (the mods' rules too); the test checks a site at the engine's replace is refused.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
With the built-in mod inspector on F8 the dev overlay gave the key up whole (modrt_dev said dev mode
was off), so Shift+F8, its reload of every folder mod, was lost. Now modrt_dev(-1) says only that the
inspector holds plain F8: the overlay stays hidden then and Shift+F8 still reloads; and in dev mode an
action on F8 is not held while Shift is (input.c), so the inspector takes plain F8 only. Tests: an
action on F8 under Shift in and out of dev mode (test_modrt check_dev_shift_f8), and the overlay's and
the host's order (test_mod_settings, whose event orders also follow the joined sequence).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The game's adapter (host/modapi/bindings.c from_value) returns null for a function with no result;
the fake game's prelude and FakeGame._call gave undefined (found by the audio work). Both give null
now. Tested in the game's runtime (test_modrt check_void_null) and the fake game
(mod_settings_fake.mjs); no test expected undefined.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The branches each counted the examples they knew of ("twenty", "nineteen"); thirty are in
modapi/examples. The guide's index names every one, and the examples page says thirty and lists
all twenty plain JavaScript ones.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The texture packs' three, the live switch's three, the screen effects' and recipes' five, then the
broker's three last: each check finds its functions after the ones before them now.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
broker_windows.c ends itself only when it could not stop acting as its client (fatal: recorded, not a
clean end), and a TerminateProcess of the confined child is not this process's exit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The AppImage and the builder package carry modapi/native/ (the host includes longshot_native.h and
nx2/native_mods.py compiles a mod with it); tests/modrt_stub.py stands in for host/mods.c's
modrt_native_* calls; the build's finish checks get what main() made before it (mod_sites, no mod
with sites); and lint does not warn about native, which a mod's native/ code holds.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The fallback upscale's and the HUD capture's fixtures stand in for the World depth test and the
screen effects; the World depth check finds the upscale's picture with its effects' input; the mods'
UI check follows the snapshot's layout serial; and the screen effects' write of the picture gives
texture_written no reason, as the upscalers' stand-ins do (it is the upscale's output, not a page
a virtual pool maps).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
gfx.shader is a permission now: the one this Longshot lacks is gfx.world. The host's World line
names the occluded roots. The port's mods-rule check uses a site naming its function.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Actor.setLife is actors.setLife with the actor first: lint follows imports, and a handle comes from a call, so a call of
such a method's name in a file that imports longshot/* keeps the declared permission from the unused warning (it never
makes one needed: log.info is not actors.info).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- test_function_ends: oot_patches' text edits are hook sites now; the check of an edit's place inside one function takes the
  one left, the preload manager's choice (main's OCB hold).
- test_host_free_marks: the fixture defines the image's segment table hos_mem_part reads (the unsafe tier's memory parts).
- test_modui: modui_frame_end decides on a snapshot with the World roots' move too (!dirty && !moved).
- test_world_depth: the snapshot version is 3 or later with the occlude field (the canvas moved it to 4).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
#1763 took the parallel replay away, and with it InitRedirect and tl_seg: the pack image's first layout change goes on the
upload command buffer as create()'s does, and pack_view no longer asks which segment filled it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The OCB hold's text patch (nx2/oot_patches.py patch_ocb_hold, kept from main for #1763) is now an engine
site: before the update's test of its choice (tbnz w21, #31 at f_832b9880+0x548), after its label on
every way in as the patch was, its callback setting x21 from hos_oot_ocb_pick with the manager in x19.
oot_patches' per-file pass edits no function now; only the output size's eight whole-file edits are left
there. ExeFS patches that would break the place are now refused like any other site's. Changes the lift
key (the table's hash and nx2/oot_patches.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Several subscribers a site (host/game/sites.c hos_site_subscribe): the owner (the engine's callback, or
the service hos_site_set gives) and up to 11 more, called by order (engine, services, mods by load order),
then by when they came. Only the first in order that asks answers and writes; a later one that asks is
not called, or (HOS_SITE_READ_IF_OUTRANKED) called to read, and the clash goes to a handler once a pair.
A site with its owner alone keeps the owner's callback in its slot (one indirect call, as before); with
more, a dispatcher over a published snapshot freed by its reader count, as the rule tables are.

Native listeners at named sites (host/modapi/native.c) are now such subscribers, after the engine's and
the services' callbacks in load order (they were told before the engine's), with the site's args by the
table (host/game/sites_forms.h, generated by nx2/hooks.py --host-forms, checked current by test_hooks).
They ask to answer only at a serial site whose form lets a listener write (not replace), and write or
answer only there on the main thread; outranked, they read, and the log and the Mods tab note name the
site and who answers. Every named site today is a worker site, so they still read there.

vslot sites: the reader takes at = entry or return; the lift checks the slot against the relocated image
(in main's data, a relocation there, a function the lift found and the one the table names, one site a
slot: place_vslots) and stops on one that fails; the slot and method go into a64_table.c
(hos_vslot_resolved; nothing with none). The host swaps a host call's address in by compare-and-swap
while the site has a subscriber; its thunk runs the callback and the method. HOS_VSLOT lines in sites.def.
Dormant: nothing. Changes the lift key (nx2/hooks.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A second copy of nx2/hooks.py (a lift module loaded by its path, as test_hooks loads make_game.py) ran
install() again past the module's own flag and wrapped the wrappers: the vslot table was appended once a
copy (test_hooks Vslots.test_a64_table_gets_them_after_the_kits), and an entry or return hook would have
been spliced twice the same way. The mark is now on a64_lift.Lifter itself.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
533916b7 marked a64_lift.Lifter and skipped install() after that, so a check that puts its own emit back
and installs again (with _installed reset) got no hooks: test_hooks Forms.test_return_wraps_the_function
and test_hooks_emit test_the_emit. The first failure's cause was that re-install wrapping _write_table,
which no check puts back, again each time: the vslot table appended once a wrap. Now install() wraps
emit_function and _write_table each unless the one in place is its own wrapper (__hooks_wrapped__).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- player.setPosition (state.write): Link's actor queued by address (GameActorWrite.address) and moved by
  actors.write through his controller's ChangePosition (f_806d2530), as the Debug tab's flight and setPosition do.
- actors.light (actors.write): the inline table rule actors.lights before QueryShootableGetState's store
  (f_82b03400 +0xa4) answers 2 for a lit actor's node for 4 frames, so the bomb's own tree lights its fuse
  (the worker-outcome rule: an inline rule, TABLE_ANSWER). The fuse's time left is not found: not offered.
- actors.damaged: while a mod listens, the rules' table is published with a flag to note, and hos_rules_life
  notes each lowering write after the rules into a lock-free ring, told at the next acquire phase by life
  component in the list.
- rules.actorLife.add: inline rules rules.lifeInitMax and rules.lifeInit in f_808f8c50 (the life
  component's set-up), over their own table rules.spawn: the maximum ruled, the life held to it.
- game.state().timeOfDay (the world's clock, QueryWorldGetCurrentTime's read), player.state().maxRupees (the
  Int flag 0xe0010a50, QueryIsRupeeMax's cap) and .velocity (his controller's body) are read.
- textShown and world.ray stay absent (has() false): what was found and what is missing is in
  game-events.md and world.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- longshot/game's paused event (order 22, state.read): the game's own pause (the pause menu's PreGamePause, GamePause
  and PostGamePause, and GameOverPause, read from its pause manager: host/game/pause.c game_pause_types) and the mods'
  pause(), told when either changes; read once a frame only while a running mod listens (gate 5), the first frame a
  baseline. map-journal logs the pause menu; the fake game's setGamePaused.
- longshot/ui project() gives behind (behind the camera), host and fake game.
- A HUD mount's hideWithGame (default true): a HUD root is left out of the snapshot while the game hides its own HUD
  (an event or a movie plays, or the game hid Layer2D: game_hud_shown, a mod's hideGameHud aside), read only while such
  a root exists; the fake game's setGameHudShown. ui-cases covers both.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A mod declares at most 256 flags in mod.json's "saveFlags" (a switch, 0 or 1, or a counter in a 32-bit range, with a
default; it needs storage) and reads and writes them by name with storage.save.flags (get, set, has, names), as
game.flags does the game's. They are storage.save's data, kept as its entry of the empty key, which no mod's key can
be: committed with the game's save, back with the slot, none on the title screen, in its quota, refused with it
(NewerDataError); keys() never lists them. The game itself never reads them: new flags in the game's own list and save
(the spec's flag list) are not built, and docs/dev/reference/content.md says why (the save layout's sizes).

The manifest reader checks the declarations as the launcher must (new cases in tests/mod_vectors/manifest.json); the
fake game's twin is lib/storage.js (readSaveFlags, flagGet/flagSet, game.storedFlags()); tests/test_modstore.py runs one
mod in the real runtime through a save, a load, the title screen and a newer version's slot, and the same mod in the
fake game (tests/modstore_flags_fake.mjs), comparing the two. The generator now types a namespace nested twice as a
member of its parent's type.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A module's map (its sourceMappingURL line, a data: URL, or <module>.js.map
beside it) is read at the mod's first stack line that needs it, once,
inside the mod's folder: a fault's first frame, a logged warning's or
error's frames, and so the mod inspector's logs, say
src/main.ts:12:5 (dist/main.js:40:3). host/modapi/sourcemap.c keeps only
sources, sourceRoot and mappings and decodes the VLQ at the first look-up.
The fake game does the same (lib/source-maps.js, Node's SourceMap), and
longshot-mod build --source-maps (or tsconfig's sourceMap) writes a map
beside each built file; off by default, so the examples' dist/ stays what
a fresh build makes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A mod's entry imports longshot/content for read.row(table, key), read.text(file, label, { language }) and
read.actorName(actor, { language }), behind the new low-risk permission content.read (facts of play: allowed with the
network). Each answers with a Promise settled by a reader thread of the host's (host/modapi/content_read.c), which reads
the file the RomFS layers serve after every mod's changes, decompresses and indexes it at its first read and keeps it
for the session (64 MiB at most), so no table is parsed in a mod's callback; nothing runs with no call (gate 5). The
formats are host/mod_read.c's: a table's rows by __RowId made JSON from the bytes, a message text made plain with the
game's control tags left out. The fake game reads what game.contentData gives, the content stages' rows and texts
applied over it; seven-rupee reads its own item's name back.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A summary is named by its path and opened as the confined game, then posted by
System32's curl.exe to the stamp's perf_reports= address with Linux's limits, on a
second pipe connection so the game's channel is never held. A download is a file the
game writes in its own temp folder; the broker reads it as the game and saves it in
the Downloads folder (<name>.new made fresh, renamed over). The renderer uses the
broker for both on Windows too. hos_broker_dbus_proxy says HOS_BROKER_NOT_ON_WINDOWS.
The messages' Windows codec is shared code in broker_frame.h, tested on Linux.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- A package's native/ is extracted by the build into its work folder and built there;
  the game hashes the archive's entries as it hashes a folder (package_code_hash), so
  acceptance carries over, and starts the library from the loader's unpacked copy.
- LsnApi 1.1 appends storage_get and storage_set: the mod's store, the same as its
  script's (storage.c modstore_mod_get/put), behind its manifest's storage; LSN_HAS,
  LSN_E_DENIED, LSN_E_NEWER; an older minor loads, a newer one is refused.
- The native loader's measuring (main thread in CPU time, sites by the wall clock) is
  published each frame for longshot/mods inspect() (native, nativeMs), the mod
  inspector and the dev overlay.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
nx2/native_mods.py refused a zip entry whose Unix mode has no file type bits (zipfile's
own for a written ZipInfo), which host/mod_archive.c takes as a file. The driver's check
count is what it now runs (63).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The launcher's native_code_hash.json, copied unchanged to tests/mod_vectors/, passes the C (cut from
host/mods.c, compiled over host/posix with the real mods_list.c) and the Python, with the two cases where
they differed checked too. nx2/native_mods.py says why an unnamed mod is not built.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
nx2/make_game.py system_mods_trust reads host/modapi/system_mods.h, the table compiled into the game, and
the stamp writes it after mods_switches=. Documented in docs/dev/reference/mods.md (with the native code
hash's rules) and docs/modding/system-mods.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
research's actors.damaged and gaps' game.paused both took order 22 (the join gave paused 23 to build). One sequence
now, as the host fires them: the actors' poll's removed, spawned, died, lifted, thrown and dropped (5 to 10), then the
frame's hits, damaged (11, from modrt_actors_frame: before at 22 the fake game held it to the frame's end), then
settings.changed 12, permissions.changed 13, the input's pressed, released and moved 14 to 16, dev.reloading 17,
lifecycle.stopping 18, and the game's moments mapLoading 19, mapLoaded 20, saveWriting 21, flagChanged 22 and
paused 23. The fake game's late events start at 19; the loader's, the docs' and the checks' order notes follow.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
nativepk made the native table 1.1 for storage; hooksx changed what listen_site means (several listeners a named site,
called after Longshot's own callback and the game services', the one answerer able to write at a serial site, and
site_nargs/site_arg/site_set_arg given a named site's table args) without a bump. No game with the 1.0 table shipped,
so both stay 1.1: longshot_native.h's version list and docs/modding/native.md say so.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The world layer (spec 10.1): gfx.world of longshot/gfx (permission gfx.world, low) draws lines, boxes,
circles and billboards (a mod's PNG, a line of text, a square) inside the 3D scene. Each is a WorldShape
handle (moveTo, setPoints, setStyle, setText, follow an actor, setVisible, release), checked and capped by
the host (host/modapi/gfx_world.c: 2,000 shapes and 16,384 primitives a mod), which makes one immutable list
a frame that changed after the UI's frame end and hands it over through MkwVkHost version 36's world_take and
world_give (gpu/vk/mod_world.h). The renderer (gpu/vk/vk_world_layer.cpp, its math in world_layer.h, shaders
world.vert and world.frag) takes it once a present and draws it at upscale_written on every path that writes
the gameplay upscale's picture, before the screen effects after it and frame generation's HUD-less copy, with
the scene's own camera (vk_temporal.cpp temporal_world_scene, its jitter taken out), each fragment tested
against the scene's depth texel under it (hide, fade or none). Quads go through the recording's stream, a
mod's image is uploaded once by id, texts use the bundled font baked once by stb_truetype. With no shape:
one relaxed load in the host and in the dispatch path (gate 5); RX_VK_WORLD=0 for an A/B.

<World metres billboard> (spec 10.2): metres sizes a World root in the world (the host turns it into px at
its point through the view, snapshot version 5; the renderer scales the root about its point). billboard is
taken: every World root faces the camera. Rendering a root's subtree into an atlas drawn in the scene was
not chosen (a second ImGui pipeline and an offscreen atlas on the present's command buffer, sampled a frame
late by the replay); cut-by-a-wall drawing is the world layer's billboards.

Upscale recipes (spec 6.3): recipe.json's upscale part (a https model address, its SHA-256, onnx or
safetensors only, scale 2 to 4, name patterns, tile/overlap/alpha) is checked by host/modapi/recipes.c, now
read before the texture packs; host/texture_packs.c writes the launcher's runner its job
(modcache/upscale/<owner>__<name>/<job>/job.json, the matched textures of the player's index) and serves the
job's textures/ as the mod's pack once done.json names it, under the mod's own images. The game runs no model.

Example mod modapi/examples/debug-hitboxes; the fake game's gfx.world (lib/fake-world.js); tests
tests/test_gfx_world.py and world_layer_test.cpp, an upscale case in test_texture_packs_host.py; docs
docs/modding/world.md, ui.md, textures.md#upscale-recipes, architecture.md#the-world-layer.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
test_gfx_effects: upscale_picture is reached with frame interpolation, an effect or a world layer to draw, and
returns on the three relaxed loads first. test_gfx_world: nothing published before the first shape (both wl
before the first list), and the world_scale check names mkwvk::modui.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Thirty-one examples, as gfxworld counted (debug-hitboxes the thirty-first), seven in TypeScript and link-hud in TSX.
gaps changed map-journal (game.paused, setGamePaused in its tests) and ui-cases (HUD roots hidden with the game's HUD,
project()'s behind): their rows say so. The gap 'drawn in the scene itself, waits for the world layer' is built now.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
host/mods.c's package_has_native and package_code_hash read a package with host/mod_archive.c, and native_start asks
modrt_content_root: tests/mods_build.py archive copies mod_archive.c and miniz beside a check's sources (copy_host too,
HEADERS names mod_archive.h), tests/modrt_stub.py stands in for modrt_content_root, and test_mods_sizes and
test_native_code_hash link the reader. test_texture_pack stubs the upscale recipes (host/modapi/recipes.c),
test_fsr3fi_hud_capture world_layer_any. host/mod_read.c maps strdup to _strdup on Windows, as mod_content.c does
(the MSVC-target build links without oldnames.lib, issue 439).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
With HOS_MODS_DEV=1 the folder of each folder mod the start serves files of
(romfs/, patches/, a content module) is watched by dev mode's thread; a change,
once quiet, rebuilds the RomFS layers at the acquire phase (order 30, main
thread): every layer walked again into a new table, what is the same found made
in modcache/, the content stage run again (modrt_content_again), and the table
compared path by path with the live one and published whole with one atomic
exchange. Readers never lock: in dev mode each hos_romfs_resolve,
hos_romfs_file and hos_romfs_dir_extras counts itself in and out of the table it
read, and a replaced table is freed once that count is seen at 0, as the hook
tables' hos_table_publish. The next open of a changed path gets the new file; an
open file keeps the old one (made files are named by content; a merged archive
made again goes beside the start's).

The game reads the resource size table once, so it is not served again: a
changed path that needs a larger entry than the table the game read keeps its
old bytes until the next start, said in the log and on the Mods tab, which
otherwise says "applies on next load". Nothing is rebuilt while the Mods tab's
order or a layer's switch differs from the start's. Without dev mode nothing is
watched and readers count nothing (gate 5).

tests/test_mods_hot.py: a patch changed and served anew while a reader holding
the old table keeps its answer, a pack member's patch, a file edited in place,
the size table hold-back, a moved list, and four reader threads through a
hundred rebuilds (AddressSanitizer where available). Spec 7.6.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Unmodified from iOrange/bcdec at 80859ed3, with its PROVENANCE.md and tree hash: the BC decoder
of the upscale runner's input pictures (gpu/vk/texture_decode.cpp, next commit).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The launcher's runner needs the textures' pixels, not only their names. For a job not done, the
start now collects the textures its patterns name, and a thread of their own (below normal
priority, off the start) reads level 0 of each from the file the game is served (a mod's file in
the game's place is what is upscaled), has the renderer decode it on the CPU, and writes
in/<file>/<name>.png (RGBA, miniz's tdefl), then job.json last with each texture's "in" (job
version 1, as the launcher's UpscaleJobs.cs reads it).

- gpu/vk/texture_decode.cpp: mkwvk_texture_decode, an export looked up by name as
  mkwvk_close_asked is (no MkwVkRenderer change): suyu's unswizzle (the Switch 2 GOB) and CPU
  ASTC decoder, the renderer's own, and bcdec for BC1 to BC5 and BC7; plain R8, R8G8, RGBA8,
  BGRA8. Values as stored (no sRGB conversion), one channel as grey, two as red and green.
- host/rx_backend.c: rx_texture_decoder, the export as soon as the module is loaded.
- host/texture_packs.c: capped (made over 8192 a side, or past 2^28 input pixels a job, left
  out); a format the decoder does not take left out of the job so the runner takes it whole;
  in/sources.txt keeps what each picture was made from, so a later start makes only what
  changed; no decoder, no job. Nothing runs without a recipe whose job is not done (gate 5).
- miniz is built with deflate for the host now (nx2/build.py MINIZ_FLAGS); bcdec goes into the
  AppImage with its licence.
- tests/test_texture_decode.py: block-linear textures made in the test (BC1, BC3, BC4, BC5, BC7,
  ASTC 4x4, 8x8, 12x12, plain), blocks of 1 to 16 GOBs, cut edges, refusals.
  tests/test_texture_packs_host.py: the job's in fields and pictures, kept pictures, a changed
  file, an untaken format, no decoder.
- docs/modding/textures.md#upscale-recipes, docs/dev/reference/architecture.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The round-3 join of mods/hotcontent and mods/upin: host/texture_packs.c's upscale thread
resolves each served file through hos_romfs_resolve, which in dev mode enters and leaves
the live table's reader count. It starts after romfs_counted (hos_mods_init), so it never
leaves a count it did not enter; test_mods_hot checks both from the source.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A typed patch kind "flags" appends entries to GameData/GameDataList's lists (bool, int, float, uint, enum,
string) with SaveFileIndex -1, hashed as the game hashes flag names; a hash any list has, or 0, does not apply,
and MetaData's all-data sizes keep their rule. content.flag declares them under <word>.<id>; the fake game has
them from the start for game.flags. Saved flags stay out: docs/dev/reference/content.md says what the game's
save writer and reader show and what a run must show first.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
flagChanged's first read of a watched flag is a baseline (schema: "the first read of a flag after a listener names it
tells nothing"), made at the end of frame 1 after that frame's writes, for game flags and mods' alike: a set in frame 1
is never told. The fake game is right; the test set the switch too early.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
check_content_read once lost "badtable ! ArgumentError": the stub's hos_log_at wrote a line in three
printf calls, and content_read.c's reader thread (started by the first read, a moment before) logged
its "content.read: RSDB/ActorInfo ... read" between them. The mod's line then no longer started with
"LOG " and mod_lines skipped it. The product's log (host/hos_thread.c) formats a line and writes it
once; the stub now does the same.

check_log_lines_whole logs 3000 lines from each of two threads at once (modrt_test's new logstorm)
and wants each whole: with the old stub 404 of 6000 came out cut.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The game run 5 found the Mods tab's switches lost at quit under the Linux sandbox: the game folder is read only and
mods.json is given alone, but host/mods.c writes it as a new file beside it, which the folder refuses. The checks:

- tests/test_mods_list.py: a folder that takes no new file while mods.json itself may be written (made with the
  folder's mode): the change is written in place and read at the next start; with no file there it is kept and said.
- tests/test_sandbox_linux.py: mods.json (the user folder's, the game folder's, HOS_MODS_LIST's) and
  longshot_mod_items.txt made before their rules and written in place; the user folder's modstore/ written; a script
  mod switched off in HOS_MODS_LIST's list does not confine.
- tests/test_sandbox_windows.py: the plan writes the user folder's modstore\ and the items' journal in place.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
longshot --mod-tests <mod or folder of mods> (or HOS_MOD_TESTS) loads the mods alone in dev
mode, granted their manifests' permissions, with a mod list of the run's own, loads the newest
save, runs each mod's dist/test/*.js (test/*.js for plain JS) in a QuickJS runtime of the
runner's own beside the mod's, writes logs/mod-tests/results.json and junit.xml and quits with
0, 1 or 2. The runner (modapi/testing/runner.js, generated into host/modapi/testing_js.h and
copied for the fake game) gives each test the real game through the API: waits, reads, the
setup API (loadSave, teleport, setPosition, switchAge, press, hold, replay, record, waitFor),
FakeOnlyError for the fake game's own helpers, per-test timeouts in frames and fault isolation.
Nothing runs without the switch (gate 5).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The setup API on the fake game (lib/game-test.js, the twin of the game's runner), a test entry's
options ({ run, fake, game, timeout, skip }, game.skip), the tests built for the game
(test/ to dist/test/) and longshot-mod test --game <game folder> [--save NAME], which starts
the game's test mode (inside a Longshot checkout: dev.py game-tests) and prints its results as
a fake-game run. docs/modding/testing.md for mod authors.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
One TypeScript mod per area (items, actors, rules, ui, text, world, audio, content, flags, input,
camera, storage, events, gfx), each with its tests in the mods' own format. Every test runs in
the fake game; most also in the real game, reaching their state through the setup API. The
features not confirmed in the game (textShown, world.ray, the bomb fuse, player.setPosition,
actors.damaged, rules.actorLife, maxRupees, timeOfDay, saved flags) have game tests that will
confirm them, skipping with a reason where has() is false. tests/test_game_features.py runs the
suite in the fake game and checks the fake-only markers.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
TypeScript 7 is the native compiler: its package has no transpileModule or
createProgram any more. longshot-mod now runs the mod's tsc (node_modules
from the mod's folder up, else LONGSHOT_TSC, else the PATH) with the mod's
tsconfig.json, extended by a generated one in a temporary folder (noCheck,
ES modules, outDir/rootDir src). build --check compares a fresh build made
there. test and dev build first and the fake game runs dist/; TypeScript
tests are compiled by the same tsc and handed to the module hooks over a
MessagePort. Without tsc, Node's type stripping stays the quick path (.ts
only, exit 77 for TSX). A library's dist/mod.d.ts is read from tsc's
declaration emit. pack leaves mise.toml out.

The docs recommend mise for Node (mise use node@24; any Node 22 or later
works) and TypeScript per mod through npm. test_modapi_schema runs
build --check before test and puts a committed dist/ back if test's build
changed it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Builds each mod and its tests, starts the runtime once through the queue (shared) from a
repository save in the game's test mode, waits for it to quit, keeps results.json, junit.xml
and the log in runs/game-tests/ and prints each test as longshot-mod test does (--json for
longshot-mod test --game). docs/dev/game-tests.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The examples, first-mod and the mod inspector pin typescript 7.0.2; every
committed dist/ (and lib's mod.d.ts, and system_mods.h, which embeds the
inspector) is what tsc 7.0.2 builds. No new type errors: tsc --noEmit is
clean on all 34 mods. first-mod gets the mise.toml the tutorial makes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
With a script mod on the game runs confined: the game folder (or the user folder) takes no new file, and mods.json is
given alone, written in place. host/mods.c wrote it as mods.json.new moved over it, which the folder refused
("mods: cannot write <game>/mods.json: the change is kept and written at the next one"), so every switch was lost at
quit (game run 5). longshot_options.ini goes through host/hos_atomic_file.h, which writes in place there.

- host/mods.c write_file: when the new file beside it is refused (EACCES, EPERM) and the file is there, the file is
  written in place, as the settings are; logged once. A file that is not there is not made: the sandbox makes it.
- The sandboxes (host/sandbox_linux.c, host/sandbox_windows.c): mods.json is HOS_MODS_LIST's list when the launcher
  names one, as host/mods.c has it (it was the user folder's: the rule named a file the game does not write, and a
  script mod switched off in the launcher's list still confined the game); nothing is carried into that list.
- The other files script mods write at the top of a folder the game may not write: the items journal
  (longshot_mod_items.txt, beside the settings: host/modapi/items.c) is made at the start when missing and written in
  place, on Linux and Windows. The mods' stores, their data and settings (<user>/modstore/: host/modapi/storage.c), were
  outside every written folder: modstore/ joins the user folder's written folders on both.
- Checked and left as they are: the content stage's outputs are in modcache/ (written); the system mods' switches are in
  mods.json; exefs_patches.txt and native_mods.txt are written by the build, never by the game.
- docs/dev/reference/sandbox.md says so.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The first in-game run failed 20 tests that read lines a mod logged at its start: the runner gave
game.logs only from the test's first frame (and the log kept 50 lines), where the fake game's is
the whole log. In the test mode a tested mod's log keeps 4000 lines and game.logs reads it whole,
once a frame. The tested mods were also off when the start indexed the mods' files (a content
module never ran: features/content did not start); they are on from the list's read now. A
teleport, an age switch and loadSave end once Link has been in play 30 frames in a row, past the
arrival's own event (mode movie). Harness checks for the start's lines, the arrival and the
test mode's Skip title.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The repo pinned Node 22.12.0, older than the website's engines (>= 22.23.4), Node's stripTypeScriptTypes (22.13) that
longshot-mod falls back to without tsc, and the process.execve (22.15) TypeScript 7's tsc launcher uses. 26.13.1 is the
newest release and the current LTS line; mod-tools' own engines stay >= 22.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The 23 example mods still in plain JavaScript (check-gift, chest-swap, damage-tuner, debug-hitboxes, enemy-hud,
enemy-names, item-tracker, map-journal, memory-viewer, minimap, misbehaving, native-hello's script, pack-heal,
photo-mode, rupee-rain, save-tally, sepia-photo, seven-rupee and its content module, site-event, sound-cues,
spin-lift, turbo-remap, ui-cases) are TypeScript in heart-log's layout: src/, tests in test/*.test.ts with
satisfies Tests, the guide's tsconfig.json, the four package.json scripts, "entry": "dist/main.js" and dist/
committed. A UI is TSX (no h()); link-hud moves to the same layout (longshot-mod build, not tsc to main.js), and the
five TypeScript examples that ignored dist/ commit it too, so test_modapi_schema checks every dist/ with build --check.
misbehaving and ui-cases mark each deliberate wrong call with @ts-expect-error.

longshot-mod: .tsx is built and tested (JSX for longshot/ui/jsx-runtime by default; Node's type stripping has no JSX,
so that is exit 77); a TypeScript content module (src/content.ts -> dist/content.js) runs from its source in the fake
game and is link-checked by the build; the link check counts a namespace's filters (game.textShown was refused).
The fake game: game.romfs was replaced by the content stage's plain object, which left game.romfs.add() and
longshot/romfs without their files; it is one FakeRomfs now. Public game.grants, game.saveSlot and game.gfx.info()
replace the tests' reads of private fields, and index.d.ts types what the tests use (setActor, damage, gfx, content,
ui.worlds, rules, rewards...); its AbortSignal, not a name in a mod's ES2023 lib, is a StopSignal.

API types: ContentItem has getMessage (the host and the fake game took it; the type did not).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
dev.py game-tests and longshot-mod test --game start the game with HOS_HEADLESS=1; --window
replaces --headless for a person who wants to watch.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
host/ts wraps oxc_parser, oxc_transformer and oxc_codegen (default features off) behind lsts_transform/lsts_free/
lsts_version (host/ts/longshot_ts.h), built as a static library by scripts/longshot_ts.py with the Rust renhdrum.py pins,
offline from third_party/oxc/vendor (cargo vendor --versioned-dirs, Cargo.lock --locked). check_third_party checks a
part of vendored crates against its lock, and --upstream each crate against crates.io's .crate. third_party/oxc-runtime
holds oxc's usingCtx helper, the one runtime helper the game provides. CI builds the library for Windows (gnullvm) and
Linux; the Builder's package and the AppImage carry it, with the crates' licences and without the crates.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The tab was every mod's switch, page lines and cheats in one long list. Now the list holds the mods alone (Built in,
then Your mods), each line its name and a short status (On, Off, Faulted, waits for restart, needs a rebuild, unsafe),
with Restart now under them while a switch waits. A mod's line opens its page: Enabled first, with the switch's rules
as before (the code warning, the dependents asked twice, a script mod's switch at once), then Permissions, which opens
their own page (each in its words with its risk; an optional one switched; a system mod's read only), its settings and
own settings page, its cheats, then About (version, state, files, notes), Start again, Reload in dev mode and Move in
the list, which takes the mod back to the list picked up. Back (Esc, the pad's back, a right click) goes up a page to
the line it came from. No new saved key, no API change (still 36).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
actors.damaged puts Link beside the nearest actor with health in the Deku Tree's first room and
waits for its hit; actorLife reads the actors that room sets up; the bomb fuse gives a bomb bag
and bombs, and its skip says the setup API cannot put an item on a button.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The mods folder and mods.json are watched while the game runs with the system's
change notices (host/mod_watch.c: inotify, one watch a folder; ReadDirectoryChangesW
on Windows; a walk every 2 s where there are none), on one thread that sleeps while
nothing changes (host/modapi/watch.c). Applied once quiet, at the acquire phase:
script mods reload (keep() for every reload), served files rebuild, a package
replaced in place reloads, a mod added (the launcher's staged .adding- folder moved
in) is listed and started or served where it can be, a mod removed stops, mods.json
changed by the launcher switches mods as the tab does, and mod.json, code and
cheats changes say restart needed. The co-op room's hold (modrt_hot_hold) keeps
changes until it lets go. Dev mode keeps only its extras: the overlay, Shift+F8,
the inspector's Reload, log.debug. HOS_MODS_WATCH=0|poll for A/B.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A .ts, .tsx or .mts module (an entry, an import, a worker's, the content module) is compiled as the runtime loads it
(host/modapi/ts.c) and kept in modcache/js/<sha256 of the compiler's version, the module's path and its source>; a
changed file alone is compiled again. ./x.js resolves to x.ts or x.tsx when there is no x.js. Its source map is given to
sourcemap.c, so a frame reads src/main.ts:12:5; a module that does not compile is the mod's fault naming file:line:col.
Compile time counts in no budget. oxc's usingCtx helper (using declarations) is served as a module. nx2/build.py
compiles ts.c with LONGSHOT_TS and links host/ts/lib/<system>/liblongshot_ts.a when it is there; make_game.py fills the
cache for the installed mods through nx2/mod_ts.py (host/ts/lsts_tool.c on the same library).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The inspector's window (F8) is now a tabbed tool:
- Overview: a table of every mod sortable by any column (state, time now,
  over a second, the most, budget bar, faults / warnings, heap) with a totals
  row; choosing a row opens its Mod tab.
- Mod: state and Restart / Turn off or on / Reload; a Canvas graph of its last
  120 frames with the 2, 5 and 8 ms budget lines and a frame marked by a slider
  (Slowest, Newest); its numbers; its native time; the last fault for time's
  breakdown as bars (parsed from lastBreakdown); its log with a level filter.
- Log: every mod's lines by frame, filtered by mod and level.
- Frame: every mod's last frames stacked, six by name and the rest together.
The header has Pause and Size (Compact, Normal, Large); the tab, size, sort,
mod and filters are kept in storage.global. Closed it costs what it did:
nothing mounted or read. Open it reads inspect() 4x/s, logs() only for the
tab that shows them, and only the shown tab has content.

The fake game's modStats takes a stand-in's log lines (logs) for logs().
system_mods.h regenerated; docs/modding/system-mods.md's inspector section.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A rows patch's add with "from" and no "set" (what actor({ from }) with nothing changed makes)
has no value; apply_row read its member count through NULL (ModJson.n, +0x38) and the game
crashed in mod_patch_apply at the start, for any mod with such a patch. The copy is now made as
it is. tests/test_mod_content.py's rows check has the case.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The fake game compiles a mod's TypeScript with npm's oxc-transform 0.157.0 (mod-tools' dependency, with
@oxc-project/runtime for the usingCtx helper) and the game's options, so a test runs the JavaScript the game runs;
tests/test_modapi_ts.py checks the game's compiler and oxc-transform give the same bytes and maps for every example's
sources. longshot-mod build is gone (the game compiles: a second emit path would be a second compiler to keep the same);
test and dev need no build; check keeps tsc --noEmit (TypeScript 7) and takes the old build's link check; pack packs
src/; a library's declarations are longshot-mod types' mod.d.ts beside mod.json, checked by check and packed. Every
committed dist/ is removed, each mod.json names its src/ entry, and system mods ship and hash their src/.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- Window x, y (its frame's top-left, kept on the screen), resizable with a
  grip, onMove and onResize: the renderer keeps where the player dropped it
  and its size until the mod gives other props, and tells the mod as the
  drag ends. Canvas onPointer ({x, y, kind: move|down|up|leave}) in its own
  coordinates, only in the window with the input, moves capped at 30/s by
  the renderer and coalesced to one a frame by the host.
  MKWVK_UI_SNAPSHOT_VERSION 6: MkwVkUiSurface.placed/x/y/resizable appended,
  the move/resize/pointer events and point/pointer values appended;
  MKWVK_API_VERSION stays 36.
- inspect()'s lastSlow: the mod's last frame over the 2 ms warning (warned
  or faulted) as numbers from the budget's own ModRtCost (cpuMs, wallMs,
  apiMs, apiCalls, calls: the costliest 8 by name, gcMs, gcRuns, ownMs,
  pageFaults), copied at the frame's end only on a slow frame; kept by the
  loader's row once the runtime goes.
- Types (longshot-ui.d.ts, longshot-together.d.ts: SlowFrame), the fake
  game (move/resize/pointer, modStats lastSlow), tests (modui_test.c,
  test_modui_layout.py, test_modui.py source checks, test_modrt.py
  check_system), docs (ui.md, ui-channel.md, system-mods.md's API,
  architecture.md rule 4).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The gameflags join left LSAPI_FEATURE_CONTENT_FLAG out of services.c's list of the host's own
features, so every content module calling content.flag failed in the game with NotAvailableError
(the fake game and the harness have it). tests/test_mod_gameflags.py now checks every content.*
feature is in that list.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The sandbox confines the game at its start only while a script mod is on. A script
mod turned on (the Mods tab, mods.json) or added while an unconfined game runs no
longer starts live: its row says to restart (it runs confined), and the menu's
restart question counts it (host/modapi/loader.c live_start_ok, host/hos_main.c's
hook). A game started with no mods now watches the mods folder (or its parent, for
it to be made) and mods.json, and nothing else, until a first mod comes; then its
files get layers (the RomFS readers count from then on, over the start's empty
table: romfs_counted_late) and a script mod gets the restart line.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A system mod is trusted by the hash of its shipped files, src/ among them, so its TypeScript is compiled from those
files at each start (about 1 ms for mod-inspector) and modcache/js/ is neither read nor written for it: a record there,
which anything writing the game folder can change, never runs with its trust. A record is now LSTS2 <key> <code bytes>
<map bytes> <sha256 of code and map>: one naming another key or whose bytes do not fit is compiled again from the
source. A player's mod's record forged whole runs as that mod, with its own grants, as an edit of its source would.
nx2/mod_ts.py pre-fills the player's mods only. test_modrt checks a tampered record is recompiled, a forged one runs
only as its own mod, and a system mod's forged record is never run.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- system/mod-inspector is TypeScript now: src/main.ts with a tsconfig that
  checks against the checkout's own @longshot/api (no npm install), built by
  longshot-mod build into dist/main.js (committed: the game build installs
  it with no Node); mod.json's entry dist/main.js; the tests are
  test/inspector.test.ts. tsc reports no errors.
- The window is resizable and keeps its place and size (onMove, onResize)
  with its tab, sort and filters in storage.global; 0.2.0's size index is
  read once. Size offers Custom once resized.
- The Mod and Frame graphs read the frame under the mouse (onPointer) and a
  click marks it; the slider stays for the keyboard and the controller. The
  hover lives in a component of its own, so a move renders the graph alone.
- The last slow frame's bars come from inspect()'s lastSlow (each of the
  costliest API calls by name, the other calls, the collector, its own
  JavaScript), not from parsing lastBreakdown.
- nx2/system_mods.py leaves src/ and longshot-env.d.ts out of what ships;
  system_mods.h regenerated; docs/modding/system-mods.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Two engine sites, menu.buttonWait (f_832e8ad0) and menu.buttonWaitNoDecideAnim (f_832e8d70), the enter of the
sequence nodes that wait for a screen's button, tell host/oot_autoload.c the screen each wait is on. A is pressed
only on Title_00, SystemLoadList_00 and SystemSaveLoad_00, 300 ms after each wait begins, instead of blind presses
from 20 s every 2 s. The game still chooses the save and loads it itself. The timed presses stay as the fallback:
a build without the sites, or no wait told by 45 s. One entry for every user: the Insert-menu row, dev.py ab and
the game's test mode. Each wait, press and the arrival in play are logged with their frame.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
This was "feat(mod-tools): longshot-mod build, test and dev compile TSX" on
mods/docs. mods/tsex, joined before it, built the same thing (the .tsx build in
compile.js, build.js, fake-game.js and ts-hooks.js, and dev()'s signal as
StopSignal in index.d.ts), with TS content modules and two fixes besides; its
implementation is kept and this commit's copies of those hunks are dropped. What
is left is the usage text of bin/longshot-mod.js, which tsex did not change.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs/user/using-mods.md rewritten for players: what mods do, installing (the
launcher's Mods page, the mods folder, .lsmod, emulator mods), the Mods tab as
redesigned, permissions and their risks, unsafe and native mods, switching,
built-in mods, Safe start, co-op, troubleshooting and uninstalling.
docs/modding/getting-started.md is a TypeScript tutorial whose mod is the new
example modapi/examples/first-mod (TSX HUD, a setting, dist/ committed);
docs/modding/api-guide.md tours the modules and shared ideas. README becomes
a landing page; stale lines in scripting.md and packages.md fixed; content.md
opens with an example. The site publishes the two at /mods/create/ and
/mods/api/, with a test.

Joined after mods/tsex, mods/modstab and mods/inspui: examples.md, scripting.md
and ui.md keep tsex's text (every example TypeScript, dist/ committed) with
first-mod added; the examples are thirty-three; the inspector's section is its
tabbed window; the Discord status is not a built-in mod on this line (its section
and "Switched in" example are gone), and Safe start starts no built-in mod.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The engine's Discord text logic (host/discord_activity.c's templates and version parts,
host/oot_area_names.c, discord_rpc.c's activity_now) is now JavaScript in the system mod
modapi/system/discord, on game.state, mapLoaded and player.state. Its tests hold a table of
what that C said for 270 states, every map and 500-odd templates (test/golden.json, made
from the C before it was deleted) and check the mod says the same, byte for byte.

The host keeps the transport (host/discord_rpc.c: the IPC, the broker, the app id, a change
within 15 s and never more often, a 60 s keep-alive) and Discord's frame rules
(host/discord_activity.c), behind longshot/presence (set, clear, options) and the
system-only permission presence (host/modapi/presence.c).

The Insert menu's Discord status row (discord_status=) stays the one switch and drives the
mod: the system mod is "with-presence" (flag 8), found while HOS_DISCORD lets it run and
started by the transport only while a Discord client answers with the row on; no
connection is tried with the row off, and no runtime or phase exists while Discord is
not running. Safe start (HOS_NO_MODS=1) keeps the status: system/discord alone, under
the same rules. player.state() gains skulltulas and heartPieces; the manifest reader
knows the presence permission.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Layer A, typed component editing (content.actor):
- components: a copied actor's components changed by reference (Life,
  LifeRef, CppExecutorParam), a path going on through the files a component
  names ("LifeParameters/MaxLife"): each file on the way copied under the new
  actor's name, the change made there, the references renamed. Relative
  numbers ({ $add }, { $mul }) against the copied file's value or its
  parents'. add (a member of the pack, or another actor's component copied
  with the files it needs: the donor's pack hashed into the cache key),
  remove (refused when one of the actor's own trees uses it).
  host/mod_content.c, host/mod_content_pack.c, host/romfs_merge.c.
- content.read.component: a component as the actor has it, parents and
  named files filled in (host/modapi/content_read.c, host/mod_read.c).
- longshot-mod types --game: every actor pack of the player's RomFS read
  (zstd, SARC, BYML) into longshot-components.d.ts and .json beside mod.json
  (never committed: .gitignore), which augment ContentComponents; the fake
  game checks a mod's components against the .json (lib/components.js).

Layer B, scripted components (longshot/behaviour):
- component(name, { rate, state, onSpawn, onUpdate, onDamaged, onDied,
  onLifted, onRemoved }), attach(type, component), each actor with a state
  of its own, run inside the mod's runtime over longshot/actors and
  longshot/game, with their permissions. content.actor's scripts attach them
  to the mod's new actors (native.attached(): host/modapi/content.c
  modrt_content_scripts). modapi/behaviour/runtime.js is the source of both
  the game's (host/modapi/behaviour_js.h, evaluated at the first import by
  host/modapi/ui_module.c) and the fake game's copy. Nothing is listened to
  until a component is attached; caps of 256 actors, 64 types, 16
  components a type and 512 onUpdate calls a frame.

Layer C, behaviour trees as data (content.tree):
- host/mod_ainb.c reads AINB 0x408 with bounds, shows it as JSON, and
  changes it in place: node parameters, inputs' defaults, blackboard
  defaults, child links; bound parameters, fed inputs and new nodes refused.
  A tree is a copy of one of the pack's, renamed, in the new actor's pack.

Schema: content.tree, content.read.component, ContentComponents and the
tree types, the longshot/behaviour module; generated files, longshot.d.ts,
the reference and the permission table regenerated. MKWVK_API_VERSION stays
36. Gate 5: with no mod using them, nothing of this runs (the module is made
at its first import; packs without the new lines are built as before).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The Discord status's main.js and status.js become src/main.ts and src/status.ts with real types (Now, Activity,
Fields, VersionParts; the API's Age and PresenceOptions), laid out as examples/heart-log is: tsconfig.json, typescript
in devDependencies, mod.json's entry dist/main.js, and dist/ committed (built by longshot-mod build with typescript
6.0.3), because the game's build installs system mods without Node. The golden table still passes byte for byte.

nx2/system_mods.py leaves src/ and longshot-env.d.ts out of a system mod's shipped files, as longshot-mod pack does
for a player's mod: the game gets mod.json and dist/, and a local build's longshot-env.d.ts cannot change the hash.
host/modapi/system_mods.h regenerated for the new tree hash. docs/modding/system-mods.md: a system mod is TypeScript,
and its build and the table's hash after a change.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- custom-enemy: the Brave Octorok, a copy of the Octorok with three times
  its life ({ $mul: 3 } through LifeParameters), a drop of its own, a copy
  of its main behaviour tree (tree(), no tweaks committed: a tree's nodes are
  the player's game's), its name in two languages, and the scripted
  component custom-enemy.Flee: below half its life it runs from Link.
- magic-item: the Shock Stone, a named copy of the bomb placed in Kokiri
  Forest, whose component magic-item.Shockwave throws back the enemies near
  it when Link lifts it and counts its uses.

TypeScript (tsc 7.0.2 --noEmit: no errors), dist/ built by longshot-mod
build and committed; tests in the fake game.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A new module, longshot/ipc (spec 9.4.1, docs/modding/ipc.md): ipc.connect(endpoint) gives a Connection at once
(a mod's resource: close() and [Symbol.dispose] release it, StaleHandleError after) with send(bytes), connected(),
and the events data (Uint8Array) and closed ({ reason, error }). Only endpoints mod.json's "ipc" declares
(unix:<path> or pipe:<name>, {a-b} ranges, $XDG_RUNTIME_DIR, $TMPDIR, $HOME: host/ipc_endpoint.h); another is
PermissionError. Limits: 4 connections, 64 KiB a send, 256 KiB/s each way, 40 attempts in 10 s. It runs on the
network engine of longshot/net (host/broker_net.c, kind BNET_IPC, GRANT carrying the patterns, BNET_VERSION 2):
in the broker under the Linux and Windows sandboxes, a thread of the game's otherwise, without libcurl or WinHTTP's
WebSockets, and nothing starts until a mod connects. The engine checks the grant again and opens only endpoints a
system mod this build ships declares (modrt_system_ipc in the generated system_mods.h). The permission ipc is
system-only (it takes presence's bit); a player's mod naming it or "ipc" is refused by the manifest reader.

The engine has no Discord code left (tests/test_no_discord_engine.py): host/discord_rpc.c, discord_activity.c,
longshot/presence and its permission, the "with-presence" start (flag 8 reserved), modrt_presence_*, the broker's
Discord relay (BROKER_DISCORD_OPEN, 3, reserved), the Insert menu's Discord status row (key discord_status retired,
option 43 reserved) and HOS_DISCORD / HOS_DISCORD_APP_ID are gone. HOS_SYSTEM_MODS_OFF=<name>[,...] or * keeps
system mods from being looked at (the parity gates, the pipeline tour and dev.py ab set *).

system/discord (TypeScript) does all of it: Discord's frames, the handshake with the app id, SET_ACTIVITY with a
nonce and ipc.pid, Ping/Pong and Close, discord_rpc.c's endpoints in its order, a sweep every 15 s and nothing else
while disconnected, a change sent at once but never sooner than 15 s after the last, the 60 s keep-alive, and
discord_activity.c's text rules. It is "always" (Safe start loads the "always" system mods). Its switch and texts are
its settings; a setting's new "legacyOption" (system mods only) has the engine take the old longshot_options.ini line
once as its first value, so discord_status=0 carries over. time.gameStarted() gives the game's start.

Tests: test_modrt check_ipc (a fake Unix-socket program) and check_discord_idle (625 KB heap, 0 ns of script CPU
and ~0.4 us of frame step per idle frame), test_broker_net's local connections in-process and through a broker
child, and the mod against a fake Discord in the fake game (lib/fake-ipc.js).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- tests/test_mod_ainb.py: a made-up AINB file read, shown and written back
  byte for byte; each kind of change writes exactly its bytes; refusals say
  why; a content stage's tree applied to a made-up pack. --files DIR (this PC
  only) does the same over a folder of the player's own trees, keeping
  nothing.
- tests/test_mod_content.py and tests/mod_vectors/content.json: the actor
  kit's pack lines in the C builder and the fake game alike (components
  through named files, relative changes, add, add-from, remove and its
  refusal, trees), and content.read.component.
- tests/test_modrt.py: longshot/behaviour in the real runtime: dispatch from
  the actors' events and the frame's snapshot, onUpdate at its rate, state
  dropped at removal and at off(), nothing subscribed before an attach
  (gate 5), the caps, and its time in the mod's own budget.
- modapi/packages/mod-tools/test/components.test.mjs: types --game over a
  made-up RomFS, the .d.ts it writes (references in order) and the fake
  game's check (the example mods' tests drive longshot/behaviour there).
- tests/mods_build.py: mod_ainb.c among the pure sources.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Other mods call into system mods as they call any library:

- a system mod lists "exports"; a mod names it in "dependencies" ("system/discord",
  "? system/discord >= 0.3.0": a range is against the system mod's own version). The resolver
  takes the build's system mods as installed: nothing is fetched. Switched off, a required
  dependent does not load (dependency-disabled); an optional one runs and, unlike another
  mod's optional dependency, is imported (the trusted manifest gives the exports while it is
  off: modrt_system_manifest), its calls refused not-running. An export runs with the system
  mod's own permissions: the caller never holds ipc by calling Discord.
- system mods' dist/mod.d.ts are included in @longshot/api (modapi/generate.py), so a
  dependent's types need no portal and no path; longshot-mod add system/<name> writes the
  mod.json entry alone.
- system/discord 0.3.0 exports setActivity and clearActivity: a slot per calling mod keyed
  by caller(), the highest priority shown (latest on a tie), else its own status; callers set
  the two lines, the small picture and its text and startTimestamp, never the large picture,
  its text or the application; Discord's 128-byte rules, one send queue, at most 10 calls a mod
  in 10 s (LimitError); answers { shown, reason }; a stopped mod's slot dropped (running() at
  each look); the setting "Let mods set my Discord status"; the log says which mod sets it.
- one switch: the "enabled" setting is gone; discord_status= is the mod's
  "system"."legacySwitch", which host/mods.c takes once when mods.json has no entry and writes
  as its entry. mods.json is read for system mods' switches with no mod of the player's and in
  Safe start (never written there).
- the fake game runs the checkout's system mod beside a dependent (game.systemMod, off: true,
  game.switches, notLoaded), steps frames while the test's mod is off, and passes the API's own
  errors through calls as the host does.
- example modapi/examples/discord-status (a speedrun split in the status), tests: resolve
  vectors (system mods), test_mods_together check_system_lib, test_mods_list system_switch,
  test_modrt check_discord_idle, the discord mod's slots, priority, stop, limits, switches.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- docs/modding/behaviour.md (new): scripted components, their callbacks,
  rates, state, caps and costs, and behaviour trees (tree()'s changes, what
  is refused, what cannot be done).
- docs/modding/content.md: components (paths through named files, relative
  values, add, remove), longshot-mod types --game, content.read.component.
- actors.md, examples.md (thirty-five examples), README.md.
- docs/dev/reference/actor-components.md and behaviour-trees.md (new): what
  the game's packs and AINB files say, read on this PC (names, paths, counts
  only), what the kit makes of them, and what a game run must confirm;
  content.md and the reference index link them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
oxc took the build step away: the game compiles a mod's TypeScript as it loads it. The branches joined beside it still
built: the game's test mode read dist/test/, dev.py game-tests and longshot-mod test --game built each mod and its tests
first, the feature suite's mods named dist/main.js, and system/discord and the discord-status example shipped a
dist/ built with TypeScript 6.

- host/modapi/testing.c runs test/*.test.ts (.mts, .tsx, .js, .mjs) as they are; the game compiles them.
- longshot-mod test --game and dev.py game-tests build nothing (gameTestFiles lists what the game will run); dev.py
  game-tests needs no Node.
- tests/game-features/*: "entry": "src/main.ts", TypeScript 7.0.2, no dist/.
- system/discord and examples/discord-status: src/ loading, TypeScript 7.0.2, no dist/; system/discord's declarations
  are mod.d.ts beside mod.json (longshot-mod types), which modapi/generate.py puts in @longshot/api.
- A test run watches nothing (hot reload off under HOS_MOD_TESTS); a start with only system mods keeps its array from
  moving, so hot reload's first mods land after them.
- Generated files regenerated.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
custom-enemy and magic-item came with a dist/ built by TypeScript 6. As every other mod since oxc: "entry": "src/main.ts",
"content": "src/content.ts", no dist/ and no build script, TypeScript 7.0.2, the examples' tsconfig.json (no
erasableSyntaxOnly: oxc compiles enums and namespaces). longshot-components.d.ts and .json stay ignored.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The tour (docs/modding/api-guide.md) came before mods/ipc and mods/actorkit: longshot/presence is gone (ipc), and
longshot/behaviour is new. longshot-mod dev's help still said only a dev-mode game reloads a copied mod; since hot
reload is every player's, any game does.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
mods/final's Mods tab still sent system/discord's switch to the Insert menu's Gameplay > Discord status row, which
mods/ipc removed: its page showed "Switched in Gameplay > Discord status", Left and Right did nothing, and the hint
named a row that is gone. Since mods/ipc the host takes the tab's switch for it (one Discord switch, the mod's own), so
the special case goes, and with it the last Discord name in the engine (tests/test_no_discord_engine.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
mods/oxc's host/mod_manifest.c takes a .ts, .tsx or .mts content module (the game compiles it), but
tests/mod_vectors/manifest.json still had "content": "content.ts" as the refused case, so
tests/test_mod_manifest.py, which runs every vector through the game's parser, failed on it. The refused case is
content.jsx now, as the launcher's copy has it, and a new valid case takes src/content.ts.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- host/hos_main.c: the game's test mode quits as a normal exit (hos_crash_clean_end before ExitProcess), so a test run
  leaves no unclean crash record; tests/test_crash_record.py lists the two exits.
- tests/test_env_on.py: HOS_MOD_TESTS_TIMEOUT is a number (seconds), not an on/off switch.
- host/modapi/services.c: content.tree and content.read.component are the host's own, as every content.* feature is
  (tests/test_mod_gameflags.py, from mods/gametest, found has() false for the actor kit's two).
- tests/test_third_party_objects.py: its stand-in arguments name no longshot_ts (mods/oxc's builder_package option),
  so the package step does not open a mock as a file.
- tests/test_modapi_ts.py: with no oxc-transform it says SKIP and passes, as the other checks do (run_all counts 77 as
  a failure).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
longshot-mod test registered the oxc module hooks only when a test file was TypeScript, so system/discord's
test/discord.test.js, which imports ../src/status.ts, failed with Node's unknown-extension error once oxc-transform was
there to run it (tests/test_modapi_schema.py). The hooks now load for any mod the fake game compiles.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The network engine's hello called curl_global_init, which starts OpenSSL, on the engine's thread. With mods/ipc the
Discord status is a system mod in every game, so every game started the engine for its local socket and with it
OpenSSL, though a local endpoint needs none of it; a process ending while that start ran crashed in OPENSSL_cleanup
(free(): invalid size, seen as SIGSEGV in tests/test_modrt.py's check_discord_idle, about one run in ten). The hello
now says whether the engine is usable without starting it, and libcurl is initialised at the first connection to a
server.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The feature suite's first game run (2026-11-20): game.flags.set("PlayerStatus.Life", 8) was taken and flagChanged said
12 -> 8, but a frame later the flag was 12 again: the game copies Link's life component into the flag each frame.
player.set's life and a write of PlayerStatus.Life by name now also queue his life component's write (by his address,
under state.write, as player.setPosition does), made at his next update by the actors' site.
tests/test_modrt.py's check_player_life checks both writes are handed over, and nothing with no Link.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The feature suite's first game run gave a bomb bag 428 times: giving it changed the flags' container, which the item
service reads as a load, so the grant went back to queued and was given again, every frame. The service now tells
whether save.load was reached; a load only the flags tell of, within 600 frames of a grant's give, leaves it given.
tests/modapi_items_test.c and tests/game_items_test.c check both kinds.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
From the first game run (2026-11-20):
- events: the teleport's map loading names the map Link was in, which the run's earlier tests chose, not
  KokiriForest_Child; read from game.state() before the teleport, and only the lines after it.
- items: items.granted's line is the grant's own (after the call, reason script): the 20 bombs another test's bag
  brought are a pickUp of the game's. Deku nuts, which a full bomb bag cannot refuse.
- items: kokiri-start's wallet is 200, as the game read it, not 99.
- README: the two skips that need a route of their own (actors.damaged, the bomb fuse).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The actor spawner (host/game/spawn.c, spawn.h) is taken from #68 by mooki: co-op's
host/oot_coop_players.c makes the other players' bodies with the game's create request
f_80392a70, the take f_8038fbd0, the drop f_8038fde0, the cancel of a pending create
(f_80b4e020 over [[0x84eb0d90]+0x458] with the matcher 0x84c795e0, then f_80b4e6e0 or
f_80b4e2e0), the placement f_80c8fd60 and the delete f_800c6490, all from Link's update,
and host/oot_coop.c gates it (a save played, no load, no scene change, the play clock
ticking; held while it stands or an event plays). The same routines are called in the
same order with the same arguments, on the same build check, through game_call,
game_peek_at and game_guest_at; one shared module co-op can use too. A taken actor is
touched again only while its number, file name and live state are the take's (the
engine's own stale-handle test, as f_829108c0 checks an actor link).

longshot/actors gains spawn({ type, position, rotation? }), a Promise of the actor's
list key (null when the game makes none), and remove(key) of the mod's own, under a new
permission actors.spawn (high; a mod with it is not "local"). 16 at once and 8 calls a
second a mod, 64 slots in all; everything a mod spawned goes when it stops or reloads,
and with its map. In a co-op room it is NotAvailableError: spawn_route is where it
becomes a shared-world event when co-op lands (#68). Nothing runs while nothing is
spawned (one load in Link's update, one at the acquire phase).

The fake game models it (game.spawned, refuseSpawn, setCoopRoom); tests:
tests/test_game_spawn.py (the call sequence, gate and cancel path over a fake guest,
and the fake game's cases), test_modrt's check_spawn, the octorok-ambush example and
tests/game-features/spawn (its game test UNCONFIRMED in the game). API stays 36.

Joined onto mods/final-r5 (mods/spawn's ef4100ac, duplicated): octorok-ambush and
tests/game-features/spawn ship src/ with no dist/ (the game compiles them), the spawn area is in
the feature suite's list and README, and actors.spawn is a permission mod.json may name.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The game places no Brave Octorok of its own, so the example asks for one (actors.spawn with
":Brave") 3 s after Link enters a map, 8 m from him; the game takes it with its map. A fake-game
test checks where it appears.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
attach(child, parent, { bone, offset?, rotation?, mode? }), detach and attached (actors.write) are the
game's own model bind: the request its action OneShotModelBindSetModelBind (f_829108c0) builds,
handed to f_808b01e0 at the child's own update (the new inline site actors.bind at GameActor's
entry, after actors.write), the parent's link made with the engine's setter f_802dc440, cleared
with f_80980340 only while the component still names the parent (host/game/attach.c). Link is
never a child; an actor the game holds (liftable bound, component bound) is refused with false,
one another mod attached with ArgumentError; 16 a mod, 64 in all; NotAvailableError in a co-op
room; undone when either actor dies or goes, the game rebinds the child, or the mod stops. Bind
types 0-4 and 6 by the game's names; MultiBone and the physics joint are not offered.

answer(query, filter, fn) answers QueryDeathIsDead, QueryLiftableIsThrownState and
QueryLiftableIsPutState for the actors a filter names: each hook is called at the frame's serial
point for each matching listed actor (32 at most, 1 ms a call), and its true or false goes into the
query's table, read by an inline rule (query_answer, the generalised actor_lights) just before the
query's store (sites actors.answers.*, host/game/queries.c). No hook, no table: one load.

The fake game models both (game.attached, holdActor, answers()). API stays 36.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/test_game_attach.py (game_attach_test.c: host/game/attach.c and queries.c over made-up guest
memory, the game's routines recorded: the request field by field, the call order, BUSY, PARENT,
REPLACED, CANCELLED, TIMEOUT, attaching again, nothing read while nothing is asked; the query
tables), test_modrt's check_attach and check_answer, mod-tools/test/attach.test.mjs, and
tests/game-features/attach (its game tests UNCONFIRMED in the game).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
TypeScript 7, src/ only, with their fake-game tests.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs/modding/actors.md (Attaching, Answers, testing, the spawn example importing after),
api-guide, api-schema, examples (and their counts), docs/dev/reference/actors.md (the model bind,
the request, the joint not built and why, the queries read and the ones not answered, the sites,
game-run checks 20 and 21), hooks.md's rules, behaviour-trees.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
modrt_reserve (hot_begin, the end of host/mods.c's start) realloc'd found after modrt_resolve had pointed every row's
chosen into it. A move left each chosen in freed memory, and the first frame's start (start_pending, inlined in
on_frame) read the manifest from there: the feature suite's 18 mods and 2 system mods grew found past its first 16
places, and the game crashed at the first frame reading a permissions list at 0. The array is now copied by hand and
each chosen moved with it while the old places can still be counted from.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The feature suite's game run of 2026-11-20 17:02 failed three tests of spawn and attach with UnknownNameError: "no
flag named \"features.attach.ask\" in this game build". In the game a test's game.setFlag is game.flags.set, which
takes only a flag of the game's list, while the fake game makes any flag it is given, so the fake game ran the same
names without a word. tests/test_game_features.py now reads, as text, each setFlag of a test that runs in the game
(not fake-only), a name given by a const of the file read through it: it must be one of the game's own flags the API
knows (the write ranges') or one of the mod's content flags (its word and an id its content module declares). Fails
here: spawn's and attach's game tests set features.spawn.* and features.attach.*.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Their game tests set features.spawn.* and features.attach.* with game.setFlag, which in the game is game.flags.set:
the game's list has no such names, so all three failed with UnknownNameError in the game run of 2026-11-20 17:02
(the fake game makes any flag it is given). Each mod now declares its flags in a content module (src/content.ts,
content.flag, int: Ask, Type, Remove for spawn; Ask, Bone, Detach, Answer for attach), as features/flags declares
Seen, holds content.add, and its main.ts and tests name them by their game names (Ma405dbba.*, Mc2887b0a.*). The
type and bone read 0 as the first one, a content flag starting at 0. README and testing.md say a test in the game
sets only flags the game's list has.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The feature suite's game run of 2026-11-20 17:02 still failed flags' life test ("12 !== 8") after 4dfcad04: its log
has flagChanged 12 -> 8, then 8 -> 12, then 12 -> 8. The game copies Link's life component into PlayerStatus.Life
before his update, where the component's write (handed over for him) is made, so the frame after the write the flag
held his old life again, and the test read it then. tests/modrt_test.c's "lifecopy" makes the game's frame between
two acquire phases that (the component copied into the flag, then his update making the write handed over), and
test_modrt's check_player_life writes 8 and reads the flag each frame after. Fails here: the first read is 12.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The game copies his life component into PlayerStatus.Life before his update, where the component's write is made
(a write is never made from the main thread), so the frame after a write of his life the flag read his old life: in
the game run of 2026-11-20 17:02, flagChanged 12 -> 8, 8 -> 12, 12 -> 8 and flags' life test read 12. For 4 frames
after such a write, at the start of the acquire phase before any script runs (modrt_writes_frame, from on_frame), the
flag is set to his life component's value when that is the value written and the flag is not: the game's own copy,
made before anything reads. host/game/actors.c's game_actor_life_now reads the component (bounded reads). Each of
those frames is logged at info for the first 3 writes ("Link's life written 8, frame +1: PlayerStatus.Life 12, his
life component 8 ..."), so the next run says what the game did if it still does not hold. Nothing without a write.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Main took version 36 for the A/B's ab_value (#1846's RX_VK_MESH_CONV). The mods' MkwVkHost functions follow
ab_value in the struct and in host/rx_backend.c's vk_host, and every place that named them as version 36 says 37.
test_hos_ab's check reads ab_value right after the Mods tab's version 35 functions instead of at the struct's end.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
#1855 added a text patch that wraps a menu screen's update so the shared map's projection is scoped to it. The
stack had made patch_file a no-op when every other per-function patch became a hook site, and the rebase's
resolutions left the HUD's lines outside any function (an IndentationError). patch_file now applies only the
HUD wrapper, report() warns when it is not found once in the supported build, and the docstring says it is the
one edit inside a function left (no site form runs code around a function's body). The menu.update entry hook
is spliced in at the emit, before this pass, so it runs inside the scope, as main's menu tick hook did.

The wrapped body is static: a mod's ExeFS patch switch writes each version of f_802f1380 in a file of its own
(a64_switch_<n>.c), and an external gameplay_hud_update_game in each clashed at the link (test_exefs_switch,
whose menus' update is that function: its fixture gets A64Fn and a hos_gameplay_hud_screen that runs the
update). test_menu_hooks lets oot_patches.py name f_802f1380 only as the HUD wrapper's head.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
test(mods): the checks main's changes reshaped, on the rebased stack
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 12s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 31s
CI / Workflow lint (actionlint) (pull_request) Successful in 32s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 38s
PR description / Description follows the template (pull_request_target) Successful in 1m14s
CI / Website build and checks (pull_request) Has been cancelled
bdc9327209
- switches.def: LONGSHOT_SANDBOX_NOTE before main's LONGSHOT_SHADER_STORE (test_switch_table: sorted by name).
- menu_record takes main's colour_vision (#1832): test_mod_settings' and test_modui's cuts name it.
- test_pacing_policy (#1591) cuts hos_vi_native_acquire, which runs the mods' frame phase: its stubs get
  GAME_PHASE_ACQUIRE and game_phase_run.
- test_image_view_retry's fixture: texture_view asks pack_view for a texture pack's image (none here) and copies
  the swizzle with std::memcpy.
- test_screensaver's fixture: the window procedure gives a mod's window its clicks and takes the mods' UI rects
  (neither here).
- modapi_items_test: the format writes a key's '-' as %2D (key_escape: '-' alone is the empty key). Failed on the
  stack before the rebase too.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The lift's hot file cut into pieces (nx2/split_hot.py) with P before the menus' update: the wrapper's static
declaration rode with P into the other piece, as in #1937's build (code_hot_5: undeclared identifier
gameplay_hud_update_game).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
fix(mods): the HUD wrapper's update is declared in the wrapper and named per ExeFS version, so a hot piece reaches it
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 10s
CI / Workflow lint (actionlint) (pull_request) Successful in 21s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 23s
Third-party parts / As their notes say (pull_request) Successful in 25s
PR description / Description follows the template (pull_request_target) Successful in 1m2s
CI / Website build and checks (pull_request) Has been cancelled
7484bf5998
The lift's hot pieces (nx2/split_hot.py) cut at the functions' heads, and text between two functions goes with the
one above: the wrapper's static declaration of gameplay_hud_update_game landed in another piece than the wrapper,
and #1937's build failed (code_hot_5: undeclared identifier). As on main, the body is not static and the wrapper
declares it; each other version a mod's ExeFS switch writes names it gameplay_hud_update_game__s<n>, so the
versions still do not clash at the link.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Most of a map's actors have no life component, so the list gave them no type (3065 of the last game run's spawned and
removed lines named none) and no filter by type could find one. The check puts a file name at the actor's +0x260 (#68's
A_FILE, what a spawn checks its actor by) and wants it as the type; an actor with a life component keeps its life's
name, and a name that is not a word, or a torn pointer, gives none.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The type was only ever the life component's resource name (its LifeParam's: "Enemy_Octorok", "Player", "Pot"), so
every actor without one was listed with an empty type: removed and spawned lines with no name in the game's log, and
nothing a filter by type could find. Such an actor now has the name its actor file has ([actor + 0x260], the pointer a
spawn compares with the name it asked for, which the last run's Octorok passed): "Obj_Pot_A_01". Where a life
component's name is there it stays the type, so Link is still "Player" and nothing already listed by type changes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The last game run's attach and answer tests failed with nothing in the log to say why. Now:

- an attach that answers false logs why (the child or parent not listed, not in play, held by its lifter, no ModelBind
  component or another class at its components' +0x18, bound already, the parent not live, no slot): game_attach_why_not;
- a bind the game made is logged, and 10 frames later whether the parent's model resolved the bone (the component's
  +0x38, 0xffff while not: a name that is not one of its bones): game_attach_bone_index;
- the answers: each change of what the hooks answered (hooks, actors asked about, answers, true ones, published), and
  every 120 frames while a table is up what the query's site met (reached, its node's actor unreadable, an answered
  actor, the answer changed), counted at the site: game_queries_counts. "no tree asked this query" or "no tree asked
  it of an answered actor" ends the line when so.

At most 32 such lines a session. Checked over made-up memory (tests/game_attach_test.c) and in the runtime's harness
(its stand-ins of the new functions).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Both failures of the last game run in tests/game-features/attach:

- the pot test: no actor has the type "Obj_Pot" (an actor's type is its LifeParam's name, and a pot's is "Pot"), so
  none was found, and the spawn of "Obj_Pot" was refused (outcome 3: no actor file of that name; a pot's is
  Obj_Pot_A_01). The mod lists "Pot" and spawns Obj_Pot_A_01, logs the pot's key, and attaches the pot it attached
  again when asked again. Link's child model has the bones Weapon_R, Head, Spine_2 and Root, but which one the bind
  follows is not known without a run, so the game test tries each in turn (the pot at Link's bone, and still there
  after he moves 3 m), tells the mod the one that held (the flag Mc2887b0a.Found: "the pot followed Link's <bone>" in
  the log) and fails naming what each did;
- the Octorok test: the mod logged every actor removed, and the log's limit (100 lines a second) dropped hundreds, so
  the line the test waits for could be lost. It logs only Octoroks and pots now, logs the first actor its hook answers
  true for, and the test's failure says whether the hook answered at all.

Pot Hat looks for "Pot" too, and the spawn feature test's pot is Obj_Pot_A_01. The fake games' pots are "Pot".

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The pages for mod authors said things the code no longer does or never did. Checked each page against host/modapi,
host/mod_manifest.c, modapi/schema and mod-tools, and type-checked every whole-module example with longshot-mod check
(TypeScript 7.0.2, oxc 0.157.0).

- Wrong: the shared writes (state.write, items.grant, content.add, actors.spawn) need "multiplayer" all or host;
  spawning is 8 calls in 60 frames; lifecycle.stopping is order 18; a Hud needs ui.hud; worker paths are from the mod's
  folder; ipc's example used TextEncoder, which the game lacks; seven-rupee's id matched no word; manifests said api 0.3.
- Stale: "the game does not load script mods yet", "no asynchronous call yet", dev mode for reloads, sites port and
  game.pause listed as not built, the UI's permissions and settings page as not wired.
- Missing: spawn's and attach's checks and limits, answers' limits, input's, audio's and IPC's caps, system-only
  permissions in the manifest's table, the restart a script mod needs in a game started unconfined.
- content.md no longer says models are made with the community's tools: none writes BFRES 10.4 or Switch 2 BNTX.
- Schema doc strings fixed and modapi/generate.py run (reference.md, permissions.md, scripting.md's tables).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- Mods are found while the game runs (hot reload is on by default), not only at a start; HOS_MODS_WATCH=0 stops the
  watching and HOS_NO_MODS=1 is Safe start without the launcher.
- An emulator mod's .zip is unpacked first: the game reads a .zip only when it holds a mod.json.
- The prompt and the mod page as vk_menu.cpp draws them: Version (and its author), Granted / Not granted.
- The log hint keys on the "mods: N mods from" line.
- Updates and saves: modstore is kept, system_mods replaced, and a script mod's granted servers are listed among what
  Longshot connects to. The README names script mods and texture packs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- actors.md: spawn's rate is 8 calls in 60 frames; its call checks and when its Promise settles with null; the answers'
  limits. mods-input.md: a keybind reads the player's chosen value. game-events.md: polled after lifecycle.stopping too.
- mods.md: script mods load (not "not yet"); the Mods tab's Discord special case is gone (system/discord); every Mods
  tab host function by its MkwVkHost version.
- api-schema's frame order gains the steps loader.c runs; architecture.md's Windows sandbox rules numbered once, and
  modcache/ and system_mods/ described; sandbox.md: only the player's mods confine the game.
- hooks.md: the HUD's wrapper (#1855) is the one text edit left; sites port and several listeners are built.
- parity-gates.md: gate 5 runs with the built-in mods off (the Discord status is always on otherwise).
- The players' feature-test runs counted where a page said nothing had run in the game; two broken anchors fixed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The sandbox confines the game at its start only for a script mod of the player's; system/discord is not one, so the
game runs unconfined. The loader's live_start_ok still lets a player's script mod added then start live, unconfined.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
modrt_resolve set script_at_start for any row with a runtime, system rows too, so in a game where only system/discord's
script ran (unconfined: host/sandbox_*.c script_mod_on count the mods folder alone) live_start_ok let a player's script
mod added with hot reload start unconfined. It now counts the player's rows only, the sandbox's own rule; the docs say so.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
has(), a manifest's requires and the thunks' NotAvailableError all ask lsapi_host_feature; the check cuts it and the
four functions it asks out of their sources and compiles them with a game whose every service was found. ipc,
ipc.connect, memory.*, romfs.*, hooks.* and time.gameStarted answer false today: no host function names them, and the
game-free runtime's stand-in answers every feature, so its checks never saw it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
modrt_service_has named none of them and the game's functions do not either, so in the game has("ipc") was false and
time.gameStarted(), memory.*, romfs.* and hooks.* threw NotAvailableError (lsapi_enter). They are the host's own: true.
ipc answers bnet_ipc_available (new): a confined game's broker, else always, since the in-process engine's local
connections need no libcurl (net.* still needs it).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
lint printed "has undefined" for a mod with content.add or actors.spawn and multiplayer local; reviewOf let a native
mod through on the automatic checks; dev said the game reloads "in dev mode" (hot reload is every player's); and
mods-together's guard() export was "not a function" to longshot-mod types: the temporary tsconfig tsc runs from did not
find the mod's @longshot/api, so the const was typed any.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
lint.js SHARED_WRITES now has content.add and actors.spawn, as host/mod_manifest.c refuses them with multiplayer local;
publish.js counts the native permission and a native/ folder as unsafe (a person approves every release); dev.js says
the game reloads with hot reload on (HOS_MODS_WATCH=0 turns it off), not in dev mode; and tscEmit gives declarations
the mod's node_modules as typeRoots, so the mod's @longshot/api is found from the temporary tsconfig and guard()'s
const is declared as the function it is.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(dev): what a game with no mods runs: the Discord status's runtime, its engine thread and 15 s sweeps; gate 5's runs keep it off
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 20s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 33s
CI / Workflow lint (actionlint) (pull_request) Successful in 36s
Third-party parts / As their notes say (pull_request) Successful in 35s
PR description / Description follows the template (pull_request_target) Successful in 2m12s
CI / Website build and checks (pull_request) Has been cancelled
fa574bf340
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
An actor's type is its life parameters' name, which many share: every pot is "Pot" whatever its file, every character
"NpcCommon", many objects "Obj_Invincible". Its file is now its own field: the name of its actor file ("Obj_Pot_A_01"),
what actors.spawn takes, read where the type's fallback read it ([actor + 0x260], the pointer a spawn checks its actor
by). ActorInfo, ActorEvent, ActorLiftEvent and ActorDamage carry `file`; list() takes `{ file }` (or `:id` for the mod's
own), the actor events' filter takes it, and so does answer()'s (a hook may name a file alone). The damage and
actor-life rules' `where.target` stays a type: a rule is applied where the game writes a life, which has the life
component, not the actor.

Gate 5: nothing is read while no mod reads actors (the service is off). With one, the text is read once an actor and
again only when its pointer changes: a poll costs one 8-byte load an actor more, and the type's fallback is a copy of it
(it read the text every poll before). An actor whose file is another, or readable for the first time, is a new actor,
as for its type. The fake game, longshot.d.ts and the reference follow (modapi/schema); pot-hat and the attach and
spawn feature tests find their pots by file. API version unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
test(gates): gate 5 allows hot reload's one idle watch thread, lsmod-watch, and states its cost
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 11s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 22s
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Third-party parts / As their notes say (pull_request) Successful in 21s
PR description / Description follows the template (pull_request_target) Successful in 1m10s
CI / Website build and checks (pull_request) Has been cancelled
94a373769d
Every game starts hot reload's watch, with no mods too (host/mods.c hot_begin_empty), so that a mod the launcher adds
while the game runs is found; gate 5 failed every lsmod- thread, so it could not pass. It now allows exactly that one
thread, and only idle: the log says the watch waits on the system's notices (not "walked every 2 s", which the watch
does where it can have none), and at the run's end /proc says it sleeps (state S), has used at most 0.1 s of CPU and
been switched in at most 64 times. Two of it, its state unread, or any other lsmod- thread, still fails.

From the code: the thread blocks in poll() on its inotify descriptor and an eventfd with no timeout (host/mod_watch.c;
WaitForMultipleObjects with INFINITE on Windows) and wakes only for a notice of the mods folder or of a file written in
mods.json's folder. parity-gates.md and mods.md ("A game with no mods") say what it costs: the thread and its 256 KiB
stack, two watches and about 68 KB, 6 us of CPU in 10 s, one load a frame at the acquire phase.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A game run refused a spawned pot for every bone: its components' +0x18 held class 0x84c81350, and attach.h checks for
0x84c81388. The ModelBind's constructor f_83b3d8a0 stores 0x84c81350 (the image's one pointer to it, [0x84ca7960] +
0x10) and lays out the fields the attacher uses; 0x84c81388 is 0x38 into that table and no object holds it. The source
check now asks for 0x84c81350, and the fake guest refuses a subclass (0x84b6f1d8, its own set-up and calc).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
attach.h named 0x84c81388, an address 0x38 into the ModelBind's vtable that no object holds, so every actor was refused
("its components' +0x18 is not a ModelBind (class 0x84c81350)" for a spawned pot in the first game run). The class is
0x84c81350: its constructor f_83b3d8a0 stores it and sets the fields the attacher reads (+0x38 the bone pair 0xffff,
the link at +0x70 with id -1, the name's buffer at +0x88/+0x94 of capacity 0x100, +0x1a0..+0x1a8), and its slots
+0x68 (f_8097f570, the set-up) and +0xf8 (f_83b3dea0, the calc) are the ones the notes read at 0x84c81388 +0x30 and
+0xc0. A subclass such as 0x84b6f1d8 overrides both and stays refused. The reference says so, and item 20 that the
first run was refused for it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The first game run answered isDead true for an Octorok: the site was reached 9592 times and took the mod's answer in
place of the game's 1199 times, and the Octorok fought on (its tree asks QueryDeathIsDead and does not die of a true by
itself). The game test now waits for the host to tell the mod that a tree took an answer not the game's, and that the
hook answered true, instead of for the Octorok's removal; test_modrt checks that line in the hooking mod's own log, once
a query for a mod with two hooks, from the scripted site's counts. Both fail until the host tells the mod.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
fix(actors): say what an answer changes, and tell the hooking mod when the trees took it
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 19s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 39s
CI / Workflow lint (actionlint) (pull_request) Successful in 41s
Third-party parts / As their notes say (pull_request) Successful in 48s
PR description / Description follows the template (pull_request_target) Successful in 2m8s
CI / Website build and checks (pull_request) Has been cancelled
a426bf1071
An answer is the query's output in the trees that ask it, and nothing more: the first game run answered isDead true for
an Octorok, the site took the mod's answer in place of the game's 1199 times, and the Octorok fought on. The docs, the
schema and keese-ko promised a death ("told it is dead, an enemy plays its death", "an enemy told it is dead is
gone"); they now say that answering isDead does not kill an actor and that what a tree does with an answer is its
own. With the site's counts in the log, the host now also tells each mod with a hook on that query, in its own log
(what its tests and logs() read), how often the trees asked it of an answered actor and took an answer not the game's.
The reference records the run, gives the bomb's tree (QueryDeathIsDead beside OneShotDeathRequestDeath) as an
unconfirmed example of one that may act on it, and item 21 asks for the count, not a death.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The first game run that made a bind (2026-11-20) bound a pot to Link's Weapon_R: the game made it, and the pot died
at once and was removed. Nothing told the mod why: the poll's undo set the attachment ending before the frame's
"an attachment ended" line, so a child or parent that died or went ended in silence.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
fix(actors): tell the mod when a bound child dies, and bind the game test's children clear of Link's body
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 43s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 53s
PR description / Description follows the template (pull_request_target) Successful in 2m59s
Website / Website on Cloudflare (pull_request) Has been cancelled
CI / Website build and checks (pull_request) Failing after 20s
CI / Conventional Commit title (pull_request) Successful in 17s
CI / Workflow lint (actionlint) (pull_request) Successful in 45s
422ede7e79
The first bind made in the game (a pot on Link's Weapon_R, 2026-11-20) broke the pot at once: 1,000,000,000 damage
not Link's, a green rupee, the pot removed. The bind only places the child; its own collision and behaviour go on,
and the game's carry does more (the Liftable's pick-up writes the lifted actor's components +0x268 table, not
identified), so the core writes none of it. Instead:

- host/modapi/attach.c: an attachment the actors' poll ends is logged with why (the child died, with the advice; the
  child went; the parent died or went);
- tests/game-features/attach: two children, each tried on each bone: a Deku stick (Weapon_DekuStick, equipment the
  game binds in Link's hand, which does not break) at the bone, and a pot 0.6 m from it; spawned 1 m ahead; a child
  that dies is reported as such, and the bone each one followed is logged;
- pot-hat: half a metre from the head bone, and its README says what the run showed;
- docs/modding/actors.md, the schema's attach doc and the reference (Attaching, item 20): the run's facts and the limit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Author
Owner

Tested in game: Linux (CachyOS, kernel 7.3.3), NVIDIA GeForce RTX 3090, driver 620.70.06, on the branch before its rebase onto main: three runs of dev.py game-tests (tests/game-features, kokiri-start save). Joined branch: 22 passed, 4 failed, 40 skipped; the 4 fixed since. With spawn/attach/answers: a start crash (loader use-after-free with >16 mods, fixed), then 25 passed, 4 failed (new feature mods' flags, Link's life read a frame early), both fixed since, not yet seen in the game. Seen working: the hooked title skip (in play ~11 s after the first controller read), Discord as a system mod from src/, actors, audio, camera, content, timers, input replay, rules, storage, HUD and windows, text, teleport. This PR's rebased head has not run in the game yet: next.

Tested in game: Linux (CachyOS, kernel 7.3.3), NVIDIA GeForce RTX 3090, driver 620.70.06, on the branch before its rebase onto main: three runs of dev.py game-tests (tests/game-features, kokiri-start save). Joined branch: 22 passed, 4 failed, 40 skipped; the 4 fixed since. With spawn/attach/answers: a start crash (loader use-after-free with >16 mods, fixed), then 25 passed, 4 failed (new feature mods' flags, Link's life read a frame early), both fixed since, not yet seen in the game. Seen working: the hooked title skip (in play ~11 s after the first controller read), Discord as a system mod from src/, actors, audio, camera, content, timers, input replay, rules, storage, HUD and windows, text, teleport. This PR's rebased head has not run in the game yet: next.
Author
Owner

Since then, on the rebased head (this branch), Linux, RTX 3090, driver 620.70.06, dev.py game-tests headless (kokiri-start):

  • 7484bf59: 27 passed, 2 failed, 45 skipped. Spawn confirmed in the game (an Octorok asked, made in 284 ms, listed, removed; an unknown type settles with null); Link's life write holds; title skip in play 12.0 s after the first controller read.
  • a426bf10: 28 passed, 1 failed. Answers confirmed: the game's trees took the mod's isDead answer (312 times by the end); the Octorok's tree doesn't act on it (now documented). Attach: the game's bind is made (ModelBind class fixed), but a pot bound into Link's hand broke.
  • 422ede7e (this head): the attach test now binds a Deku stick and a pot kept 0.6 m clear, and the host says why an attachment ends. Not yet run in the game.
Since then, on the rebased head (this branch), Linux, RTX 3090, driver 620.70.06, `dev.py game-tests` headless (kokiri-start): - 7484bf59: 27 passed, 2 failed, 45 skipped. Spawn confirmed in the game (an Octorok asked, made in 284 ms, listed, removed; an unknown type settles with null); Link's life write holds; title skip in play 12.0 s after the first controller read. - a426bf10: 28 passed, 1 failed. Answers confirmed: the game's trees took the mod's isDead answer (312 times by the end); the Octorok's tree doesn't act on it (now documented). Attach: the game's bind is made (ModelBind class fixed), but a pot bound into Link's hand broke. - 422ede7e (this head): the attach test now binds a Deku stick and a pot kept 0.6 m clear, and the host says why an attachment ends. Not yet run in the game.
BeanBot left a comment

Recommendation: Request changes. The Modding API adds useful capabilities, but packaged scripts can start without the promised sandbox, CircleCI release packages omit the TypeScript compiler, and the new hook table contains instruction words taken from the game. Hot reload and save handling also have correctness issues that need fixing before merge.

Adds TypeScript and JavaScript mods, permissions and settings, built-in mods, hot reload, custom actors, graphics and audio APIs, and in-game tests. The shared API and loader give mod authors a consistent way to extend the game. The cost includes a compiler and runtime in player builds, additional startup and frame work, and new interactions with saves, input, Vulkan, and the launcher.

Does it help: Unproven at 422ede7e79. The description reports 22 passed, 4 failed, and 40 skipped on the earlier joined branch, then 25 passed and 4 failed after spawn and attach were added. It also reports reaching play about 11 seconds after the first controller read on one PC. There is no matching base run, repeatable frame-time comparison, or build, startup, memory, and VRAM comparison. The reported fixes after those runs still need evidence from the rebased head.
Other systems: Both release pipelines, the Vulkan renderer, input and title flow, save storage, existing file and ExeFS mods, and launcher-owned mod lists are affected. The earlier Linux NVIDIA run provides some feature evidence. Windows, AMD, Intel, Steam Deck, controller navigation, and rendering with and without each upscaler and frame generation still need coverage where affected.
Switches: HOS_MODS_DEV defaults off. HOS_MODS_LIST defaults to mods.json beside the settings file, with a game-folder fallback. HOS_MODS_WATCH defaults on with notification or polling fallback. HOS_MOD_TESTS and HOS_MOD_TESTS_SAVE default unset, HOS_MOD_TESTS_ONLY defaults to all candidates, and HOS_MOD_TESTS_TIMEOUT defaults to 3600 seconds. HOS_NO_MODS defaults off. HOS_QUERY_MEMORY_OLD defaults off, selecting the new module-aware query. HOS_SANDBOX defaults to automatic, but its discovery and failure handling need fixing before that default can be relied on. HOS_SYSTEM_MODS_OFF defaults unset, so built-in mods follow their own rules. LONGSHOT_BROKER_FD, LONGSHOT_BROKER_PIPE, and LONGSHOT_SANDBOX_NOTE default unset and are internal. RX_VK_FX, RX_VK_TEX_PACKS, and RX_VK_WORLD default on where the corresponding mod feature is used. RX_VK_FX_BUDGET_US defaults to 2000, and RX_VK_LOG_TEX_HASH defaults off. HOS_DISCORD and HOS_DISCORD_APP_ID are removed without GONE rows. The former defaults enabled and the latter defaults to the saved or built-in app ID on base. The new --mod-tests, game-tests, and --sandbox-revoke modes require an explicit invocation or their documented environment equivalent where applicable. --window is opt-in. LONGSHOT_TS_A and --longshot-ts are unset by default in packaging, which currently permits incomplete release artifacts. The test and diagnostic defaults are reasonable in intent, but the player-facing runtime and renderer defaults lack measurements.

Reviewed: 422ede7e79 against 51f5f9da56: Read the base AGENTS.md, CONTRIBUTING.md, and Forgejo template in full, plus the applicable sections of docs/dev/standards.md. docs/review-checklist.md is absent. Read host/game/camera.c, host/game/modsites.c, host/game/phases.c, host/game/flags.c, and host/mod_switch.c in full. Inspected selected changes and callers in startup, sandbox discovery, loader and workers, attachment, save hooks, mod-list watching, the Mods tab, texture logging and crash reports, CI packaging, and the game and runtime test harnesses. Skimmed commit subjects and trailers, generated bindings and shader checks, vendored provenance, modding documentation, and the reported pre-rebase runs. The supplied discussion was empty. Coverage is incomplete across the 4,627 changed files, including the vendored source, the rest of the host and renderer, the mod tools and examples, translations, and much of the test suite.; nothing run (a code review).
Checked and fine:

  • MKWVK_API_VERSION moves from 36 to 37 with the host interface additions.
  • The effects and world shader checks include comparisons against headers regenerated from shader sources when glslang is available.
  • The loader's reserve step relocates existing chosen pointers before freeing the old array.
  • The spawn path retains the explicit co-op restriction described in the PR.

Blocking (to change before merge)

  1. game/e0f3ccfaf50065ae4ea01eb5aeb13b1a45da3348/sites.toml:20: The hook table commits exact instruction words from the supported game alongside masked words. The base contribution rules prohibit anything made from the dump, including these signatures, even though this PR's new hook docs permit them. Derive and verify the signatures locally from the player's copy, and use authored fixtures for the repository tests.
  2. host/modapi/loader.c:1055: Startup can create a player script runtime without confirmation that the sandbox succeeded. Both sandbox preflights scan folder manifests, while the loader also accepts .lsmod packages and uses manifest IDs. A player with only an enabled script package can reach this path without automatic confinement. Use the same discovery and ID resolution for both paths and require successful confinement before any player script or scripted content starts, except after an explicit sandbox opt-out.
  3. host/sandbox_linux.c:736: Linux reports confinement to the loader when Landlock succeeds even if seccomp fails. A run with files confined and network open can therefore pass the live-start check, and script_at_start also lets it pass independently. Require both protections for script execution and keep the game playable with scripts held when either setup step fails.
  4. scripts/linux/appimage.sh:88: Only Forgejo builds and supplies the compiler archive. CircleCI's Linux AppImage and Windows Builder release jobs still invoke packaging without it. Those artifacts can ship successfully but reject TypeScript mods, including built-in Discord. Supply the archives and notices in both CI systems and make release packaging fail if the compiler is missing.
  5. host/game/camera.c:33: The sequence check still races on ordinary C payloads. A camera worker can update last while game_camera_last copies it, get_set can race with camera override writes, and re-enabling watching resets matrix_ns outside the writer protocol. Use synchronized snapshots or an atomic payload with serialized writers, including the reset.
  6. host/oot_autoload.c:256: The title wait counter changes only after the publisher writes both fields. If the next wait starts during this copy, the second count read can match while the screen and time already belong to different waits. That can schedule A for the wrong screen or consume the same wait twice. Publish a coherent event with serialized writers and test a wait arriving during the read.
  7. host/game/attach.c:256: An in-flight bind table identifies a request by slot and state alone. If a child update holds the old table while the main thread cancels, releases, and reuses its slot, the old update can claim the new request and run it in the wrong child's update. Include a generation in the atomic claim or defer reuse until the old readers have left.
  8. host/game/flags.c:28: The shared guest accessor checks the reserved window only. An actor disappearing during a poll can leave a pointer into a decommitted Windows page, and the follow-up memcpy can fault. Flag table reads also add offsets before passing them to the accessor. Validate checked address arithmetic and use a read or write primitive that checks backing memory and keeps it valid through the access.
  9. host/modapi/memory.c:82: The raw memory API treats a logically allocated heap range as readable backing. On Windows the heap is committed on touch, so a read can commit pages as a side effect or fault if commitment fails. The region lock is also released before reads and queued writes touch the range. Check backing and perform the access under a lifetime guarantee, returning a MemoryError when the bytes cannot be accessed.
  10. host/mods.c:3028: The renderer reads live mod rows and their loader strings while the game thread can change them. For example, the Mods page can format a row's why string while a reload rewrites it. The state acquire load only orders the preceding write and does not protect the next one. Publish an owned menu snapshot and resolve edits against stable mod IDs.
  11. host/mods.c:3335: A deleted mod remains a known path for the rest of the session. If the launcher reinstalls the same folder after the watcher has observed its removal, discovery skips it and the script stays stopped until restart. Reconcile a returned path with its tombstoned row and revalidate its manifest, grants, and package before starting it.
  12. host/mod_watch.c:431: On Linux, mods/ can be absent while mods.json lives in its parent folder. Inotify returns the same watch descriptor for both registrations. The parent branch then consumes list events, and creating mods/ removes the watch that the list still claims to own. Share the watch with both event roles or use independent descriptors, and test list updates before and after creating mods/.
  13. host/modapi/watch.c:346: If thread creation fails, started remains set and the allocated watcher and its handles stay open. If phase registration fails, the thread runs but changes never apply and startup returns success. Roll back each partial initialization and report watcher availability only after both steps succeed.
  14. host/nn_fs.c:558: A failed or short WriteFile still marks the handle as written, and SetFileSize marks it before either filesystem call succeeds. Closing a save after a disk-full write can therefore commit mod storage for progress that was never saved. Track failures through the save sequence and publish the commit event only after the save completes successfully.
  15. gpu/vk/vk_texture.cpp:1969: Texture diagnostics write game-derived hashes into the normal log, which feeds both manual and automatic crash reports. A crash during a texture comparison can put those lines in a report the player is asked to share. Write them to a separate local diagnostic file and point the comparison tool there.
  16. host/modapi/testing.c:116: Linux realpath writes into a 1024-byte static buffer even though a valid resolved path can be longer. Windows also treats a GetFullPathNameA required-size return as success. Resolve dynamically on both platforms and reject oversized paths before setting any test switches.
  17. scripts/devtools/gametests.py:155: The runner copies reports from the shared runtime and returns the exit value from the JSON alone. If a launch fails before clearing old reports, a previous passing JSON can make the new failed run pass. Runs sharing the runtime can also overwrite each other's reports. Use a per-run output directory and require the expected process exit and fresh, complete reports.
  18. scripts/devtools/gametests.py:139: The launcher inherits the caller's environment even with an empty env file. For example, HOS_MOD_TESTS_ONLY can silently omit most of a suite and HOS_HEADLESS can defeat --window. Strip inherited game switches and apply a declared set for the run. Also isolate the runtime fixture's environment, which currently inherits switches in drive().
  19. host/modapi/testing.c:271: A passing run exits zero even if it cannot write JSON or JUnit. Allocation failure while collecting results can also silently drop a mod before the final totals are calculated. Treat lost results and failed writes as incomplete runs and add a failure-path test.
  20. tests/test_modrt.py:3752: The main runtime suite exits successfully on Windows without executing its checks, defaults to gcc even when CC is set, and only exercises successful TypeScript loading if a Linux archive happens to exist locally. A compiler regression can pass clean CI. Honor the selected compiler and run the runtime and compiler regressions against target-matched archives on both supported platforms.
  21. scripts/longshot_ts.py:294: Splitting the flags string on spaces also splits path arguments. A checkout or cache under a path such as C:\Users\Jane Doe fails before Cargo can compile the library. Construct one argument per remap and join those complete arguments with Cargo's separator.
  22. scripts/longshot_ts.py:273: Builds using the same cache delete a shared work directory before starting and again on exit. Concurrent Linux and Windows builds can remove each other's source or output mid-build. Use per-invocation work directories, synchronize toolchain installation, and publish the archive atomically.
  23. gpu/vk/switches.def:36: Both retired Discord switches were deleted without the required GONE entries. In particular, a user relying on HOS_DISCORD=0 can start publishing presence after upgrading, and HOS_DISCORD_APP_ID no longer selects their application. Preserve or migrate those preferences, and document any retired switch with its replacement in the table.
  24. host/modapi/loader.c:1071: The first frame that starts Discord verifies its files and synchronously compiles its TypeScript on the game thread, even with no installed mods or running Discord client. Trusted modules deliberately bypass the disk cache, so this repeats on warm starts. Prepare trusted code from verified bytes ahead of the frame or ship trusted compiled modules bound to the build.

Waiting on the author (a run, a measurement or a decision; no edit does it)

  • docs/dev/reference/parity-gates.md:210: Gate 5 disables Discord, while the shipped default starts its script runtime and network worker with no player mods. Measure the shipped default as well as the gate configuration against base on matching builds, hardware, settings, and scenes. Report interleaved startup, build time and size, RAM and VRAM, average FPS, 1% lows, and frame-time tails, including the watcher and Discord retry costs.
  • Provide results from the rebased head and identify any failures shared with base. The older run did not verify the subsequent fixes, Windows confinement, or the Mods tab, and the review has no same-scene base comparison for title skip. Include the listed hands-on checks, affected Tier 1 coverage, and same-spot menu and inspector screenshots.
  • The AI attribution checklist is marked complete even though commits c1bfc0d6b, 57e55aa3b, 00f7c1e9c, 1c61d3190, and 31c612120 have neither trailer. Confirm their attribution and add the required trailers wherever assistance was used, including the squash message.

Testing: Static review only. No build, test, or project script was run. The PR description contains the only runtime evidence and describes runs before the rebase. The reported strict suite result does not name the failures shared with main.
Overlaps and merge order: #1937 is the predecessor. Confirm with snaildev99 whether #961, #984, #1036, and #1089 are superseded before merging either stack. Coordinate #1577 and #659 because they share the title-to-save path, and keep shared-world spawning gated until #68 lands. The launcher companion PR needs a compatibility run with this game's mod-list and Safe start behavior. Merge order for the title and launcher work is unverified.


Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.

**Recommendation: Request changes.** The Modding API adds useful capabilities, but packaged scripts can start without the promised sandbox, CircleCI release packages omit the TypeScript compiler, and the new hook table contains instruction words taken from the game. Hot reload and save handling also have correctness issues that need fixing before merge. Adds TypeScript and JavaScript mods, permissions and settings, built-in mods, hot reload, custom actors, graphics and audio APIs, and in-game tests. The shared API and loader give mod authors a consistent way to extend the game. The cost includes a compiler and runtime in player builds, additional startup and frame work, and new interactions with saves, input, Vulkan, and the launcher. **Does it help:** Unproven at 422ede7e794a. The description reports 22 passed, 4 failed, and 40 skipped on the earlier joined branch, then 25 passed and 4 failed after spawn and attach were added. It also reports reaching play about 11 seconds after the first controller read on one PC. There is no matching base run, repeatable frame-time comparison, or build, startup, memory, and VRAM comparison. The reported fixes after those runs still need evidence from the rebased head. **Other systems:** Both release pipelines, the Vulkan renderer, input and title flow, save storage, existing file and ExeFS mods, and launcher-owned mod lists are affected. The earlier Linux NVIDIA run provides some feature evidence. Windows, AMD, Intel, Steam Deck, controller navigation, and rendering with and without each upscaler and frame generation still need coverage where affected. **Switches:** HOS_MODS_DEV defaults off. HOS_MODS_LIST defaults to mods.json beside the settings file, with a game-folder fallback. HOS_MODS_WATCH defaults on with notification or polling fallback. HOS_MOD_TESTS and HOS_MOD_TESTS_SAVE default unset, HOS_MOD_TESTS_ONLY defaults to all candidates, and HOS_MOD_TESTS_TIMEOUT defaults to 3600 seconds. HOS_NO_MODS defaults off. HOS_QUERY_MEMORY_OLD defaults off, selecting the new module-aware query. HOS_SANDBOX defaults to automatic, but its discovery and failure handling need fixing before that default can be relied on. HOS_SYSTEM_MODS_OFF defaults unset, so built-in mods follow their own rules. LONGSHOT_BROKER_FD, LONGSHOT_BROKER_PIPE, and LONGSHOT_SANDBOX_NOTE default unset and are internal. RX_VK_FX, RX_VK_TEX_PACKS, and RX_VK_WORLD default on where the corresponding mod feature is used. RX_VK_FX_BUDGET_US defaults to 2000, and RX_VK_LOG_TEX_HASH defaults off. HOS_DISCORD and HOS_DISCORD_APP_ID are removed without GONE rows. The former defaults enabled and the latter defaults to the saved or built-in app ID on base. The new --mod-tests, game-tests, and --sandbox-revoke modes require an explicit invocation or their documented environment equivalent where applicable. --window is opt-in. LONGSHOT_TS_A and --longshot-ts are unset by default in packaging, which currently permits incomplete release artifacts. The test and diagnostic defaults are reasonable in intent, but the player-facing runtime and renderer defaults lack measurements. **Reviewed:** 422ede7e794a against 51f5f9da5641: Read the base AGENTS.md, CONTRIBUTING.md, and Forgejo template in full, plus the applicable sections of docs/dev/standards.md. docs/review-checklist.md is absent. Read host/game/camera.c, host/game/modsites.c, host/game/phases.c, host/game/flags.c, and host/mod_switch.c in full. Inspected selected changes and callers in startup, sandbox discovery, loader and workers, attachment, save hooks, mod-list watching, the Mods tab, texture logging and crash reports, CI packaging, and the game and runtime test harnesses. Skimmed commit subjects and trailers, generated bindings and shader checks, vendored provenance, modding documentation, and the reported pre-rebase runs. The supplied discussion was empty. Coverage is incomplete across the 4,627 changed files, including the vendored source, the rest of the host and renderer, the mod tools and examples, translations, and much of the test suite.; nothing run (a code review). **Checked and fine:** - MKWVK_API_VERSION moves from 36 to 37 with the host interface additions. - The effects and world shader checks include comparisons against headers regenerated from shader sources when glslang is available. - The loader's reserve step relocates existing chosen pointers before freeing the old array. - The spawn path retains the explicit co-op restriction described in the PR. **Blocking** (to change before merge) 1. game/e0f3ccfaf50065ae4ea01eb5aeb13b1a45da3348/sites.toml:20: The hook table commits exact instruction words from the supported game alongside masked words. The base contribution rules prohibit anything made from the dump, including these signatures, even though this PR's new hook docs permit them. Derive and verify the signatures locally from the player's copy, and use authored fixtures for the repository tests. 2. host/modapi/loader.c:1055: Startup can create a player script runtime without confirmation that the sandbox succeeded. Both sandbox preflights scan folder manifests, while the loader also accepts .lsmod packages and uses manifest IDs. A player with only an enabled script package can reach this path without automatic confinement. Use the same discovery and ID resolution for both paths and require successful confinement before any player script or scripted content starts, except after an explicit sandbox opt-out. 3. host/sandbox_linux.c:736: Linux reports confinement to the loader when Landlock succeeds even if seccomp fails. A run with files confined and network open can therefore pass the live-start check, and script_at_start also lets it pass independently. Require both protections for script execution and keep the game playable with scripts held when either setup step fails. 4. scripts/linux/appimage.sh:88: Only Forgejo builds and supplies the compiler archive. CircleCI's Linux AppImage and Windows Builder release jobs still invoke packaging without it. Those artifacts can ship successfully but reject TypeScript mods, including built-in Discord. Supply the archives and notices in both CI systems and make release packaging fail if the compiler is missing. 5. host/game/camera.c:33: The sequence check still races on ordinary C payloads. A camera worker can update last while game_camera_last copies it, get_set can race with camera override writes, and re-enabling watching resets matrix_ns outside the writer protocol. Use synchronized snapshots or an atomic payload with serialized writers, including the reset. 6. host/oot_autoload.c:256: The title wait counter changes only after the publisher writes both fields. If the next wait starts during this copy, the second count read can match while the screen and time already belong to different waits. That can schedule A for the wrong screen or consume the same wait twice. Publish a coherent event with serialized writers and test a wait arriving during the read. 7. host/game/attach.c:256: An in-flight bind table identifies a request by slot and state alone. If a child update holds the old table while the main thread cancels, releases, and reuses its slot, the old update can claim the new request and run it in the wrong child's update. Include a generation in the atomic claim or defer reuse until the old readers have left. 8. host/game/flags.c:28: The shared guest accessor checks the reserved window only. An actor disappearing during a poll can leave a pointer into a decommitted Windows page, and the follow-up memcpy can fault. Flag table reads also add offsets before passing them to the accessor. Validate checked address arithmetic and use a read or write primitive that checks backing memory and keeps it valid through the access. 9. host/modapi/memory.c:82: The raw memory API treats a logically allocated heap range as readable backing. On Windows the heap is committed on touch, so a read can commit pages as a side effect or fault if commitment fails. The region lock is also released before reads and queued writes touch the range. Check backing and perform the access under a lifetime guarantee, returning a MemoryError when the bytes cannot be accessed. 10. host/mods.c:3028: The renderer reads live mod rows and their loader strings while the game thread can change them. For example, the Mods page can format a row's why string while a reload rewrites it. The state acquire load only orders the preceding write and does not protect the next one. Publish an owned menu snapshot and resolve edits against stable mod IDs. 11. host/mods.c:3335: A deleted mod remains a known path for the rest of the session. If the launcher reinstalls the same folder after the watcher has observed its removal, discovery skips it and the script stays stopped until restart. Reconcile a returned path with its tombstoned row and revalidate its manifest, grants, and package before starting it. 12. host/mod_watch.c:431: On Linux, mods/ can be absent while mods.json lives in its parent folder. Inotify returns the same watch descriptor for both registrations. The parent branch then consumes list events, and creating mods/ removes the watch that the list still claims to own. Share the watch with both event roles or use independent descriptors, and test list updates before and after creating mods/. 13. host/modapi/watch.c:346: If thread creation fails, started remains set and the allocated watcher and its handles stay open. If phase registration fails, the thread runs but changes never apply and startup returns success. Roll back each partial initialization and report watcher availability only after both steps succeed. 14. host/nn_fs.c:558: A failed or short WriteFile still marks the handle as written, and SetFileSize marks it before either filesystem call succeeds. Closing a save after a disk-full write can therefore commit mod storage for progress that was never saved. Track failures through the save sequence and publish the commit event only after the save completes successfully. 15. gpu/vk/vk_texture.cpp:1969: Texture diagnostics write game-derived hashes into the normal log, which feeds both manual and automatic crash reports. A crash during a texture comparison can put those lines in a report the player is asked to share. Write them to a separate local diagnostic file and point the comparison tool there. 16. host/modapi/testing.c:116: Linux realpath writes into a 1024-byte static buffer even though a valid resolved path can be longer. Windows also treats a GetFullPathNameA required-size return as success. Resolve dynamically on both platforms and reject oversized paths before setting any test switches. 17. scripts/devtools/gametests.py:155: The runner copies reports from the shared runtime and returns the exit value from the JSON alone. If a launch fails before clearing old reports, a previous passing JSON can make the new failed run pass. Runs sharing the runtime can also overwrite each other's reports. Use a per-run output directory and require the expected process exit and fresh, complete reports. 18. scripts/devtools/gametests.py:139: The launcher inherits the caller's environment even with an empty env file. For example, HOS_MOD_TESTS_ONLY can silently omit most of a suite and HOS_HEADLESS can defeat --window. Strip inherited game switches and apply a declared set for the run. Also isolate the runtime fixture's environment, which currently inherits switches in drive(). 19. host/modapi/testing.c:271: A passing run exits zero even if it cannot write JSON or JUnit. Allocation failure while collecting results can also silently drop a mod before the final totals are calculated. Treat lost results and failed writes as incomplete runs and add a failure-path test. 20. tests/test_modrt.py:3752: The main runtime suite exits successfully on Windows without executing its checks, defaults to gcc even when CC is set, and only exercises successful TypeScript loading if a Linux archive happens to exist locally. A compiler regression can pass clean CI. Honor the selected compiler and run the runtime and compiler regressions against target-matched archives on both supported platforms. 21. scripts/longshot_ts.py:294: Splitting the flags string on spaces also splits path arguments. A checkout or cache under a path such as C:\Users\Jane Doe fails before Cargo can compile the library. Construct one argument per remap and join those complete arguments with Cargo's separator. 22. scripts/longshot_ts.py:273: Builds using the same cache delete a shared work directory before starting and again on exit. Concurrent Linux and Windows builds can remove each other's source or output mid-build. Use per-invocation work directories, synchronize toolchain installation, and publish the archive atomically. 23. gpu/vk/switches.def:36: Both retired Discord switches were deleted without the required GONE entries. In particular, a user relying on HOS_DISCORD=0 can start publishing presence after upgrading, and HOS_DISCORD_APP_ID no longer selects their application. Preserve or migrate those preferences, and document any retired switch with its replacement in the table. 24. host/modapi/loader.c:1071: The first frame that starts Discord verifies its files and synchronously compiles its TypeScript on the game thread, even with no installed mods or running Discord client. Trusted modules deliberately bypass the disk cache, so this repeats on warm starts. Prepare trusted code from verified bytes ahead of the frame or ship trusted compiled modules bound to the build. **Waiting on the author** (a run, a measurement or a decision; no edit does it) - docs/dev/reference/parity-gates.md:210: Gate 5 disables Discord, while the shipped default starts its script runtime and network worker with no player mods. Measure the shipped default as well as the gate configuration against base on matching builds, hardware, settings, and scenes. Report interleaved startup, build time and size, RAM and VRAM, average FPS, 1% lows, and frame-time tails, including the watcher and Discord retry costs. - Provide results from the rebased head and identify any failures shared with base. The older run did not verify the subsequent fixes, Windows confinement, or the Mods tab, and the review has no same-scene base comparison for title skip. Include the listed hands-on checks, affected Tier 1 coverage, and same-spot menu and inspector screenshots. - The AI attribution checklist is marked complete even though commits c1bfc0d6b, 57e55aa3b, 00f7c1e9c, 1c61d3190, and 31c612120 have neither trailer. Confirm their attribution and add the required trailers wherever assistance was used, including the squash message. **Testing:** Static review only. No build, test, or project script was run. The PR description contains the only runtime evidence and describes runs before the rebase. The reported strict suite result does not name the failures shared with main. **Overlaps and merge order:** #1937 is the predecessor. Confirm with snaildev99 whether #961, #984, #1036, and #1089 are superseded before merging either stack. Coordinate #1577 and #659 because they share the title-to-save path, and keep shared-world spawning gated until #68 lands. The launcher companion PR needs a compatibility run with this game's mod-list and Safe start behavior. Merge order for the title and launcher work is unverified. --- <sub>Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.</sub>
@ -0,0 +207,4 @@
## Gate 5: nothing started
With no mods, and the built-in ones kept off as the gates' runs keep them (`HOS_SYSTEM_MODS_OFF=*`), the game starts
Member

Measure the shipped no-player-mod configuration with Discord enabled as well as the gate configuration.

Measure the shipped no-player-mod configuration with Discord enabled as well as the gate configuration.
@ -0,0 +17,4 @@
at = "after"
offset = 0x74 # (ldrh w9, [x19, #0x6e]; then cbz w9 to the return)
signature_offset = 0x74
signature = "7940de69 34000009/ff00001f 37200008/fff8001f" # (ldrh w9, [x19, #0x6e]; cbz w9, *; tbnz w8, #4, *)
Member

This commits instruction words from the game. Derive and verify signatures locally from the player's copy.

This commits instruction words from the game. Derive and verify signatures locally from the player's copy.
@ -35,4 +35,2 @@
SW(HOS_DAV1D_THREADS, hw, int, "dav1d's own (one per logical core); 2 on a PC with 4 or fewer", "Sets dav1d's decoder thread count.")
SW(HOS_DISCORD, kill, bool, "on: the Discord presence thread starts", "=0 starts no Discord rich presence thread at all.")
SW(HOS_DISCORD_APP_ID, player, string, "the options file's discord_app_id=, else the built-in id", "Sets the Discord application id used for rich presence, over the options file's.")
SW(HOS_DISPLAY_MODES, diag, string, "the screen's own display modes", "Gives a list of WxH display modes in place of the screen's, to check the menu's size rows for a screen you lack.")
Member

Keep users' Discord opt-out and app-ID preferences across the update, and add GONE rows for any retired switches.

Keep users' Discord opt-out and app-ID preferences across the update, and add GONE rows for any retired switches.
@ -1704,0 +1966,4 @@
const uint64_t hash = size == total && tex.astc && tex.blocks_hash ? tex.blocks_hash : texture_pack::full_hash(size, bytes);
char of[48] = "";
if (size != total) snprintf(of, sizeof of, " of %llu", (unsigned long long)total);
logf("vk: texture hash #%u gpu %#llx NVN %#x %ux%u levels %u%s size %llu%s xxh64 %016llx sig %016llx", tex.id,
Member

The normal log feeds crash reports. Write game-derived texture hashes to a separate local diagnostic file.

The normal log feeds crash reports. Write game-derived texture hashes to a separate local diagnostic file.
@ -0,0 +253,4 @@
if (e->slot < 1 || e->slot > GAME_ATTACH_SLOTS) continue;
Slot *s = &bind_slots[e->slot - 1];
int want = e->op ? S_ASKED : S_UNBINDING;
if (!__atomic_compare_exchange_n(&s->state, &want, S_BUSY, 0, __ATOMIC_ACQ_REL, __ATOMIC_RELAXED)) continue;
Member

An old table can claim a recycled slot for a different child. Include the generation in the claim or wait for old readers before reuse.

An old table can claim a recycled slot for a different child. Include the generation in the claim or wait for old readers before reuse.
@ -0,0 +338,4 @@
int game_attach_busy(void) { return busy; }
void game_attach_counts(GameAttachCounts *out) { *out = counts; }
Member

Copying the struct races with atomic counter updates from actor threads. Load the shared counters atomically.

Copying the struct races with atomic counter updates from actor threads. Load the shared counters atomically.
@ -0,0 +30,4 @@
const unsigned a = __atomic_load_n(&last_seq, __ATOMIC_ACQUIRE);
if (a & 1u) continue;
GameCamera copy;
memcpy(&copy, &last, sizeof copy);
Member

The sequence counter does not make these plain payload accesses race-free. Synchronize both snapshots and the matrix reset.

The sequence counter does not make these plain payload accesses race-free. Synchronize both snapshots and the matrix reset.
@ -0,0 +25,4 @@
}
void *game_guest_at(uint64_t base, uint64_t off, size_t n) {
if (off > UINT64_MAX - base) return NULL; /* (base + off would wrap: never p + off <= end, which wraps too) */
return base + off >= 0x100000 ? hos_guest_range(base + off, n) : NULL;
Member

The reserved-window check accepts decommitted addresses. Check backing and lifetime through the copy, and check offsets before adding them.

The reserved-window check accepts decommitted addresses. Check backing and lifetime through the copy, and check offsets before adding them.
host/mod_watch.c Outdated
@ -0,0 +428,4 @@
fn(user, MOD_WATCH_OVERFLOW, ""), told++;
continue;
}
if (e->wd == w->parent_wd && w->parent_wd >= 0) { /* (the root made, or moved in?) */
Member

The parent and list watches can share one inotify descriptor. Dispatch both roles and preserve the list watch when mods/ appears.

The parent and list watches can share one inotify descriptor. Dispatch both roles and preserve the list watch when mods/ appears.
@ -0,0 +1052,4 @@
modstore_attach(r->id, man->version.major, man->version.minor, man->version.patch);
modrt_settings_attach(r->id, man); /* (its declared settings' values: host/modapi/settings.c, no permission) */
if (r->system) modrt_settings_migrate(r->id, man); /* (a setting that was a line of the options file, once) */
ModRt *m = modrt_create(r->id, r->root, r->start_grants, MODRT_HEAP_LIMIT, why, sizeof why);
Member

Require confirmed confinement here and for scripted content. The preflight misses enabled script packages and can disagree on manifest IDs.

Require confirmed confinement here and for scripted content. The preflight misses enabled script packages and can disagree on manifest IDs.
@ -0,0 +1068,4 @@
r->start_origins = NULL, r->nstart_origins = 0;
}
}
if (m && !modrt_run_entry(m, man->entry, why, sizeof why)) {
Member

Default Discord synchronously compiles on the game thread every launch. Prepare verified code before the frame or ship build-bound compiled modules.

Default Discord synchronously compiles on the game thread every launch. Prepare verified code before the frame or ship build-bound compiled modules.
@ -0,0 +79,4 @@
int part;
const lsapi_status st = check(ctx, address, length, 0, &part);
if (st != LSAPI_OK) return st;
hos_mem_copy_out((uint64_t)address, read_buf, (uint64_t)length);
Member

The logical heap check does not guarantee backed pages or protect the mapping through the copy. Return an API error when access cannot be completed.

The logical heap check does not guarantee backed pages or protect the mapping through the copy. Return an API error when access cannot be completed.
@ -0,0 +113,4 @@
#ifdef _WIN32
if (!GetFullPathNameA(asked, sizeof whole, whole, NULL)) snprintf(whole, sizeof whole, "%s", asked);
#else
if (!realpath(asked, whole)) snprintf(whole, sizeof whole, "%s", asked);
Member

realpath can write past this buffer. Also check the Windows required-size return and reject long paths before applying test settings.

realpath can write past this buffer. Also check the Windows required-size return and reject long paths before applying test settings.
@ -0,0 +268,4 @@
"failures=\"%d\">\n", T.passed + T.failed + T.skipped, T.failed);
for (int i = 0; i < T.n; i++) put(&x, "%s\n", T.junit[i] ? T.junit[i] : "");
put(&x, "</testsuites>\n");
const int wrote = j.s && x.s && write_text("results.json", j.s) && write_text("junit.xml", x.s);
Member

A failed report write or dropped result must make the run incomplete.

A failed report write or dropped result must make the run incomplete.
@ -0,0 +343,4 @@
}
started = 1;
wgive();
if (!mod_watch_thread(watch_main, NULL, "lsmod-watch")) {
Member

Roll back the watcher and started flag on partial startup failure, including failure to register the frame phase.

Roll back the watcher and started flag on partial startup failure, including failure to register the frame phase.
host/mods.c Outdated
@ -1043,0 +3025,4 @@
/* (longshot, version 37) a script mod's page: its header, its declared settings and its permissions (host/modapi/modrt.h);
0 for an emulator mod or past the end */
int hos_mod_page(int i, MkwVkModPage *out) { return i >= 0 && i < nmods && mods[i].id && modrt_page(mods[i].id, out); }
Member

The renderer reads mutable loader rows and strings while the game thread updates them. Publish an owned snapshot and use stable IDs for edits.

The renderer reads mutable loader rows and strings while the game thread updates them. Publish an owned snapshot and use stable IDs for edits.
host/mods.c Outdated
@ -1076,0 +3332,4 @@
static int known_path(const char *path) {
for (int i = 0; i < nmods; i++)
if (hot_same(mods[i].path, path)) return 1;
Member

A removed folder still counts as known, so reinstalling it at the same path does not restart it. Reconcile the tombstoned row.

A removed folder still counts as known, so reinstalling it at the same path does not restart it. Reconcile the tombstoned row.
host/nn_fs.c Outdated
@ -530,6 +555,7 @@ HLE(_ZN2nn2fs9WriteFileENS0_10FileHandleElPKvmRKNS0_11WriteOptionE) {
wrote_now();
WriteFile(fh->h, GP(ARG(2)), (DWORD)ARG(3), &put, &ov);
wrote_now();
fh->wrote = 1;
Member

Failed or short writes still cause a save commit at close. Publish the storage event only for a completed save.

Failed or short writes still cause a save commit at close. Publish the storage event only for a completed save.
@ -178,0 +253,4 @@
if (count != wait_seen) {
const int screen = __atomic_load_n(&told_screen, __ATOMIC_RELAXED);
const int64_t begun = __atomic_load_n(&told_ms, __ATOMIC_RELAXED);
if (__atomic_load_n(&told_count, __ATOMIC_ACQUIRE) != count) return; /* (another began meanwhile: the next read) */
Member

A writer can change the fields before incrementing the count. Publish the screen and timestamp as one coherent event.

A writer can change the fields before incrementing the count. Publish the screen and timestamp as one coherent event.
@ -0,0 +733,4 @@
const int fs = plan.abi >= 1 ? apply_landlock(&plan, &in, threads) : 0;
if (plan.abi < 1) say("sandbox: no Landlock in this kernel (%s): files and folders are not confined", abi_raw < 0 ? strerror(abi_err) : "ABI 0");
const int net = apply_seccomp(threads);
confined = fs, network_closed = net;
Member

Require both Landlock and seccomp before allowing player scripts. This currently treats files-only confinement as success.

Require both Landlock and seccomp before allowing player scripts. This currently treats files-only confinement as success.
@ -0,0 +136,4 @@
"--mode", "shared", "--desc", plan["desc"], "--"]
if not quiet:
say("queued (shared); %s" % plan["desc"])
session = longshot_bridge.start_session(
Member

An empty env file still leaves inherited switches such as HOS_MOD_TESTS_ONLY and HOS_HEADLESS. Scrub them before starting the run.

An empty env file still leaves inherited switches such as HOS_MOD_TESTS_ONLY and HOS_HEADLESS. Scrub them before starting the run.
@ -0,0 +152,4 @@
break
time.sleep(2)
info = session.info()
for name in ("results.json", "junit.xml"):
Member

A failed launch can reuse the previous run's passing JSON. Use per-run report paths and validate the process exit.

A failed launch can reuse the previous run's passing JSON. Use per-run report paths and validate the process exit.
@ -73,0 +85,4 @@
# (scripts/longshot_ts.py build --target linux) and named by LONGSHOT_TS_A, which a player's build links into the game
# (nx2/build.py ts_library). Its crates' licences go with it; the crates themselves (third_party/oxc/vendor) stay out.
# Without it the game runs JavaScript mods only)
if [ -n "${LONGSHOT_TS_A:-}" ]; then
Member

CircleCI release jobs supply no compiler archive on either platform. Make the release input required and wire it into both pipelines.

CircleCI release jobs supply no compiler archive on either platform. Make the release input required and wire it into both pipelines.
@ -0,0 +270,4 @@
# (the tracked source copied out of the tree, with a cargo home of its own that replaces crates.io by the vendored
# crates: target/ and the cargo home are never written into host/ or third_party/. One fixed folder, emptied first)
work = os.path.join(cache, "work-longshot_ts")
shutil.rmtree(work, ignore_errors=True)
Member

Concurrent builds sharing this cache delete each other's work directory. Give each invocation a separate directory.

Concurrent builds sharing this cache delete each other's work directory. Give each invocation a separate directory.
@ -0,0 +291,4 @@
"RUSTC": os.path.join(bin_dir, "rustc" + exe),
"CARGO_HOME": home,
"CARGO_TARGET_DIR": os.path.join(work, "target"),
"CARGO_ENCODED_RUSTFLAGS": "\x1f".join(flags.split(" ")),
Member

Splitting on spaces breaks remap arguments for checkout and cache paths containing spaces.

Splitting on spaces breaks remap arguments for checkout and cache paths containing spaces.
@ -0,0 +3749,4 @@
p.add_argument("--cc", default="gcc")
p.add_argument("--only", help="run only the checks whose name holds this (check_source_maps: source_maps)")
a = p.parse_args()
if os.name == "nt" or not shutil.which(a.cc):
Member

Run this suite on Windows, honor CC, and make successful TypeScript compilation a required case with a target-matched archive.

Run this suite on Windows, honor CC, and make successful TypeScript compilation a required case with a target-matched archive.
longshot/content's read.placements(map, { param }) answers the actors placed in one of the game's maps, from its
Banc/<folder>/<map>_Dynamic and _Static files as the RomFS layers serve them: each { id, actor, layer, position,
params }, the id being the placement id items.checked names a check by and rules.rewards takes. A randomizer or a
tracker then learns the game's checks at run time from the player's game, with no table of ids (game data) in the mod.

host/mod_read.c mod_read_placements_json (bounded BYML reading, 8 MiB at most), host/modapi/content_read.c's
reader thread (the Banc folders listed once; each call reads the files again), the schema (content.read.toml,
PlacementsOptions) and the generated files, services.c's feature, the fake game's contentData({ placements }).
Tests: tests/test_mod_content.py (the reader over made-up files, both byte orders, the filter, refusals),
tests/test_modrt.py check_content_read (the call in the real runtime). API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
A feature area of its own: Kokiri Forest's placements with a drop read (both ages, and a map the game lacks), their
kinds logged by name, the first chest given a reward by the id read, its check told apart. Fake game (made-up
placements) and the game (UNCONFIRMED). Listed in test_game_features.py's AREAS, the suite's README and
docs/dev/game-tests.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(modding): the randomizer example's entry in examples.md
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 14s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 32s
CI / Workflow lint (actionlint) (pull_request) Successful in 34s
Third-party parts / As their notes say (pull_request) Successful in 37s
PR description / Description follows the template (pull_request_target) Successful in 1m13s
CI / Website build and checks (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
947d3824c8
Its folder comes with the randomizer's own pull request (modapi/examples/randomizer), on this one.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- tests/mod_settings_fake.mjs: a content module reads a restart setting the player set, and its settings.set is
  ContextError; items.remove takes at the call, down to none, refuses a count of 0 and a name that is none, queues nothing.
- tests/game_items_test.c: game_items_take takes a pouch content with the add's action and a negative count (no add
  reported), a song by its flag through the game's setter (the save's copy follows), and its flag back to 0 is no load.
- tests/modapi_items_test.c: items.remove at the call only when the game can take one, its count's range, a refusal.
- tests/test_mod_content.py: the content module may import longshot/settings and only get has the content context; the
  content plan's key holds the restart settings' values.

These fail before the next commit (no game_items_take, no items.remove, settings.get refused in the content module).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Gap 3 of the randomizer's: a content module may import longshot/settings and call get (read only; set and changed stay
the entry's). The content plan's key (host/modapi/content.c plan_key) now holds the values of the mod's settings marked
restart, so a change of one runs the content module again at the next start: the randomizer's gossip stones can carry
the seed's hints. generate.py allows settings.get alone of the game namespaces in the content context.

Gap 7: items.remove(item, { count }) takes from Link at the call, in play only: a pouch content through the add's own
action, OneShotAddOrRemovePouchContent (f_828d4a70), with a negative count, as the Debug tab's remove; a song by its
IsGet flag through the game's setter, marked so the poll does not take the flag back to 0 for a load. Permission
items.grant; nothing queued or kept; has("items.remove") with the give. Fake game, docs and generated files follow.

API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- tests/test_mod_travel.py with tests/modapi_travel_test.c: host/modapi/travel.c over a scripted queue (the Debug tab's
  and the control bridge's hos_oot_teleport_ask, hos_oot_age_ask and hos_oot_teleport_result): the destinations' JSON,
  either age's map, an unknown map, an age refused, and each outcome settling once (sent, refused with the host's words,
  already that age, replaced, not taken in 30 s and cancelled); nothing asked while nothing waits (gate 5).
- tests/mod_settings_fake.mjs: the fake game takes a travel and an age switch at the next frame in play, one at a time.
- tests/modrt_test.c, tests/test_modrt.py: the runtime's test build links travel.c over a queue that takes nothing.

These fail before the next commit (no travel.c, no such functions).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Gap 5 of the randomizer's. The host's own map change (host/hos_main.c oot_teleport: the event request an entrance
sends, built by the host) and its age switch (oot_toggle_age: Sequence_IsChildhood set, the map loaded again for that
age), which the Debug tab's Teleport and Switch age and the control bridge already use, become the mod API's:

- world.destinations(): the host's table of the game's maps (child's, adult's), names only (state.read).
- world.travel(map) and player.setAge(age) (state.write): asked into the host's one queue (taken at Link's next update
  in play), settled { done, map, why } at the acquire phase after update by host/modapi/travel.c (modrt_travel_frame);
  a later ask replaces one not taken, 30 s untaken is cancelled. One load a frame while nothing waits (gate 5).
- has() true in Ocarina of Time builds; the fake game models it (setDestinations, travels); docs/modding/writes.md.

API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- tests/test_game_skips.py with tests/game_skips_test.c: host/game/skips.c over made-up guest memory (the offsets
  written out): no table answering -1 at every site, a request of another name not arming, a skipped event's request
  arming once, its timelines unstarted with the player's hold bit cleared, the skip query answered in x0, the arm dropped
  when no event plays and at another request, an unreadable request left alone, the table taken back; and in the source,
  the opening sites calling the skips before Skip opening, the reset with Skip opening's, the HOS_TABLE line, rules.c's
  frame and a stopped mod's skips.
- tests/test_modrt.py (check_skips) and tests/modrt_test.c: Rule handles, bad rules refused, each name once in the table
  handed to the game, PermissionError without state.write.
- tests/mod_settings_fake.mjs: the fake game's skips, requestEvent and eventsSkipped.

These fail before the next commit (no skips.c, no rules.skips).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Gap 10 of the randomizer's. The three sites Skip opening already uses (opening.request f_80d9a820, opening.timeline
f_83b5bfb0, opening.skipQuery f_80de6cb0) call host/game/skips.c first: while the latest one-shot event a sequence asked
for is one a mod named, its timelines are left unstarted (the player's hold bit cleared, as for the opening's) and the
event's script is told it was skipped, so it takes its own branch for a skip. The arm goes at another request and once
no event plays (reset with Skip opening's in Link's update).

rules.skips.add({ event }) returns a Rule (state.write, 64 a mod); host/modapi/rules.c publishes the running mods'
names once each as the HOS_TABLE events.skips at the rules' point. With no skip the sites read one pointer (gate 5).
The fake game models it (skips, requestEvent), docs/modding/rules.md#skips. No event names ship: a mod names them, and
the log says when a skipped one is asked for. API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- tests/mod_vectors/content.json: a case of changes (an actor and params on one file, params on another, an actor alone;
  refused: a file that is not a map's placements, an id that is not 16 hex digits, a change of nothing, a key with a
  slash, a value that is an object, an unknown field), the host's and the fake game's outputs compared with it.
- tests/test_modrt.py: content.read.placements gives each placement's file (what content.change names).
- tests/test_mod_content.py: the reader's harness passes no file.

These fail before the next commit (no change kind, no file in read.placements).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Gap 8 of the randomizer's, and part of gap 2. A content module changes one of the game's own placements: its actor
(Gyaml) and keys of its parameters (Dynamic) it already has, by the placement's file and id as content.read.placements
gives them (each placement now has its file: the RomFS path the reader found it in). Each change is a set op of a
placements patch (host/mod_patch.c apply_place), one patch a map file (patches/change-<n>.json).

The research behind it (cited by address only): an exit is a placement of FieldAndDungeonEntranceEventRequestActor whose
Dynamic names its destination (NextBancParamNameChild/Adult, NextStartPosName, NextEventName), read by the query
QueryBancChangeEventRequestArg (f_829df380) into the event request the map change runs, so an exit is redirected by
data with no site. Freestanding heart pieces give themselves (their actor placed), business scrubs' stock is their
placements' ScrubBusiness_ShopItemActorName0..2. With settings readable in the content module, an entry decides, keeps
the plan in a restart setting, and the next start applies it. Fake game (outputs, problems, read.placements after the
changes), docs/modding/content.md, docs/dev/reference/content.md (what a run must confirm). API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/game_items_test.c: Item_Dungeon_<kind>_<dungeon> names (an unknown dungeon or kind none), a map given through the
game's queued Bool setter, small keys added in place with the count ever got, both reported to the next poll with their
tags, keys taken never below 0, a map taken, a dungeon item whose flag the game lacks not given now.

Fails before the next commit (no game_items_dungeon_item).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Gap 6 of the randomizer's. The game keeps a dungeon's map, compass, boss key and small keys in GameData's Struct
DungeonInfo.<dungeon>, whose members are ordinary saved flags DungeonInfo.<dungeon>.IsGetMap/IsGetCompass/IsGetBossKey
(Bools) and SmallKeyNum/SmallKeyTotalNum (Ints), read by the queries QueryDungeonIsGetMap (f_82a0bfd0), IsGetCompass
(f_82a0bea0), IsGetBossKey (f_82a0bd70) and GetSmallKeyNum (f_82a0bb10) that the doors ask. host/game/items.c gives,
reads and takes Item_Dungeon_<Map|Compass|BossKey|SmallKey>_<dungeon> through them (a Bool by the queued setter, the
counts in place) and reports a give to the poll with its tag, so granted fires. Keysy is a mod's: the counts kept up.
docs/dev/reference/items.md says what was found and what a run must confirm. API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- tests/test_mod_world_state.py with tests/modapi_world_state_test.c: host/modapi/worldstate.c over scripted flags (the
  names, a state read from its flags, null with no save or a flag the game lacks, set on and off through the queued
  setter in play only, an unknown name); the host's table and the fake game's are the same.
- tests/mod_settings_fake.mjs: the fake game's states; tests/modrt_test.c: the runtime's build has none.

Fails before the next commit (no worldstate.c, no such functions).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Gap 4 of the randomizer's. Parts of the game's story state by name, each a few of the game's own saved switches written
through its queued setter, in play only: openForest, openDoorOfTime, kakarikoGate, gerudoCard, ganonCastleGate, the six
trials and trialsCleared, ganonBossKey (the tower door's QueryDungeonIsGetBossKey f_82a0bd70 reads its DungeonInfo flag).
Found by reading the game's data and code on a developer's PC (names only; docs/dev/reference/world.md says how and what
a run must confirm). Not there: Zora's Fountain (King Zora's state not found), the rainbow bridge (a step of the
Step_Defeat_Ganon enum, and enums are not written), the carpenters. host/modapi/worldstate.c, the fake game's twin
table (WORLD_STATES), docs/modding/writes.md#the-worlds-state. API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- tests/test_game_rewards.py with tests/game_rewards_test.c: the site rewards.gift at f_828d4a70 +0x254 (its table
  template over the frame and the node, its HOS_TABLE line), and its C over a made-up frame and node: no table nothing,
  a map's gift over any map's, a giver's over a map's, no owner no giver, an item with no gift its own, a text outside
  the frame's buffer or a capacity too small never written, the table taken back.
- tests/test_modrt.py (check_gifts), tests/modrt_test.c: where.gives with map and giver, refusals, the gifts' table
  beside the drops'.
- tests/mod_settings_fake.mjs: the fake game's giftFor.

These fail before the next commit (no site, no gifts).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Gap 2 of the randomizer's (with content.change for freestanding items and scrubs' stock). Every give of an event flow
ends in the event action OneShotAddOrRemovePouchContent (f_828d4a70), which copies the item's name into a buffer of its
own frame before it turns the name into a category and adds it. A new inline site, rewards.gift (+0x254, where its four
paths join; template reward_rules_gift), writes a gift's item into that buffer, within its capacity, when the name, the
map and the giver (the action's owner's placement id) match: rules.rewards.add({ where: { gives, map?, giver? }, give })
beside the drops' where.location, under the same claim. host/game/rewards.c publishes the gifts' own table only once a
gift is added (a mod of drops alone costs nothing more: gate 5); with none the site is one load.

Not covered and said so: the event's text and shown item stay the game's, shops' prices, cows' milk, tokens. The site's
signature is unique in build e0f3ccfa (nx2/hooks.py); the lift key changes with the table. Fake game (giftFor), docs
(rules.md#rewards, items.md: what a run must confirm). API version stays 37.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/test_modrt.py: the fixture's chest has a Name, which the placement's result carries (a Gossip Stone's Name is its
message's label). Fails before the next commit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
For the randomizer's gossip stones (gap 3): a stone (Obj_GossipStone_A_01) shows the label of
EventFlowMsg/GossipStone.msbt that its placement's Name names (its flow's EventTalkWithInstanceNameLabel), so a mod
finds each stone's label at run time and its content module replaces the text with content.text. Fake game, schema.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/test_mod_content.py: the reader keeps one actor's placements when asked (the Octorok alone). Fails before the next
commit (no such argument).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
read.placements(map, { actor }) keeps one actor's placements (its Gyaml), filtered on the reader's thread, so a mod
asks a map for its Gossip Stones (Obj_GossipStone_A_01, whose placements have no parameters to filter by) without the
whole map's placements crossing into its script. Fake game, schema.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(modding): the randomizer's examples.md entry names the API it now uses
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
ci/circleci: setup-pr
CI / Conventional Commit title (pull_request) Successful in 11s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 23s
CI / Workflow lint (actionlint) (pull_request) Successful in 28s
Third-party parts / As their notes say (pull_request) Successful in 31s
PR description / Description follows the template (pull_request_target) Successful in 1m3s
CI / Website build and checks (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
79da3021b3
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(modding): new nodes in a tree (behaviour.md), and the adding, its checks, the data links' coverage and what a game run confirms (behaviour-trees.md)
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 9s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 15s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 20s
PR description / Description follows the template (pull_request_target) Successful in 55s
CI / Website build and checks (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
3e92b24957
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
richgel999/bc7enc at f66c2e48 (MIT or the Unlicense: taken under MIT), its bc7enc.c, bc7enc.h and LICENSE
unmodified, with its provenance note and tree hash. Not built yet: host/bntx_write.c, the BNTX writer of a
mod's PNG skins, is its user.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/test_mod_assets.py, on files made in the test (no game data): the BNTX writer's files read back by
nx2/texture_index.py and decoded level by level by gpu/vk/texture_decode.cpp (RGBA8 and its mip chain
exactly, BC7 within a few steps), the Switch 2 GOB layout and NVN's per-level block heights, the file's
frame (header, string table, its one-key dictionary, BRTI, the relocation table pointer by pointer); a
made-up BFRES 10.4 whose materials' textures and file name are renamed, with and without room after the
string pool, every other byte and pointer as it was; refusals and cut or damaged files; a skin made of a
model and PNGs. tests/mod_vectors/content.json: a case of actors and an item with skins, and the refusals,
for host/mod_content.c and the fake game alike. Fails until the skin is built (the next commit).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
actor({ id, from, skin: { "<texture name>": "x.png" | { file, format } } }): the content stage gives the
copy its own model project (<word>_<id>: ModelInfo's ModelProjectName and the ActorInfo row's, FmdbName
kept) and copies the images into its folder; the merged-file step, once the copy's pack is served, reads
the copied actor's model as the layers serve it and makes, in modcache/files on the player's PC:

- Model/<project>.<fmdb>.bfres.zs: the game's model with each skinned texture's references in every
  material renamed <project>_<n> (host/bfres_edit.c: strings added in the room after the pool, or after
  everything with the relocation table moved; nothing else changed; checked over 200 of the game's
  models on this PC, made from the game and kept off the repository);
- Tex/<project>_<n>.bntx.zs: the PNG as a BNTX of the Switch 2's (host/bntx_write.c: 4.1.1, Ounc,
  block-linear in the Switch 2 GOB, mips down to 1x1, BC7 by bc7enc or RGBA8), in the game texture's
  colour space and channels. The writer's frame re-creates 373 of 373 sampled game textures byte for
  byte from their data, on this PC.

The makers are hooks the content stage sets (romfs_merge_assets), so the merged-file step still links
without the encoders. Keyed by the spec, the model's, the images' and the game textures' bytes. Not yet
run in the game: docs/dev/reference/assets.md (next) lists what a first run has to confirm.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/test_mod_assets.py: mod_assets_model_check on made-up BFRES files and a made-up pack: a model used,
the bones its actor's components name that its skeleton lacks said (strings under keys with "Bone",
FmdbNameForRepresentativeBone and paths aside); refused: a model named otherwise than its file, a texture
neither the mod nor the game has, version 9, two models, no bones, not a BFRES.
tests/mod_vectors/content.json: content.model's textures as .png images (a string, or { file, format,
srgb }) made BNTX files, a .bntx.zs kept, and the refusals. Fails until the next commit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- textures may be .png images ("<word>_<name>.png", or { file, format: "bc7" | "rgba8", srgb }):
  the content stage makes each Tex/<word>_<name>.bntx.zs on the player's PC (host/bntx_write.c, keyed
  by the image's size and last write), as the skins' are;
- the merged-file step checks the model before it serves the actor's pack (host/mod_assets.c
  mod_assets_model_check, a hook the content stage sets): a BFRES 10 of one model named as its file
  (the game finds it by FmdbName), each texture its materials name served by the mod or the game; a
  model that fails leaves the actor out, with why in the log. The bones the actor's components name
  (Phive, ModelBind, LookIK, FootIK...: every string under a key with "Bone" in its pack) that the
  model's skeleton lacks are said, kept in the pack's record so a start from the cache says them too;
- the model's bytes are part of the pack's key, so a changed model is checked again.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/test_mod_assets.py: a glTF made in the test written by longshot-mod anim's writer and read back on its
own (header, two FSKA, bones' base values and curves, 16-bit frames, Hermite values and slopes, quaternions,
the values at each frame for linear, step and slerp, a dictionary every name of which the game's radix-tree
search finds, every relocated pointer inside the file); host/mod_assets.c's check of it against a made-up
model (the bones it lacks said), a model refused as one, cut and damaged copies read without a crash.
tests/test_mod_content.py: the pack's AnimationResources with the mod's files first and last, over a list
of the component's own or its parent's. tests/mod_vectors/content.json: content.actor's "animations" and
its refusals. Fails until the next commit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
- content.actor({ animations: ["anims/x.anim.bfres" | { file, order: "first" | "last" }] }): each file
  served as Model/<word>_<id>_A<n>.anim.bfres.zs (a plain .anim.bfres made a zstd frame on the player's
  PC) and named in the copy's Animation component's AnimationResources, before the game's (first) or
  after; an animation named as one the actor plays can take its place (which one the game picks across
  several resources is a game run's to say). The pack builder copies a list the parent gives into the
  component before it adds to it.
- The merged-file step checks each file (host/mod_assets.c mod_assets_anim_check: a BFRES 10 of FSKA and
  no model, every field inside the file) against the model the new pack names, and says what it holds
  and the bones it moves that the model lacks (never refused: the game binds bones by name).
- longshot-mod anim <gltf|glb>: a glTF's named animations sampled at 30 frames a second and written as
  the game's animation file (lib/assets.js: FSKA with quaternion rotations, 16-bit frames, float keys:
  Hermite values and slopes, quaternion keys; the names' dictionary as nn::util::ResDic builds it, which
  gives the same nodes as all 252 dictionaries of 60 animation files and 200 models of the game read on
  this PC, kept off the repository). The author's curves only: the file ships with the mod.
- longshot-mod skeleton --game DIR --model <project>.<fmdb>: the skeleton of a model of the author's own
  game as a glTF to animate against (never shipped: pack leaves *.skeleton.gltf out).
- longshot-mod check: the mod's PNGs (at most 4096 a side, not interlaced) and glTF files (as anim takes
  them).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
tests/game-features/assets: a cucco of the mod's own with its PNG on its body and its animation file
first in its AnimationResources, placed in Kokiri Forest. In the fake game: the content stage's files.
In the game (UNCONFIRMED): that the copy's ModelInfo names the skin's model and its AnimationResources
the mod's clip first. tests/test_game_features.py runs the area.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
red-cucco: a copy of the cucco whose body wears skins/red_body.png (drawn for the example); puffed-cucco:
a copy whose Wait is the mod's, anims/puff.anim.bfres written by longshot-mod anim from the hand-written
anims/puff.gltf (one bone's scale by its name: no rest pose of the game's). TypeScript 7, src/ only, each
with its fake-game tests.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(modding): assets: skins, models and animations, the formats, and what a game run must confirm
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
ci/circleci: setup-pr
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 9s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 17s
CI / Workflow lint (actionlint) (pull_request) Successful in 17s
Third-party parts / As their notes say (pull_request) Successful in 20s
PR description / Description follows the template (pull_request_target) Successful in 56s
CI / Website build and checks (pull_request) Failing after 20s
Website / Website on Cloudflare (pull_request) Failing after 16s
443f7d3d3f
docs/modding/assets.md, the author's guide: skins, models (PNG textures, the checks), animations (glTF,
longshot-mod skeleton and anim, order), limits and what is not yet. docs/dev/reference/assets.md: where
each file is made, the BNTX, BFRES and FSKA layouts with how sure each part is, the game-run checks in
order (the copied model under a new name, a renamed texture, a BNTX of ours first), the ASB 0x41B work
next (3b: not built, no byte-exact reader over the game's files yet) and the glTF-to-BFRES design with
its open questions. content.md, tools.md, examples.md and the indexes point at them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(modding): spawning seen once in the game, the longshot-mod add usage's version inside its argument, and two copies of longshot-env.d.ts the examples' .gitignore leaves out removed
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
ci/circleci: setup-pr
CI / Conventional Commit title (pull_request) Successful in 9s
CI / Website build and checks (pull_request) Failing after 25s
CI / Workflow lint (actionlint) (pull_request) Successful in 27s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 28s
Third-party parts / As their notes say (pull_request) Successful in 39s
Website / Website on Cloudflare (pull_request) Failing after 37s
PR description / Description follows the template (pull_request_target) Successful in 1m22s
25a664bdf7
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(modding): content.actor's def names components, add, remove and scripts; rupee-rain's bound comment matches the flag's; the preview banners say the feature tests are the only runs
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 22s
CI / Workflow lint (actionlint) (pull_request) Successful in 23s
Third-party parts / As their notes say (pull_request) Successful in 25s
PR description / Description follows the template (pull_request_target) Successful in 1m2s
CI / Website build and checks (pull_request) Failing after 46s
Website / Website on Cloudflare (pull_request) Failing after 30s
2749e50672
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
HumanBean force-pushed mod-api from 2749e50672
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 22s
CI / Workflow lint (actionlint) (pull_request) Successful in 23s
Third-party parts / As their notes say (pull_request) Successful in 25s
PR description / Description follows the template (pull_request_target) Successful in 1m2s
CI / Website build and checks (pull_request) Failing after 46s
Website / Website on Cloudflare (pull_request) Failing after 30s
to 2233d622ae
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 19s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 40s
CI / Workflow lint (actionlint) (pull_request) Successful in 44s
Third-party parts / As their notes say (pull_request) Successful in 1m14s
PR description / Description follows the template (pull_request_target) Successful in 2m34s
CI / Website build and checks (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
2026-11-21 06:13:14 +00:00
Compare
fix(game): main's teleport check reads Sequence_IsLoadingBanc through host/game/'s flag reader (oot_gamedata_bool is gone), and its check's stubs follow
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 26s
Third-party parts / As their notes say (pull_request) Successful in 31s
PR description / Description follows the template (pull_request_target) Successful in 1m18s
CI / Website build and checks (pull_request) Successful in 5m42s
Website / Website on Cloudflare (pull_request) Successful in 7m40s
b184b67c22
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Author
Owner
<!-- website-preview --> **Website preview:** https://pr-1958-longshot-website.hckr-5e0.workers.dev This commit (5702ebc5e08a) on its own: https://f769b7cb-longshot-website.hckr-5e0.workers.dev
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
docs(modding): the mod inspector fullscreen with the input, its cards, its Mods tab of the table beside the mod chosen, and what it costs; the player's page to match
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 36s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 38s
Third-party parts / As their notes say (pull_request) Successful in 33s
PR description / Description follows the template (pull_request_target) Successful in 1m26s
CI / Website build and checks (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
05caf59e97
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The host takes occlude="depth" as a prop or a mount's opts (MKWVK_UI_OCCLUDE_DEPTH) and puts each World root's point (its
at plus its offset, 0 while hidden) and its metres prop in the snapshot, for the renderer to draw it in the scene. The fake
game takes the value and gives worlds()' point; the types say what it does.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
The present lays such a root out as any World root and draws it into its cell of one atlas (2048 x 1024 of the overlays'
format, 64 cells kept while their size fits, a cell let go reused 8 presents later) on its own command buffer before the
window's pass, and publishes where each stands; the world layer draws each as a quad on its point after its shapes, as high
as the label is over the picture or metres high, tested with the billboards' bias. Nothing is read back and nothing waits;
with no such root no atlas exists and world_layer_any() stays one relaxed load. A root with no cell, an HDR window or
RX_VK_WORLD=0 draws it over the picture as hide. ImGui's vertex buffers doubled, as a frame may draw twice. The math and the
atlas checked by tests/world_layer_test.cpp, the wiring by tests/test_gfx_world.py.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
ui.md's World section, world.md, ui-channel.md, examples.md and architecture.md's world layer (rule 7). enemy-names draws its
labels in the scene: a name over an enemy should be cut by the pillar in front of it, and its tests read the label's point.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
test(mods): modrt_test links the assets' sources content.c now calls (mod_assets.c, bfres_edit.c, bntx_write.c, bc7enc), so test_modrt and test_gfx_world's host half link again
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
ci/circleci: setup-pr
CI / Conventional Commit title (pull_request) Successful in 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 25s
Third-party parts / As their notes say (pull_request) Successful in 32s
PR description / Description follows the template (pull_request_target) Successful in 1m5s
CI / Website build and checks (pull_request) Successful in 2m58s
Website / Website on Cloudflare (pull_request) Successful in 4m42s
5702ebc5e0
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
HumanBean force-pushed mod-api from 5702ebc5e0
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
ci/circleci: setup-pr
CI / Conventional Commit title (pull_request) Successful in 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 25s
Third-party parts / As their notes say (pull_request) Successful in 32s
PR description / Description follows the template (pull_request_target) Successful in 1m5s
CI / Website build and checks (pull_request) Successful in 2m58s
Website / Website on Cloudflare (pull_request) Successful in 4m42s
to 1297f8701b
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
CI / Website build and checks (pull_request) Waiting to run
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Waiting to run
CI / Conventional Commit title (pull_request) Successful in 23s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 46s
CI / Workflow lint (actionlint) (pull_request) Successful in 49s
Third-party parts / As their notes say (pull_request) Successful in 1m2s
PR description / Description follows the template (pull_request_target) Successful in 2m32s
2026-11-21 09:14:07 +00:00
Compare
Some checks failed
ci/circleci: setup-pr
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
CI / Website build and checks (pull_request) Waiting to run
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Waiting to run
CI / Conventional Commit title (pull_request) Successful in 23s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 46s
CI / Workflow lint (actionlint) (pull_request) Successful in 49s
Third-party parts / As their notes say (pull_request) Successful in 1m2s
PR description / Description follows the template (pull_request_target) Successful in 2m32s
This pull request is marked as a work in progress.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin 'mod-api:mod-api'
git switch 'mod-api'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1958
No description provided.