13 Modding API Spec
HumanBean edited this page 2026-11-16 19:57:24 +00:00

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:

  1. 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.
  2. Scripts in TypeScript/JavaScript, each in its own sandboxed interpreter, talking to the game only through the longshot API and only with permissions the player granted.
  3. 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.py measured 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 is you/minimap.
  • Ownership is the namespace, checked by the portal at publish. longshot/... is reserved for the engine's own built-in content and libraries, and local/... 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 --mods the 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/ .ips and .pchtxt patches 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 layout atmosphere/exefs_patches/<name>/*.ips is 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 main or main.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 .zip of 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.ts for 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, WebAssembly and QuickJS's std and os modules. 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.
  • frame fires once per game frame (generated frames do not count). update fires 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, and longshot.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.
  • builds is 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.py builds 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 exefs permission, 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 bl and go back with b <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 in nx2/oot_patches.py edits 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 PermissionDenied naming 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 @since on 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: and https:. Loopback, private and link-local addresses are refused unless the mod holds net.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 session is "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; when decides 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.
  • camera is 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>
  • billboard faces the camera; without it the panel has a fixed orientation (a sign, a screen on a wall).
  • occlude hides it behind geometry using the game's depth; maxDistance fades it out; size can be fixed in metres or constant on screen.
  • at may 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 effects registry; the player can switch each off; they run after upscaling at output resolution unless they ask for scene resolution.
  • gfx.shader is 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 like host/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.
  • Image and Icon take the mod's own assets (from the mod's own folder: PNG, decoded by the host, size capped). ButtonPrompt uses 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.read and memory.read give raw game data. Neither can be held together with any net or session permission. The loader refuses the manifest.
  • The named API and content.read return facts about play (a position, a flag, an item's name), not assets or code, so they combine with net freely.
  • 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-names adds the dependency to mod.json and fetches that library's .d.ts from the portal into types/, so import ... 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.reload and mod.eval, scoped to one mod and its permissions.
  • For AI tools: one .d.ts is the whole API; longshot-mod test gives 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.js against longshot.ui.h(...), put the folder in mods/.
  • Content-only mods need no Node at all: patches are JSON files. longshot-mod can 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 the mods folder as a local mod (section 5.5). Emulator mods are not converted. Opening a .lsmod file 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 is git 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

  1. 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).
  2. 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 publish does 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:

  1. 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.
  2. Speed parity. The measure skill, a no-mods build against main, inside the 2% neutral band.
  3. Behaviour parity. A scripted input run on a fixed save through the control bridge: map, position and changed flags match main.
  4. Save parity. The default profile's save is byte-compatible and loads in the emulators the docs name.
  5. Nothing started. With no mods: no script runtime, no merged-file cache written, no broker process.
  6. 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.
  • GameInteractor is 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

  1. 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?
  2. 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.
  3. 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.
  4. 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).
  5. 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 license either way.
  6. 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.
  7. 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.
  8. Who reviews portal mods, and where packages are hosted and mirrored (the index is signed from day one).
  9. How strict is a room? Section 9.8 compares "all" mods and the data fingerprint exactly.
  10. Runtime vtable hooks (section 8.1) would make many named hooks free and rebuild-free. Needs a spike.
  11. Parallel script. Different mods' runtimes are isolated, so their frame handlers could run on different threads. That needs thread-safe services and loses a defined order; not planned, noted.
  12. Mod bundles of npm code make review harder. Is a size cap and "source must be in the tagged repository" enough?
  13. 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.
  14. 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).
  15. 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.c has 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/ and nx2/ 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.
# 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