Feedback on the Modding API Spec from the code mod work (#134 and its stack) #1097
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot#1097
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What this is
Feedback on the Modding API Spec (as of its 2026-11-16 revision with section 5.5), asked for by its author. It is only about the part this contributor's work touches: mods made for a console or an emulator, loaded as they are (5.4, 5.5, 6.1, 8.4, and the unverified list in 19). Nothing here is about the script API, the UI toolkit or the portal. Every point comes from something built and run in the game on #134 and the pull requests stacked on it; where it is only read or reasoned, it says so.
1. Section 5.5, "Not loaded: a whole replacement main, subsdk":
subsdkcan be loaded, and is a different case frommainThe spec marks this line as an assumption. A replaced
mainis a different game executable, and the reason given holds for it. A mod'ssubsdk*is not a replacement: it is one more module beside the game's, and the lift takes it like the game's own modules.exefs/subsdk*in with the game: laid out after the game's last module (no game address moves), relocated and bound as the game's modules are, translated, its start routine called after theirs. The Always-On Rupee Counter (a module plus an.ipswhose stubs call into it) plays.mods/modules-stackon the fork runs the start-up once at build time in a processor emulator against the image, takes the bytes it wrote as it takes a patch file's, and leaves the start-up out of the game. Ragdoll Button plays that way. An independent review went through it for what a hostile module can do to the build (time and memory bounds, user mode in the emulator, refusals named).Suggested change: split the line. A whole
main(andmain.npdm): not loaded, as written.subsdk*: the unsafe tier, the same warning and the same rebuild as ExeFS patches, with the Mods tab saying per module "built in", "waits for a build" or "left out, and why" (#940 has the note for the case where it is not loaded at all).2. Section 8.4, switching a code mod: there is a half state between "switched" and "rebuilt", and it can be closed
A mod with patches has files that follow the switch at the next start and code that follows it at the next build. In between the game runs half a mod. Both directions were seen in the game: Off after a build left the code in and drew a menu without its layout; On before a build served the files and the mod's menu did nothing. A tester raised it on #134.
exefs/is off when found and warns first. That fits: the warning gates whether the build takes the mod's code at all; once it has, the switch is free.Suggested change to 8.4: "Enabling or disabling one offers Rebuild for mods" becomes: a code mod the last build took is switched at the next start; one it did not take (new, edited, or never accepted) is held back whole, files included, until Rebuild for mods. Two settings are yours (they are one constant each in #1036): whether the build takes the code of mods that are Off (so they can be switched on later) or only those On; and how many mods changing one function are switchable separately (each combination is a version: two mods, four versions; the cap is two, the rest fall back to a build).
3. Section 8.4, "Two mods writing the same bytes ... neither is applied until the player picks one"
Two things from real mods:
main+0x3C46700, inside the range a fourth mod's code occupies. Picking one does not help the player who wants both, and order cannot fix it either. The fix that would is on the format's side: a mod declares how much space it needs and the build places it (for.ipsthat needs relocating the mod's branches into its cave, which the build can do for direct branches, since it knows what the patch wrote). Not built; raised here because the spec is where such a rule would live.4. Section 8.4, "A patch must not break the engine"
Checkable today only for the hooks that have addresses (
nx2/oot_wide.py,oot_fov.py,oot_jitter.py): a branch for that exists (a note when a patch writes there, the hook then left out). The roughly forty text patches ofnx2/oot_patches.pyhave no address list, so a mod patching one of those functions is not detected, and with #1036 the engine's edit and the mod's version have to be kept apart by hand (it is, with a test). Step 1's site table makes this rule enforceable; until then the spec's sentence promises more than the build can know.5. A rule the spec lacks: hooks written for a console that return with a branch
Many mods enter their hook with
blwritten over a game instruction and go back withb <the next instruction>, because their own calls used up the link register. On a console that branch is a return. Lifted,blis a C call and theba goto into the rest of the caller, inside the callee: the game crashes a few calls later. It took down a real mod. #960 rewrites that branch as a return before the lift, only where the routine was all written by the patch and is entered from that one call; otherwise it leaves it and says so in the file's note. Worth one bullet in 8.4, since it is the first thing an emulator mod's author hits here.6. Section 6.1, "Resource size table: never shipped. Computed from the final merged files", and section 19's "the size rule per file type"
What the merge of #134 and #942 learned, all on this game:
host/restbl.c. For parameter files (BYML) the entry follows the number of list elements: fits over 5,772 files of two types give a constant, about one entry byte a file byte, and 60 to 290 bytes per element. Growing an entry in proportion to the file was not enough in the game (a load failed on a null object); 8 entry bytes per byte grown is, at the price of about twice the heap such a file needs.7. Section 6.1, archives by member path, and section 19's "the game loads a pack written by a host tool"
8. Section 11.7 and section 19, "the game's UI layout format"
Mapped, for what a mod needs: a mod on this stack adds its own screen to the game's menu with its own layouts, panes, pane animations and texts, written by a tool, not edited by hand. Known pitfalls: the layout archive stores every layout four times and all four must change; panes must be stored in pre-order; an animation on a pane's alpha does not reach the children of a child pane that has its own. If a write-up would help 11.7, say so and it will be added to the docs.
9. Section 5.4,
mods.json: where the build finds itBuilt on a branch for #134 (the list as
mods.jsonbeside the settings file, unknown keys kept, the old file read once, a file that is not a list never overwritten). One gap the spec does not cover:nx2/make_game.pyknows the game folder, not the user folder, and it must read the same list as the game, or a code mod is built for one order and served in another. The branch lets the build ask, in order,HOS_OPTIONS_FILE, a newmake_game.py --user <folder>, and a one-line note the game leaves in the game folder when the list is elsewhere. If the launcher always passes--user, the note can go. Which do you want?10. Small points
atmosphere/exefs_patches/<name>/*.ips(the files right in the folder, noexefs/). A branch reads that layout too.exefs_patches.txt, which is what that check needs.OOT_variable (Hookshot's main did that): the patches' hash has to be named in it, or a changed patch silently keeps the old translation.Where each thing is
mods/modules-stackAddendum: a census of real code mods, and point 9 is on #134
Since this was posted, nine public code mods for this game were put through the stack's own build-time checks (game-free; three of them have been played on the stack, the rest not). What that adds to the points above:
subsdk). Six of the nine ship asubsdk*module: four are a module plus a small.ipswhose stubs call into it, two install their hooks at start-up (exlaunch). Three are patches only. None replacesmain, none is a plugin loader, none uses the network. So "subsdk: not loaded" would leave out two thirds of the code mods that exist for this game today. None of the nine holds an instruction the translator lacks.nn::oe::RestartProgramonly logs. A mod that restarts the game after a choice works if the player restarts by hand.Point 9 is done on #134: the list is
mods.jsonat head3fbc327a, reviewed independently, its first three commits played (comment there). The question for you stands: the one-line note the game leaves for the build, or the launcher always passing--user.