WIP: feat(mods): a code mod is switched off and on at a restart, without a build #1036

Draft
snaildev99 wants to merge 27 commits from snaildev99/Longshot:mods/patch-switch-stack into main
Contributor

Type: feat · Risk: medium · Tested on: Windows 11, RTX 3090 (in the game, twice, on the base before the last rebase; the game-free checks at this head) · Needs: Linux, any GPU: a build and the round below; a frame-rate comparison

Why

With #134 a mod's code is built into the game, so switching such a mod Off or On only takes effect at the next build. Until then the game runs half a mod: Off leaves its code in while its files are gone (seen: a menu drawn without its layout), On serves its files while its code is not there (seen: a menu page that opens and does nothing). The Mods tab says so, but a switch that needs a ten-minute build is not much of a switch, and a tester on #134 asked for exactly this gap to be closed.

This makes the switch work the way it does for any other mod: Off, restart, the plain game; On, restart, the mod is back. No build.

The idea in one line: for a mod to be switched back on without a build, its code has to be in the game already. So the build keeps both versions of the few functions a mod changes, the game's own and the mod's, and the game picks one at its start. With the mod Off the game runs its own, unchanged code; the mod's version is there and never reached.

It is stacked on #134 and on the patch-build follow-ups (#960, #961 and three branches that have no pull request yet, see What changed), so only the last three commits are this change.

What changed

A mod with ExeFS patches that is in mods when the game is built, On or Off, is switched at the next start.

  • build (nx2/exefs_switch.py, new; hooks in exefs_patches.py, lift.py, chunks.py, build.py): every function that holds a word a mod writes is translated once more for each other state of the mods that touch it. The function as written gets one line at its top that reads a byte the host sets (hos_patch_on[]) and goes to the right version; every other function is translated once, as now. It works a function at a time, so a real code cave (branches, calls, adrp) needs no special rule. The lift is told the calls of every state, so a function only the game's own code calls is a function with the mod Off too. Jump tables in data a mod writes are read again per state.
  • host (host/mod_switch.c, new; host/mods.c, host/hos_main.c): at the start, before any game code runs, the switches are set from the Mods tab's list and the bytes of the mods that are On are written into the loaded image (first the game's own byte of each place, then each On mod's in the list's order). image.bin itself stays the game's.
  • exefs_patches.txt marks each file with its switch (code+switch<n>), a mod that is Off included.
  • What still needs a build, and says so on the Mods tab: a mod added or edited after the build; more than two mods on one function (the lowest in the list are built in for good); a mod that writes a place Longshot itself hooks; two mods whose patches change how each other is built; and any mod for which a version would end in a call into code that is no function (the build finds that and falls back, rather than let a switched-off mod stop the game).
  • Underneath, as merged: the branch of #960, the branch of #961, and three patch-build branches without a pull request of their own yet (mods/port-sites: a note when a patch lands where Longshot hooks the game's code; mods/atmosphere-patches: a console pack's atmosphere/exefs_patches/<name>/ folder is a mod; mods/lift-key-bytes: the lift's key follows the patched bytes, so a renamed mod keeps the translation). The switch builds on the last one's key.

Measurements

Verdict: the cost in the build is small and measured; the cost while playing is not measured yet (expected: one byte load and a predictable branch at the entry of the switched functions).

Hardware: Windows 11, RTX 3090, driver 610.88
Scene: none (the build's own numbers)
Method: the build's log and a dry run of the build's steps over the game's code
How to reproduce: build with the two mods below in mods; the exefs: switched at a start line

Before: #134 and the patch-build stack After: this PR
A 7.7 KB patch with a code cave (1,942 instructions) and a 49-byte .pchtxt: functions translated twice 0 58 (22,615 instructions, 0.13 % of the lift)
The same: time added to the lift 0 about 5 s (0.7 s the versions, about 4 s the jump tables)
Switching one of the mods a build (2 to 10 minutes here) a restart

Flags and settings

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
LONGSHOT_PATCH_SWITCH at the build: which mods get a switch (no switches) unset: every mod in mods, On or Off 0: none, every function as before this PR; on: only the mods On at the build 0 checked to give the same translated files as the base; on untested in a game unset

Testing

Tested:

  • In the game, Windows 11, RTX 3090 (driver 610.88), two builds of this branch on the base before the last rebase (#134 @ 5192b46f), before and after an independent review's nine findings were answered. Mods: Character Select v0.2.1 (6,903 files, a 7.7 KB patch with a code cave) On, and Auto Jump (a .pchtxt) Off at the build. Four starts each time, no build between them: (1) the mod works, Auto Jump is listed Off; (2) Character Select switched Off on the Mods tab, restart: the plain game, three tabs in the game's menu, nothing drawn wrong; (3) On, restart: the mod back whole; (4) Auto Jump switched On, restart: its change works and the other mod still does. The Mods tab only ever asked for a restart. The log: its ExeFS patches are off at this start (built in behind a switch), 1 of 2 switched mods on; 15481 bytes of the game's code and data set to match.
  • tests/test_exefs_switch.py (new): a made-up program through the build's own steps, compiled and run in every state against a small interpreter: a cave with a conditional branch, a call and an adr; a mod off at the build; two mods on one function (four states); a third past the cap; a function only the unpatched code calls; Longshot's own edits of the translated C with two mods on the same functions; jump tables; a file saved again.
  • tests/test_mods_switch.py (new): host/mods.c and host/mod_switch.c over made-up mods and memory, several starts: the switches, every byte, the Mods tab's lines, the log.
  • tests/run_all.py on Windows at this head: 564 passed, 21 failed, 85 skipped; the same twenty-one fail on #134's head in the same session (557 passed there).
  • A second reader went through the branch cold (correctness of the versions across functions, the cap, the unmodded translation, the host's writes, Longshot's own edits, the hot file); its nine findings, two of them serious, are answered in the last of the three commits, each with a test that failed before.

Not tested: this head in a game (the two rounds were on the base before #134's last rebase; nothing in this branch's own files changed since); Linux; frame rate; the emit's spawned workers together with the picking line; more than two mods on one real function.

Must be tested:

  • Windows or Linux, any GPU: build with a code mod in mods, then on the Mods tab switch it Off and restart (the plain game), On and restart (the mod back), with no build between; longshot_log.txt has the built in behind a switch lines (by hand).
  • Any system: the same scene with the mod On, built with LONGSHOT_PATCH_SWITCH=0 and without it: the frame rate, three runs a side.

Risks

What could break: a state of the switches the tests do not cover reaching code translated for another state (the review looked for this and found the design sound: every way from one function to another goes through the function's own name, which is the picking line). A switched function that is hot runs its usual version from the hot file with the mod On and a plain copy with it Off. The game holds the code of mods that are Off: it is never reached, but it is in the executable, and a mod with an instruction the lift lacks shows up at the build even when Off.

Turning it off: LONGSHOT_PATCH_SWITCH=0 at the build: no switches, the translation as before this PR.

Compatibility: the first build translates the game again. A game folder built before this has no switches; its mods need a build to switch, as before.

Reviewer notes

Two decisions here are the maintainer's, and the code follows either answer with one setting:

  1. Which mods the build takes. Today: every mod in mods, On or Off, so any of them can be switched later. The other choice (LONGSHOT_PATCH_SWITCH=on): only the mods On at the build, so nothing a player switched Off is in the executable, and a mod that was Off needs a build to come on.
  2. Two mods that change the same function. Each combination needs its own version (two mods: four). The cap is two; past it, the extra mods fall back to needing a build. No two mods we have looked at change the same function except where they write the same place, which the build already reports. It is one number.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main. (on #134's head and the patch-build follow-ups)
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows here; Linux by the round above)
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** medium · **Tested on:** Windows 11, RTX 3090 (in the game, twice, on the base before the last rebase; the game-free checks at this head) · **Needs:** Linux, any GPU: a build and the round below; a frame-rate comparison ## Why With #134 a mod's code is built into the game, so switching such a mod Off or On only takes effect at the next build. Until then the game runs half a mod: Off leaves its code in while its files are gone (seen: a menu drawn without its layout), On serves its files while its code is not there (seen: a menu page that opens and does nothing). The Mods tab says so, but a switch that needs a ten-minute build is not much of a switch, and a tester on #134 asked for exactly this gap to be closed. This makes the switch work the way it does for any other mod: Off, restart, the plain game; On, restart, the mod is back. No build. The idea in one line: for a mod to be switched back on without a build, its code has to be in the game already. So the build keeps both versions of the few functions a mod changes, the game's own and the mod's, and the game picks one at its start. With the mod Off the game runs its own, unchanged code; the mod's version is there and never reached. It is stacked on #134 and on the patch-build follow-ups (#960, #961 and three branches that have no pull request yet, see What changed), so only the last three commits are this change. ## What changed A mod with ExeFS patches that is in `mods` when the game is built, On or Off, is switched at the next start. - build (`nx2/exefs_switch.py`, new; hooks in `exefs_patches.py`, `lift.py`, `chunks.py`, `build.py`): every function that holds a word a mod writes is translated once more for each other state of the mods that touch it. The function as written gets one line at its top that reads a byte the host sets (`hos_patch_on[]`) and goes to the right version; every other function is translated once, as now. It works a function at a time, so a real code cave (branches, calls, `adrp`) needs no special rule. The lift is told the calls of every state, so a function only the game's own code calls is a function with the mod Off too. Jump tables in data a mod writes are read again per state. - host (`host/mod_switch.c`, new; `host/mods.c`, `host/hos_main.c`): at the start, before any game code runs, the switches are set from the Mods tab's list and the bytes of the mods that are On are written into the loaded image (first the game's own byte of each place, then each On mod's in the list's order). `image.bin` itself stays the game's. - `exefs_patches.txt` marks each file with its switch (`code+switch<n>`), a mod that is Off included. - What still needs a build, and says so on the Mods tab: a mod added or edited after the build; more than two mods on one function (the lowest in the list are built in for good); a mod that writes a place Longshot itself hooks; two mods whose patches change how each other is built; and any mod for which a version would end in a call into code that is no function (the build finds that and falls back, rather than let a switched-off mod stop the game). - Underneath, as merged: the branch of #960, the branch of #961, and three patch-build branches without a pull request of their own yet (`mods/port-sites`: a note when a patch lands where Longshot hooks the game's code; `mods/atmosphere-patches`: a console pack's `atmosphere/exefs_patches/<name>/` folder is a mod; `mods/lift-key-bytes`: the lift's key follows the patched bytes, so a renamed mod keeps the translation). The switch builds on the last one's key. ## Measurements **Verdict:** the cost in the build is small and measured; the cost while playing is not measured yet (expected: one byte load and a predictable branch at the entry of the switched functions). Hardware: Windows 11, RTX 3090, driver 610.88 Scene: none (the build's own numbers) Method: the build's log and a dry run of the build's steps over the game's code How to reproduce: build with the two mods below in `mods`; the `exefs: switched at a start` line | | Before: #134 and the patch-build stack | After: this PR | |---|---|---| | A 7.7 KB patch with a code cave (1,942 instructions) and a 49-byte `.pchtxt`: functions translated twice | 0 | 58 (22,615 instructions, 0.13 % of the lift) | | The same: time added to the lift | 0 | about 5 s (0.7 s the versions, about 4 s the jump tables) | | Switching one of the mods | a build (2 to 10 minutes here) | a restart | ### Flags and settings | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `LONGSHOT_PATCH_SWITCH` | at the build: which mods get a switch | (no switches) | unset: every mod in `mods`, On or Off | `0`: none, every function as before this PR; `on`: only the mods On at the build | `0` checked to give the same translated files as the base; `on` untested in a game | unset | ## Testing **Tested:** - In the game, Windows 11, RTX 3090 (driver 610.88), two builds of this branch on the base before the last rebase (#134 @ 5192b46f), before and after an independent review's nine findings were answered. Mods: Character Select v0.2.1 (6,903 files, a 7.7 KB patch with a code cave) On, and Auto Jump (a `.pchtxt`) Off at the build. Four starts each time, no build between them: (1) the mod works, Auto Jump is listed Off; (2) Character Select switched Off on the Mods tab, restart: the plain game, three tabs in the game's menu, nothing drawn wrong; (3) On, restart: the mod back whole; (4) Auto Jump switched On, restart: its change works and the other mod still does. The Mods tab only ever asked for a restart. The log: `its ExeFS patches are off at this start (built in behind a switch)`, `1 of 2 switched mods on; 15481 bytes of the game's code and data set to match`. - `tests/test_exefs_switch.py` (new): a made-up program through the build's own steps, compiled and run in every state against a small interpreter: a cave with a conditional branch, a call and an `adr`; a mod off at the build; two mods on one function (four states); a third past the cap; a function only the unpatched code calls; Longshot's own edits of the translated C with two mods on the same functions; jump tables; a file saved again. - `tests/test_mods_switch.py` (new): `host/mods.c` and `host/mod_switch.c` over made-up mods and memory, several starts: the switches, every byte, the Mods tab's lines, the log. - `tests/run_all.py` on Windows at this head: 564 passed, 21 failed, 85 skipped; the same twenty-one fail on #134's head in the same session (557 passed there). - A second reader went through the branch cold (correctness of the versions across functions, the cap, the unmodded translation, the host's writes, Longshot's own edits, the hot file); its nine findings, two of them serious, are answered in the last of the three commits, each with a test that failed before. **Not tested:** this head in a game (the two rounds were on the base before #134's last rebase; nothing in this branch's own files changed since); Linux; frame rate; the emit's spawned workers together with the picking line; more than two mods on one real function. **Must be tested:** - Windows or Linux, any GPU: build with a code mod in `mods`, then on the Mods tab switch it Off and restart (the plain game), On and restart (the mod back), with no build between; `longshot_log.txt` has the `built in behind a switch` lines (by hand). - Any system: the same scene with the mod On, built with `LONGSHOT_PATCH_SWITCH=0` and without it: the frame rate, three runs a side. ## Risks **What could break:** a state of the switches the tests do not cover reaching code translated for another state (the review looked for this and found the design sound: every way from one function to another goes through the function's own name, which is the picking line). A switched function that is hot runs its usual version from the hot file with the mod On and a plain copy with it Off. The game holds the code of mods that are Off: it is never reached, but it is in the executable, and a mod with an instruction the lift lacks shows up at the build even when Off. **Turning it off:** `LONGSHOT_PATCH_SWITCH=0` at the build: no switches, the translation as before this PR. **Compatibility:** the first build translates the game again. A game folder built before this has no switches; its mods need a build to switch, as before. ## Reviewer notes Two decisions here are the maintainer's, and the code follows either answer with one setting: 1. **Which mods the build takes.** Today: every mod in `mods`, On or Off, so any of them can be switched later. The other choice (`LONGSHOT_PATCH_SWITCH=on`): only the mods On at the build, so nothing a player switched Off is in the executable, and a mod that was Off needs a build to come on. 2. **Two mods that change the same function.** Each combination needs its own version (two mods: four). The cap is two; past it, the extra mods fall back to needing a build. No two mods we have looked at change the same function except where they write the same place, which the build already reports. It is one number. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [ ] Rebased on current `main`. (on #134's head and the patch-build follow-ups) - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows here; Linux by the round above) - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Mods that each grow files (HD texture packs) could not be combined: only one
resource size table was used. Hookshot now merges every enabled mod's table
into the game's at start (the button prompts' entries kept) and raises the
entry of every file a mod serves to fit its size (host/mods.c, host/restbl.c,
host/zs.c). #2270's merge of the prompts' entries into the winning mod's table
stays as the fallback when no merged table can be made.

The Insert menu gets a Mods tab (shown only when there are mods): each mod on
or off and its place in the list, kept in hookshot_mods.txt and applied at the
next start (the restart question names them), and the cheats of the enabled
mods, switched at once.

ExeFS patches (IPS, IPS32, IPSwitch .pchtxt) are applied to main's image when
the game is built (nx2/exefs_patches.py, nx2/image.py), so the code is
translated from the patched instructions; a write into the padding after the
code (a code cave) makes it code. exefs_patches.txt in the game folder lists
what a build applied; the Mods tab says when a patch waits for a build.

Atmosphere cheat-code files (separate from the Debug tab's built-in cheats)
run in a cheat VM after dmnt's (host/cheats.c), every presented frame, on
guest memory the game was given; cheats that write the game's code are
listed as not supported.

The list, order and switches, the size table's merge, the patch formats and
the cheat VM follow valentderah/totk-pc-recomp (MIT), whose notice is kept in
host/restbl.h and nx2/exefs_patches.py.

Co-authored-by: Valiantsin Dzerakh <[email protected]>
Co-authored-by: conongnang <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The control bridge's bridge_fill names each MenuTab and checks the count: with the Mods tab
added before Debug, its table needs "mods" there.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The compact bar (added to main after the Mods tab was written) draws the
selected row of the current tab. The Mods tab has no such rows: its lines come
from the host. With the bar asked for on the Mods tab the full page is drawn.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
- hos_mods_file gives prompts.c no table when the merged one is served.
- A mod that is off: its ExeFS files are not counted as waiting for a build
  (the Mods tab's text and the log's line).
- The Mods tab's texts and longshot_mods.txt's header say Longshot.
- A Restart or Quit waiting for its second press is cleared on the Mods tab.
- The merged size table: a mod file whose path is in another case than the
  game's takes the game's entry (looked up only when the mod's own case
  misses the table).
- exefs_patches.py: bytes into a relocated word are left out and the file's
  note says so; the comment on DT_RELR words says what happens.
- The compact bar on the Mods tab dims the game behind, as the full menu.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Co-Authored-By: Claude Fable 5.2 <[email protected]>
The test cuts restart_values out of vk_menu.cpp; with the Mods tab that
function also fills the mods' slot, so the harness declares the slot (none
here), can_mods and the host's mods_changed beside its pad_raw.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
docs(mods): the file contract's document and its example follow the Mods tab, the merged table and ExeFS patches
Some checks failed
PR description / Description follows the template (pull_request_target) Has been cancelled
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
fafc7ab26c
docs/mods.md (from #93) describes the loader as it was: ExeFS left out, one
mod's size table, no Mods tab. With this branch an exefs folder's patches
belong to the build, the size table is merged at a start, and the Mods tab's
longshot_mods.txt can change the order and the switches; without that file
the order is the documented one. The example's check for the old ExeFS log
line now looks for the line that lists the mod with its ExeFS folder.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
The branch of #960 (mods/bl-return), as it is in the stack the switch is built on.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The branch of #961 (mods/exefs-clashes, three commits), as merged after the one before it.

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]>
test(mods): the switch test's fixture has a stand-in for hos_texts_romfs
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
36b9bd51c0
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]>
Author
Contributor

Tested in game: Windows 11, RTX 3090 (driver 610.88), two builds of this change on the base before #134's last rebase (5192b46f), the F1 menu's Mods tab and the game's own menu: Character Select v0.2.1 (a 7.7 KB patch with a code cave) On and Auto Jump (.pchtxt) Off at the build. Off on the Mods tab and a restart: the plain game, three tabs, nothing drawn wrong; On and a restart: the mod back whole; Auto Jump On and a restart: its change works; no build between any of them, the tab only asked for restarts. The log: 'its ExeFS patches are off at this start (built in behind a switch)'. Not built at this head (nothing in this change's own files moved in the rebase). Stacked on #134, #960 and #961 and three more patch-build branches, so the diff shows those commits too; the last three commits are this change.

Tested in game: Windows 11, RTX 3090 (driver 610.88), two builds of this change on the base before #134's last rebase (5192b46f), the F1 menu's Mods tab and the game's own menu: Character Select v0.2.1 (a 7.7 KB patch with a code cave) On and Auto Jump (.pchtxt) Off at the build. Off on the Mods tab and a restart: the plain game, three tabs, nothing drawn wrong; On and a restart: the mod back whole; Auto Jump On and a restart: its change works; no build between any of them, the tab only asked for restarts. The log: 'its ExeFS patches are off at this start (built in behind a switch)'. Not built at this head (nothing in this change's own files moved in the rebase). Stacked on #134, #960 and #961 and three more patch-build branches, so the diff shows those commits too; the last three commits are this change.
snaildev99 force-pushed mods/patch-switch-stack from 36b9bd51c0
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
to 0ec18e14c7
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 7s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
2026-11-16 04:27:34 +00:00
Compare
Author
Contributor

Moved onto #134's new head fb2a419c (rebased onto main @ e4d035e9; the Mods tab's functions are API version 25 there, after main's audio outputs): head 0ec18e14. No conflict, no change in this branch's own files; its tests pass at this head. Not built or played at it.

Moved onto #134's new head fb2a419c (rebased onto main @ e4d035e9; the Mods tab's functions are API version 25 there, after main's audio outputs): head 0ec18e14. No conflict, no change in this branch's own files; its tests pass at this head. Not built or played at it.
snaildev99 force-pushed mods/patch-switch-stack from 0ec18e14c7
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 7s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
to 04bd8dc670
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 7s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
2026-11-16 10:11:35 +00:00
Compare
Author
Contributor

Moved onto #134's new head 3fbc327a (the list of mods is mods.json there now: #134 (comment)). Head 04bd8dc6.

The same conflicts as #960 and #961 in nx2/exefs_patches.py, and one in nx2/make_game.py (this branch's lift_env call with #134's collect(..., user=...)). One commit on top: tests/test_mods_switch.py builds host/mods_list.c, has the stand-ins, writes mods.json for its three changes between starts, and has a new check that the build reads the same mods.json into the same order and switches the plan was made from (a mod that is off is listed too); the atmosphere, overlaps and switch build tests write mods.json; tests/test_mods_list.py stubs the three passes that need a game image. tests/test_longshot_ctl.py failed once in the parallel run on a locked temporary file and passes alone (it does not touch the mods).

tests/run_all.py on Windows: nothing fails that #134's head passes. Not built or played at this head; the Linux halves of the changed fixtures were read, not run.

Moved onto #134's new head 3fbc327a (the list of mods is `mods.json` there now: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/134#issuecomment-34804). Head **04bd8dc6**. The same conflicts as #960 and #961 in `nx2/exefs_patches.py`, and one in `nx2/make_game.py` (this branch's `lift_env` call with #134's `collect(..., user=...)`). One commit on top: `tests/test_mods_switch.py` builds `host/mods_list.c`, has the stand-ins, writes `mods.json` for its three changes between starts, and has a new check that the build reads the same `mods.json` into the same order and switches the plan was made from (a mod that is off is listed too); the atmosphere, overlaps and switch build tests write `mods.json`; `tests/test_mods_list.py` stubs the three passes that need a game image. `tests/test_longshot_ctl.py` failed once in the parallel run on a locked temporary file and passes alone (it does not touch the mods). `tests/run_all.py` on Windows: nothing fails that #134's head passes. Not built or played at this head; the Linux halves of the changed fixtures were read, not run.
snaildev99 force-pushed mods/patch-switch-stack from 04bd8dc670
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 7s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
to 934d41ebc6
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 7s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
2026-11-16 11:11:28 +00:00
Compare
Author
Contributor

Moved onto #134's new head 2b52cd1b (#134 was rebased onto main @ 8a4aa282: the Mods tab's functions are API version 26, and the patches' hash is named in the lift's key after main's #22: #134 (comment)). Head 934d41eb.

No conflict. One commit on top, for the lift's key on the new base (tests and one line, no change in behaviour): the switch's plan (which file is of which switch, an off mod taken in or left out) reaches the key through the patches' list, whose hash #134 names; LONGSHOT_PATCH_SWITCH is read only by the plan, so it is listed as changing nothing the lift writes by itself. tests/test_exefs_lift_key.py shows it through make_game.lift_key: =0 against unset, an off mod joining or leaving the plan and a changed byte change the key; a renamed mod, and the variable alone with the same list, do not.

A reviewer note this brought up (as it was before the move, not new): once switches exist, the key also holds whether each switched mod is On, because a function more than two mods touch is built with the extra ones in their current state. So switching at a start needs no build, as played, but the next build after a switch translates the game again where it could keep the translation. Narrowing that to the mods that are built in for good is a small follow-up; say if you want it in this pull request.

tests/run_all.py on Windows: nothing fails that #134's head passes. Not built or played at this head.

Moved onto #134's new head 2b52cd1b (#134 was rebased onto main @ 8a4aa282: the Mods tab's functions are API version 26, and the patches' hash is named in the lift's key after main's #22: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/134#issuecomment-35102). Head **934d41eb**. No conflict. One commit on top, for the lift's key on the new base (tests and one line, no change in behaviour): the switch's plan (which file is of which switch, an off mod taken in or left out) reaches the key through the patches' list, whose hash #134 names; `LONGSHOT_PATCH_SWITCH` is read only by the plan, so it is listed as changing nothing the lift writes by itself. `tests/test_exefs_lift_key.py` shows it through `make_game.lift_key`: `=0` against unset, an off mod joining or leaving the plan and a changed byte change the key; a renamed mod, and the variable alone with the same list, do not. **A reviewer note this brought up** (as it was before the move, not new): once switches exist, the key also holds whether each switched mod is On, because a function more than two mods touch is built with the extra ones in their current state. So switching at a start needs no build, as played, but the next build after a switch translates the game again where it could keep the translation. Narrowing that to the mods that are built in for good is a small follow-up; say if you want it in this pull request. `tests/run_all.py` on Windows: nothing fails that #134's head passes. Not built or played at this head.
snaildev99 force-pushed mods/patch-switch-stack from 934d41ebc6
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 7s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
to d25f2625ff
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 7s
2026-11-16 19:47:42 +00:00
Compare
Author
Contributor

Moved onto #134's new head c5cead8d (#134 was rebased onto main @ ac778751 and brings main's new players' mods guide in line with it: #134 (comment)). Head d25f2625.

One conflict, in nx2/lift.py: main's lift now passes its coverage report to chunks.write to run beside the emit's processes (#1128 and the commit before it); that argument and this branch's line that writes a64_switch.c after the emit are both kept. Read against main's new emit in new processes (the Windows path): the other versions of a switched function are made in the lift's own process before the write, the picking line is added in that process as each function comes back, and the FPX shapes of the other versions still reach a64_fpx.h through the header function this branch wraps. That path is not covered by a game-free test here (it starts at 4,000 functions, and tests/test_spawn_emit.py fails on main on this PC), so it wants a real Windows build before this is taken.

One commit on top: the players' guide (docs/using-mods.md, main's #1210) says that a mod whose patches a build took in is switched at a start without a build.

Nothing fails in tests/run_all.py on Windows that #134's head passes. Not built or played at this head.

Moved onto #134's new head c5cead8d (#134 was rebased onto main @ ac778751 and brings main's new players' mods guide in line with it: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/134#issuecomment-37590). Head **d25f2625**. One conflict, in `nx2/lift.py`: main's lift now passes its coverage report to `chunks.write` to run beside the emit's processes (#1128 and the commit before it); that argument and this branch's line that writes `a64_switch.c` after the emit are both kept. Read against main's new emit in new processes (the Windows path): the other versions of a switched function are made in the lift's own process before the write, the picking line is added in that process as each function comes back, and the FPX shapes of the other versions still reach `a64_fpx.h` through the header function this branch wraps. That path is **not covered by a game-free test here** (it starts at 4,000 functions, and `tests/test_spawn_emit.py` fails on main on this PC), so it wants a real Windows build before this is taken. One commit on top: the players' guide (`docs/using-mods.md`, main's #1210) says that a mod whose patches a build took in is switched at a start without a build. Nothing fails in `tests/run_all.py` on Windows that #134's head passes. Not built or played at this head.
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 7s
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'mods/patch-switch-stack:snaildev99-mods/patch-switch-stack'
git switch 'snaildev99-mods/patch-switch-stack'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!1036
No description provided.