Table of contents
- Modding API Plan
- 1. Where things stand
- 2. Tracks
- 3. Questions to answer first (spikes)
- 4. Milestones
- M0. Emulator mods land (track A, spec step 0)
- M1. The gates (track B, section 16)
- M2. Hook compiler (track B, spec step 1)
- M3. Game services and frame phases (track B, spec step 2)
- M4. First scripts (track D, spec step 3)
- M5. File layers (track C, spec step 4)
- M6. Save profiles (track B and E, spec step 5)
- M7. Change and connect (track D, spec step 6)
- M8. Process sandbox (track F, spec step 7)
- M9. Session API and voice (track F, spec step 8)
- M10. Graphics (track D, spec step 9)
- M11. Unsafe tier for packaged mods (track A, spec step 10)
- M12. Portal (track E, spec step 11)
- After: API 1.0
- 5. What waits for what
- 6. Decisions needed
- 7. Rules for every piece
- 8. Where this plan differs from the spec
Modding API Plan
Status: draft plan (2026-11-16) for the Modding API Spec, revision 3. Nobody is assigned to anything here and nothing is scheduled. The spec says what to build; this page says in what order, in what pieces, what has to be answered first, and what "done" means for each piece. Section numbers are the spec's.
Contents: 1 Where things stand · 2 Tracks · 3 Questions to answer first · 4 Milestones · 5 What waits for what · 6 Decisions needed · 7 Rules for every piece · 8 Where this plan differs from the spec
1. Where things stand
Checked on the forge on 2026-11-16.
| Part | State |
|---|---|
| Emulator mods and code mods (5.5, 8.4, 8.5) | In flight, by snaildev99. #134 is open and out of WIP. Stacked on it, all open and WIP: #305, #940, #942, #960, #961, #984, #1036, #1089. The branch mods/modules-stack (modules that hook the game themselves) has no pull request |
| Co-op (9.7) | #68 is open, early. The session API waits for it |
| The six core pieces (section 4) | Not started. On main there is host/mods.c (whole-file replacement), host/control.c (the bridge) and nx2/oot_patches.py (the text patches). There is no nx2/hooks.py, no host/game/, and host/restbl.c exists only on #134's branch |
| Script runtime, API, UI toolkit, dev tools | Not started. third_party/ has no QuickJS and no zip reader |
| Process sandbox, network broker | Not started. Owner: HumanBean (decided 2026-11-16). An AppContainer exists for the test farm only (#544, merged) |
| Launcher mod manager, portal, index repository | Not started |
2. Tracks
The spec's order of work (section 17) is one list. The work splits into six tracks that mostly do not wait for each other, so several people can move at once.
| Track | What | Spec steps | Starts when |
|---|---|---|---|
| A. Emulator and code mods | Land the stack; finish what the spec decided on top of it | 0, part of 10 | Now |
| B. Core | Hook compiler, game services and frame phases, save profiles, settings and menu registry | 1, 2, 5, part of 9 | Now, after the first spikes |
| C. Files | The layered file system and typed patches | 4 | When #134, #942 and #1089 have merged |
| D. Scripts | API schema, runtime, the API's namespaces, UI toolkit, dev tools, graphics | 3, 6, 9 | Schema and tools now; in the game after B's game services |
| E. Launcher and portal | Mods page, profiles, the index, the website | 11 | Mods page now (it only needs mods.json); the portal when a script mod can run |
| F. Sandbox, broker, session | The confined process, the broker, session, voice |
7, 8 | The broker with D's net; the sandbox after spike S7; session after #68 |
3. Questions to answer first (spikes)
Each is a few days, ends in a written answer on the spec (the "Unverified" list shrinks), and needs no merge. They come first because each can change a milestone's design.
| # | Question | From | What the answer changes |
|---|---|---|---|
| S1 | Does the frame have clean serial points, before the jobs start and after they join, also in menus, pause and loading? | Open question 3, 7.4 | Everything in track D: where update fires, and how many hooks can be filters. Do this one first |
| S2 | How much of the item-give path can be found: chests, drops, shops, gifts, scripted events? | Open question 4 | Whether items.checked / items.granted are clean events, so the tracker and the randomizer demos |
| S3 | Can a host thunk in a guest vtable slot hook a virtual method at run time? | Open question 10, 8.1 | The size of the site table: many named hooks would need no site |
| S4 | Does the game load a table a host tool wrote? And does it prefer a loose file over the same path in a pack? | Unverified list | Whether row patches work at all, and how pack members are served (M5) |
| S5 | How does the renderer know which texture an upload is: a content-hash index built locally, or a hook on the texture load? | 6.3 | Texture packs (M10) |
| S6 | QuickJS-ng embedded: size, a per-callback interrupt, a hard heap limit, the cost of an idle runtime, frozen prototypes | 7.2, 7.5, 12.3 | Whether the budgets of 7.5 are enforceable as written (M4) |
| S7 | The game confined on both systems: Landlock and a network restriction on Linux, an AppContainer for players on Windows; what co-op, the Discord status and the updater do inside | 12.2 | The size of M8 and what moves to the broker |
| S8 | Does the emulated start-up capture exlaunch's trampoline memory? Read mods/modules-stack |
8.5 | Whether exlaunch-style mods that call the original function work (M0) |
| S9 | Does Longshot still sync host/ and nx2/ from mkw-recomp? |
Unverified list | Whether the core edits existing files or must stay in new ones (M2, M3) |
| S10 | Which zip reader goes into third_party/ (deflate and stored only), with its provenance |
5.5 | .lsmod and plain .zip mods (M0, M5) |
| S11 | Does linking the Opus encoder work in the build as it is? | 9.7 | Voice (M9) |
4. Milestones
Sizes are relative: S is one pull request, M a handful, L many pull requests over a long time. Each milestone lists its pieces in the order they would be opened, each piece one pull request.
M0. Emulator mods land (track A, spec step 0)
A player drops an emulator mod into the mods folder and it works, with the warning for code.
- Land #134. It already reads and writes
mods.json. - Land the stack in its own order: #305, #940, #942, #960, #961, #984, #1036, #1089.
- What the spec decided and no pull request is known to do yet. Each needs checking against the stack before it
is started:
make_game.py --mods <path to a mods.json>; no mods without it; the build writes its code mods and their order toexefs_patches.txtand the game compares (5.4). S- The launcher passes the code mods of every profile to one build, and the build takes every accepted mod, on or off (decided, 5.4 and 8.4); a second build only where two profiles' code mods cannot share one. M
- The warning of 5.5, shown once per mod and again when its patches change; a mod with code is off when found. S
- A plain
.zipof an emulator mod, and theatmosphere/exefs_patches/<name>/*.ipslayout (needs S10). S - Modules that hook the game themselves: a pull request for
mods/modules-stack, with the five rules of 8.5 (after the warning, a confined process, writes checked as data, bounded, cached by hash) and the answer to S8. M - The Mods tab's three words for a module: "built in", "waits for a build", "left out", with the reason. S
Done when: the nine public code mods of #1097's census each either run or are named with the reason they cannot, and a file-only emulator mod needs no build. Not in M0: placing mods' new code so two mods do not claim the same free space (decided: later, M11), and the check that a patch does not break one of the engine's text patches (needs M2).
M1. The gates (track B, section 16)
The parity gates have to exist before the first refactor, or there is nothing to compare against.
- Gate 1, code parity: the existing comparison (
nx2/test_leaf.py) run with a site table present and empty. S - Gate 3, behaviour parity: a scripted input run on a fixed save through the control bridge, comparing map,
position and changed flags with
main. M - Gate 4, save parity, and gate 5, "nothing started" (no runtime, no merged-file cache, no broker with no mods). S
- Gate 2, speed parity, is the
measureskill as it is.
Done when: the gates pass on main against itself and fail on a deliberately broken build.
M2. Hook compiler (track B, spec step 1)
- The site table format (
game/<build id>/sites.toml), the signature resolver andnx2/hooks.py, with no sites. A site that does not resolve exactly once fails the build. M - One feature converted end to end (text speed is small and serial), its text patch deleted in the same pull request, gates 1 to 3. S
- The rest of the roughly forty sites, one feature per pull request: damage, camera speed, widescreen, FOV, the high-frame-rate fixes. L
- The string matcher deleted. S
- The check of 8.4 switched on: a mod's ExeFS patch that stops a site resolving is refused and named. S
Done when: nx2/oot_patches.py has no exact-text patch left and a no-mods build is inside the 2% band.
Needs: M1, S9. S3 may remove sites from piece 3.
M3. Game services and frame phases (track B, spec step 2)
host/game/with onegame_call()and the flags service; the second flag reader deleted. M- The frame phase scheduler (S1's answer as code), with
frameandupdateand nothing subscribed. M - The Debug tab, the control bridge and the state tap moved onto the services, one per pull request; the try-lock in Link's update deleted. M
- Player, camera, actors and items as services, each when its first user needs it (the Debug tab's "give item" is the item service's first). L, continues through M7
Done when: no host file outside host/game/ holds a guest address for game state.
Needs: M1, S1. Can overlap M2: they touch different files.
M4. First scripts (track D, spec step 3)
A mod that reads the game and draws on the HUD, developed with ordinary tools.
- The API schema and its generator: C bindings,
longshot.d.ts, the reference, the permission table. Starts withlog,game,playerandgame.flagsread-only. No game needed, so it can start now. M - The fake game and
longshot-mod test, generated from the same schema. M - QuickJS-ng in
third_party/with its provenance; one runtime per mod; the language cuts of 7.2 and 12.3; budgets and faults (7.5). Gate 5: none of it starts with no mods. M - The mod loader:
mod.json, the dependency resolver (the launcher uses the same one), permissions and the game-drawn prompt, folder mods and.lsmodpackages with the unpack checks (5.5). M - Events delivered at serial phases; stopping a mod disposes everything it made; hot reload (7.6). M
- The settings half of the registry: declared settings, the generated page in the Mods tab, the engine's own rows moved onto it one tab at a time. L
- The UI channel to the renderer (one generic channel for trees and draw lists, one interface version bump),
then the toolkit: host validation and caps, flex layout and controller focus in the renderer,
Hudfirst, thenWindow, then the settings surface, thenCanvas. L @longshot/api,@longshot/mod-tools(dev,lint,pack), the project template, the dev overlay. M
Done when: three mods exist in a public repository and run: a heart HUD, an item tracker, a speedrun timer.
The tracker needs items read-only, so S2.
Needs: M3 pieces 1 and 2 for anything in the game; S6; the reconciler decision (section 6 below).
M5. File layers (track C, spec step 4)
- The virtual file system behind
host/nn_fs.c, with only the "last layer wins" rule, replacinghost/mods.c's lookup. A refactor: same behaviour, gates 3 and 5. M - The size table computed from the final files, walking pack members, with an emulator mod's own table as a floor, cached by content. Replaces the merge of #134. M
- Pack members by path, applied to every pack that carries the member (on #1089's writer). M
- Typed patches, one type per pull request, each with its own serialiser: parameter keys, text by label, table rows (needs S4), map placements by hash. L
- The merged-file cache by content hash; conflicts named ("both set Octorok's Life") in the Mods tab. M
- Mod-owned ids mapped to free game ids (needs M6 to keep the mapping with the save). M
Done when: a rebalance mod and a translation run with no code, and two mods patching different keys of one file both apply. Needs: M0. Does not need M2 to M4.
M6. Save profiles (track B and E, spec step 5)
- Every save in a profile; vanilla is the profile with no mods; the default profile's files unchanged (gate 4). M
- Profiles in LongshotLauncher: each has its own
mods.json, pinned versions and settings, and names its list to the build. M storagein its three scopes;storage.savecommitted at the game's own save moment, copied and deleted with the slot. M- Co-op's isolated saves moved onto profiles (with #68). S
Done when: a playthrough's mod data survives copy, reload after death, and export.
Needs: M4 for storage.
M7. Change and connect (track D, spec step 6)
- Writes: flags, Link's values, with the deny list and range checks. M
- Data rules:
damageTaken,damageDealt,actorLife,items.rewards, applied in C from frozen tables. The engine's damage scaling becomes the first user. M - The item service's write side:
items.grantwith its saved queue. M actors: live handles, events,spawnwith a cap. Lcontent.patchfrom scripts in a prepare stage. Minput(actions, filter, timed presses) and camera rigs: the free camera, the FOV row and native mouse look become one camera service. Lnet, through the broker process from its first version (see section 8 below). M- Mods together: exports, events, registries, claims, guards (9.8). M
Done when: a chest randomizer in its own profile and an Archipelago client run; the three Ship of Harkinian ports of 18.1 are attempted and what they could not do is written down. Needs: M3 to M6, S2.
M8. Process sandbox (track F, spec step 7)
- The game confined on Linux, then on Windows, read access to the game folder and write access to the user folder only. L
- Everything that used the network moved to the broker: co-op, the Discord status; the updater checked. M
Done when: vanilla runs confined on both systems and gate 5 still holds. Owner: HumanBean. Needs: S7. The portal does not wait for it (decided, 12.2), so until it lands an interpreter bug in a published script mod reaches the player's files.
M9. Session API and voice (track F, spec step 8)
- #68's game access moved onto the game services, its sockets into the broker. M
longshot.session: room, peers, typed channels, shared state with engine-owned merges, room rules. L- The room's mod comparison and the fingerprint of the merged data (9.8). M
- Voice in the engine (capture, encode, jitter buffer, mix, consent), then
session.voicecontrols. L
Done when: a game mode (tag) is a mod, and voice works in a room. Needs: #68 merged, M7, S11. The comparison in piece 3 is exact (decided).
M10. Graphics (track D, spec step 9)
- The world layer: primitives, then static glTF models. L
<World>panels, followed by the renderer. M- Texture packs replaced at upload (needs S5). L
- Shader effects: the template, the pinned compiler, the interface check, per-effect GPU time. L
- The menu half of the registry: the Insert menu's own tabs drawn from it. M
- Upscale recipes: the launcher's confined runner for weight-only model files named by hash (6.3). L
Done when: name tags over enemies, an authored HD texture pack and a colour-grade effect run. Needs: M4's UI channel.
M11. Unsafe tier for packaged mods (track A, spec step 10)
- Mod-declared sites through the same compiler; the lift key; Rebuild for mods for them. M
memory.*, with the rule that it cannot be held withnetorsession. Slongshot-mod sites port. M- Placing mods' new code, so two mods do not claim the same free space. L, not designed
Done when: a mod hooks a function the team never named, on two game versions. Needs: M2, M4.
M12. Portal (track E, spec step 11)
- The launcher's Mods page on
mods.json: installed list, switches, Add from file, Safe start. No portal needed, so it can be the first thing built in track E. M MagicBeanDev/Mods: the index layout, the CI that builds a package from a tag, the signedindex.json. L- Browse, install with dependencies, updates, sync with a save or a room. L
- The automatic checks of 15.4, and the approval path for file-replacing and unsafe releases. L
- The website and the dashboard. L
- Every Longshot release candidate run against every portal mod in the fake game. M
Done when: a mod and its dependencies install with one click. Needs: M4 to have anything to publish. Before it opens to the public: the mod reviewer team exists and has members, and somewhere to host and mirror packages is chosen. The licence rule and the 2 MB cap on bundled script are decided (15.4, 13) and are checks in piece 4.
After: API 1.0
The API stays 0.x until the entry test of 18.1 passes: a gameplay feature, a tracker and an actor-heavy mod ported from Ship of Harkinian's feature list, and the enemy editor of section 18, all built for real.
5. What waits for what
M0 emulator mods ──────────────► M5 file layers ───────────────┐
├─► M7 change and connect ─► M9 session, voice
M1 gates ─► M2 hook compiler ──────────────► M11 unsafe tier │ ▲ ▲
└──► M3 services, phases ─► M4 first scripts ─► M6 profiles │ #68
│ broker ─► M8 sandbox
├─► M10 graphics
└─► M12 portal (M12 piece 1 and M4 pieces 1, 2, 8 can start now)
What can start today without waiting: M0, the spikes, M1, M4's schema, fake game and tools, M12's Mods page.
6. Decisions needed
The spec's fifteen open questions were answered on 2026-11-16 (its section 19 has the table). What is left:
| Decision | Blocks |
|---|---|
| Whether the UI reconciler is ours or an existing small one (Preact was raised; sections 11.1 to 11.3 assume ours) | M4 piece 7 |
| Where portal packages are hosted and mirrored | M12 opening |
| Who the first mod reviewers are | M12 opening |
Three of the fifteen are facts, not choices, and are spikes S1 to S3 above.
7. Rules for every piece
From section 16 and the project's own rules:
- Refactor first. A core piece lands with no new feature and removes the old path in the same pull request.
- The gates run on every change to the core, and a no-mods build stays inside the 2% band.
- A new hook with no subscriber returns the vanilla value; a new registry is a no-op when empty; a new event builds no payload when nothing listens.
- A change the game runs is played in the game before its pull request opens.
- No game files, or anything made from them, leave the PC. That covers test fixtures, the fake game, the portal's hash list (hashes only) and every example mod.
- Defaults right for everyone: no player knobs for budgets or sandbox strength.
8. Where this plan differs from the spec
Found while reading the whole spec for this page. The spec has not been changed for them.
netbefore the sandbox. Section 17 putsnetin step 6 and the broker in step 7, but 9.4 and 12.7 say all network I/O is in the broker. Here the broker is built withnet(M7) and only the confinement is M8.- Settings before the registry. Step 3 delivers settings and step 9 the settings and menu registry they are drawn by. Here the settings half and the renderer channel are in M4, the menu half in M10.
- The gates are a milestone. Section 16 lists them; gate 3's scripted run does not exist, so it is work (M1).
- "The portal only behind the sandbox" (section 17's first line) is older than the decision in 12.2 that the portal does not wait for it. This plan follows 12.2.
- Section 3 still says #134 writes
longshot_mods.txt; 5.4 says it now writesmods.json. - Section 11 says "three places" and lists four surfaces.
- Section 8.5's last bullet ("A module the image builder cannot place...") sits after the unverified note, apart from the list it belongs to.