Table of contents
- Modding API Spec
- 1. Summary
- 2. Goals and non-goals
- 3. Facts that shape the design
- 4. Architecture: the engine is the first mod
- 5. A mod package
- 5.1 Ids are scoped to their owner
- 5.2 The manifest
- 5.3 Dependencies and load order
- 5.4 One list of what is on
- 5.5 Packages, local mods and emulator mods
- 6. Content without code: the file layer
- 6.1 How RomFS works, and how it changes
- 6.2 Why this is safer and friendlier
- 6.3 Textures
- 6.4 Models
- 6.5 What data alone cannot do
- 6.6 How far to trust files
- 7. Runtimes
- 7.1 One API, defined language-neutrally
- 7.2 TypeScript and JavaScript
- 7.3 One runtime per mod
- 7.4 Threads: the game's, and a mod's
- 7.5 Budgets
- 7.6 Hot reload
- 8. Hooks
- 8.1 The site table
- 8.2 Shapes
- 8.3 Unsafe build-time hooks, across game versions
- 8.4 ExeFS patches
- 8.5 Code modules (exefs/subsdk*)
- 9. The API
- 9.1 What it looks like
- 9.2 Rules of the API
- 9.3 State, actors and facts
- 9.4 Network
- 9.5 Storage
- 9.6 Saves
- 9.7 Multiplayer: the engine's session, and voice
- 9.8 Mods working together
- 9.9 Input
- 9.10 Camera
- 10. Graphics: world drawing, models, shaders
- 10.1 The world layer
- 10.2 Billboards: UI in the world
- 10.3 Shaders
- 10.4 Not offered: replacing the game's own shaders
- 10.5 First person and VR
- 11. Custom UI
- 11.1 The model
- 11.2 Three ways to write it, one tree
- 11.3 Components and state
- 11.4 Elements
- 11.5 Settings, and a mod's settings page
- 11.6 Surfaces and their rules
- 11.7 Not planned: the game's own layouts
- 12. The sandbox
- 12.1 What we defend against
- 12.2 The base: the process is the sandbox, for everyone
- 12.3 The language gives nothing
- 12.4 Permissions
- 12.5 Game data stays on the PC
- 12.6 Limits
- 12.7 The network broker
- 12.8 When the interpreter itself has a bug
- 12.9 What a mod can still do
- 13. Developing a mod
- 14. Lifecycle and compatibility
- 15. The mod portal and the launcher's mod manager
- 15.1 The mod manager in the launcher
- 15.2 The repository of mods
- 15.3 Submitting a mod
- 15.4 What the portal checks
- 15.5 The website
- 16. Parity gates: vanilla runs like vanilla
- 17. Order of work
- 18. A worked example: the Bestiary / Enemy Editor
- 19. Open questions, and what is unverified
- Credits
- Appendix: related pull requests and issues
Modding API Spec
Status: draft proposal, revision 3 (2026-11-16). Nothing here is implemented. It extends the tiers of issue #42. Revision 2 folds in a contributor's research notes (what is moddable today, the game's file formats as found on an installed build, and a comparison with gen1recomp's mod platform) and the maintainer's follow-up questions. Statements about the game's files come from those notes and were not re-checked for this page; section 19 lists what nobody has verified.
Contents: 1 Summary · 2 Goals · 3 Facts · 4 Architecture · 5 Packages · 6 Content without code · 7 Runtimes · 8 Hooks · 9 The API · 10 Graphics · 11 UI · 12 Sandbox · 13 Developing a mod · 14 Lifecycle and compatibility · 15 Portal and launcher · 16 Parity gates · 17 Order of work · 18 Worked example · 19 Open questions
1. Summary
A mod is a package with a manifest. It can carry three kinds of thing, from safest to least safe:
- Content patches: small typed changes to the game's data (a parameter key, a table row, an actor placement, a line of text), plus authored textures, models and shaders. No code runs. Longshot builds the changed files on the player's PC from the player's own dump.
- Scripts in TypeScript/JavaScript, each in its own sandboxed interpreter, talking to the game only through
the
longshotAPI and only with permissions the player granted. - Unsafe hooks and memory access, clearly labelled, for what the first two cannot reach.
The engine itself uses the same machinery: Longshot's own features (damage scaling, text speed, widescreen, the Debug tab) become the first users of the hook table, the game services and the file layers. A mod and an engine feature are then the same kind of thing, and "the game with no mods" is that machinery with nothing subscribed.
| Decision | Choice | Why |
|---|---|---|
| Core | The engine is the first mod. One hook compiler, one game-services layer, one layered file system, one save-profile path, each replacing what exists | A mod layer beside hand-patched engine features would be a second path for everything. One path is tested by every player every frame |
| Language | TypeScript/JavaScript on QuickJS-ng first; the API is defined language-neutrally so Lua can follow | Types are the contract; people and AI tools write TypeScript well. A neutral schema means a second runtime is an adapter, not a second API |
| Trust | Mods are untrusted downloads; the game process is OS-sandboxed for everyone | A portal with one-click installs is only safe if a hostile mod can do no more than it was granted, even after an interpreter bug |
| Reach into game code | Named hooks from a per-build site table, plus unsafe build-time hooks | The game is compiled ahead of time. Named hooks are stable and always compiled in; raw hooks cover the rest |
| Multiplayer | Transport, rooms, presence and voice stay in the engine. Mods build game modes and synced state on a session API |
Sockets, relays, consent and microphones are the parts that must be right once, and reviewed |
| Distribution | A mod portal and a mod manager in the launcher, with dependencies, modelled on Factorio's. Script mods publish on automatic checks; mods that replace game files need approval for every update; authored textures only | Players install and switch mods without touching folders; authors publish from git or a dashboard |
| Packages | A package is a .lsmod, a zip. Local mods and emulator mods (romfs/, exefs/) load straight from the mods folder; ExeFS patches warn first |
Players already have emulator mods, and authors need to run a mod without publishing it |
| Camera, input, VR | Camera rigs and input actions are mod API; VR is an engine feature mods plug into | First person works as a mod now; stereo rendering and head tracking cannot be done from a sandboxed script |
| Stability | The API is 0.x until real mods prove it; then 1.0 with "minors only add" | Freezing early creates compatibility shims that never go away |
2. Goals and non-goals
Goals
- Vanilla runs like vanilla. With no mods, the lifted code is bit-exact, frame time is within the project's 2% neutral band, saves are identical, and nothing mod-related is started. Section 16 makes this a set of tests.
- A hostile mod cannot read the player's files, reach the network, or damage a save beyond what the player granted.
- A slow or broken mod cannot stall or crash the game: it is cut off, reported by name, and disabled.
- Most content mods need no code and no dangerous permission.
- Mods can add UI on the HUD, in windows, in their settings page and in the world.
- A mod that uses only the stable API keeps working across Longshot releases and game updates.
- A player installs a mod and everything it depends on with one click; an author publishes without a Longshot change.
- Mods can be developed with ordinary tools (an editor,
tsc, a watcher) and tested without the game.
Non-goals
- Native code mods. Issue #42's tier 4 stays a separate decision. No mod supplies C, a DLL or WebAssembly.
- Patching instructions while the game runs.
- Replacing the game's own shaders or UI layouts through the API (sections 10.4 and 11.7 say what is offered instead).
- Designing VR rendering. It is an engine feature; section 10.5 fixes what mods need around it.
- Mods that own sockets or microphones (section 9.7).
- Deterministic lockstep netcode.
2.1 Common mods, and the route for each
The design is checked against the kinds of mod people make for games like this one. "Step" is the step of section 17 that makes it possible.
| Mod | Route | Code? | Step |
|---|---|---|---|
| HD or restyled texture pack | Images named for the game's textures, replaced in the renderer (6.3) | No | 9 |
| Model or costume swap | A replacement model file plus textures (6.4) | No | 4 |
| Translation, script rewrite, text fixes | Text entries by label (6.1) | No | 4 |
| Rebalance, difficulty mode | Parameter and table patches; data rules for damage and health (8.2) | No, or a little | 4, 6 |
| Enemy or item randomizer | A script registers placement and reward patches for a seed (6.2), in its own save profile | Yes | 4 to 6 |
| Multiworld (Archipelago) | The item service, net, a save profile |
Yes | 6 |
| HUD, tracker, minimap, input display | UI toolkit on the HUD; the markers registry |
Yes | 3 |
| Speedrun timer, practice tools | Events for splits; flags, teleport through the event service, save-slot copies in a profile | Yes | 3, 6 |
| Quality of life (text speed, skips, faster menus) | Data rules and named hooks; these are what the engine's own rows become | Little | 1, 6 |
| Cheats and trainers | state.write and data rules on the safe side; cheat files in the unsafe tier |
Either | 6, 10 |
| First person, photo mode, custom cameras | Camera rigs and scripted views (9.10) | Yes | 6 |
| Control remaps, accessibility | Input filters and actions (9.9); UI scale; a colour-filter screen effect | Yes | 6, 9 |
| Graphics effects (colour grade, CRT, outlines) | Screen-effect shaders (10.3) | Shader | 9 |
| Music and sound replacement | An opaque audio file today (last layer wins); the mod's own sounds through audio. Replacement by name with a host-side converter is a later tool, like textures |
No | 4 |
| New item or enemy from existing behaviour | Table rows, parameters inheriting from an existing actor, mod-owned ids (6.2) | No | 4, 5 |
| New item or enemy with new behaviour | Actor services, named hooks, then unsafe sites | Yes | 6, 10 |
| New dialogue and small quests | Text patches, flags, the event service; the game's event flows themselves are opaque files | Yes | 6 |
| New maps | Not yet: needs baked data nobody can produce (6.5) | ||
| Co-op game modes (tag, race, hide and seek) | session messages and shared state on the engine's rooms (9.7) |
Yes | 8 |
| Proximity or team voice | session.voice controls (9.7) |
Yes | 8 |
| Stream and chat integrations | net to the service, then commands, toasts and data rules |
Yes | 6 |
| Achievements, challenge runs | Events, storage.save, toasts |
Yes | 3, 5 |
| Editors and debug tools | Actor services, world layer, windows (section 18) | Yes | 6, 9 |
| VR | An engine feature mods plug into (10.5) | later |
3. Facts that shape the design
The code
- Ahead-of-time code. The game's AArch64 is lifted to one C function per guest function (294,450) and compiled on the player's PC. A hook exists only if the lifted C has it.
- Today hooks are made four ways: exact-text patches on the generated C (
nx2/oot_patches.py, about 40 sites; a site that is not found only warns), instruction hooks in the lifter (oot_wide.py,oot_fov.py), SDK function replacement by symbol, and guest addresses in host C. All are pinned to one game build id. - Game knowledge is in the host, duplicated: flags are read two ways (
hos_main.c,oot_state_tap.c), and each guest call hand-rolls its context handling. - The game updates on job threads. A hook in actor code is reached from several threads. The one existing
"safe point" (
hos_oot_lift_player) is a try-lock inside Link's update on a worker thread, and does not run on the title screen, in pause or while loading. - Hook placement is a performance decision. A call that takes the guest context stops the compiler optimising
around it (
nx2/poll.pymeasured this). The game is CPU-bound. - Guest memory is not a wall. Anything that controls guest code can reach the whole process.
- The renderer owns the Vulkan images and sees textures at upload, so it can substitute one without the game
knowing. The overlay is Dear ImGui inside the renderer module, across the versioned interface in
vk_api.h. - A local control bridge exists (
host/control.c): JSON over a local socket with state, input and opt-in memory. - Mods work is in flight: #134 (a Mods tab,
longshot_mods.txt, merged size tables, build-time ExeFS patches, cheat files) is open, with #940 and #942 on it.
The game's files (from the research notes; one installed build)
| Area | What is there | What follows |
|---|---|---|
| Actor packs | 8,373 archives, but they are per-actor copies of one logical tree: 13,686 member paths sit in more than one pack, every copy identical | Replacing a whole pack is the wrong unit. Patch by member path |
| Parameters | 139,195 small typed files in 491 classes, inheriting through a $parent key |
Patch single keys; a new actor can inherit from an existing one |
| Data tables | 20 tables of rows, most keyed by __RowId |
Patch rows by key |
| Map placements | 160 files, 120,834 placements, each with a Hash |
Add, move, remove a placement by hash |
| Text | 16 languages, every text has a label | Merge per label; a mod's text needs a default language |
| Textures | 20,667 files, one texture each, with readable stable names | Texture packs keyed by name |
| Models | 7,891 standalone files naming their textures | A model swap is one file plus textures |
| Flags | One list, 26,654 entries, hash only, no names; the save layout is computed from it | Names come from a maintained list; adding a flag changes the save layout |
| Inventory UI | Fixed slot arrays (24 items, 15 equipment...) | A new item needs a slot or a mod-drawn screen |
| New maps | Need baked culling, terrain, collision and nav mesh data | Out of reach for now; placement patches are the first step |
The rule above all: no game files, or anything made from them, leave the PC. A mod package holds authored code and assets only, and nothing in the system may send game data out.
4. Architecture: the engine is the first mod
mods/<owner>/<name>/ mod.json · patches/ · textures/ · assets/ · *.js
│
▼
┌─ game process (OS-sandboxed, no network) ─────────────────────────────────────────────┐
│ │
│ script runtimes (one per mod, QuickJS) engine features (damage, text speed, │
│ │ `longshot` API, permission-checked Debug tab, co-op, control bridge) │
│ └──────────────┬───────────────────────────────┘ │
│ ▼ │
│ ┌─ the core, used by both ────────────────────────────────────────────────────────┐ │
│ │ hook sites (site table) game services + frame phases file layers profiles │ │
│ │ settings/menu registry session (rooms, peers, voice) │ │
│ └──────────┬─────────────────────────┬──────────────────────────┬─────────────────┘ │
│ ▼ ▼ ▼ │
│ lifted game code renderer module player's dump + caches │
│ (hooks compiled in) (UI, world layer, textures) │
└───────────────────────────────────────┬────────────────────────────────────────────────┘
│ local IPC
network broker process
(the only thing with sockets; holds each mod's granted origins)
Six pieces of core. Each replaces what exists, lands first as a refactor with no new feature, and deletes the old path in the same change.
| Core piece | Today | Becomes | First users |
|---|---|---|---|
Hook compiler (nx2/hooks.py) |
Text patches, lifter snippets, addresses in host C | One site table per game build, as data. Sites are found by instruction signature; a site that does not resolve exactly once fails the build | Damage, text speed, camera speed, widescreen, FOV, the high-frame-rate fixes |
Game services (host/game/) |
Game knowledge spread over hos_main.c and oot_state_tap.c |
Flags, events, items, actors, player, camera, one game_call(), and a frame phase scheduler that finds the serial points of the game's frame |
Debug tab, control bridge, state tap, co-op |
| File layers | Whole-file replacement, one size table wins, special cases for prompts and tests | One virtual file system: the dump is layer 0, mods are layers, each file type has a merge rule; the size table is computed | Button prompts, every file mod |
| Save profiles | One user folder; copies made by the launcher and by co-op | Every save lives in a profile; vanilla is the profile with no mods | Co-op playtests, randomizer seeds |
| Settings and menu registry | Hand-written rows and integer option ids, an interface bump per feature | Declared settings the menu draws; one generic channel to the renderer for settings, UI trees and draw lists | The Insert menu's own tabs, then mods |
| Process sandbox and network broker | Nothing for players (an AppContainer exists for the test farm) | The game always runs confined; a small broker process owns all sockets | Co-op, Discord status, mods |
The script runtime sits on top and adds no second route to anything: a script's longshot.items.grant and the
Debug tab's "give item" button call the same service.
5. A mod package
5.1 Ids are scoped to their owner
A mod's id is owner/name: mooki/heart-tracker. The owner is a Forgejo account or organisation on the portal.
- No squatting and no collisions. Two people can both publish a
minimap; a fork isyou/minimap. - Ownership is the namespace, checked by the portal at publish.
longshot/...is reserved for the engine's own built-in content and libraries, andlocal/...for mods that were never published (dropped into the folder). - Everything a mod creates carries the id: imports (
mod:mooki/item-names), events (mooki/heart-tracker:changed), content ids (mooki/boots:item), storage, logs, grants. - On disk:
mods/<owner>/<name>/, and a package is<owner>.<name>_<version>.lsmod(section 5.5). - A rename or a transfer leaves a redirect on the portal, and the manifest's
"replaces"field lets the launcher carry settings and save data across.
5.2 The manifest
{
"id": "mooki/heart-tracker",
"name": "Heart Tracker",
"version": "1.2.0",
"license": "MIT",
"api": "0.3",
"runtime": "js",
"entry": "main.js",
"game": { "builds": ["*"] },
"permissions": ["state.read", "ui.hud", "ui.settings", "storage"],
"optionalPermissions": ["net:wss://tracker.example.org"],
"dependencies": ["mooki/item-names >= 2.0.0", "? ana/minimap >= 1.1.0", "! old/heart-hud"],
"requires": ["player.life"],
"claims": [],
"multiplayer": "local",
"saves": "shared",
"settings": [],
"defaultLanguage": "USen"
}
| Field | Meaning |
|---|---|
api |
The API version it was written for (section 14.1) |
runtime |
"js" today. Absent for a content-only mod, which runs no code at all |
game.builds |
"*" for mods on the stable API and typed patches. Unsafe mods list game build ids |
permissions, optionalPermissions |
Required at enable; asked for at runtime with longshot.permissions.request() |
dependencies |
Other mods, in Factorio's notation (5.3) |
requires |
API features the mod cannot run without, so the launcher can tell before the game starts |
claims |
Things only one mod may own at a time (section 9.8) |
multiplayer |
"local", "all" or "host": who in a room needs the mod (section 9.8) |
saves |
"shared" or "separate" (section 9.6) |
settings |
Declared settings (section 11.5) |
defaultLanguage |
Which of the mod's languages fills the others when text is merged for the game's 16 |
sites |
Unsafe build-time hooks (section 8.3). An exefs/ folder of patches is the other unsafe code route (section 8.4) |
The manifest is data: nothing in it is executed, and unknown fields are ignored. Everything the launcher needs to decide "will this load, and with what" is in it, so no script has to run to find out.
5.3 Dependencies and load order
Each entry is [prefix] <owner/name> [<op> <version>]:
| Prefix | Meaning |
|---|---|
| none | Required. Loads after it; does not load without it |
? |
Optional. Loads after it when present |
(?) |
Hidden optional: not shown to players |
! |
Incompatible: cannot be enabled together |
~ |
Required, but does not affect load order (breaks a cycle) |
longshot >= <version> names the Longshot release. Load order is dependencies first, then by id. The game
resolves this at the start and never downloads; the launcher uses the same resolver to decide what to fetch.
5.4 One list of what is on
There is one source of truth for which mods are enabled, in which order and at which version: mods.json in
the user folder, written by the launcher and by the game's Mods tab.
{ "profile": "randomizer",
"mods": [ { "id": "mooki/heart-tracker", "enabled": true, "version": "1.2.0" },
{ "id": "local/my-textures", "enabled": false } ] }
Decided 2026-11-16: #134 currently writes
longshot_mods.txt (order and switches). It changes to this JSON list before it merges, so no second file
appears later: profiles, pinned versions and room sync need the extra fields. (Done on #134's branch: it
reads and writes mods.json, keeps keys it does not know, and reads the old file once.)
The build reads the same list. ExeFS patches and code modules are built in, in list order, so
nx2/make_game.py must see the list the game will see, or a mod is built for one order and served in another.
Decided 2026-11-16: the build is given the list: make_game.py --mods <path to a mods.json>. It does not
go looking for a user folder, and the game leaves no note for it. The launcher will have user profiles, each with
its own mods, so "the user's list" is not one file: each profile has its own mods.json, and whoever starts a
build says which one.
- Without
--modsthe build takes no mods. A build by hand names the list like any other input. - The build records the list's code mods and their order in
exefs_patches.txt; the game compares that with the list it was started with, and a difference is "waits for a build", never a silent mismatch. - Profiles and builds. A build is keyed by the bytes its code mods apply, so profiles with the same code mods share one build, and file or script mods never need one. Proposed: the launcher passes the code mods of all profiles to one build, each switched at the start by the profile being played (section 8.4), so changing profile is a restart. Where two profiles' code mods cannot share a build (they clash, or pass the cap on one function), the launcher keeps a build per set.
The list says what is on; the mods folder says what is there. Anything found in the folder and missing
from the list is added to it at the next start (section 5.5 says in which state). A folder whose name starts with
., _ or - is still skipped, as today: that is "not installed", not a second switch.
5.5 Packages, local mods and emulator mods
Decided 2026-11-16: a mod does not have to come from the portal, and a mod made for an emulator loads as it is. (This replaces the earlier plan of importing emulator mods into generated packages.)
Three things the mods folder can hold, all loaded the same way:
| What | How it is recognised | Id |
|---|---|---|
A package: something.lsmod |
A zip with mod.json at its root |
The manifest's |
| A folder mod | A folder with mod.json |
The manifest's. A folder wins over a package of the same id, which is what development wants |
| An emulator mod | A folder, or a plain .zip, with romfs/ or exefs/ inside and no manifest |
local/<folder or file name> |
The .lsmod format. It is an ordinary zip under its own extension:
- Zip, because every tool on every system makes and opens one, it has an index (one file can be read without the rest), and each file is compressed on its own, so files that are already compressed (most of the game's formats, PNG) are stored as they are. Factorio's mods are zips for the same reasons.
- Its own extension, so the launcher can register it: opening a
.lsmod, or dropping one on the launcher, starts "Install this mod?" with its permissions listed. - Deflate or stored only. Zstandard inside zip exists, but the usual tools cannot open it, and the saving is small on content that is mostly compressed already. A tar with Zstandard has no index.
- Unpacked once into a cache, keyed by the package's hash, at install or at the first start that sees it. The game reads replacement files by offset, which a compressed zip entry does not allow, and one rule is simpler than reading some kinds from the archive and others from disk. The package itself is never changed.
- Checked while unpacking: links, absolute paths,
.., names that differ only by case, duplicate names, encrypted entries and nested archives are refused, and there are limits on file count, unpacked size and compression ratio. - Unverified: the game has no zip reader today (
third_party/has Zstandard, not zlib or miniz). One has to be added there with its provenance.
Local mods. A local mod is any of the three that the portal did not deliver: dropped into the folder, or added with Add from file in the launcher or the game's Mods tab. It needs no account, no network and no signature.
- It gets the same permission prompts, limits and sandbox as a portal mod. Nothing is trusted more for being local.
- It is marked Local in the list: no update check, no portal page. If its hash matches the signed index it is shown as the portal's release instead.
- A package or folder mod found for the first time is off until the player has seen what it asks for.
Emulator mods. A folder in the layout emulators use works with no manifest and no conversion. The discovery
rules stay as docs/mods.md describes them: from one to four levels below the root, so
mods/contents/<title id>/<name>/romfs works.
romfs/is loaded as replacement files, as today. A mod with only this is on when found, as today. If it ships a resource size table, its entries are a floor: its author measured them on the real thing, so each entry is the larger of the mod's and the computed one (section 6.1), as #134's merge does.- An archive two mods both ship (an actor pack, the layout archive, a text archive) is merged member by member against the game's copy; only a member both changed goes to the lower mod in the list (#1089).
exefs/.ipsand.pchtxtpatches are applied at build time under every rule of section 8.4. A mod that has them is off when found, and turning it on shows the warning below and then offers Rebuild for mods. The console layoutatmosphere/exefs_patches/<name>/*.ipsis read too.exefs/subsdk*, a compiled code module, is built in with the game under the same warning (section 8.5).cheats/follows #134.- Not loaded: a whole replacement
mainormain.npdm. It would mean lifting a different game executable, and such a file is the game's own code. The Mods tab names the file and says why (#940). - A plain
.zipof such a folder, as mod sites offer it, is unpacked the same way as a package. - It has no version and no dependencies, and it takes its place in the order from the list like any other mod.
The warning for a mod with ExeFS patches, shown once per mod and again when its patches change:
This mod changes the game's code. Longshot cannot check or limit what the changed code does. It can crash the game or damage a save. Turn it on only if you trust where it came from. Applying it rebuilds part of the game, which takes a few minutes.
This tier is being built now, on #134 and the pull requests stacked on it, and played in the game with real mods. Where this page and that work disagreed, the page was changed (#1097); the appendix lists each pull request.
6. Content without code: the file layer
Most mods people want (a texture pack, a rebalanced enemy, a chest that holds something else, a translation, an enemy randomizer) change data, not behaviour. They should need no script and no risky permission.
6.1 How RomFS works, and how it changes
RomFS is the game's read-only data: 186,583 files. Here it is a plain folder extracted from the player's dump.
When the game opens rom:/Some/File, host/nn_fs.c opens that file. Today host/mods.c adds one rule: "a mod
has this path, read that file instead".
The file layer replaces that with a virtual file system every open goes through. Layer 0 is the dump. Each enabled mod is a layer, in load order. Each path is resolved by the rule for its type:
| Type | What a mod ships | How layers combine |
|---|---|---|
| Parameter files | Patch operations on keys: set, add, remove |
Folded over the base in load order. $parent stays meaningful |
| Data tables | Row operations by the table's key column | Folded in load order |
| Map placements | Placement operations by Hash: add, move, remove, change |
Folded in load order |
| Text | Entries by label, per language | Merged per label; missing languages filled from defaultLanguage |
| Flag list | Entries by hash, in a typed table | Adding one is a declared, save-changing capability (section 9.6) |
| Archives (actor packs) | An override of a member path | Applied to every pack that carries the member; packs rebuilt locally. #1089 already merges the archives mods ship, member by member |
| Opaque files (models, audio, event flows, AI, animation graphs) | A whole file | Last layer wins, as today |
| Resource size table | Never shipped in a package. An emulator mod's own table is kept as a floor | Computed from the final merged files, including every file inside a pack |
// patches/Component/EnemyParam/Octorok.json: one key, not a whole pack
{ "target": "Component/EnemyParam/Octorok.game__component__EnemyParam.bgyml",
"ops": [ { "op": "set", "path": "Life", "value": 12 } ] }
What the size table needs, learned in the game on #134 and #942:
- An entry is not a function of file size alone. The per-type factors measured on the game's table are in
host/restbl.c. A parameter file's entry follows its number of list elements; growing the entry in proportion to the file was not enough (a load failed). 8 entry bytes for each byte grown is, at about twice the heap. - Every file inside an actor pack has its own entry, and the game enforces it. A grown member with its old entry hangs a loading screen. The computation walks the packs' members.
- Cache it by the files' content. The first start after new mod files reads every served file's header (seconds); later starts must not.
What writing archives needs, from #1089: each member keeps the alignment its own archive gave it; the layout archive holds some names several times, taken together and in order; nodes are sorted by hash; a member name is untrusted text; the result's size is bounded. The game does load host-written packs, as a Zstandard frame of raw blocks without the pack dictionary.
6.2 Why this is safer and friendlier
- Built on the player's PC. The merged files are produced from the dump and the patches, cached by content hash. A mod ships patches and authored files only, which is the no-game-files rule by construction.
- The game's parsers see well-formed input. The host writes typed files with its own serialisers, so the "hostile file attacks the game's parser" risk shrinks to the opaque types.
- Conflicts become small and visible. Two mods changing different keys of one file both apply. Two changing the same key is a named conflict the launcher shows ("both set Octorok's Life"), resolved by load order.
- Randomizers need no raw file access. A script decides placements and rewards and registers patch
operations (
longshot.content.patch(...)) during a prepare stage. Raw bytes never enter the script, so it may also hold a network permission. That removes the conflict between reading game files and multiworld. - Mod-owned ids. A new table row or item is
mooki/boots:item; the host maps it to a free game id per profile and keeps the mapping with the save.
6.3 Textures
Texture packs do not go through RomFS. The renderer replaces a texture at upload: when a pack is on, it
recognises the game's texture and loads the pack's image into its own Vulkan image, at any resolution. The game's
memory, heap and size table are not involved, so the usual cause of an endless loading screen disappears, and the
host decodes the image, never the game. That makes gfx.textures a low permission.
A pack is a folder of images named for the game's textures: textures/<Name>.png (or KTX2). How the renderer
connects a name to an upload (a content-hash index built locally, or a hook on the texture load) is a spike.
Textures the game makes at run time have no file and cannot be replaced by name.
Decided 2026-11-16: the portal hosts authored textures only. An upscaled or repainted copy of a game texture is made from a game file, so it is not distributed. An upscale pack ships as a recipe (the model and its settings) that the launcher runs on the player's own dump, the same way typed patches are built locally.
6.4 Models
- Swap an existing model: an opaque file in the layer, plus textures by name. Works today for whole files.
- Authored formats (glTF in, the game's format out, converted on the player's PC) is a later tool.
- Mod-drawn models that are not game actors (a hat, a co-op marker, a preview in a window) go through the world layer (section 10), which needs no game format at all.
6.5 What data alone cannot do
- A new actor can only use a class that already exists in the game's code. New behaviour needs hooks.
- The inventory screen has fixed slots. A truly new item needs a free slot or a mod-drawn screen.
- A new map needs baked data nobody can produce yet.
- Event flows, AI and animation graphs are opaque: last layer wins, no merge.
So "new item" is two features: a re-parameterised existing item (data only, safe) and an item with new behaviour (hooks, section 8).
6.6 How far to trust files
| Kind | Trust | Why |
|---|---|---|
| Typed patches, text, textures | Low risk | The host parses and writes them; the game sees well-formed files |
| Opaque replacement files | Fairly safe in practice: "replaces game files". Every portal update is approved by a person, mainly to check the files are not the game's own | Parsed by the game's own code, which trusts them completely. A malformed one could in principle attack that parser and take over the game's code |
romfs.provide (raw bytes from a script) |
High, reviewed | Same as opaque files, chosen at run time |
Packages are unpacked with the checks in section 5.5.
7. Runtimes
7.1 One API, defined language-neutrally
The API is not defined by its TypeScript. It is defined by an API schema: data files in the repository that list every namespace, function, event, type, permission and since-version. Hook entries are generated from the site table (section 8), so the API cannot promise an argument a site does not have. From the schema are generated:
- the C bindings, with every argument validated and copied in one generated place;
longshot.d.tsfor TypeScript;- the reference documentation, the permission table and the feature list for
longshot.has(); - the fake game used for tests (section 13);
- later, the bindings and type annotations for another language.
Underneath, the host services speak a small value model: numbers, strings, booleans, byte buffers, lists, records and handles (an id plus a generation, never a pointer). Everything that crosses between a mod and the host, or between two mods, is one of those. A runtime adapter is what turns that into a language: load a module, call a function, convert values, enforce a memory limit, interrupt a callback.
So Lua can follow without a second API. A Lua (or Luau) adapter would expose the same namespaces with the same names, permissions and semantics; a Lua mod and a TypeScript mod could depend on each other, because exports, events and registries cross as values. UI trees are data, so Lua builds them with tables where TypeScript uses TSX. What a second language costs is documentation, examples and tooling in two dialects, which is why it is not in the first phases (open question 7).
7.2 TypeScript and JavaScript
- The game loads ES modules in plain JavaScript, with source maps. It does not compile TypeScript and does not need Node. Authors compile with ordinary tools (section 13). Plain JavaScript mods need no build step.
- A mod imports its own files by relative path and a dependency by id (
import { names } from "mod:mooki/item-names"). Nothing else resolves. - The language is ES2023 as QuickJS-ng implements it, minus
eval,new Function,SharedArrayBuffer,Atomics,WebAssemblyand QuickJS'sstdandosmodules. Precompiled QuickJS bytecode is refused: only source is loaded.
7.3 One runtime per mod
Each mod gets its own interpreter instance with its own heap and limits. Two mods can never share an object.
7.4 Threads: the game's, and a mod's
The game's threads. The game updates actors on job threads, so a hook can be reached from several threads at once. The rules:
- Script runs only in serial phases of the frame, found by the frame phase scheduler: before the game starts its jobs and after they join. One callback at a time, in a defined order, the same in menus, pause and loading.
framefires once per game frame (generated frames do not count).updatefires in the serial phase where game state is consistent to read; state writes made elsewhere are queued for it.- No script runs inline on a worker thread. A hook reached there does one of two things (section 8.2): apply a data rule from a frozen table in C, or record an event for the next serial phase.
- Nothing in the API blocks. Anything that waits returns a Promise, delivered at a serial phase.
This keeps the game's job system parallel and makes mod order the same every frame.
A mod's own threads: workers. For heavy computation (generating a seed, pathfinding, parsing a big file) a mod can start a worker:
const gen = longshot.worker("generate.js");
gen.post({ seed, settings });
gen.onMessage((m) => applyPlacements(m.placements));
- A worker is another interpreter of the same mod on a host thread. It talks to the mod by messages (values are copied; byte buffers can be moved). There is no shared memory.
- A worker has no game API except
log: it computes and answers. So it cannot race the game. - Workers run on a small low-priority pool sized by the host, not by the mod, because the CPU saturates first in
this game (
docs/design.md). A mod may have 2 workers; their memory counts against the mod's limit. - The host's own slow work (network, storage, image decoding, building merged files) is already off the game's threads and needs no worker.
7.5 Budgets
| Limit | Default | When exceeded |
|---|---|---|
| Heap per mod (workers included) | 64 MB | Allocation fails with an exception |
| One callback | 5 ms | Interrupted; counted as a fault |
| One mod's script per frame | 2 ms warned, 8 ms a fault | Shown per mod in the Mods tab and the frame-time Breakdown (#928) |
| All mods together per frame | 4 ms warned | Callbacks that can wait (events, UI rebuilds) are deferred to the next frame, oldest first |
| Faults | 3 in a minute | The mod is stopped for the session and named |
The numbers are starting points to measure. What happens on a fault is set per hook: a cosmetic filter that faults is skipped; a progression-critical one (the reward table under a claim) pauses the game and says so, because silently giving the vanilla item would break a seed without telling anyone.
7.6 Hot reload
Yes, and it is the same mechanism for developers and players.
- The host owns everything a mod created (subscriptions, timers, UI trees, connections, workers, world objects) as handles. Stopping a mod disposes them all, so a stopped mod leaves nothing behind. Starting it again runs its entry module fresh.
- Players: enabling, disabling or updating a script mod in the Mods tab takes effect at once, with no restart.
- Developers: with dev mode on, saving a file reloads that mod within the frame. State survives if the mod
asks:
const state = longshot.dev.keep("state", () => initial)returns the same value across reloads, andlongshot.on("reload", ...)runs before the old instance is disposed. Storage and settings persist anyway. - UI, shaders, textures and other authored assets reload the same way.
- Content patches reload too, but the game only reads a file when it loads it: a changed patch shows at the next load of that file (re-enter the map), and the Mods tab says "applies on next load".
- Not hot: unsafe build-time hooks (a rebuild), and a mod that a co-op room requires (
"multiplayer": "all") while in the room.
8. Hooks
8.1 The site table
For each supported game build there is one table of sites (game/<build id>/sites.toml). A site names a
function and a point in it, its shape, its typed arguments by register, the thread it is reached on (serial or
worker), and a signature of masked instruction words that identifies it.
- The lifter resolves each site's address from its signature and emits the hook as part of code generation. A site that does not resolve exactly once fails the build of a supported game version, loudly.
- Signatures, not addresses, so most sites find themselves again when the game updates. The team fixes the few that do not, and mods on named hooks need no change.
- Hooks default to a wrapper around the function (one flag check outside; the body's optimisation untouched). Mid-function sites are allowed, are reported when they sit inside a loop, and need a measurement.
- A dormant site costs one byte load and a predicted branch, what today's hand patches already cost.
- Named hooks are always compiled in, so ordinary mods never need a rebuild.
- A spike worth doing: hooking virtual methods at run time by placing a host thunk in a guest vtable slot. Much of what mods want (actor updates, actions, UI screens) is virtual. Untested.
8.2 Shapes
| Shape | What it is | Where it may run |
|---|---|---|
| Event | Tells a mod something happened; cannot change it | Anywhere. From a worker-thread site it is recorded and delivered at the next serial phase |
| Filter | Runs synchronously in script and may change or cancel the outcome | Only at sites the table marks serial |
| Data rule | A frozen table the mod fills ahead of time, applied in C at the site | Anywhere, including worker threads and hot paths |
Data rules are how a mod changes something on a hot or parallel path without running script there:
longshot.items.rewards.set("Kokiri/Chest_MidoHouse_0", "Rupee_Blue"); // a reward table
longshot.rules.damageTaken.scale(0.5); // a multiplier
longshot.rules.damageTaken.scale(2, { source: "Enemy_Octorok" });
Filters run in load order, then priority; each sees the previous one's result. With dev mode on, a trace shows
which mod changed what.
A first set of named hooks, to grow by pull request:
| Hook | Shape |
|---|---|
frame, update, mapLoading, mapLoaded, saveLoaded, saveWriting, paused |
event |
flagChanged (a watched flag) |
event |
actor.spawned, actor.removed, actor.defeated, actor.damaged |
event |
items.checked (a location was checked), items.granted (an item reached the inventory) |
event |
items.rewards, damageTaken, damageDealt, actorLife |
data rule |
textShown, input |
filter (serial sites) |
Issue #42's rule is kept in the names: a checked location and a granted item are different events, because in a multiworld another player's reward completes a check without adding anything locally.
8.3 Unsafe build-time hooks, across game versions
A mod that needs a function the team has not named declares its own sites. They use the same site format and the same compiler, in the unsafe tier:
"permissions": ["hooks.unsafe", "memory.read"],
"sites": [
{ "name": "textStep", "when": "entry", "args": ["x0:ptr", "s0:f32"], "returns": "void", "thread": "serial",
"match": { "signature": "fd7bbfa9 ?? ?? 00 91 e0 03 ?? aa 08 ?? 40 f9", "function": true },
"builds": {
"e0f3ccfaf50065ae4ea01eb5aeb13b1a45da3348": "0x80b1e140",
"5c1d09a2...": "0x80b20f80" } }
]
Several game versions are supported by design, because players build from their own dump and the game will be updated:
- A site is found by signature first. If the signature matches exactly once in the player's build, it is used, whatever the build id. This is what lets one mod release work on game versions its author never saw.
buildsis an optional per-build address, checked against the signature when both are given. It settles cases where the signature is ambiguous or the code changed.- If the player's build is in neither, or the signature matches zero or several places, the mod does not load on that build, and the launcher says "not available for your game version" before any rebuild is attempted. A hook is never placed by guess.
- The lift key is: the dump's build id, the Longshot version, the site table's hash, and the hash of the enabled
unsafe sites. Enabling such a mod offers Rebuild for mods, which recompiles only the files holding the
hooked functions (minutes, once), as
scripts/dev_packs.pybuilds a pack. longshot-mod sites port --from <build> --to <build>(section 13) re-finds a mod's sites in a newer build from their signatures and reports the ones that need a person.- The mod supplies data, never C. The emitted code is the compiler's own template.
- ExeFS patches and cheat files (#134) are the same trust level and are listed in the unsafe tier with these.
A site several mods need is a candidate to become a named hook.
8.4 ExeFS patches
A mod may ship ExeFS patches: an exefs/ folder of .ips and .pchtxt files, the format emulator mods
already use. An emulator mod's own exefs/ folder is read directly, with no manifest (section 5.5); it has the
exefs permission by being what it is, and the player accepts the warning before it is applied. They change the game's code, so they are the plainly unsafe kind of mod, and the main reason to
support them is that existing mods work.
- Applied at build time, as #134 does: written into the game's code before it is lifted, then compiled like the rest. The bytes the patches apply are part of the lift key, not the mods' names, so renaming a mod's folder does not translate the game again.
- Switching does not need a build (#1036). The build keeps two versions of each function a patch touches, the game's and the mod's, and the game picks one at its start. So a code mod the last build took is switched at the next start, like any other mod. One the build did not take (new, edited, or its warning never accepted) is held back whole, files included, until Rebuild for mods: a mod with its files and without its code, or the reverse, is a broken mod. Proposed: the build takes every accepted mod in the folder, on or off; at most two mods changing one function are switchable separately, more fall back to a build.
- Unsafe tier: the
exefspermission, the same warning, a person's approval for every portal release. - One game version each. A patch names the build it was made for and is applied only to that build. On another the mod is "not available for your game version"; nothing is applied by guess.
- Two mods writing the same place differently: the mod lower in the list wins every byte of that place, the rule files already follow, and both mods and the place are named in the log and the Mods tab (#961). Patches that touch different bytes both apply. (Changed: this page said neither applies until the player picks. The list's order is that pick already.)
- The usual clash is over free space, not game code. Mod authors all find the same padding after the game's code for their new code: of nine public code mods, five overlap one larger mod there, and no two change the same game instruction. Order cannot give the player both. The fix would be the build placing each mod's new code itself and re-pointing the mod's direct branches to it. Not built; a package's own patches should declare the space they need rather than pick an address.
- A hook that returns with a branch is rewritten. Many console mods enter a hook with
bland go back withb <next instruction>. Lifted, that is a call followed by a jump into the caller, and the game crashes. The build makes that branch a return where the hook's code was all written by the patch and is entered only from that call; otherwise it leaves it and says so (#960). - A patch must not break the engine. After patching, every site in the site table must still resolve. If a
patch changed a function one of Longshot's own hooks sits in, that mod is refused and named, and the build
goes ahead without it. The stock game failing to resolve a site is still a build failure; a mod causing it is
the mod's fault and is reported as such. This needs the site table (step 1). Today it can be checked only
for the hooks that have addresses (
nx2/oot_wide.py,oot_fov.py,oot_jitter.py); a patch to a function one of the roughly forty text patches innx2/oot_patches.pyedits is not detected. - A patch aimed at code Longshot does not run (a function the host replaces) is reported as having no effect, so its author and its players are not left guessing.
- Cheats follow #134: Atmosphere's data opcodes run each frame; a cheat that writes code is refused.
- New mods should prefer named hooks and signature-matched sites (8.3): they survive game updates and cannot collide with the engine this way.
8.5 Code modules (exefs/subsdk*)
Six of nine public code mods for this game ship a compiled module beside their patch file, so leaving modules out would leave out most code mods that exist. A module is not a replacement for the game's code: it is one more module beside the game's, and the lift takes it like the game's own.
| How the module hooks the game | State |
|---|---|
| A patch file's stubs call into it | Built in: placed after the game's last module (no game address moves), translated, started with the game's modules. Played in the game (#984) |
| It writes branches into the game's code at start-up (exlaunch and similar) | The start-up is run once at build time in a processor emulator; the bytes it wrote are taken like a patch file's. Played; on a branch (mods/modules-stack), no pull request yet |
| It re-points the game's import table at start-up | The same, since imports are bound when the game is built. On a branch; tested without the game, not played |
| It hooks later, or by a setting read while the game runs | Cannot work: the build never sees those writes |
| It needs sockets, or loads more code while running | Not supported; the build should name the stubbed imports |
- Unsafe tier, with the warning, the build and the switch of section 8.4. The Mods tab says for each module "built in", "waits for a build" or "left out", with the reason.
Modules that hook the game themselves (exlaunch and similar). Decided 2026-11-16: supported, the same way as patch files. Such a mod ends up as the same thing as an ExeFS patch plus a module: bytes written over the game's code that point into the mod's code. The only difference is where the bytes come from. A patch file lists them; an exlaunch-style module works them out in its start-up code, by making the game's code writable and writing branches into it. A game compiled ahead of time has no instructions in memory to overwrite, so that start-up cannot run in the game.
So the build gets the bytes once, and from there the mod is a patch file: the same warning, build, clash naming (section 8.4) and switch without a build. Getting them means running the mod's start-up in a processor emulator against the game's image, under these rules:
- Only after the player accepted the mod's warning. Until then the build does not touch its code.
- In a separate confined process, which is given the game's image and the module and gives back a list of writes. It has no files and no network.
- The writes are checked as data. They may land only in the game's code, the padding after it and the import table, and there is a limit on how many. Anything else leaves the module out, with the reason.
- Bounded in time and memory, in user mode, so a start-up that loops or fills memory ends as "left out".
- Cached by the module's hash, so it runs once for each version of a mod.
This is less power than the mod gets anyway: once accepted, its code runs inside the game with everything the game can do. The rules are there so that stays true only after the warning, and so a fault in the emulator is not a way into the build, which can read the dump and write the game.
Unverified: exlaunch's trampoline hooks copy the game's original instructions into memory the module allocates, so the mod can call the original function. The emulated run has to take that memory too. Whether the branch does has not been read.
- A module the image builder cannot place is left out with a note; it never stops the build.
9. The API
Everything is on the longshot global. longshot.has("items.rewards") says whether a feature exists in this
game build, so one mod can support several versions.
| Namespace | Does | Permission |
|---|---|---|
log, dev |
Logging; dev-mode helpers | none |
game, game.flags, player, camera |
Map, time, age, flags by name, Link (position, velocity, health, rupees, wallet), the camera (and the engine's free camera); frame, update and map events; game-time timers |
state.read |
actors |
Find and watch actors; read name, type, position, health | actors.read |
actors (write), rules, game.flags.set, player.set... |
Spawn (existing classes, capped) and steer actors, set data rules, write flags and Link's values (health, rupees, velocity) | state.write, actors.write |
world, capture |
A collision ray query; a thumbnail of the picture as an opaque image handle | state.read, ui.* |
items |
Checks, grants, rewards, the inventory | items.read, items.grant |
content |
Register patch operations; read facts from the merged data (names, table rows) | content.patch, content.read |
storage |
The mod's own data: global, per profile, per save | storage |
ui |
Components, surfaces, settings (section 11) | per surface |
gfx |
World drawing, models, shader effects (section 10) | gfx.world, gfx.shader |
audio |
Play the mod's own sounds | audio |
input |
Rebindable actions, reading and filtering the controller, mouse look, rumble (9.9) | input.read, input.write |
camera (control) |
Camera rigs and scripted views (9.10) | camera.control |
net |
WebSocket and HTTPS to declared origins | net:<origin> |
session |
The engine's multiplayer room: peers, messages, shared state, voice controls (9.7) | session |
mods |
Other mods: exports, events, registries, claims (9.8) | none |
worker |
Background computation (7.4) | none |
hooks, memory |
Unsafe hooks; guest memory by address | hooks.unsafe, memory.* |
9.1 What it looks like
// main.tsx: show the hearts as a number, with a setting for where
import { Hud, Text, useGame, useSetting } from "longshot/ui";
function Hearts() {
const p = useGame((g) => g.player); // re-renders when what it read changes
const [corner] = useSetting("corner");
if (!p.present) return null; // title screen, loading
return (
<Hud anchor={corner === 0 ? "top-left" : "top-right"} margin={24}>
<Text size={28} outline>{p.life / 4} / {p.maxLife / 4}</Text>
</Hud>
);
}
longshot.ui.mount(<Hearts />);
// A multiworld client's core
const ws = await longshot.net.connect("wss://ap.example.org:38281");
for (const p of placements) // which chest holds what: a data rule, applied in C
longshot.items.rewards.set(p.location, p.local ? p.item : longshot.items.NOTHING, { message: p.label });
longshot.items.on("checked", (e) => ws.send(JSON.stringify({ cmd: "check", location: e.location })));
ws.onMessage(async (m) => {
const msg = JSON.parse(m.text);
if (msg.cmd === "receive") await longshot.items.grant(msg.item, { from: msg.player });
});
items.grant resolves when the item really reached the inventory. While the game cannot take an item, grants
wait in a queue saved with the mod's data, so a crash does not lose one.
9.2 Rules of the API
- Units and meanings are the game's, written down: metres, degrees, quarter hearts.
- Game objects are handles. A stale handle throws
StaleHandle; it never reads freed memory. - Values cross by copy. A script never holds a view of host or guest memory.
- Every call checks its permission and throws
PermissionDeniednaming it. - Names over numbers: items, maps, actors and flags by name. Flags have no names in the game's files, so Longshot ships a name list the community extends; a mod's own flags are named by the mod.
- Additive within a version line (section 14.1), with
@sinceon everything.
9.3 State, actors and facts
game.flags.get("PlayerStatus.Life") and the others read through the game services. Writes check type and range,
and a short deny list covers flags a mod must not write blind.
actors gives handles with facts: name (the game's actor name), kind (enemy, npc, item...), pos, life,
maxLife, and events for spawn, damage and defeat. content.read gives facts from the merged data: a row of a
table by key, an actor's display name in the current language, its category. These are facts about play, not
assets or code, so they may be combined with network permissions (section 12.5).
9.4 Network
- The manifest names each origin:
net:wss://ap.example.org:38281. A wildcard is allowed for clients where the player types the server, and is shown to the player as "any server on the internet". - Only
wss:andhttps:. Loopback, private and link-local addresses are refused unless the mod holdsnet.lan. The address is resolved once per connection and pinned, and every redirect is checked against the grant again. - I/O happens in the broker process (section 12.7). Messages arrive as events. Per mod: 8 connections, 1 MB a message, a byte-rate cap. No raw sockets, no listening.
9.5 Storage
storage is a key-value store with string keys and structured values. There are no paths in the API, so
there is no path to escape with. Three scopes:
| Scope | Lives | For |
|---|---|---|
storage.global |
With the mod | Caches, things true across all play |
storage.profile |
With the launcher profile | Settings-like state for one mod set |
storage.save |
With the save slot | Anything that is part of a playthrough |
9.6 Saves
Yes, mods can store data in saves, in two ways.
Mod data that travels with a save (the normal way). storage.save is kept beside the save slot, per mod:
- It is written at the game's own save moment and committed together with it. If the player dies and reloads, the mod's data goes back with the game's, so a tracker or a quest log never gets ahead of the save.
- It is copied, exported, imported and deleted with the slot, in the game and in the launcher.
- It carries a schema number; a newer mod version gets
migrate(from)first. Data from a newer mod version than the installed one is refused for that mod, not guessed at. - 4 MB per mod per slot. The game's own save file is untouched and keeps its layout, so it stays loadable by the unmodded game and by emulators.
New game flags inside the game's save (the exception). The game computes its save layout from the flag list,
so adding a flag changes the layout of the save. That is a declared capability (save.flags): a profile using it
is marked not vanilla-compatible, its saves are never offered to the default profile, and removing the mod
has a defined result (the profile refuses to load without it, or the host strips the added flags and says so).
A mod needs this only when the game's own code or data must read the flag, for example a new chest that
remembers it was opened.
Profiles. Every save lives in a profile; vanilla is the profile with no mods, through the same code. A profile
records its mods and versions and the table of mod-owned ids its saves use. A mod that changes progression
declares "saves": "separate" and plays in its own profile (and, through saves.profile(name), one per seed or
room), so the player's own saves are never opened. The default profile's files stay byte-compatible with
emulators.
9.7 Multiplayer: the engine's session, and voice
Networking for multiplayer stays in the engine. The co-op work in #68 (early, not merged; now including what was #355) already has the shape of a core service, described here from its headers and write-up, not from a test:
- Transport: UDP through a relay that only forwards and cannot read messages; optional direct paths, off by default. Rooms of up to 8, named by a secret shared out of band; messages sealed end to end; each player signs their identity and the room's maker signs its rules.
- Consent: off until a player makes or joins a room; separate consents for progress, presence and downloads; a whole-save backup before anything is applied.
- Game side: progress synced through the game's own flag setters with a core-owned merge; remote players drawn
as real game actors (
Player_Child/Player_Adult), which is why they look native. - One session thread owns the socket and never touches game memory.
The spec keeps all of that in the engine and moves two things under it: its sockets go to the broker process (section 12.7), and its game access goes through the game services (section 4) instead of addresses of its own. What stays out of mods on purpose: sockets, relays, keys, room secrets, peers' addresses, consent screens, and microphones.
What mods get: longshot.session. A mod adds a game mode, synced state or messages to the room the player is
already in. It cannot make, join or leave rooms; that stays in the Co-op tab.
const s = longshot.session;
s.room; // state, self, maker, peers (name, fingerprint, away, accepted)
s.on("peer", (ev, peer) => { /* joined, accepted, left */ });
s.pose(peer); // area, position, facing: accepted peers only
// Typed messages. The engine namespaces them by mod id, checks them against the schema, and enforces size and rate.
const tag = s.channel("tag", TagMsg, { delivery: "reliable" });
tag.send({ it: peer.id });
tag.on((from, msg) => setIt(msg.it));
// Shared state with an engine-owned merge rule, applied only after consent.
const score = s.shared("score", Score, "max", 0); // "max" | "lastWriterWins" | "pool" | "makerOnly"
// A rule the mod adds to the maker's signed room rules, shown on the consent screen.
const rounds = s.rule("rounds", { label: "Rounds", min: 1, max: 9, default: 3 });
- Messages from peers are untrusted input. They arrive already checked against the mod's declared schema, with nothing a peer sends becoming a name, a path or a pointer. A mod cannot skip the schema.
- A mod with
sessionis"multiplayer": "all"by definition, so the room's mod comparison (section 9.8) covers it and a peer without the mod is refused before anything is exchanged. - Messages ride the room's existing relay budget; a chatty mod is throttled, not the room.
net(section 9.4) remains for servers that are not rooms, such as a multiworld server.
Voice chat is an engine feature, with controls for mods. Most of the parts exist on main, unconnected:
| Part | Today | To add |
|---|---|---|
| Microphone | Captured for the ocarina only (host/nn_audio_in.c), with a device row in the menu |
A host tap for voice when the ocarina is not listening; echo cancellation and noise suppression (none in the repository) |
| Codec | libopus is in third_party/, used to decode only |
Encoding 20 ms frames (the encoder sources are listed; linking is unchecked) |
| Transport | The room's sealed, unreliable datagrams | A voice message kind with sequence and timestamp; a relay budget for 50 packets a second per talker |
| Playback | The host mixer (host/nn_audio.c) has no input for host-made sound |
A per-peer jitter buffer with loss concealment, mixed after the game's audio, with its own volume |
| Controls | A chat key and chat mute exist as patterns | Push-to-talk, per-peer volume and mute, a talking indicator |
| Consent | Room rules are signed and accepted per player | A voice rule in the room's rules and a per-player consent |
Mods get controls only. Audio never reaches a script, in either direction, and neither does a peer's address:
const v = longshot.session.voice;
v.available; // the room allows it, the player consented, a mic is chosen
v.setGroup(teamPeers); // who hears whom: team channels in a game mode
v.setSpatial({ enabled: true, fullVolumeMeters: 5, silentMeters: 40 }); // by the poses the engine already has
v.setPeer(peer, { volume: 0.5 }); // the player's own mute always wins
v.on("talking", (peer, talking) => showIcon(peer, talking));
So proximity chat, team channels, a "dead players cannot talk" rule or a talking icon over a head (a billboard, section 10.2) are mods; capturing, encoding, sending and mixing voice are not.
9.8 Mods working together
Everything between two mods goes through the host, which copies the values and knows who is calling.
Exports: a mod as a library. Whatever a mod's entry module exports, a dependent can import:
// mooki/item-names (a library)
export function displayName(item: string): string { /* ... */ }
// mooki/heart-tracker, with "mooki/item-names >= 2.0.0" in its dependencies
import { displayName } from "mod:mooki/item-names";
const name = await displayName("Rupee_Blue");
- Calls to another mod are asynchronous (they return a Promise). The function runs in the other mod's runtime at a serial phase. This costs a little convenience and keeps the door open to moving mods out of the game process later, and to a mod in another language.
- Time is charged to the caller's budget. Only a declared dependency can be imported.
- A library ships its
.d.ts; the portal publishes it with the release.
Events. longshot.mods.emit("changed", data) publishes mooki/heart-tracker:changed; any mod can listen. The
host stamps the sender, so a mod cannot speak as another. This is the coupling for optional dependencies.
Registries: shared lists several mods add to, for the things that otherwise collide. The engine registers its own entries the same way.
| Built-in registry | Mods add | The game resolves |
|---|---|---|
keybinds |
Actions with a default key | Conflicts shown and rebound in the menu |
hud |
<Hud anchor> trees |
Trees on one anchor stack; the player can move and hide each |
markers |
Points on the map or in the world | One marker layer any minimap or compass can draw |
commands |
Named commands with typed arguments | One command palette |
items, locations, actors |
Names and metadata for new or renamed things | One table trackers and randomizers read |
Permissions do not leak across mods. A function runs with the permissions of the mod that defined it, so:
- The callee always knows the caller (
longshot.mods.caller). - An export can require a permission of its caller, enforced by the host:
export const grant = longshot.mods.guard("items.grant", (item) => longshot.items.grant(item)); - The portal flags a mod that holds a medium or higher permission and exports functions without a guard.
- The game-data rule (section 12.5) holds across exports, events and registries.
Conflicts, visible before they break a save.
- Filters and data rules chain in load order.
- Claims are exclusive. The reward table, taking over the controller, the save profile, a path given by
romfs.provide: a mod lists them in"claims". Two enabled mods with one claim is a conflict shown before the game starts, without either author having heard of the other. - Patches report same-key conflicts (section 6.2); opaque files report overlapping paths.
In a room. "multiplayer" says who needs the mod: "local" (each player's choice: a HUD), "all" (everyone,
same version: a randomizer), "host" (only the host). Joining compares the "all" mods' ids and versions and a
fingerprint of the merged game data and save-scoped settings, so two players whose patches fold to different
data are caught even when their mod lists look alike. A mismatch is refused with the list, and the launcher
offers to sync. A mod with state.write or items.grant cannot declare "local".
9.9 Input
The game reads the controller once a frame, at one place (host/nn_hid.c), which is a serial point. Everything
here hangs off that read.
Actions: the normal way to take input. A mod declares named actions; the player rebinds them in the menu with
everything else, conflicts are detected by the keybinds registry, and <ButtonPrompt action> shows the right
glyph for the player's device.
const toggle = longshot.input.action({
id: "toggle-view", label: "First person",
default: { key: "V", pad: "RS" }, // a key and a pad button; chords like "L+RS" allowed
consume: true, // while bound, the game does not also see this press
});
toggle.on("press", () => { rig.enabled = !rig.enabled; });
toggle.held; // for hold actions
Reading what the game sees (input.read): buttons, both sticks, triggers, gyro, and which kind of device is
in use, as the game got them this frame. With longshot.input.pointer.capture() (only while the mod's own window or
camera rig is active) a mod also gets mouse movement as deltas, for mouse look.
Changing what the game sees (input.write): a filter at the game's controller read, and timed presses, the
same thing the control bridge's inputs are today.
longshot.input.filter((pad) => { // remap, add, suppress; runs once a frame, serial
if (pad.buttons.L && pad.buttons.R) pad.buttons.ZL = true;
pad.left.x *= southpaw ? -1 : 1;
});
longshot.input.press("A", { frames: 2 });
- Filters chain in load order. Taking the controller away from the player entirely is the exclusive claim
input.exclusive, so two such mods conflict before the game starts. longshot.input.rumble({ low, high, ms })plays on the active pad (low risk, rate-limited).- No raw keyboard. A script sees its own actions, the game's buttons, and text the player submitted to its own
<TextInput>. It never sees arbitrary keys, so a mod cannot log what the player types, and it sees the mouse's position only over its own windows. - A mod's input can never answer a permission prompt or operate the Insert menu.
- Head and hand poses (
longshot.input.poses) appear when the engine has VR (section 10.5).
9.10 Camera
The engine already changes the camera in three ways: the free camera rewrites the gameplay view after the game's
own update (hos_oot_free_view), the field-of-view row scales the angle before the projection is built
(host/oot_fov.c), and native mouse look sets the player camera's yaw and pitch (host/mouse_native.c). The camera
service is those three as one mechanism, which mods use too.
Reading (state.read): eye, target, up, field of view, and the camera's mode (gameplay, aiming, lock-on,
event), each frame.
Rigs: the normal way to control it (camera.control). A rig is data the engine evaluates in C at the game's
camera site every frame, so it has no frame of delay and runs no script there:
const rig = longshot.camera.rig({
attach: longshot.player, bone: "Head", offset: [0, 0.05, 0.08], // metres, in the bone's space
look: "input", // yaw and pitch from the camera stick or mouse; or "bone", "target", "fixed"
pitchLimits: [-80, 80],
fov: 75, near: 0.05,
when: ["gameplay", "aiming"], // event cameras keep their authored view unless "event" is listed
drivePlayerFacing: true, // the game's own camera yaw follows, so "forward" on the stick is where you look
collide: false,
blendMs: 150,
});
rig.enabled = true;
A scripted view, for what a rig cannot describe (a photo mode on rails, a cinematic, a replay camera):
longshot.camera.override((view, dt) => { view.eye = ...; view.target = ...; view.fov = ...; }). It runs in the
serial phase and applies to the next frame.
How it behaves:
- The view is replaced after the game's own camera update and before projection and culling, where the free camera and the field-of-view row sit today. So culling, upscaler jitter and motion vectors follow the new view, and the game's source camera is never written: disabling a rig restores the game's view on the next frame.
- The game's collision, lock-on and scripted cameras still run underneath;
whendecides which of them the rig yields to. - A camera far from Link shows what the game has loaded there, which may be nothing. That is the free camera's limit today and stays one.
camerais an exclusive claim. A first-person mod and a photo mode cannot both own the view; the conflict is shown before the game starts. The engine's free camera is a rig like any other.- What a first-person view also needs, and where it comes from: hiding Link's head without losing his shadow
(
longshot.player.model.setVisible("Head", false, { shadows: true }), unverified: needs a model-part visibility service), mouse look (input.pointer.capture), and the aim reticle (the HUD).
10. Graphics: world drawing, models, shaders
Scripts never get a Vulkan handle. They describe what to draw as data, and the renderer draws it, as with UI.
10.1 The world layer
A list of things the renderer draws inside the 3D scene, depth-tested against the game's own depth, before the game's HUD:
const w = longshot.gfx.world;
w.line(a, b, { color: "#ffcc00", width: 2 });
w.circle(pos, { radius: 1.5, color: "accent" }); // on the ground
const hat = await longshot.assets.model("assets/hat.glb"); // the mod's own glTF
w.model(hat, { at: pos, rotation, scale: 1 });
- Primitives: lines, circles, boxes, quads with a texture, and models from the mod's own glTF files (static first; skinned later).
- Objects are handles the mod updates or removes; nothing is resent each frame unless it changes.
- They are lit by a simple model with the scene's sun direction, not by the game's own lighting and shadows. That is the honest limit: a world-layer model looks like an overlay object, not like a game actor.
- To look native, a thing has to be a game actor: spawned through
actors, using an existing class and a model file from the file layer. Co-op's remote players should be game actors for that reason. - Attaching to an actor or a bone (
{ attach: actor, bone: "Head" }) needs the skeleton service; later, unverified. - Limits per mod: 2,000 objects, 200,000 triangles, 64 MB of meshes and textures.
10.2 Billboards: UI in the world
Any UI tree can be placed in the world. It is the same components as the HUD (section 11), on a fourth surface:
<World at={enemy.pos} offset={[0, 2.2, 0]} billboard maxDistance={40} occlude>
<Column align="center">
<Text outline>{name}</Text>
<Progress value={enemy.life} max={enemy.maxLife} width={120} />
</Column>
</World>
billboardfaces the camera; without it the panel has a fixed orientation (a sign, a screen on a wall).occludehides it behind geometry using the game's depth;maxDistancefades it out; size can be fixed in metres or constant on screen.atmay be a position or an actor handle, which the renderer follows every frame with no script running.- For a flat marker on the HUD that tracks a world position,
longshot.ui.project(pos)gives screen coordinates. - World panels are display only: they take no input. (A "look at it and press A" interaction is a later hook.)
10.3 Shaders
Mods can supply their own fragment shaders in two places:
| Where | What it does | Inputs |
|---|---|---|
| Screen effects | A pass over the picture: colour grading, a CRT look, outlines, underwater tint | Scene colour, scene depth, time, resolution, the mod's own uniforms and textures |
Materials for the mod's own drawing (world quads and models, <Canvas>) |
How the mod's own things look | The object's texture, UVs, normal, colour, time, uniforms |
const grade = await longshot.gfx.effect({
fragment: "assets/sepia.frag", stage: "scene", // before the HUD; "final" is after it
uniforms: { amount: 0.6 },
});
grade.set({ amount: 0.8 }); grade.enabled = false;
How this stays safe:
- Shaders are authored GLSL in a fixed template: one fragment entry point, declared inputs only. No compute, no vertex stage, no arbitrary bindings, bounded loops and texture reads.
- They are compiled to SPIR-V by a pinned compiler that is ours (in the portal's build and in the launcher and dev tool), never taken as binary from a mod. The renderer checks the result against the template's interface and capability list before making a pipeline.
- A shader's output goes to the screen. Nothing reads it back into a script, so a shader that samples the scene cannot be used to copy the picture out.
- Effects are ordered by the
effectsregistry; the player can switch each off; they run after upscaling at output resolution unless they ask for scene resolution. gfx.shaderis a medium permission: a GPU driver compiles the result, which is the same exposure as a web page's WebGL.- GPU time is measured per effect and shown beside the mod's CPU time.
10.4 Not offered: replacing the game's own shaders
The game's shaders are console GPU binaries that Longshot recompiles per program and variant. Editing one means shipping a derived game file, and there is no stable name to patch by. Screen effects and material parameters in the file layer cover most of what people want from this; a named hook on specific material inputs could come later.
10.5 First person and VR
First person is a mod, with what sections 9.9 and 9.10 give: a rig on Link's head bone, an action to toggle it, mouse or stick look, the head hidden, a reticle on the HUD. It needs no engine change beyond the camera and input services, and it answers issue #922.
VR is an engine feature that mods plug into. A sandboxed script cannot do the parts that make VR work: an OpenXR session in the renderer, two views per frame, and the head pose applied at the last moment before the picture is shown. That is renderer work with open questions of its own (drawing the scene twice in a CPU-bound game, or reprojecting one view; what the upscalers and frame generation do with two eyes), and it is not designed here. What this spec fixes is the contract around it, so that mods written before VR exists keep working in it:
| A VR-ready mod uses | Which is |
|---|---|
camera.rig({ look: "head" }) |
The same rig, with orientation from the headset instead of the stick. On a flat screen "head" falls back to "input" |
longshot.input.poses |
Head, left hand and right hand as positions and rotations, plus the usual actions for their buttons |
<World> panels |
UI placed in the world. In VR the engine shows the HUD and the menus on a panel too, so a mod's <Hud> needs no change |
longshot.has("xr"), longshot.xr.active |
Whether a headset is in use, to change comfort settings (snap turning, vignette as a screen effect) |
| World-layer models attached to a hand pose | A sword or a pointer in the hand |
Aiming with a hand, or swinging the sword by motion, need named hooks on the game's aim and attack inputs; those are gameplay hooks like any other and can be added when someone builds it.
11. Custom UI
Mods get a real UI toolkit: components written in TSX, a small set of built-in elements, and three places to put them (the HUD, windows, the mod's settings page, and panels in the world). The same components work in all four.
11.1 The model
mod's script (sandboxed) host renderer module
┌──────────────────────────────┐ tree or ┌───────────┐ per-frame ┌─────────────────────┐
│ components (TSX) + hooks │ patches ──▶ │ validate, │ ─────────▶ │ layout (flex), draw, │
│ reconciler (JS, in the mod's │ │ cap, own │ │ focus, controller │
│ own runtime) │ ◀── events ── │ handles │ ◀───────── │ navigation, text │
└──────────────────────────────┘ └───────────┘ input └─────────────────────┘
- The script describes UI as a tree of elements. The reconciler (the part that reruns components and works out what changed) is JavaScript that ships with the API and runs inside the mod's own sandbox. So it adds no trusted native code, and a bug in it harms only that mod.
- The host receives plain data: element type, props, children. It validates and caps it (section 12.6), then hands it to the renderer, which does layout and drawing in the Insert menu's style and owns focus, controller and mouse navigation, scrolling and text entry.
- Events (a press, a changed value, submitted text) come back to the script at the next
frame. - A mod never gets ImGui, a Vulkan handle, a font atlas or a pixel of the screen.
11.2 Three ways to write it, one tree
The tree is data, so it is not tied to TypeScript: any runtime (section 7.1) builds the same tree with h().
TSX, the recommended way. tsconfig.json sets "jsx": "react-jsx" and "jsxImportSource": "longshot/ui", and
tsc or esbuild compiles it (the game runs the resulting .js):
import { Window, Column, Row, Text, Button, TextInput, List, Badge, useState } from "longshot/ui";
function RoomWindow({ room }: { room: Room }) {
const [draft, setDraft] = useState("");
return (
<Window id="room" title="Co-op room" width={420}>
<Column gap={8}>
<Text>Room {room.code}</Text>
<List items={room.players} keyOf={(p) => p.id} render={(p) => (
<Row gap={8}><Text grow>{p.name}</Text><Badge>{p.map}</Badge></Row>
)} />
<Row gap={8}>
<TextInput grow value={draft} onChange={setDraft} placeholder="Message"
onSubmit={() => { room.chat(draft); setDraft(""); }} />
<Button onPress={() => room.leave()}>Leave</Button>
</Row>
</Column>
</Window>
);
}
const win = longshot.ui.mount(<RoomWindow room={room} />);
win.open();
The direct API, for plain JavaScript with no build step. TSX compiles to exactly these calls:
const { h, Window, Text, Button } = longshot.ui;
longshot.ui.mount(h(Window, { id: "hello", title: "Hello" },
h(Text, null, "No compiler needed"),
h(Button, { onPress: () => longshot.log.info("pressed") }, "OK")));
Free drawing, for what elements cannot express (a minimap, a graph, a marker in the world). <Canvas> is an
element like any other, so drawing sits inside layout:
<Canvas width={200} height={200} onDraw={(d) => {
d.circle({ x: 100, y: 100, r: 96, stroke: "#ffffff" });
for (const m of markers) d.image(icon, { x: m.x, y: m.y, size: 16 });
}} />
d has text, rect, line, circle, path, image, clip and measure. On the HUD,
longshot.ui.project(worldPos) gives screen coordinates for a world position (name tags over co-op players).
11.3 Components and state
Function components and a deliberately small, React-shaped set of hooks, because that is the shape people and AI tools already know:
| Hook | Does |
|---|---|
useState, useReducer, useRef, useMemo, useEffect |
As in React, with the same rules |
useGame(selector) |
Reads game state and re-renders the component only when the selected value changes, at update |
useSetting(id) |
A setting's value and setter (section 11.5) |
useEvent(target, name, fn) |
Subscribes for the component's lifetime |
useFrame(fn) |
Runs every game frame (animation); the one hook that costs every frame |
It is not React: no DOM, no CSS, no portals, no suspense, no class components, no third-party React libraries.
The spec names the subset so nobody expects more. A tree re-renders only when its state, a useGame selection or
its props change, so an idle window costs nothing per frame.
11.4 Elements
| Kind | Elements |
|---|---|
| Layout | Row, Column, Stack, Grid, Scroll, Spacer, Divider, Tabs / Tab, Section |
| Content | Text, Image, Icon, Badge, Progress, ButtonPrompt (the pad's or keyboard's glyph for an action), Canvas |
| Input | Button, Toggle, Choice, Slider, TextInput, Keybind, List (virtualised, selectable) |
| Surfaces | Hud, Window, SettingsPage, World |
- Layout is a flexbox subset:
gap,padding,grow,width,height,align,justify,wrap. Sizes are in a 1920x1080 virtual space the renderer scales to the picture, ultrawide-aware likehost/hos_wide_ui.c. - Style is tokens, not free CSS:
color="accent" | "muted" | "danger" | "#rrggbb",size,weight,outline. Defaults match the Insert menu, so an unstyled mod already looks like part of the game. - Controller navigation is automatic. The renderer builds focus order from layout. A mod can hint
(
focusKey,autoFocus) but cannot break it. ImageandIcontake the mod's own assets (from the mod's own folder: PNG, decoded by the host, size capped).ButtonPromptuses the prompt artwork Longshot already ships, so mod UI shows the player's actual controller.- Text is plain text: no markup, no links.
11.5 Settings, and a mod's settings page
Every mod has a page in the Mods tab of the Insert menu. The engine's own tabs are built from the same settings registry (section 4), so a mod's rows and the game's rows are the same thing. The game draws the page's frame: the mod's name, version, author, on/off switch, permissions, frame time. The mod's own settings are embedded below it. Two levels:
Declared settings (most mods need only this). They are data, so they can be listed in mod.json and shown and
edited by the launcher too, without the game running, as Factorio's mod settings are:
"settings": [
{ "id": "corner", "type": "choice", "label": "Position", "options": ["Top left", "Top right"], "default": 0 },
{ "id": "scale", "type": "slider", "label": "Size", "min": 50, "max": 200, "step": 10, "default": 100, "unit": "%" },
{ "id": "toggleKey", "type": "keybind", "label": "Show or hide", "default": "F6" }
]
Types: toggle, choice, slider, number, text, keybind, color. Each may carry help (shown in the
menu's help box), restart: true, and scope: "global", "profile" or "save". With nothing else, the game
generates the page from these rows, drawn by the menu's own row code. The script reads them with
longshot.ui.settings.get("scale"), useSetting("scale"), or settings.on("changed", ...). Values live in the
mod's storage and travel with a launcher profile.
A custom settings page, when rows are not enough (a preview, a list the player edits, a "Connect" button with live status). The mod mounts a component on the settings surface, and it is embedded in the same place:
import { SettingsPage, Section, SettingRow, Row, Text, Button, Badge, useSetting } from "longshot/ui";
function Settings() {
const [server] = useSetting("server");
const status = useConnection();
return (
<SettingsPage>
<Section title="Server">
<SettingRow id="server" /> {/* a declared setting, drawn as the standard row */}
<SettingRow id="slot" />
<Row gap={8}>
<Badge color={status.ok ? "accent" : "danger"}>{status.text}</Badge>
<Button onPress={() => connect(server)}>Connect</Button>
</Row>
</Section>
<Section title="Display"><SettingRow id="corner" /><SettingRow id="scale" /></Section>
</SettingsPage>
);
}
longshot.ui.settings.page(<Settings />);
<SettingRow id>places a declared setting as the standard row, so custom pages stay consistent and the launcher can still show those settings.- The page is rendered only while the player looks at it. It scrolls inside the tab; it cannot leave its area or draw over the game-drawn header, so the on/off switch and the permissions are always reachable.
- If the mod is off, stopped or its page throws, the game falls back to the generated rows, so a broken page never locks a player out of a mod's settings.
11.6 Surfaces and their rules
| Surface | Mounted with | Shown | Permission |
|---|---|---|---|
| HUD | <Hud anchor margin> |
With the game's HUD, under the Insert menu; reused for generated frames; hidden when the game hides its HUD | ui.hud |
| Window | <Window id title> |
Floating; opened by the mod or from a keybind; closed by the player with the usual button | ui.window |
| Settings page | ui.settings.page(...) |
Inside the mod's page of the Mods tab | ui.settings |
| World | <World at billboard> |
In the 3D scene, depth-tested, following a position or an actor (section 10.2) | gfx.world |
- Windows carry the mod's name in a title bar the game draws. A mod cannot make a window that looks like a permission prompt or the game's own dialogs, and cannot remove the title bar.
- The Insert menu and permission prompts are always on top and take all input while open.
- A window takes input only while focused. The HUD never takes input.
- Limits: 4 windows and 2,000 elements per mod, 10,000 draw commands per canvas, 16 MB of images.
11.7 Not planned: the game's own layouts
Driving the game's NintendoWare UI panes from a script (a new icon in the pause screen, for example) needs engine knowledge nobody has mapped for scripts yet. A RomFS mod can already replace a layout file, and one mod on #134's stack adds its own screen to the game's menu with layouts written by a tool. Known rules: the layout archive stores every layout four times and all four must change; panes are stored in pre-order; an animation on a pane's alpha does not reach the children of a child pane that has its own. A pane API could come later as named hooks on specific screens.
12. The sandbox
12.1 What we defend against
A mod is assumed hostile. It may try to: read or write the player's files; reach the network; send game data out; damage saves; show a fake prompt; stall or crash the game; attack another mod; or exploit a bug in the interpreter, the API's C code, the game's parsers or the GPU driver.
12.2 The base: the process is the sandbox, for everyone
The game process runs confined for every player, modded or not: an AppContainer on Windows (the test farm already runs the game in one, #544), Landlock plus a network restriction on Linux. Read access to the game folder, write access to the user folder, no network.
- A script escape, a hostile file or an unsafe mod then wins a process that can only touch its own folder.
- "Game data stays on the PC" is enforced by the operating system, not by a check a memory bug could skip.
- Because vanilla runs in the same sandbox, the confined path is the one everybody tests.
This has no owner or open proposal today, and co-op, the Discord status and the updater have to be checked against it. Decided 2026-11-16: the portal does not wait for it, and review is by what a mod carries, not by a blanket rule (section 15.4): script and typed-patch mods publish on automatic checks, and mods that replace game files need a person's approval for every update. Until the game runs confined, a script mod that found an interpreter bug would win the game process, not just its sandbox. That risk is accepted for the time being and is the reason the sandbox still matters.
12.3 The language gives nothing
A fresh interpreter has no I/O. We add only longshot. No std, no os, no FFI, no native modules, no eval, no
bytecode. Built-in prototypes are frozen before the mod's code runs. One runtime per mod.
12.4 Permissions
| Permission | The player is told | Risk |
|---|---|---|
state.read, actors.read, items.read, input.read, content.read |
Can see what happens in your game | low |
ui.*, gfx.world, gfx.textures, audio, storage, content.patch (typed patches) |
Can draw, play its own sounds, keep its own data, and change game data in checked ways | low |
session |
Can exchange messages with players in your room | low |
state.write, actors.write, items.grant |
Can change your game and what gets saved | medium |
input.write |
Can press buttons for you | medium |
camera.control |
Can move the camera | low |
gfx.shader |
Can run its own graphics effects on your GPU | medium |
net:<origin> |
Can talk to origin | medium |
opaque replacement files, romfs.read, save.flags |
Replaces game files / reads them / changes the save's format | medium |
net:*, net.lan, romfs.provide |
Any server / your home network / game files made at run time | high |
memory.*, hooks.unsafe, exefs (ExeFS patches), cheat files |
Full access to the running game. Only for mods you trust | unsafe |
Grants are per mod and per permission, shown and revocable in the Mods tab. The prompt is the game's own UI,
drawn above everything a mod can draw, and it cannot be answered by input.write. An update that asks for more is
asked about again.
The unsafe tier, stated honestly. memory.write and hooks.unsafe let a mod steer the game's own code, which
can do whatever the game can. The guest window and the nn:: boundary were built for correctness, not as a
security boundary. These mods are marked Unsafe in the same words everywhere, load only on game builds where
their sites resolve, and are reviewed per release on the portal. The process sandbox is what bounds them.
12.5 Game data stays on the PC
romfs.readandmemory.readgive raw game data. Neither can be held together with anynetorsessionpermission. The loader refuses the manifest.- The named API and
content.readreturn facts about play (a position, a flag, an item's name), not assets or code, so they combine withnetfreely. - Nothing reads the screen back as bytes: no screenshot call, no shader readback. A captured thumbnail is an opaque handle a mod can show and keep locally, never read.
- No value crosses from a mod holding raw-data permissions to one holding
net, by exports, events or registries. - The broker is the only process with sockets, and it only knows granted origins (12.7).
12.6 Limits
Section 7.5's budgets, plus: storage 16 MB global and 4 MB per save; 2,000 UI elements and 4 windows; world-layer and shader limits as in section 10; log 100 lines a second; network caps as in 9.4. Hitting a limit is an exception in the script, never a stall in the game.
12.7 The network broker
A small separate process, started only when something needs the network. It holds each mod's granted origins and the room's relay connection, does TLS and DNS, and passes messages over local IPC. The game process has no network access of its own, so an escaped script cannot open a connection the player did not grant. Co-op's sockets live here too. With no mods and no room, it is never started.
12.8 When the interpreter itself has a bug
An in-process interpreter is not a hard boundary by itself. The mitigations: bindings generated from the API
schema, every argument validated and copied, handles never pointers; QuickJS pinned in third_party/ with its
PROVENANCE.md; the bindings, the manifest parser and the patch folder fuzzed against a fake game; and the
process sandbox underneath. Because calls between mods and to the host are asynchronous except for serial
filters, moving the runtimes into their own process later would not change mod code.
12.9 What a mod can still do
A granted mod can do what it was granted: state.write can ruin the save it runs on (hence profiles), a mod's
window can show something misleading inside its own frame, and a net grant tells that server the player's IP
address. The Mods tab says these things in plain words at the grant.
13. Developing a mod
Starting
npm create longshot-mod@latest heart-tracker # asks: TypeScript or JavaScript, UI or not, a starter example
cd heart-tracker && npm install
That gives a normal project: mod.json, src/main.tsx, tsconfig.json, package.json, a test, and
AGENTS.md/README.md that point an AI tool at the types. Nothing about it is special to Longshot except two
dev dependencies.
Packages and types
| Package | What it is |
|---|---|
@longshot/api |
Types only: longshot.d.ts and the longshot/ui JSX types, generated from the API schema. Its version is the API version, so "@longshot/api": "~0.3" in package.json is the mod's "api": "0.3" |
@longshot/mod-tools |
The longshot-mod command: build, watch, test, lint, pack, publish |
- Type checking is plain
tsc --noEmit(and the editor's own). The types carry the documentation, the permission each call needs and its since-version, so a wrong call is red in the editor before the game runs. - Other mods' types.
longshot-mod add mooki/item-namesadds the dependency tomod.jsonand fetches that library's.d.tsfrom the portal intotypes/, soimport ... from "mod:mooki/item-names"is typed. A lock file records versions and hashes. - npm libraries are allowed and bundled. The build bundles pure-JavaScript packages into the mod with esbuild. Anything that needs Node or the browser fails at build time, not in the game. The portal rebuilds from source with the lock file and install scripts off, so the package players get is what the source says.
- Packages are published to npm and to the Forgejo's package registry, so no account elsewhere is needed.
The loop
| Command | Does |
|---|---|
longshot-mod dev |
Watches, type-checks, builds to the game's mods folder, and tells the running game to hot-reload (section 7.6) through the control bridge. Errors appear in the terminal and in the game with source-mapped stacks. console-style logs stream back |
longshot-mod test |
Runs the mod's tests against the fake game: scripted events ("map loaded", "enemy defeated", "setting changed"), UI you can query and press, fake time, a fake room with fake peers. No game, no dump, any PC, any CI |
longshot-mod lint |
Checks the manifest; compares the permissions the code uses with the ones it declares; refuses game-derived bytes in the package |
longshot-mod pack / publish |
Builds the package; opens the portal submission (section 15.3) |
longshot-mod sites port |
For unsafe mods: re-finds hook sites in another game build (section 8.3) |
- In the game, dev mode adds a small overlay: per-mod frame time, a filter trace, a UI inspector, and reload.
- The control bridge gains
mod.reloadandmod.eval, scoped to one mod and its permissions. - For AI tools: one
.d.tsis the whole API;longshot-mod testgives a pass/fail loop with no game; the template and three examples (a HUD, a data rule, a network client) are the reference. - Plain JavaScript needs none of this: write
main.jsagainstlongshot.ui.h(...), put the folder inmods/. - Content-only mods need no Node at all: patches are JSON files.
longshot-modcan still lint and pack them, and a companion tool lists patchable names (texture names, table keys, parameter keys) from the player's own dump, locally.
14. Lifecycle and compatibility
For the player
- The Mods tab lists mods with their state (on, off, needs permission, needs rebuild, not available for this game version, stopped after faults), permissions, CPU and GPU time, and settings page.
- Safe start: a launcher switch starts the game with no mods. A start that crashed before the title screen with mods on offers it next time.
- Crash records and bug reports name the enabled mods and versions.
- Defaults are right for everyone: there are no player knobs for budgets or sandbox strength.
- Fail loudly. Where something is missing (a site, a dependency, a feature), the mod does not load and says why. Nothing is half-applied with a warning.
14.1 Compatibility
| Axis | Declared by | On a mismatch |
|---|---|---|
| API | "api": "0.3" |
While the API is 0.x, a minor may break and the portal marks which releases fit. From 1.0, minors only add; a mod for 1.3 runs on 1.9. There are no side-by-side majors and no shims before 1.0 |
| API features | "requires"; longshot.has() for optional ones |
A named hook can be missing on one game build until its site is mapped. A required feature that is missing keeps the mod off, with the reason |
| Longshot | "longshot >= 0.9.0" |
The launcher offers the update |
| Game version | "game.builds": ["*"], or resolved sites for unsafe mods |
Named sites relocate by signature and the team fixes the rest. Unsafe mods load where their sites resolve |
| Other mods | Dependencies, !, claims |
Resolved before the game starts |
- Everything is decidable before the game starts, from manifests alone.
- Every Longshot release is tested against the portal first. CI runs every portal mod's latest release in the fake game against the release candidate. A break is either our regression (fixed before release) or a real change (the author is told, the notes say so).
- Profiles pin versions, so a profile, a save and a room reproduce exactly. Updating is the player's action.
- 1.0 has an entry test (section 18.1): real ports of a gameplay feature, a tracker and an actor-heavy mod.
- A save records the mods it was written with; loading it with one missing or older warns and offers sync.
- Find the broken mod: the launcher bisects the enabled set across a few starts until one mod is named.
15. The mod portal and the launcher's mod manager
Factorio is the model: one portal, a manager built into the product, dependencies resolved for the player, mod settings in one place, and "sync mods with this save".
15.1 The mod manager in the launcher
A Mods page in LongshotLauncher:
- Installed: every mod, with its version, state, permissions and an on/off switch. It reads and writes the one mod list (section 5.4), so it and the game's Mods tab always agree.
- Browse: search the portal by name, owner, tag and category. By default it shows only what fits the player's Longshot and game version. A mod's page shows description, screenshots, versions, dependencies, permissions in the same words as the game's prompt, and whether it is Unsafe.
- Install resolves dependencies with the game's resolver, shows the whole set and what each asks for ("installs
3 mods; ana/minimap will be able to talk to tiles.example.org"), downloads, checks each package's hash against
the signed index, and unpacks (links, absolute paths and
..refused). It also compiles shaders and builds merged files, so the first start is not the slow one. - Updates: checked when the launcher opens, applied when the player says so. A new permission is called out.
- Declared settings (section 11.5) can be edited here without starting the game.
- Profiles: named sets of enabled mods, pinned versions, settings and saves (section 9.6): "vanilla", "randomizer seed 12", "co-op with friends". A profile exports as a small file of ids and versions, which a friend's launcher installs from the portal: a modpack.
- Sync: a save and a room record the mods they were made with; the launcher offers to install and enable exactly those.
- Add from file: a
.lsmod, a zip or a folder is copied into themodsfolder as a local mod (section 5.5). Emulator mods are not converted. Opening a.lsmodfile starts the same prompt. - Rebuild for mods (section 8.3), Safe start and Find the broken mod (section 14) live here too.
The launcher is the only part that downloads. The game never fetches mods.
15.2 The repository of mods
The portal's source of truth is a git repository on the team's Forgejo, MagicBeanDev/Mods: an index, not a
copy of every mod.
mods/mooki/heart-tracker/mod.toml source repository, categories, summary
mods/mooki/heart-tracker/releases.json per version: package URL, hash, size, manifest copy, review state
- A mod's source lives in its author's own git repository. A release is a tag; its package is built by the index's CI from that tag (lock file honoured, install scripts off, shaders compiled by our compiler), so what players get is what the source says.
- CI publishes one static, signed
index.json. The launcher and the website read that file: no database, a mirror can serve it, and the history of who published what isgit log. - The owner part of an id is the publishing account (section 5.1), so ownership needs no separate record.
15.3 Submitting a mod
- From git. A pull request to the index that adds or changes the mod's entry. For a script or typed-patch mod it merges on green checks alone: push a tag, the release is out in minutes. A mod that replaces game files waits for a person's approval each time (section 15.4).
- From the dashboard. A page on the Longshot website, signed in with the same Forgejo sign-in: "My mods",
"Submit a mod" (a repository URL or a zip), release notes, screenshots, download counts. Behind it the
dashboard opens that same pull request, so there is one process and one audit trail, and an author never has
to know git exists.
longshot-mod publishdoes the same from the terminal.
15.4 What the portal checks
Automatic, on every release:
- The manifest is valid, the owner matches the account, the version is new, the licence is stated, dependencies exist.
- No game files. A package may hold scripts, typed patches, text, upscale recipes, and authored images, sounds,
models and shader source. Textures made from the game's own (upscaled, repainted) are refused (section 6.3).
Files in the game's own formats (a
romfs/tree) are allowed only through approval, below, because a check cannot tell an authored one from an edited copy. Images are compared against hashes of the game's own, kept as hashes only. - No hidden code: no binaries, no interpreter bytecode, no bundle without its source in the tagged repository.
- The permission set and its diff from the previous version, shown on the mod's page.
- The mod loads in the fake game (section 13) and its own tests pass; its patches fold without error on the supported game versions' key lists.
Who approves what (decided 2026-11-16):
| A release that carries | Published by |
|---|---|
| Scripts on the sandboxed API, typed patches, text, authored textures, sounds, models and shaders | Automatic checks alone, for the first release and every update. Push a tag, it is out in minutes |
Replacement game files (a romfs/ tree of opaque files), or romfs.provide |
A person approves every release, updates included. The reviewer checks that the files are authored, not copied or edited from the game, and that they are what the mod says |
Unsafe permissions (memory.*, hooks.unsafe, ExeFS patches, cheat files) |
A person approves every release |
A release that adds net:*, net.lan or a medium-or-higher permission the previous version did not have |
A person approves that release; later ones without a new permission are automatic again |
- A mod's page says which of these it is, so players can see "updates are reviewed" or "updates are automatic".
- An update that changes only the script of a file-replacing mod still waits for approval: the rule follows the package, so it stays simple to explain.
- Replacement files are still parsed by the game's own code (section 6.6). Approval is a check on where they came from and what they claim to be, not a proof that they are harmless.
Afterwards: a report link on every page; a takedown is a commit that marks a version withdrawn, which the launcher shows to players who have it. Packages are identified by hash, so a withdrawn or altered package cannot come back under the same version.
15.5 The website
A browsable portal on the Longshot site, generated from index.json: search, categories (HUD, content,
randomizer, multiplayer, graphics, library), a page per mod, and an "Install in launcher" link
(longshot://mod/<owner>/<name>). Ratings and comments are left out at first; discussion links to the mod's own
repository.
16. Parity gates: vanilla runs like vanilla
The core in section 4 changes how Longshot's own features are built. These tests are what make that safe, and they run on every change to the core:
- Code parity. Lift the fixture functions with the site table present and no subscribers, and run the existing
comparison against the original instructions (
nx2/test_leaf.py): registers, vector registers and every changed page identical. - Speed parity. The
measureskill, a no-mods build againstmain, inside the 2% neutral band. - Behaviour parity. A scripted input run on a fixed save through the control bridge: map, position and
changed flags match
main. - Save parity. The default profile's save is byte-compatible and loads in the emulators the docs name.
- Nothing started. With no mods: no script runtime, no merged-file cache written, no broker process.
- Refactor first. Each core piece lands with no new feature and the old path removed, so the gates compare like with like.
And three rules for anything added later, borrowed from gen1recomp: a new hook with no subscriber returns the vanilla value; a new registry is a provable no-op when empty; a new event does not build its payload when nothing listens.
17. Order of work
The core first, as refactors; scripts as soon as the services exist; the portal only behind the sandbox.
| Step | What | Proven by |
|---|---|---|
| 0 | Change #134's list to mods.json (section 5.4) |
One file, no legacy on arrival |
| 1 | Hook compiler: the site table; convert existing patches one feature at a time, deleting each text patch | Parity gates 1 to 3; the string matcher deleted |
| 2 | Game services and frame phases; move the Debug tab, the control bridge and the state tap onto them | The second flag reader and the try-lock deleted |
| 3 | Script runtime, read-only API, UI toolkit, HUD, settings, dev tools (can start after step 2) | A heart HUD; an item tracker; a speedrun timer |
| 4 | File layers: opaque files and the computed size table (replacing #134's merge), then pack members, parameter keys, table rows, placements, text | A rebalance mod and a translation with no code; two mods patching one file |
| 5 | Save profiles; storage.save |
A playthrough's mod data survives copy, reload and export |
| 6 | Change and connect: writes, data rules, the item service, net, content.patch from scripts |
A chest randomizer; an Archipelago client |
| 7 | Process sandbox and broker | Vanilla runs confined on both systems |
| 8 | Session API and voice on the engine's co-op | A game mode as a mod; voice in a room |
| 9 | World layer, billboards, texture packs, shader effects; the settings and menu registry | Name tags over enemies; an HD texture pack; a colour-grade effect |
| 10 | Unsafe tier: build-time sites across game versions, memory, rebuild for mods | A mod hooking a function the team never named, on two game versions |
| 11 | Portal (the index and launcher manager can be built from step 3; script mods publish on automatic checks; file-replacing and unsafe mods need approval per release) | One-click install with dependencies |
18. A worked example: the Bestiary / Enemy Editor
longshot-bestiary-features.html describes a developer feature set (a snapshot of a feat/ngplus-dev branch):
despite the name it is an enemy editor, not a player's journal. It is a useful test of the spec because it
needs almost every part. Could it be a mod?
| Its feature | Needs | In this spec | Verdict |
|---|---|---|---|
| Catalog of 376 actor records: categories, search, sort, six tabs, controller navigation | The actor-type list with names and classes; a full window | content.read (the actor tables), the actors registry for readable names, Window, Tabs, List, TextInput |
Fits. The readable names and categories are the mod's own data |
| Live inspection: per-instance HP, max HP, instance id, freshness | Enumerate live actors with stable handles; spawn and remove events | actors.live(), handles with a generation, actor.spawned / actor.removed |
Fits |
| HP and damage multipliers per type and per placement, with inheritance | Max HP at spawn; damage scaled per hit, on a hot path | Data rules (rules.damageDealt.scale, rules.actorLife.scale keyed by type or placement) |
Fits, as data rules. Not a script callback per hit |
| Movement speed, attack cooldown, detection range multipliers | Per-class behaviour values | A parameter patch where the value is data; otherwise a named site per actor class | Partly. The document itself excludes bosses and says it needs "compatible native behavior". A general promise is not possible |
| Global difficulty presets, stored apart from progression | Settings and storage | Declared settings; storage.profile |
Fits |
| Quick Placement HUD (F5 or stick press), prompts, picker | Keybinds, HUD with images, controller prompts | keybinds registry, Hud, ButtonPrompt, Image |
Fits |
| Spawn, respawn, remove enemies | Spawn an existing actor class at a position | actors.spawn(type, pos), handle.remove() (actors.write) |
Fits, with a host cap on live mod-spawned actors (the document uses 16) and a clear "may not work in every area" |
| Ground markers by a free-camera ray using the game's collision | A collision ray query; free camera; ring and beacon in the world; a sound | New: longshot.world.raycast(origin, dir); camera.free (the engine's existing free camera as a service); world-layer primitives; audio |
Fits once raycast is a service |
| Placed Enemies screen, encounter groups | Lists, drafts, per-area data | UI toolkit; storage.profile keyed by area, room and age |
Fits. Limits (16 per area, 256 per profile) are the mod's |
| Labels above editor-spawned enemies | Text following an actor | <World at={actor} billboard> |
Fits, and better: followed by the renderer with no per-frame script, and it can be depth-tested |
| Thumbnails: capture with F11, crop editor, 128 by 128 image, manual import | A picture of the game into a mod-visible image | New, constrained: longshot.capture.thumbnail({ rect, size }) returning an opaque image handle usable in <Image> and storable locally, with no access to its pixels |
Fits only this way. Game pixels as bytes in a script would break the no-game-data rule |
| "Developer NG+ only; normal game unaffected"; progression saves never rewritten | A separate play space | "saves": "separate": its own profile |
Fits exactly; this is what profiles are for |
| The "Model" tab's discovered model information | Model metadata | Names and counts through content.read; no geometry |
Metadata only |
What the example added to the spec: world.raycast, camera.free, opaque thumbnail capture, actors.spawn
with a cap, and life and behaviour data rules keyed by actor type or placement. What it confirms: hot-path
changes must be data rules; in-world labels belong to the renderer; an editor like this wants its own save
profile. Permissions it would hold: actors.read, actors.write, state.write, content.read, ui.*,
gfx.world, audio, storage, input.read, and no network, which the document also says it does not need.
It needs steps 2, 3, 5, 6 and 9 of section 17, and is a good target to build the actor services against.
18.1 Checked against Ship of Harkinian
Ship of Harkinian (the PC port of the original game) is where most people who mod this game's ancestor work, so
its features are the realistic test of this API. What follows is from a contributor's review of Shipwright at
commit 051e497, not re-checked for this page.
How Ship does mods. Asset mods are resource archives (.otr, .o2r) in a mods folder, with enable, disable
and drag ordering in a menu, and a restart to apply. Code mods are C/C++ changes compiled into a custom build:
fork, edit, rebuild, and combine mods by merging branches. Inside that code there is a hook system,
GameInteractor: callbacks for game events, for specific actor ids or pointers, with filters, unregistering, and
registration that follows a setting. Features can also reach any game structure or function directly.
What that means here.
- No Ship mod carries over as it is, in any language. Ship mods use the original game's decompiled structures, actor types and save fields; this is a different engine and different files. C++ would not change that. Ship's asset archives are for the original game's assets and do not convert either.
GameInteractoris the precedent for named hooks (section 8): the same idea, but here behind permissions and a sandbox instead of open C++.- Ship authors are used to deep access. Where the stable API cannot reach, the answer in this spec is the unsafe tier (sites, memory, ExeFS patches); native modules stay issue #42's open decision.
- What decides whether a port is possible is which hooks and operations exist, not the language.
Three ports as a test. One simple gameplay feature, one tracker, one actor-heavy change:
| Ship feature | What it does | Needs here | Covered? |
|---|---|---|---|
| Moon Jump (cheat) | While L is held, sets Link's upward velocity each update | An input action or button read; a write to Link's velocity at update |
Input yes (9.9). Velocity was missing: added as player.velocity and player.setVelocity() under state.write. It needs a motion service and a site in Link's movement; unverified |
| Rupee Dash (mode) | Drains rupees on a timer, faster with a bigger wallet; drains health at zero | Rupees, wallet size and health, read and write; a timer on game time | Rupees and health yes. Wallet capacity and game-time timers were missing: added as player.wallet and longshot.game.every(seconds, fn), which pauses with the game |
| Item tracker (HUD) | Shows what the player has, updating live | Inventory read, item names and icons, HUD | Yes: items, content.read, the UI toolkit. Icons are the game's, shown by name through <Icon item>, never as bytes |
| Enemy randomizer (actor-heavy) | Replaces enemies as rooms load | Change which actor a placement spawns, per map | Yes, as placement patches registered before the map loads (6.2), with no code running at spawn. Per-actor behaviour changes are the hard part and need named sites per class |
Three additions to the API came out of this, and one design point: Ship's "callback for this actor id" becomes,
here, an event filtered by actor type (actors.on("spawned", { type: "Enemy_Octorok" }, fn)) or a data rule,
because actor code runs on job threads where script may not (section 7.4).
A gate before freezing. The API does not become 1.0 until these three kinds of port (a gameplay feature, a tracker, an actor-heavy change) and the enemy editor above have been built on it for real. What they cannot do becomes either a new service or a documented reason to use the unsafe tier.
19. Open questions, and what is unverified
Open questions
- Review capacity. File-replacing and unsafe mods need a person's approval for every release (decided). Who are the reviewers, and what turnaround do authors get?
- Who owns the process sandbox? Script mods are published without review, so until the game runs confined an interpreter bug is the whole distance to the player's files. It has no proposal yet.
- Does the frame have clean serial points? Section 7.4 assumes the game's frame loop has places where no job runs. If it does not, filters get rarer and data rules carry more.
- How much of the item service is knowable? Checks, grants and rewards as clean events depend on finding the game's item-give path for every source (chests, drops, shops, gifts, scripted events).
- Licence. The build is GPL. Whether a script or a patch that only uses the API must carry a compatible
licence needs an answer before the portal opens. The manifest requires a
licenseeither way. - Upscale recipes. Decided: the portal hosts authored textures only. What a recipe may name (which models, run by which tool on the player's PC) still needs a design.
- Lua as well? Section 7.1 makes it possible. One language keeps documentation and examples in one place; this spec recommends waiting until the API is 1.0.
- Who reviews portal mods, and where packages are hosted and mirrored (the index is signed from day one).
- How strict is a room? Section 9.8 compares
"all"mods and the data fingerprint exactly. - Runtime vtable hooks (section 8.1) would make many named hooks free and rebuild-free. Needs a spike.
- Parallel script. Different mods' runtimes are isolated, so their
framehandlers could run on different threads. That needs thread-safe services and loses a defined order; not planned, noted. - Mod bundles of npm code make review harder. Is a size cap and "source must be in the tagged repository" enough?
- One build for all profiles' code mods, or one per profile (section 5.4). Decided already: the build is
passed the list (
--mods), not a user folder or a note. That answers the question in #1097. - Code mods the build takes (section 8.4): every accepted mod in the folder, or only those switched on; and how many mods on one function stay switchable (two today).
- Placing mods' new code so two mods do not claim the same free space (section 8.4). Not built.
Unverified (nobody has tested these; several come from the research notes' own list)
- The size rule per file type, beyond the types
host/restbl.chas measured (section 6.1). - That the game loads a table written by a host tool. (Packs, the layout archive and text archives: verified.)
- Whether the game prefers a loose file over the same path inside a pack.
- Both ways of connecting a texture name to an upload (section 6.3).
- Whether a map can load without its baked data.
- The sandbox details on either system; how co-op, Discord status and the updater behave inside it.
- Shader compilation at install time on players' PCs (compiler size, time, driver differences).
- Skeleton access for attaching world-layer models and camera rigs to bones; hiding a part of Link's model.
- That driving the game's own camera yaw from a rig behaves in every camera state (native mouse look does it for the free-control states only).
- Anything about VR rendering.
- A supported way to write Link's velocity (section 18.1).
- Whether Longshot still syncs
host/andnx2/from mkw-recomp. If it does, the core stays in new files.
Credits
This page is HumanBean's draft. It stands on other people's work:
- snaildev99 ported the Mods tab draft to Longshot (#134) and built the code mod work on top of it: code modules, the switch without a build, patch clashes, hooks that return with a branch, merged archives and the size table inside packs. Their feedback in #1097, with a census of nine public code mods, corrected sections 5.4, 5.5, 6.1, 8.4 and 11.7 and is the basis of section 8.5.
- mooki opened the tiered mod interface discussion this page extends (#42) and wrote the multiplayer work the session API is designed around (#68).
- The testers on #134, whose runs found the half state between switching a code mod and building it.
- The authors of the research notes on the game's files and moddability (section 3), and of the review against Ship of Harkinian (section 18.1).
- Ship of Harkinian, whose hook system is the precedent for named hooks, and Factorio, whose mod portal and dependency rules sections 5 and 15 follow.
Appendix: related pull requests and issues
| # | What it is |
|---|---|
| #42 | The tiered mod interface discussion this page extends |
| #134 | Mods tab, the mod list (mods.json), merged size tables, build-time ExeFS patches, cheat files. Everything below is stacked on it |
| #305 | The restart question names which mods were switched |
| #940, #942 | Say when a mod's code is not loaded; size table entries for files inside packs |
| #960, #961 | A hook that returns with a branch; two mods' patches on one place |
| #984 | A mod's code module (exefs/subsdk*) built in with the game |
| #1036 | A code mod switched at a restart, without a build |
| #1089 | An archive several mods ship, merged member by member |
| #1097 | Feedback on this page from that work, with a census of nine public code mods |
| #68, #355, #463 | Co-op rooms, relay and progress sync; presence and isolated saves; the path from playtest to merge |
| #544 | The control bridge inside an AppContainer |
| #928 | The frame-time Breakdown that would show mod time |