WIP: feat(mods): a mod's code module (exefs/subsdk*) is built in with the game #984

Draft
snaildev99 wants to merge 23 commits from snaildev99/Longshot:mods/code-modules into main
Contributor

Type: feat · Risk: medium · Tested on: Windows 11, RTX 3090 (in the game, and the game-free checks) · Needs: Linux, any GPU: one build with a module mod

Why

Some mods ship compiled code of their own beside a patch file (exefs/subsdk*). Longshot ignores that file, so such a
mod is listed and does nothing: its patch's stubs find their pointer empty and run the game's own code. Three public
HUD mods are of this kind (Always-On Rupee Counter, HUD of Time, Edge-to-Edge Ultrawide HUD). This builds such a
module in with the game, as the patch files of WIP #134 are, which this depends on.

What changed

A mod's exefs/subsdk0..9 is loaded after the game's own modules when the game is built, translated with it and
started before the game. The running game answers svcQueryMemory module by module, which is how such a module
finds the game's main. Modules that install hooks by writing code while the game runs are left out with a note (a follow-up on top of this builds those in too; it is not part of this PR). A module the image builder cannot place (a relocation kind it does not know, an offset outside the module, headers that disagree about its size, a header asking for more than 64 MB) is left out with a note; it never stops the build.

  • build: nx2/exefs_modules.py (new): collect (the mods' order and switches, as the patches), classify (system
    calls against host/hos_svc.c's, imports against the game's exports and host/), load, entries;
    nx2/image.py loads the modules after sdk and adds the entries; nx2/make_game.py keys the lift on them and lists
    them in exefs_patches.txt; nx2/chunks.py with_mod_modules.
  • host: host/hos_svc.c image_region, query_memory; nx2/standalone.py regions, region_lines.
  • docs: README (Mods), docs/mods.md, docs/development.md.

Measurements

Verdict: no cost measured in the game (a module of 4 KB; the frame rate was not compared). The lift's discovery with three real module mods: +68 functions
(54 of the modules, 4 stubs, 10 entries), +10,574 of 17.6 million instructions, no game function lost, no game
address moved.

Flags and settings

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_QUERY_MEMORY_OLD the image as one region for svcQueryMemory (always so) off on: a module mod does not find the game untested in the game off: for A/B only

Testing

Tested:

  • In the game, Windows 11, RTX 3090 (driver 610.88), three builds of #134's head with this branch and its follow-ups merged in (this branch alone was not built): the Always-On Rupee Counter's exefs/subsdk7 and its .ips. The build's log says exefs: module Rupee Counter/exefs/subsdk7 (4188 bytes) and that it is built in; the game's log has the module's own [rupee] module ready at the start and its lines all through play; the rupee counter stays on screen in the field, which is what the mod does. Three starts, a child save, no stop.
  • tests/run_all.py on Windows: 541 passed, 24 failed, 81 skipped; the same 24 fail on #134's head in the same run (539 passed there). tests/test_exefs_modules.py and tests/test_query_memory.py (new).
  • The three mods above and one hooking module through collect and through the lift's discovery on the real game.
  • A second reader went through the branch for what a broken or hostile module file can do to the build; its points (a relocation the builder does not know, an offset outside the module, sizes from the header, a line break in a symbol's name reaching the list) are answered here with tests.

Not tested: Linux; HUD of Time and Edge-to-Edge in the game (they pass the game-free checks as the Rupee Counter does); this branch built without its follow-ups.

Must be tested:

  • Linux, any GPU: build with the Always-On Rupee Counter (its exefs folder as a mod), start the game, expecting [rupee] module ready in the log and the rupee counter staying on screen (by hand).

Risks

What could break: SDK code that asks svcQueryMemory about the image now gets a module's segment, not the whole
image (the console's answer); a constant a module adds to an address that is a code address of main without being a
jump target cuts one game function in two at that place (the first part tail-calls the second: correct, a call
slower there).

Turning it off: HOS_QUERY_MEMORY_OLD=1 for the host's answer; without a module mod the build is byte for byte
as before apart from the region table in gen/hos_image.c.

Compatibility: the first build after updating translates the game again (the translator's files changed), as
after any change to the lift; after that a new, changed or switched module mod translates it again, as a patch file does.

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)
  • 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.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows here; Linux by the test above)
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** medium · **Tested on:** Windows 11, RTX 3090 (in the game, and the game-free checks) · **Needs:** Linux, any GPU: one build with a module mod ## Why Some mods ship compiled code of their own beside a patch file (`exefs/subsdk*`). Longshot ignores that file, so such a mod is listed and does nothing: its patch's stubs find their pointer empty and run the game's own code. Three public HUD mods are of this kind (Always-On Rupee Counter, HUD of Time, Edge-to-Edge Ultrawide HUD). This builds such a module in with the game, as the patch files of WIP #134 are, which this depends on. ## What changed A mod's `exefs/subsdk0..9` is loaded after the game's own modules when the game is built, translated with it and started before the game. The running game answers `svcQueryMemory` module by module, which is how such a module finds the game's main. Modules that install hooks by writing code while the game runs are left out with a note (a follow-up on top of this builds those in too; it is not part of this PR). A module the image builder cannot place (a relocation kind it does not know, an offset outside the module, headers that disagree about its size, a header asking for more than 64 MB) is left out with a note; it never stops the build. - build: `nx2/exefs_modules.py` (new): `collect` (the mods' order and switches, as the patches), `classify` (system calls against `host/hos_svc.c`'s, imports against the game's exports and host/), `load`, `entries`; `nx2/image.py` loads the modules after sdk and adds the entries; `nx2/make_game.py` keys the lift on them and lists them in `exefs_patches.txt`; `nx2/chunks.py` `with_mod_modules`. - host: `host/hos_svc.c` `image_region`, `query_memory`; `nx2/standalone.py` `regions`, `region_lines`. - docs: README (Mods), `docs/mods.md`, `docs/development.md`. ## Measurements **Verdict:** no cost measured in the game (a module of 4 KB; the frame rate was not compared). The lift's discovery with three real module mods: +68 functions (54 of the modules, 4 stubs, 10 entries), +10,574 of 17.6 million instructions, no game function lost, no game address moved. ### Flags and settings | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_QUERY_MEMORY_OLD` | the image as one region for `svcQueryMemory` | (always so) | off | on: a module mod does not find the game | untested in the game | off: for A/B only | ## Testing **Tested:** - In the game, Windows 11, RTX 3090 (driver 610.88), three builds of #134's head with this branch and its follow-ups merged in (this branch alone was not built): the Always-On Rupee Counter's `exefs/subsdk7` and its `.ips`. The build's log says `exefs: module Rupee Counter/exefs/subsdk7 (4188 bytes)` and that it is built in; the game's log has the module's own `[rupee] module ready` at the start and its lines all through play; the rupee counter stays on screen in the field, which is what the mod does. Three starts, a child save, no stop. - `tests/run_all.py` on Windows: 541 passed, 24 failed, 81 skipped; the same 24 fail on #134's head in the same run (539 passed there). `tests/test_exefs_modules.py` and `tests/test_query_memory.py` (new). - The three mods above and one hooking module through `collect` and through the lift's discovery on the real game. - A second reader went through the branch for what a broken or hostile module file can do to the build; its points (a relocation the builder does not know, an offset outside the module, sizes from the header, a line break in a symbol's name reaching the list) are answered here with tests. **Not tested:** Linux; HUD of Time and Edge-to-Edge in the game (they pass the game-free checks as the Rupee Counter does); this branch built without its follow-ups. **Must be tested:** - Linux, any GPU: build with the Always-On Rupee Counter (its `exefs` folder as a mod), start the game, expecting `[rupee] module ready` in the log and the rupee counter staying on screen (by hand). ## Risks **What could break:** SDK code that asks `svcQueryMemory` about the image now gets a module's segment, not the whole image (the console's answer); a constant a module adds to an address that is a code address of main without being a jump target cuts one game function in two at that place (the first part tail-calls the second: correct, a call slower there). **Turning it off:** `HOS_QUERY_MEMORY_OLD=1` for the host's answer; without a module mod the build is byte for byte as before apart from the region table in `gen/hos_image.c`. **Compatibility:** the first build after updating translates the game again (the translator's files changed), as after any change to the lift; after that a new, changed or switched module mod translates it again, as a patch file does. ## 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) - [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. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Windows here; Linux by the test above) - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [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) Successful in 4s
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
5192b46f4b
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 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]>
fix(mods): a module the image builder cannot place is left out, not a stopped build; constants only where they are added
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
f929331c7d
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]>
Author
Contributor

Tested in game: Windows 11, RTX 3090 (driver 610.88), builds of #134's head 5192b46f with this branch and its follow-ups merged in, the Always-On Rupee Counter's exefs folder (a subsdk7 module and its .ips) as a mod, a child save in the field: the build's log says the module is built in, the game's log has the module's own '[rupee] module ready' and its lines all through play, and the rupee counter stays on screen, which is what the mod does; three starts, no stop. This branch is stacked on #134 (it depends on it), so the diff shows #134's commits too until that merges.

Tested in game: Windows 11, RTX 3090 (driver 610.88), builds of #134's head 5192b46f with this branch and its follow-ups merged in, the Always-On Rupee Counter's exefs folder (a subsdk7 module and its .ips) as a mod, a child save in the field: the build's log says the module is built in, the game's log has the module's own '[rupee] module ready' and its lines all through play, and the rupee counter stays on screen, which is what the mod does; three starts, no stop. This branch is stacked on #134 (it depends on it), so the diff shows #134's commits too until that merges.
snaildev99 force-pushed mods/code-modules from f929331c7d
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 4886c09230
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
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 02:50:43 +00:00
Compare
Author
Contributor

Moved onto #134's new head fafc7ab2 (it was rebased onto main @ 343a1dfa): head 4886c092. No conflict, no change in this branch's own files; its tests pass. Not built or played at this head.

Moved onto #134's new head fafc7ab2 (it was rebased onto main @ 343a1dfa): head 4886c092. No conflict, no change in this branch's own files; its tests pass. Not built or played at this head.
snaildev99 force-pushed mods/code-modules from 4886c09230
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
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 5c9361de93
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 10s
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:28 +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 5c9361de. 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 5c9361de. No conflict, no change in this branch's own files; its tests pass at this head. Not built or played at it.
Author
Contributor

The rest of the module work is up as branches on the fork, not as pull requests (they stack on this one):

  • mods/module-startup (head 8db1fa8d, on this PR's head): modules that install their hooks at start-up, exlaunch style. The build runs the module's start-up once in a processor emulator against the image, takes what it wrote as it takes a patch file's bytes, and leaves the start-up out of the game. With it Ragdoll Button plays (Windows 11, RTX 3090, on an earlier base): its seven hooks, its settings file on the SD card folder. A second reader went through it for what a broken or hostile module can do to the build; its eleven findings are answered there with tests (bounds on the start-up's time and memory, user mode in the emulator, a hook into a function the host replaces refused by name).
  • mods/modules-stack (head 2d846a5b): the same, plus #940's note and a commit that makes the Mods tab and the log say what became of a module (built in, waiting for a build, left out and why).

Both: the mod checks pass and tests/run_all.py matches #134's head here (568 passed, 21 failed, the same twenty-one). Not built or played at these heads.

The rest of the module work is up as branches on the fork, not as pull requests (they stack on this one): - `mods/module-startup` (head 8db1fa8d, on this PR's head): modules that install their hooks at start-up, exlaunch style. The build runs the module's start-up once in a processor emulator against the image, takes what it wrote as it takes a patch file's bytes, and leaves the start-up out of the game. With it Ragdoll Button plays (Windows 11, RTX 3090, on an earlier base): its seven hooks, its settings file on the SD card folder. A second reader went through it for what a broken or hostile module can do to the build; its eleven findings are answered there with tests (bounds on the start-up's time and memory, user mode in the emulator, a hook into a function the host replaces refused by name). - `mods/modules-stack` (head 2d846a5b): the same, plus #940's note and a commit that makes the Mods tab and the log say what became of a module (built in, waiting for a build, left out and why). Both: the mod checks pass and `tests/run_all.py` matches #134's head here (568 passed, 21 failed, the same twenty-one). Not built or played at these heads.
snaildev99 force-pushed mods/code-modules from 5c9361de93
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 10s
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 06a8fef992
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 10s
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:13:03 +00:00
Compare
Author
Contributor

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

No conflict; the commits are unchanged. One commit on top, and it is a fix, not only a test change: nx2/exefs_modules.py still handed the old longshot_mods.txt to exefs_patches.ordered, which takes mods.json since #134's change, so the modules would have been read as all on, by name, while the patch files followed the list. It now finds the list exactly as exefs_patches.collect does (list_file, the old file once, HOS_OPTIONS_FILE, make_game.py --user passed down). tests/test_exefs_modules.py fails if the two ever give ordered different files, with and without a user folder.

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 **06a8fef9**. No conflict; the commits are unchanged. One commit on top, and it is a **fix, not only a test change**: `nx2/exefs_modules.py` still handed the old `longshot_mods.txt` to `exefs_patches.ordered`, which takes `mods.json` since #134's change, so the modules would have been read as all on, by name, while the patch files followed the list. It now finds the list exactly as `exefs_patches.collect` does (`list_file`, the old file once, `HOS_OPTIONS_FILE`, `make_game.py --user` passed down). `tests/test_exefs_modules.py` fails if the two ever give `ordered` different files, with and without a user folder. `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/code-modules from 06a8fef992
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 10s
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 c498d3b946
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 8s
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:19:42 +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 c498d3b9.

No conflict. One commit on top, and it is a fix the new base forces: main's lift key (#22) hashes only named variables, and this branch gives the lift its modules through OOT_EXEFS_MODULES with their hash in OOT_EXEFS_MODULES_SHA1, which was in the key only because every OOT_ variable was. On the new base a build after a module was added, changed or removed would have kept the old translation, with no error. The hash is in LIFT_ENV_NAMES now and the JSON's path in LIFT_PATH_ENV; tests/test_lift_cache.py has both cases, and the hash's case fails without the change (run that way first). Main's own check of the lift's variables does not see a hash that is only set, so nothing else would have caught it.

The branches on top of this one (mods/module-startup, mods/modules-stack, mods/module-gaps on the fork) are moved too; a start-up recording reaches the key through the same hash, and tests/test_exefs_startup.py checks that link now.

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 **c498d3b9**. No conflict. One commit on top, and it is a **fix the new base forces**: main's lift key (#22) hashes only named variables, and this branch gives the lift its modules through `OOT_EXEFS_MODULES` with their hash in `OOT_EXEFS_MODULES_SHA1`, which was in the key only because every `OOT_` variable was. On the new base a build after a module was added, changed or removed would have kept the old translation, with no error. The hash is in `LIFT_ENV_NAMES` now and the JSON's path in `LIFT_PATH_ENV`; `tests/test_lift_cache.py` has both cases, and the hash's case fails without the change (run that way first). Main's own check of the lift's variables does not see a hash that is only set, so nothing else would have caught it. The branches on top of this one (`mods/module-startup`, `mods/modules-stack`, `mods/module-gaps` on the fork) are moved too; a start-up recording reaches the key through the same hash, and `tests/test_exefs_startup.py` checks that link now. `tests/run_all.py` on Windows: nothing fails that #134's head passes. Not built or played at this head.
snaildev99 force-pushed mods/code-modules from c498d3b946
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 8s
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 02e563a2cd
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 6s
2026-11-16 19:47:46 +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 02e563a2.

No conflict. One commit on top: the players' guide (docs/using-mods.md, main's #1210) says under "What doesn't work" that a mod's code module is built in at a build like a code patch, and which kind is left out. (The branches on the fork above this one are moved too; mods/module-startup had one conflict in nx2/lift.py, where main's lift now writes its coverage report while the emit's processes work: the module check that reads the functions runs inside that report.)

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 **02e563a2**. No conflict. One commit on top: the players' guide (`docs/using-mods.md`, main's #1210) says under "What doesn't work" that a mod's code module is built in at a build like a code patch, and which kind is left out. (The branches on the fork above this one are moved too; `mods/module-startup` had one conflict in `nx2/lift.py`, where main's lift now writes its coverage report while the emit's processes work: the module check that reads the functions runs inside that report.) Nothing fails in `tests/run_all.py` on Windows that #134's head passes. Not built or played at this head.
Author
Contributor

Played at this head with the branches above it (mods/module-gaps on the fork = #134 @ c5cead8d, this pull request @ 02e563a2, mods/module-startup, mods/modules-stack and the import slot fix): Windows 11, RTX 3090, a full build in 8 min 22 s, 0 failed compiles, on main's new lift (the emit in 16 new processes: the modules' translator forms and jump tables reached the new processes). Five mods with a code module and two with patches only, in one game.

Mod's module Kind In the game
a rupee counter (subsdk7, 4 KB) static, reached through a patch's stubs works, as before
a clock for the HUD (subsdk9, 25 KB) static works (first time played here)
a ragdoll button (subsdk7, exlaunch) hooks set at start-up, run at the build works, as before
a save profiles mod (subsdk9) points 20 of the game's import slots at its own code at start-up works with the fix on the fork (mods/module-gaps): its file, save and controller calls all go through the mod, profiles get their own save folders, the old save is untouched. Without the fix it was built in and did nothing
a first person camera (subsdk6, exlaunch) hooks at start-up and one more when first person is switched on stops the game at that moment: FATAL: svc 0x74 not implemented, from the module, mapping main's code to patch a function. Everything before that works

Two modules share the file name subsdk7 and two subsdk9; both pairs load.

What the round found, for this stack:

  1. A real mod that hooks later. The first person mod installs a hook the first time its feature is used, not at start-up, so a recompiled game cannot have it. Until now no mod at hand did this (the census said so; it was wrong about this one). Two things would make it kinder, neither built: the build's note can say that a module still holds the calls that map the game's code after its start-up (svc 0x74 / 0x75) and so may stop the game; and the host could refuse that call with an error instead of stopping, so the mod's feature fails and the game goes on.
  2. A module that is switched Off goes on running (its code is built in until the next build). The tab says so, but for a mod that is nothing but a module the switch then visibly does nothing: the player switched the save profiles mod Off and stayed in its profile. #1036's switch covers patch files; a module's start routine could be skipped by the same byte. Not built.
  3. Main's reworded texts (#604) and a module that edits texts as the game reads them. The save profiles mod writes its menu row's label into the text archive when the game opens it. Longshot serves its own copy of that archive from texts/ (the microphone hint), and the mod does not recognise it: the label shows as a missing message. With HOS_TEXTS=0 the label is right. So a mod that replaces the text file wins over the rewording, and a mod that patches it in memory loses to it. The row's value text is still missing with HOS_TEXTS=0; the mod's own log says it does not know that text's format, and whether that is the same on an emulator is not checked.
  4. nn::oe::RestartProgram returns without restarting, as known: the mod says so in its log and the change applies at the next start by hand.
**Played at this head** with the branches above it (`mods/module-gaps` on the fork = #134 @ c5cead8d, this pull request @ 02e563a2, `mods/module-startup`, `mods/modules-stack` and the import slot fix): Windows 11, RTX 3090, a full build in 8 min 22 s, 0 failed compiles, on main's new lift (the emit in 16 new processes: the modules' translator forms and jump tables reached the new processes). Five mods with a code module and two with patches only, in one game. | Mod's module | Kind | In the game | |---|---|---| | a rupee counter (`subsdk7`, 4 KB) | static, reached through a patch's stubs | works, as before | | a clock for the HUD (`subsdk9`, 25 KB) | static | works (first time played here) | | a ragdoll button (`subsdk7`, exlaunch) | hooks set at start-up, run at the build | works, as before | | a save profiles mod (`subsdk9`) | points 20 of the game's import slots at its own code at start-up | **works with the fix on the fork** (`mods/module-gaps`): its file, save and controller calls all go through the mod, profiles get their own save folders, the old save is untouched. Without the fix it was built in and did nothing | | a first person camera (`subsdk6`, exlaunch) | hooks at start-up **and one more when first person is switched on** | **stops the game** at that moment: `FATAL: svc 0x74 not implemented`, from the module, mapping `main`'s code to patch a function. Everything before that works | Two modules share the file name `subsdk7` and two `subsdk9`; both pairs load. **What the round found, for this stack:** 1. **A real mod that hooks later.** The first person mod installs a hook the first time its feature is used, not at start-up, so a recompiled game cannot have it. Until now no mod at hand did this (the census said so; it was wrong about this one). Two things would make it kinder, neither built: the build's note can say that a module still holds the calls that map the game's code after its start-up (`svc 0x74` / `0x75`) and so may stop the game; and the host could refuse that call with an error instead of stopping, so the mod's feature fails and the game goes on. 2. **A module that is switched Off goes on running** (its code is built in until the next build). The tab says so, but for a mod that is nothing but a module the switch then visibly does nothing: the player switched the save profiles mod Off and stayed in its profile. #1036's switch covers patch files; a module's start routine could be skipped by the same byte. Not built. 3. **Main's reworded texts (#604) and a module that edits texts as the game reads them.** The save profiles mod writes its menu row's label into the text archive when the game opens it. Longshot serves its own copy of that archive from `texts/` (the microphone hint), and the mod does not recognise it: the label shows as a missing message. With `HOS_TEXTS=0` the label is right. So a mod that replaces the text file wins over the rewording, and a mod that patches it in memory loses to it. The row's value text is still missing with `HOS_TEXTS=0`; the mod's own log says it does not know that text's format, and whether that is the same on an emulator is not checked. 4. `nn::oe::RestartProgram` returns without restarting, as known: the mod says so in its log and the change applies at the next start by hand.
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 6s
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'mods/code-modules:snaildev99-mods/code-modules'
git switch 'snaildev99-mods/code-modules'
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!984
No description provided.