WIP: feat(mods): the Modding API: TypeScript mods the game compiles and sandboxes, system mods, a Mods tab, hot reload, custom actors and in-game tests #1958
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1958
Loading…
Reference in a new issue
No description provided.
Delete branch "mod-api"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Longshot gets a Modding API: mods written in TypeScript that change and add to the game, loaded and checked by the game
itself, with a permission prompt, a sandbox and a Mods tab to switch them. Until now a mod could only replace game files
(RomFS and ExeFS); with this, a mod can read and change the game as it runs, add content, and talk to other mods.
What a player gets:
settings. Safe start runs the game with only the built-in mods.
the mods' time, faults and heap; the mods' table beside the chosen mod's graph, numbers, slow frame and log), and the
Discord status. The engine has no Discord code: all of it is the
system/discordmod over a genericlongshot/ipc.started, reloaded or stopped without a restart.
waits for a button, instead of on a timer; in play about 11 s after the first controller read on this PC.
What a mod author gets:
src/itself (oxc, linked in, cached inmodcache/js);longshot-mod checktype-checks,packpackssrc/,typeswrites a library'smod.d.ts.longshot/*): game state and flags, items and grants, rules (damage, actor life, rewards), actors (list,writes, events, bomb light), camera, input (filters, replays), audio, UI (HUD, windows), world shapes and effects, text,
storage, settings, content (new actors, items, text, flags), calls between mods and to system mods (
caller()sayswho), and native C/C++ mods built with the game (unsafe, marked as such).
longshot-mod types --game), attach scriptedcomponents (
longshot/behaviour), copy and edit behaviour trees (values and links).actors.spawn/remove, over the game's own create path taken from #68 by mooki (credited; refused in aco-op room until #68 lands, then a shared-world event).
actors.attachbinds an actor to another's bone through the game's ModelBind;actors.answeranswers three of the trees' queries (isDead, isThrown, isPutAway) for chosen actors.content.treeadds nodes (a sequence, a command's behaviour) to a copied tree, checked against aschema built from the player's own game in
modcache/; the tree writer was checked byte-exact on all 11,707 of thegame's trees, locally.
content.actor'sskinswaps a copied model's textures for the mod's PNGs (madeinto the game's textures on the player's PC, with bc7enc, MIT, vendored);
content.modelchecks a model a mod brings;a mod's clips join an actor's animations (
longshot-mod animfrom glTF,skeleton --gameto rig against). No gamedata ships with a mod: models are copied from the player's game when the mod loads.
content.read.placements(a map's placements, read from the player's game),content.change,rules.rewards(what events give),rules.skips(cutscenes by name),world.states,world.destinations/travel,player.setAge, dungeon items initems.*. The randomizer itself is its own PR on topof this one, #1959.
fullscreenWindow (the whole screen under the game's title bar, never dragged orresized), and
<World occlude="depth">: a label drawn in the scene by the world layer, each pixel tested against thegame's depth, so a wall or a pillar cuts it at its edge (one 2048 x 1024 atlas of 64 labels, made with the first such
label and let go after the last).
--mod-tests <folder>runs a mod's own tests in the real game (the same files as the fake game);dev.py game-testsrunstests/game-features/, headless unless--window.This branch also carries snaildev99's ExeFS-patch and code-module work from #961, #984, #1036 and #1089 (their commits,
their authorship), which the API builds on; if snaildev99 agrees, this PR supersedes those four.
Read first:
docs/modding/README.mdandapi-guide.md(for authors),docs/user/"Using mods" (for players),docs/dev/reference/mods.mdandactors.md(for contributors); code:host/modapi/loader.c(start and the frame'sorder),
runtime.c(modules, budgets),perms.c,host/broker.c(the sandbox),modapi/schema/(the API's sourceof truth, generated into the C bindings,
longshot.d.tsand the reference).Overlaps: #1577 (dyst, a test switch that boots straight into a save) and #659 (NitnekLeBorgne, cancels the title
presses when the player takes over; also edits
host/oot_autoload.c).Testing
Tested: Linux (CachyOS, kernel 7.3.3), NVIDIA GeForce RTX 3090, driver 620.70.06, on the branch before its rebase
onto main: the in-game feature suite (
dev.py game-tests, the kokiri-start save) in three runs.wallet's size), 40 skipped (fake-game-only, or a route of their own). All four fixed since; the grant one was a real
bug (a bag given 428 times).
(fixed, with a test that crashed the same way); then 25 passed, 4 failed (the new feature mods' flags undeclared, and
Link's life read back a frame early), both fixed since with game-free tests. Its next run (2026-11-20,
a426bf10): 28passed, 1 failed (attach: the pot broke inside Link; the test now binds a Deku stick and keeps the pot 0.6 m clear,
not run since). Seen in that run: spawn (an Octorok made in about 284 ms), Link's life written, answers reaching the
trees, a ModelBind made.
57 rewards set, 22 starting items; a seed in game mode failed before its fix (a partly bound dungeon's keys).
from
src/main.ts, actors, audio, camera, content, timers, input replay, rules, storage, HUD and windows, text,teleport. The game-free suite (
run_all.py --strict) on the branch: every failure is one main has.Still to test:
dev.py game-tests --window, expecting the 4 fixes to hold and spawn's,attach's and the answers' game tests to pass or skip with a reason (by hand)
frame, the mouse and the controller on it, Esc and B), hot reload of a mod added while the game runs (by hand)
nodes (trees), placements; enemy-names with
occlude="depth"in Kokiri Forest and at the Deku Tree, on the game'supscale and on DLSS (a label cut at a trunk's edge, no fringe, no stray picture) (by hand)
(@Beanstalk start the game with no mods and with modapi/examples, check the log for the sandbox and mods lines)
Measurements
TODO before ready: main against this PR with no mods (gate 5: a game with no mod pays nothing), fps and frame time in
the standard areas, two interleaved runs each; and the game's build time against main (the TypeScript compiler library
is linked in).
Risks
lsmod-watchthread for hot reload (asleep, at most 0.1 s of CPU and 64 switches in a run;scripts/parity_gates.pychecks it).granted; native mods are not sandboxed and are marked unsafe in the Mods tab.
HOS_MODS_WATCH=0turns it off). Safe start, or removing the mod, undoes any mod.longshot_options.inigains the Mods tab's rows; the Discord status's old switch is read once andcarried into
mods.json;modcache/is new.third_party/oxc) adds about 4.5 MB.Checklist
Ready for review
main; the title is a Conventional Commit. (One topic as the user asked: the Modding API, as one PR.)mise run testpasses (any failure that also fails onmainis named). (Suite on the rebased head running.)main, or Measurements says why there is nothing to measure. (TODO.)third_party/untouched; nothing GPL-incompatible. (third_party/oxcandthird_party/oxc-runtimeare added, all permissive and GPL-3-compatible, listed in PROVENANCE: to be checked in review.)When it applies
mainand passes here.tests/that reads changed source is updated, not weakened.MKWVK_API_VERSIONbumped (MkwVkHostorMkwVkRendereringpu/vk/vk_api.hchanged). (42, on main's 41.)mainand here, for a change that shows on screen. (The Mods tab and the inspector: TODO.)Assisted-by:/Co-Authored-By:trailers.Ready to merge
main, measured again or a comment says why the numbers still hold.🤖 Generated with Claude Code
https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt
Where two patch files write the same byte, the one lower in the list won, and nobody was told. collect() now names every such place (overlaps): in the build's log, and in both files' notes in exefs_patches.txt ("120 of its bytes are taken by HUD lower in the list (main+...)" / "... written differently by Characters higher in the list; this one's are used"), where the Mods tab can show it. The lower file now also wins where it writes the game's own byte back over a higher file's change. Main.classify leaves out the bytes a file writes that equal the game's, so such a byte was not applied and the higher file's byte stayed: a mix of two mods' code that neither wrote. Those bytes are put back into the lower file's writes, and a file that was "empty" (every byte the game's) becomes code or data when it puts bytes back. Modelled on a real case: two HUD mods put a stub inside the range a character mod's patch writes. parse_file() is classify_file()'s parse, shared. apply() closes the JSON it reads. Co-Authored-By: Claude Opus 5.5 <[email protected]>Checked at the top of hos_mods_init: one log line ("mods: off for this start (HOS_NO_MODS): ..."), no mod files and no cheats loaded, and the list neither read nor written, so the Mods tab changes nothing and the next normal start is as before. The ExeFS patches a build took are compiled into the game and stay; the log line says so. A row in switches.def; tests/test_mods_list.py checks the start, the log line and that the list is left as it is. Co-Authored-By: Claude Opus 5.5 <[email protected]>An independent review of the switch found nine things the game round did not meet. Each is answered here with a test that fails on the commit before and passes now. 1. The lift's key did not cover what a64_switch.c carried (HIGH). The table named each switched file and the hash of its bytes; the key is made of the bytes the files write. A file saved again, renamed or encoded another way kept the key and the old table, so its switch stayed off for good while the Mods tab said "built into the game". a64_switch.c now has numbers and bytes only (what became of each switch of the plan, and the writes); which file is of which switch is in exefs_patches.txt ("code+switch<n>"), which every build writes, a switched mod that is off included, and host/mods.c reads it there. 2. Longshot's own edits of the lifted C and the line at a switched function's top (HIGH). The line was put in when the function was written, so an edit that puts a host call first in a function put it above the line, and the call ran again in the version the line left for; an edit that matches the head with the first instruction found nothing; and of several other versions under one head only the first was edited. The line now goes in after the edits: chunks.edit_c takes the lines out before its first pass and puts them in after its last (exefs_switch.strip_lines, add_lines; a64_switch.c records them), and each other version is edited by itself (exefs_switch.edit). Not the picking function of its own the review proposed: that needs the function as written under another symbol, a #define above it, and the lift's cuts of a file (chunks._cut, split_hot.py) are made at a function's head line, which would leave the #define in the piece before. 3. A function only the unpatched code calls was no entry (MEDIUM): the image takes its entries from main with every switch on, so the version with a mod off called code with no function and was written as a trap. The calls of the game's own words and of each switched mod's own words at every place such a mod writes are entries now (exefs_switch.entries, nx2/image.py), and so are the code addresses the game's own words form there with ADR (plain_image, nx2/lift.py). Where a version would still stop at code that is no function and the function as written would not, the function's switches are built in for good, with a line in the log: such a mod takes a build to switch, as before, and no state traps. 4. A mod that is off decided how a mod that is on was built (MEDIUM): make_returns saw the off mod's bytes in the on mod's hook routine and left its B where a build without the off mod writes a RET. Two switched mods of which one changes what make_returns writes for the other are no switches (exefs_switch.entangled, settled before the whole-list steps); built in or left out as they are at the build, the step sees exactly what the game has. A note about bytes a switched mod takes says "while that mod is on". 5. The cap's re-walk dropped the table of a jump another function shares (LOW): the table is kept unless the walk without the mod reads it again, and read again from the image without the mod when another function still holds the jump. 6. Two mods that ship the same patch file (LOW): each file is its own mod's by the list's line, so one mod's file is not counted for the other's switch. 7. The log said a deleted switched mod's code stays in the game (LOW): a switched file's line is not counted there; its switch is off. 8. Jump tables (LOW): the table check runs for every switch, not only those that write data, once with every switch off and then a switch at a time, each both ways (two mods on one table); a version's jump that its own code does not resolve has no targets left from the lift. 9. A mod that is off could stop the supported build (LOW): an output-size place that only a version with a mod off has counts as found, with a warning that the place is lost while that mod is on. tests/test_exefs_switch.py is written again around the shapes the review named, each run in every state against the interpreter: a function only the unpatched code calls; Longshot's own head hooks on functions two mods switch, through chunks.write and edit_c as the supported build runs them, with the host calls counted; a hook's return with an off mod over its routine; a left-out mod whose routine shared a jump; the hot file cut by split_hot.py and the compile's cut of a giant; the kept translation for a file saved again. tests/test_mods_switch.py: the list of a later build, the same file in two mods, a deleted mod, a left-out mod's bytes, a write outside the game's memory. Two of patch-build's tests read a line of the list: its kind is "code+switch0" there now. Co-Authored-By: Claude Fable 5.2 <[email protected]>"Restart needed: the mods" and "Restart to apply the mods?" read the same for one mod or several, switched on or off, and the question put every changed row into one sentence. - The question counts what a restart applies ("Restart to apply 1 setting and 2 mods?") and lists it under that, a line each: the rows changed, the mods switched with their switch's word ("Character field swap (Off)"), the order when it changed. Eight lines at most; its window is as tall as its lines, and as before for one line and no list. - The "Restart needed" line keeps the rows by name and groups the mods after them: one mod's switch by name, more as "2 mods" (menu_restart.h line_forms: the first form that fits the line). - On the Mods tab the line is not shown while the selected mod's own switch, which its help says, is all that waits. - menu_restart.h: mod_changes (what differs from the mods as the game started), list and line_forms, checked in tests/test_menu_restart.cpp; vk_menu.cpp keeps the mods as the game started before the Mods tab's first change. "the mods" stays for when they are not known. - A mod switched since the start has the gold mark a changed row has, and its help says it takes effect after a restart. - A mod's change is told to the restart state as set_row tells a row's: after Later, a mod switched again in the same visit to the menu is asked about at the next close. Co-Authored-By: Claude Fable 5.2 <[email protected]>The review's suggestions on the restart texts: - The "Restart needed" line: with mods switched and the order changed too, the order comes after them ("Music (Off), the mods' order", "2 mods, the mods' order"), where one mod and a new order read "1 mod" while the question listed the order. menu_restart.h mods_part, checked in tests/test_menu_restart.cpp. - counted_mods has the third plural form counted_settings has (" mods (many)", for Russian and Polish at 5 and up), through one counted_text; a many form with no translation yet (the Mods tab's texts have none) is shown as the other form, never as its key. - restart_line takes the caller's RestartTexts (which now carry restart_pending's bits): draw_mods asked the host for every mod twice a frame, through restart_texts and again inside restart_line. tests/test_mods_menu.py follows: the line groups the mods with mods_part, takes its texts from its caller, and the count's forms. Co-Authored-By: Claude Opus 5.5 <[email protected]>A restart switches a mod's files, its cheats and the ExeFS patches the build made a switch (mod_switch.c), but not code that is not built into the game yet (a mod accepted since the start, edited since the build, left out while it was off) or code built in for good (a code module, patches the build could not switch): that goes in or out at the next build. The restart texts said "Randomizer (On)" for both. - MkwVkHost.mod_build (API version 37; host/mods.c hos_mod_build): whether mod i, as it is switched now, has code a restart does not switch; on with patches or modules not in the game (or in another order than at the build with a mod writing the same bytes), off with code built in for good, as the tab's note says. - menu_restart.h: a Mod's build flag; mod_changes says "<name> (On, its code needs a build)" for a switched one and counts them. Not switched, a mod that waits for a build is not listed (a restart does nothing for it); a mod whose warning waits is off and not switched, so not listed until it is accepted. - The line counts them ("2 mods (1 needs a build)"); the question adds, when one is listed, that a mod's code that needs a build goes in or out when the game is built again and everything else applies at the restart. - README's Mods paragraph and docs/using-mods.md say so. Tests (written, not run): tests/test_menu_restart.cpp (the build flag in mod_changes), tests/test_mods_switch.py (hos_mod_build for each made-up mod as switched and switched the other way: switched patches need none either way; edited or left-out ones need one to be on, built-in-for-good ones to be off), tests/test_mods_menu.py (the API, the host's table and the menu's use). Co-Authored-By: Claude Opus 5.5 <[email protected]>A mod or a patch file named with a line feed and tabs ("x\nb_victim\tv.ips\t<fnv32>\tcode\tz.ips", possible on Linux) made the build write a line that read as another mod's, and both readers (taken_before, built_before) took the first line that matched: that mod's code was accepted at the next start without the warning. - write_list leaves out the line of any file whose mod's or own name is not listable (a tab, a carriage return or a line feed in it, or not UTF-8), counts them in a comment and names them in the build's log; a note's breaks are spaces. The module entries go through the same list. - Such a mod with code is never accepted, on both sides (code "unnamed"): mods.json could not keep its acceptance nor exefs_patches.txt its lines. hos_mod_code says why; the same holds for a mod whose folder's name is not UTF-8 (Linux), whose acceptance could not be saved and which was taken "once" at every start. - exefs_patches.txt starts with "# exefs_patches.txt 2:" (LIST_HEADER); taken_before and built_before migrate only from a list without it, a build's from before, so the migration is one-time in fact. taken_before splits lines at line feeds alone, as the game does. Test: tests/test_mods_list.py forged_lines (game and build, Linux names included). Co-Authored-By: Claude Opus 5.5 <[email protected]>Modding API spec 8.4: a code mod the last build did not take (new, edited since, or accepted since) is held back whole until it is built in, since a mod with its files and without its code is a broken mod. The branch served its RomFS and left the code for later ("On, its code needs a build"). host/mods.c: exefs_status runs before the files are indexed, and hold_back marks a mod that is on with a patch file or code module not in the game as it is now: its RomFS files (and size table) are not indexed, its cheats are not offered (hos_mod_cheats_dir), and its switch stays off. The Mods tab says it waits for a build; the restart texts count it as before (hos_mod_build). A mod that cannot be switched and is turned off loses its files at once and the tab says its code stays until the next build. The restart question says what applies when, both ways. Docs: docs/mods.md (switching), docs/using-mods.md, README's Mods section. Tests: tests/test_mods_list.py held_whole (held, built in, edited, off with code built in); the notes expected by tests/test_mods_switch.py, tests/test_mods_modules.py and tests/test_mods_sizes.py (whose 01-first is all built now, so its files are still served there). Co-Authored-By: Claude Opus 5.5 <[email protected]>A mod's patches/<path>.json beside its romfs sets, adds or removes keys of one BYML file (Modding API spec 6.1, parameter files): a file of the RomFS, or a member patched in every pack that carries it. The patches of a file are applied in the list's order onto the file the layers serve (or the member a mod puts in); two mods changing different keys both apply, and two setting one key to different values are a conflict named in the log and on both mods' Mods tab lines ("Both A and B set Octorok's Life: B's is used"), read from the ops alone. A mod lower in the list serving the whole file wins over the patches of mods above it. An op that does not apply is left out and said; a file that is not a patch file is named with its line and why. The repo had no BYML writer: host/byml.c reads a document into a tree and writes it back (both byte orders, versions 2 to 7, every node type the game's files use but aligned binaries), with bounds on every offset, a depth limit and a node limit (a shared container is read as a copy each time). The patch files are read by host/mod_patch.c's own strict JSON reader (UTF-8, depth and size limits). The patched files are made in modcache/files/ by content, like the packs. Co-Authored-By: Claude Opus 5.5 <[email protected]>- Each mod's realm is created with vm.constants.DONT_CONTEXTIFY (a null-prototype object on older Node), so its global is not an object of the host's realm: a contextified {} let globalThis.constructor.constructor reach the host's Function and process. - node:vm is still not a security boundary, and the docs now say so: the guide warns that the fake game runs a mod with Node's rights (test only mods you trust), and the sandbox it lists is the game's; prelude.js, fake-game.js and api-schema.md say the same. - A call checks context, permission and feature before its arguments, as the C thunks do (a new bridge step); on() subscribes before it checks the listener. - Strings with a lone surrogate are refused, log's parts included, as the C bindings' UTF-8 check refuses them; numbers must be finite (NaN and the infinities would cross as null); -0 is noted. - The entry module and each round of listeners run with a time limit (2 s: an endless loop becomes a fault instead of a hang); a revoked permission or a removed feature stops its events; the fake's own result checks report InternalError. Co-Authored-By: Claude Opus 5.5 <[email protected]>The guide said the fake game has no time limits, but a round of listeners that runs over 2 s becomes a Timeout fault (as docs/modding/api-schema.md says). It named new FakeGame({ strict: false }) without saying how a test reaches it when longshot-mod test hands it a strict game: game.constructor with the game's modDir and manifest, which index.d.ts now declares. Co-Authored-By: Claude Opus 5.5 <[email protected]>longshot.game.on("no-such-event") said: has no event no-such-event (it has "frame", "update"). A name with spaces or an empty one read as nothing at all. Co-Authored-By: Claude Opus 5.5 <[email protected]>QuickJS-ng 0.18 does not ask the interrupt handler inside native builtins, and several are reachable without allocating: - Array.prototype's methods walk ToLength(this.length) in C (join, reverse, copyWithin, splice, shift, unshift, slice, concat...): `join.call({length: 2**53-1})` froze the main thread for ever. The prelude now wraps each method to refuse a length above 2^22 (no array a mod's heap holds is longer), reading a length it would read twice (an accessor, an inherited one) once and handing the method a stand-in, refusing such objects for the mutating methods; concat checks its spreadable arguments too; flat and flatMap are JavaScript, so nested sparse arrays are interrupted. - import() read and compiled a file in a native job, uncached on failure: refused now, always (the spec's modules are static imports; the fake game refuses it too). The deadline is also looked at between promise jobs: what is left stays queued and the call is a fault. - Error.prepareStackTrace and Error.stackTraceLimit are accessors that Object.freeze leaves working (a mod's function ran inside the engine's error paths and got the frames' functions; the old limit leaked): fixed as plain values. - BigInt maths near the engine's million bits takes seconds in C: not capped, a fault when it returns (documented). Also: subscriptions reuse the slots off() frees and the 1,024 bound counts stored slots, ids are never 0 nor a live one's, and one made during a round of events waits for the next; a Uint8Array argument is copied before later arguments run the script's code; lsapi_result is zeroed before each call; the heap counter is charged our header and an estimate of the C library's per allocation; unhandled rejections are attributed to the call they happen in and at most 32 are kept (the rest counted); log lines lose C1 controls, NEL, line separators and direction overrides. Co-Authored-By: Claude Opus 5.5 <[email protected]>The site forms M2's conversions need beyond entry and after: - entry with can_return: if (on && fn(c)) return;, as nx2/entry_hooks.py's hooks; - return: the function lifted as f_1<address> under a wrapper f_<address> that calls it and then the hook, so every way out (ret, tail call, indirect jump) runs it and the body keeps its locals; - before: before the instruction at offset, of any kind, after its label; - replace: if (on) fn(c); else { the instruction }, a plain instruction only; - branch: before a conditional branch, a non-zero answer takes it. before, replace and branch are emitted by lines of nx2/fastfp.py's copy of the kit's emit_function tagged "# (hooks)" (tests/test_fastfp_override.py takes both tags out before comparing with the kit), from Lifter.site_before, site_replace and site_branch, sent to the emit's processes with the others. Every callback is int fn(Ctx *): only can_return and branch read the answer (hos_text_letter_step returns 0). Inline data rules (rule = mul_f32, scale_f32, note_u64): the compiler's own C inlined at the site, reading a host value named in host/game/sites.def (HOS_VALUE, the feature's own variable): one load and a predicted branch when off, no call. The host fills a value with one atomic store and a table by publishing a new one with one pointer exchange, the old kept until a quiescent point (host/game/sites.c hos_value_set, hos_table_publish, hos_tables_quiesce): no lock on the game's side. Co-Authored-By: Claude Opus 5.5 <[email protected]>The hook site callbacks became int (an entry that can return, a branch) after the text.letterStep site was written, and the two checks still cut "void hos_text_letter_step(", which no source has: both would stop on the missing marker. sites.h and docs/hooks.md said the sites' several subscribers come with the script runtime, which is in without them: they come with the API's hook namespaces. Co-Authored-By: Claude Opus 5.5 <[email protected]>The modding API reshaped before more namespaces are built on it (nothing is published, so 0.1 changes in place): - Modules, no global. A script imports "longshot" (version, has, the error classes, the shared types), "longshot/game" (state, frame, update, flags), "longshot/player" (state) and "longshot/log"; each has named exports and a default, its frozen namespace object. Export lists are fixed per API version: a member a build lacks is there and throws NotAvailableError. "longshot/ui", "longshot/ui/jsx-runtime", "longshot/storage" and "longshot/worker" are reserved (refused naming why). The schema maps namespaces to modules ([[module]], a namespace's module key or its top-level name's); longshot.d.ts is one declare module per module. The runtime makes C modules (JS_NewCModule) from the frozen API objects; the fake game a vm.SyntheticModule per specifier. - version is one frozen record { api, longshot, gameBuild } (was apiVersion and game.version()). - Events are values: frame and update are Event<Frame> objects whose on(listener, options) returns a Subscription with off() and [Symbol.dispose] (the same function). Both carry { frame, dt }; frame needs no permission. on()'s options record (SubscribeOptions) has no field yet: an unknown one is an ArgumentError. - Errors are classes made in each mod's realm: LongshotError extends Error; ArgumentError, ContextError, PermissionError (permission), NotAvailableError (feature), UnknownNameError (list, value), LimitError, HostError (was InternalError, which QuickJS-ng's own error collides with). The schema stays name-based with fields. - log never throws: past 100 lines a second they are dropped and counted, and said once the second is over. - player.state() is PlayerState | null; a field whose feature a build lacks reads null, never 0. game.state() and player.state() return frozen records carrying their frame, the same object within a frame. Opt<F, T> types such fields; longshot-mod types writes a mod's longshot-env.d.ts from its requires to drop the null. - has() takes the closed feature list (a schema type, feature): any other name is an ArgumentError. Field features are named by record path (player.state.life, game.state.timeOfDay). - Names and units: position/velocity, PlayerState, maxRupees (its own feature), flags.has; units in the schema ([[unit]]: QuarterHearts, Seconds, Hours). The C side keeps every safety property (the prelude's cuts, the freeze, the array-length guards, no import(), the budgets and faults); the examples, the guide, the API schema page, the reference and the tests follow. Co-Authored-By: Claude Opus 5.5 <[email protected]>The storage branch on the reshaped API. The generator gains [[interface]] (types.toml): functions written once and bound by every namespace that says implements = "Store", each binding a plain object (a Lua table) with its own paths and features, one C service per function told which binding was called (lsapi_impl_store_get(ctx, binding, ...)), one TypeScript interface, and the reference listing it once. - longshot/storage is no longer reserved: global, profile and save, each a Store (get, has, set, remove, keys, usedBytes, dataVersion, setDataVersion: schema()/setSchema() and used() renamed; has new), values typed Value - save.slot(), and the event save.loaded ({ slot: number | null }) when a slot's data becomes current: fired between frame and update (update is order 2 now), so a mod migrates there and its update sees the result - QuotaError (scope) and NewerDataError (scope, version) are classes; services set an error's fields (modrt_error_fields) - the files' "schema" is "dataVersion"; the name global is kept and why is written down (Lua 5.5, LUA_COMPAT_GLOBAL) - save-tally migrates at start and at save.loaded; test_modstore, storage.md and the guide follow Co-Authored-By: Claude Opus 5.5 <[email protected]>game.flags.set, player.setLife and player.setRupees (spec 9.2, 9.3, 12.4; plan M7 piece 1). The permission state.write (medium: "Can change your game and what gets saved") and the error Denied join api.toml. The rules are one table, game.flags.toml's [[writable]] (bool 0..1, int 32 bits), [[deny]] (Sequence_IsChildhood, Sequence_IsLoadingBanc, MapIconDeactivateByAreaActor, PlayerStatus.MaxLife, OptionData.VoiceLanguage, each with its reason) and [[range]] (PlayerStatus.Life 0..MaxLife, PlayerStatus.CurrentRupee 0..999). The generator checks them and puts them into longshot_api.h (lsapi_flag_kinds, _deny, _ranges), the fake game's schema.json and the reference's Writes, so the game and the fake game cannot drift. host/modapi/writes.c applies them in one order (acquire phase, deny by hash, play only, the flag, its kind, its value; refused, never clamped) and keeps a trace of every attempt (the first taken write of a mod logged at info, the rest at debug, the last 64 for dev mode). The game's half is services_game.c over host/game: a switch through the game's own Bool setter (new host/game/flag_set.c, game_call, the setter hos_main.c's teleport already uses, which queues the save's copy), a counter in place (flags.c game_flag_set_int). No new guest address. The fake game applies the same tables (lib/services.js writeFlag), records game.writes, reads Link's flags from setPlayer and takes setFlag(name, value, { kind }). tests/modrt_test.c gets the scripted game's half and a trace command; tests/test_modrt.py checks the deny list, kinds, ranges, play only, the permission, a missing feature, a write the game does not take, the trace, and that every denied or ranged name hashes to a flag the host's source knows. Not run here. Co-Authored-By: Claude Opus 5.5 <[email protected]>The writes branch on the reshaped API, and the write semantics decided: a write is checked at the call and made after the frame's update listeners (modrt_writes_apply; the fake game's _applyWrites), in call order, so reads within a frame see the frame's snapshot and writes take effect by the next frame. - game.flags.set(name, value): boolean, and player.set({ life?, rupees? }): boolean (all or nothing), replacing setLife/setRupees; outside play (or before the game's flags exist) a write returns false and writes nothing - the deny list and a kind no mod writes throw WriteRefusedError (fields flag and reason: deny, kind; "flag", not "name", which is the error class's own); a value outside its kind or range is ArgumentError, never clamped - the generator takes record parameters: an options record with fields, handed over by name (LSAPI_V_FIELDS) and checked by a generated lsapi_arg_rec_<record>; lsapi_function.record_args; PlayerChanges is the first - the one schema table of kinds, deny list and ranges stays; player.set's record must hold exactly the ranges' fields - rupee-rain and misbehaving, their tests, test_modrt's writes, writes.md and the guide follow Co-Authored-By: Claude Opus 5.5 <[email protected]>The game runs JavaScript only (spec 7.2), so a mod written in TypeScript is compiled before it reaches it: - build: src/**/*.ts and .mts to dist/ as ES modules, one per file, relative imports as written (naming the built .js), nothing bundled; then the built modules are linked (not run) as the game links them, so an import of a file the build did not make, or of a name nothing exports, fails here. --check compares dist/ with a fresh build. - The compiler: the mod's own typescript (transpileModule, file by file, target from its tsconfig.json, ES2023 by default), else Node's module.stripTypeScriptTypes (22.13+/23.2+; erasable syntax only, refusing enums, namespaces and parameter properties with a message), else exit 77 saying what to install. No dependency added, nothing downloaded. - test: .test.ts files and the mod's src/ are compiled on the fly with the same compiler (in memory; node:module register hooks for the tests, lib/compile.js in the fake game, which runs a TypeScript mod's entry from src/). JavaScript mods are unchanged. - check: mod.json and its entry, then tsc --noEmit with the mod's typescript. - pack: builds, then packs mod.json, dist/ and the mod's other files (not src/ unless --with-source, tests, npm or TypeScript files) into <owner>.<name>_<version>.lsmod, checking every name against host/mod_archive.c's rules (docs/modding/packages.md) and the entry's presence first; a plain zip with no time stamps. - index.d.ts: Assert and Tests types (export default {...} satisfies Tests) so TypeScript tests need no @types/node, a Manifest type, and no /// reference to @longshot/api (npm links file: dependencies, and it is not found from the link's real folder); the mod's tsconfig brings the global in. Co-Authored-By: Claude Opus 5.5 <[email protected]>heart-log, speedrun-timer, flag-tracker and lib-and-dependent's two mods are TypeScript now, behaviour unchanged: src/main.ts (lib: src/format.ts too, imported as ./format.js), test/*.test.ts (export default {...} satisfies Tests), the recommended tsconfig.json (ES2023, NodeNext, moduleDetection force, strict, isolatedModules, verbatimModuleSyntax, erasableSyntaxOnly, types @longshot/api), typescript 6.0.3 beside the two file: packages in package.json, and "entry": "dist/main.js". tsc 6.0.3 checks all five with no error. dist/ is committed where a check needs a runnable file with no compiler: heart-log (tests/test_modrt.py runs it in the real runtime, now as dist/main.js) and lib-and-dependent's two (tests/test_mod_examples.py packs them, now with what longshot-mod pack packs: mod.json, dist/, the README). Each built file's first line says it is built from src/; they are typescript 6.0.3's output through longshot-mod's compile step. tests/test_modapi_schema.py runs longshot-mod build --check on those, and treats exit 77 (TypeScript, no compiler) as a skip. speedrun-timer and flag-tracker ignore dist/. misbehaving stays plain JavaScript on purpose: it passes the API wrong types, which TypeScript would mark, and it shows a mod with no build (its README says so). The resolver's example cases in tests/mod_vectors/resolve.json and lib-and-dependent's variants say "entry": "dist/main.js", as the manifests they must equal. docs: scripting.md's getting started is TypeScript (layout, manifest, tsconfig and package.json, building, the compiler order) with a short Plain JavaScript section, and the dev loop lists build, test, check and pack; examples.md and the modding README follow. Co-Authored-By: Claude Opus 5.5 <[email protected]>The TypeScript branch on the reshaped API. - heart-log, speedrun-timer, flag-tracker and lib-and-dependent's two mods in TypeScript import the API's modules (import { update } from "longshot/game"; import player from "longshot/player"...), subscribe through event objects and handle the nullable fields (player.state() null without Link; a field's feature in requires drops its null) - longshot-mod build and check write longshot-env.d.ts from mod.json's requires (as longshot-mod types does) before they compile or type-check; the examples' tsconfig.json includes it, .gitignore and pack leave it out - the build's link step knows the API's modules by their export lists (lib/schema.json), so a name a module does not export, or a module this API version does not have, fails at the build - dist/ rebuilt for heart-log and lib-and-dependent with typescript 6.0.3 (longshot-mod build); every TypeScript example type-checks with tsc --noEmit - the guide's TypeScript settings, packages.md and examples.md follow Co-Authored-By: Claude Opus 5.5 <[email protected]>The Modding API spec's 11, decided: the reconciler is JavaScript run inside each mod's own runtime, shipped by the host as the modules "longshot/ui" and "longshot/ui/jsx-runtime" (no longer reserved); the host composes mods. - modapi/ui/runtime.js, one function expression called with the UI channel's native part (commit, onEvents; and requestFlush, settings when the host has them) and the mod's own longshot/game and longshot objects. A fiber per element; function components re-render on their state, a useGame value, a setting, or props that changed (shallowly); children matched by key, else by place; the difference emitted as the contract's ops (set with only the props that changed, inserts by a right-to-left walk that keeps what is already in order, removes of the top host nodes only); handlers kept in the mod ("onPress": true is sent); events mapped back by node id. At most one commit a frame, at the end of the update round (requestFlush; a promise job until the host has it). Hooks: useState, useReducer, useRef, useMemo, useEffect (after the commit, cleanups on change and unmount), useGame (selectors read at update, shallow compare), useSetting, useEvent (event values of the reshaped API), useFrame. The game's events are subscribed only while a hook needs them: an idle tree costs nothing a frame. A component that throws is a fault naming it (and its owners), and takes its mount down; a refused batch makes it send its trees again. Elements are typed components (Row ... Window, SettingsPage, World stub, Canvas place only, Slot); mount() with a disposable handle (update, open, close, isOpen, unmount, Symbol.dispose); a slot filled with surface "slot". - The schema: a [[module]] may be js + types, JavaScript the host ships with hand-written declarations (modapi/ui/longshot-ui.d.ts, included in longshot.d.ts: elements as components, props per element, empty JSX.IntrinsicElements). generate.py makes host/modapi/ui_js.h (a C string naming the source's sha256) and the fake game's lib/ui-runtime.js from the source; lsapi_module gains js. - The host: host/modapi/ui_module.c evaluates the source at the mod's first import of either module and bindings.c makes C modules of what it returns, as for schema namespaces. Tests (written, not run here): tests/test_modrt.py imports both modules in the real runtime, checks they are made and frozen, a Hud mounts without a fault, and a component that throws is a fault naming it. Co-Authored-By: Claude Opus 5.5 <[email protected]>The items namespace of API 0.1 (modapi/schema/items.toml): items.checked (a place checked: map/id, and whether the game resets it) and items.granted (an item reached the inventory: the game's actor name, the count, the game's reason, and the mod and key of a mod's grant), both fired after update from the item service; items.grant(item, count, key), items.pending() and items.held(item), with the permissions items.read and items.grant. host/modapi/items.c keeps each mod's grants in longshot_mod_items.txt in the user folder: queued, given (since the game's last save: a load or a new start queues it again) or saved (a key stays known for ever). One grant a frame goes to a running mod that holds items.grant, in play only. The schema keeps API 0.1's shape (longshot.items.on("checked"), errors by name); the reshape into modules with event objects and error classes maps each [[event]] and throws name one to one. grant answers queued/known rather than a Promise, and takes scalars rather than an options record, until the bindings have both. The fake game scripts checks, items, saves and loads; tests/test_game_items.py checks the service and the queue with made-up guest memory and a scripted service. Co-Authored-By: Claude Opus 5.5 <[email protected]>The items namespace joins the API's modules: `import { checked, granted, grant, pending, held } from "longshot/items"`, its events values with on() (order 3 and 4, after storage.save.loaded and update, fired from modrt_items_frame after update and before the UI's flush), its errors the classes (UnknownNameError with the list "items", ArgumentError, LimitError). grant takes an options record, GrantOptions { count?, key? }, as the spec has it; the record itself may be left out (grant(item): one, no key). The generator learns that: the last parameter, when it is an options record, may be `optional = true`; its thunk takes argc N-1 and hands the service a record with no field (lsapi_no_fields), the C adapter drops a trailing undefined record, the fake game's prelude does the same, and TypeScript sees options?. A key given is 1 to 200 bytes (empty is ArgumentError: leave it out). grant still answers "queued" or "known" at once: the generator has no asynchronous call yet, so no Promise; the mod hears its grant arrive through granted. The fake game's items join its save slots: saveGame(slot) keeps the grants given so far, loadSlot and reload give back those given since (its own saveGame/loadSave are gone). item-tracker and check-gift import their modules; their tests use loadSlot and PermissionError. tests/test_modrt.py checks the options record left out, undefined and given; modapi_items_test.c the defaults. Co-Authored-By: Claude Opus 5.5 <[email protected]>The launcher's Browse installs a portal mod into mods/<owner>/<name>/ with its mod.json, and names it owner/name in mods.json. The loader now holds a folder to its id's path: a folder with mod.json inside a folder of the mods folder is its manifest's id (checked by the manifest's id rules) when its path ends in <owner>/<name> of that id (mods/<owner>/<name>/, or deeper, as emulators keep folders of folders); one that does not is refused with the reason ("its folder mods/o/renamed is not where its id o/original goes"), under local/ and its path, and nothing of it is served (modrt_broken stays for an unreadable mod.json, whose romfs folder is still an emulator mod's). A folder directly in mods/ (mods/<name>/, no owner folder) may hold any id, as a mod being made sits; a folder without mod.json is local/ and its path, as before. tests/test_modrt.py: placed, deeper, directly in mods/, renamed and elsewhere. manifest.md (Ids), packages.md, mods.md and the author's guide say where a folder goes. Co-Authored-By: Claude Opus 5.5 <[email protected]><Badge>{n} rupees</Badge> made two Texts ("5", " rupees"), so the Badge's label was not "5 rupees" (link-hud's tests and docs/modding/ui.md's own example): strings and numbers next to each other in one list of children are one string now. A flush an interrupt cut short was only noticed at the next flush, which a press that sets the state already set never asked for, so the UI stayed as the cut flush left it (ui-cases' hang test): the update, the frame and the events now ask for a flush while one was cut short. Generated: host/modapi/ui_js.h, modapi/packages/mod-tools/lib/ui-runtime.js. Co-Authored-By: Claude Opus 5.5 <[email protected]>A forward declaration of game_in_front made "static int game_in_front(" appear twice in host/nn_hid.c, and the checks that cut it (tests/srccut.py's block, as test_input_background does) stop on a marker that is not unique. The script mods' key read now sits after the function it calls. Co-Authored-By: Claude Opus 5.5 <[email protected]>- An action's key and a chosen button are the keybind setting's value now that settings keeps one (settings.c modrt_setting_keybind; the fake input reads lib/settings.js's), the manifest's "pad" chord beside it. - loader.c grants_now counts a granted net:<origin> as can_start does. - The adapter's handle_object takes a handle of no schema type as the bare object it was; the fake game's values take a handle as its id or as {$handle, id, generation}; schema.json's functions say method and dispose again (rule.remove() on the prototype). - A hot reload in the fake game restarts that mod alone. - enemy-hud asks for ui.hud, which its Hud needs since mount() checks it. Co-Authored-By: Claude Opus 5.5 <[email protected]>The cloth solve job's text patch (nx2/oot_patches.py patch_cloth_solve: if (!hos_oot_cloth_solve(the frame step at 0x84d61fc8)) { x0 = 0; return; } first in f_81b47080) is the site cloth.solve, the job's entry with can_return, its callback host/oot_sites.c's hos_site_cloth_solve: it reads the step as the patch did and answers 1, x0 = 0, for a frame the gate holds. Identity: the same call with the same word read, before the job saves anything (its first line, the prologue's store, comes after the entry hook as it came after the patch); a held frame returns with x0 = 0 and the stack pointer as given. tests/test_oot_cloth_60.py builds the job with the emitted hook and with the patch's line side by side and checks they solve and hold the same frames in every case (240, 144, 120, 60 and 30 fps, a cap of 60, a step of 0 and NaN, a load), for HOS_FPS_CLOTH_60 unset, 1 and 0. The patch, its constants and its report line are deleted; the job may now get locals. Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (Zora's Domain near King Zora at a cap of 240 with HOS_FPS_CLOTH_60=1: the cloth solved some 60 times a second, HOS_FPS_LOG's counts as on main) need a lift and a game run. Co-Authored-By: Claude Opus 5.5 <[email protected]>The camera centering's text patch (nx2/oot_patches.py patch_camera_centering: if (hos_disable_camera_centering()) { x25 = x26; goto L_80645ad8; } on the fall-through of f_80644c80's b.ne at L_8064720c, the follow camera's movement yaw) is the site camera.followYaw, a jump site before +0x2590 to +0xe58, its callback host/oot_sites.c's hos_site_camera_follow_yaw: with the row on, x25 = x26 and the answer 1. Identity: the same call at the same point (+0x2590 is the b.ne's fall-through and no label: nothing else reaches it, so a before site there runs only where the patch's line ran), the same register written, the same label jumped to. The function keeps every flag store now (the jump's edge, which the flow analysis does not see); the patch's goto was not seen either, so this keeps more, never less. The signature takes the b.ne, the call the movement path starts with and its x25 = x26. tests/test_camera_centering.py checks the site and runs a block with the emitted hook and one with the patch's line, row off and on: the same way out, the same registers. The patch, CAM_HEAD and its report entry are deleted: f_80644c80 is no longer named by nx2/oot_patches.py. Gates: gate 1 (nx2/test_leaf.py with the table) and gate 3 (walking with the row on and off on a fixed save: the yaw follows Link's movement only with it off, as on main) need a lift and a game run. Co-Authored-By: Claude Opus 5.5 <[email protected]>- tests/test_mods_archives.py, test_mods_modules.py, test_mods_packs.py and test_mods_switch.py (and test_mod_patch.py and test_mods_members.py, which build with the first) cut host/posix/win32_posix.c's find_next, which gives a file's times through filetime_of since the script API's dev reload needed them: the helper is in their cut lists, as the API's own checks had it. - tests/test_mods_list.py's stand-in build (no game code) also stands in for exefs_patches.refuse_site_clashes, which looks the hook sites up in main's code. - gpu/vk/vk_menu.cpp: the Mods tab's keys run mods_tick unless a mod's own page is open, written without a nested "} else {", so tests/test_mods_menu.py's cut of the tab's branch (to its first "} else {") still holds the restart state's note after it. Co-Authored-By: Claude Opus 5.5 <[email protected]><World at offset maxDistance fade> (spec 10.2/11.4) is a fifth surface, mounted with ["mount", id, "world", opts] under ui.hud: at a point {x, y, z} or an actor {actor: {id, generation}}, at most 64 a mod, display only. At the acquire phase, on the main thread, ui.c world_resolve reads each actor's position (actors.c) and projects the point through the frame's recorded view (camera.c modrt_camera_project); a World surface of the snapshot carries its fx, fy, depth, alpha and visible (hidden behind the camera, off the picture, past maxDistance, its actor gone, no view). A snapshot of moved points only keeps the trees' layout serial (MkwVkUiSnapshot.layout, snapshot version 2), so the renderer keeps its measures and its node state. vk_modui draws them over the picture as the present places it, under the HUD, farther first, faded, never focusable. The reconciler's World turns an Actor handle (native.actorRef), an actor's snapshot or event, its key or a position into the wire's at; ui.project(position) gives {x, y, visible} or null (state.read). The d.ts, the fake game (a projection through its camera, game.ui.worlds()) and the docs follow. Co-Authored-By: Claude Opus 5.5 <[email protected]>A mod window opened with { open: true } took the focus at once (the host's default focus: 1), so on the title screen it held back all of the game's input; and its close box answered the mouse only while it had the focus and the window's thread had been told to let the mouse go. The mouse, as it was: - the close box's hit rectangle (close_box) was set only for the focused window, so an unfocused window (after the Insert menu, or another window) could not be closed or focused by a click at all; - a click reaches the renderer only while the window's thread thinks a menu has the mouse (WM_APP + 8). The Insert menu (vk_menu.cpp, told) and the mod windows (vk_modui.cpp, released) each posted that one flag from their own memory, so closing the menu over a focused window let the mouse go and took it back in turn; - with no menu open, a click on Linux captured the mouse for the game (display_sdl.c) and on Windows went to the game's own menu (the title screen) or a capture: an unfocused window could never get a click; - windows were placed by their place in the drawing order, so a window brought to the front moved under the cursor. Now: - the host mounts a window unfocused unless its mod passes focus: true; the renderer gives the focus on opening only then. A click on a window gives it the focus, its close box closes it (focused or not), a click outside every window gives the input back to the game (the window stays open, dimmed); - closing (close box, Esc, the controller's back) hides the window in the renderer at once; the host marks the mount closed when the event arrives and drops any later event of that window's nodes, and a second close; the reconciler marks the handle closed (isOpen false) before onClose runs, as a notice; - the window frames and the click test are modui::window_frame and modui::window_at (modui_layout), with a cascade place kept from each window's first opening; the close box's hit area is the title bar's height square; - the menu tells the window's thread to let the mouse go for both (now_open || modui_window_focused()), from one place; - the renderer tells the window's thread where the windows are (MKWVK_UI_RECT_MSG, WM_APP + 13, fractions of the window; not part of MkwVkHost, no version), and a click there with no menu open is published to the renderer instead of capturing the mouse or reaching the game's menu (display.c, display_sdl.c, display_pointer.h); - the fake game keeps a focused window (game.ui.click, clickOutside, focused): the game reads nothing and no key reaches an action meanwhile, as option 1 in the game. Tests: test_modui_layout (the frames and the hits), modui_test.c (unfocused by default, nothing after a close, one notice), test_modui (the wiring), display_pointer_test (a click on a mod window with no menu open, Linux and Windows). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe example's window was mounted with { open: true } and took the game's input from the start (the title screen included). It now starts closed and a keybind setting ("rupee_log", F7, "Show the rupee log") opens and closes it through longshot/input's action (permission input.read); opened, it leaves the game its input until the player clicks it. onClose only logs: the player's close has hidden it already, and the handle says closed, so the key opens it again. docs/modding/ui.md: Windows and the game's input (the focus, closing, the example); the fake game's click, clickOutside and focused. Its tests: closed at the start, the key opens and closes it, the game keeps its input until a click and gets it back by a click outside, changes listed while closed, the player's close. test_modrt runs it through the loader (its setting declared from mod.json for the action). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtBudgets (host/modapi/runtime.c, modrt_internal.h): every budget (5 ms a callback, 2 and 8 ms a mod's frame, 4 ms all mods, 1 s the entry) counts the thread's CPU time (Linux CLOCK_THREAD_CPUTIME_ID; Windows QueryThreadCycleTime scaled by the TSC's rate, measured once in 2 ms), not the wall clock: a loaded or swapping PC no longer faults and stops mods. The wall clock is a hard cap for real hangs (10x the budget, at least 50 ms a callback), in the interrupt handler and when native code returns. A callback that faulted for its time is not faulted again for its frame's 8 ms (one stall cost two of the three strikes). Where the time went (ModRtCost): counters while a mod's callbacks run (the API's calls by name, the result's script value included; longshot/ui commit; major page faults on Linux, RUSAGE_THREAD), said only in a warning or a fault: its CPU and wall time, the API's sum and costliest call, the collector, its own JavaScript, the page faults. The collector of a mod's runtime runs at the frame's end, timed, when the heap grew by half (QuickJS-ng's own moved up to a net, counted when it runs inside a callback); its time is in the frame's warning, never a fault. actors.list(filter) takes an ActorQuery: type, typePrefix, key, near { position, within }, nearest, limit, answered in C before any object is made. The frame's snapshots are made once for all mods, each answer is kept for the frame by its fields, and its number (lsapi_ctx.result_key) lets the adapter give the same frozen array again (MODRT_KEYED). The fake game answers the same, with the same errors and the same array. The generator names a C field near_ (C_MACROS): windows.h defines near away. In the C harness with 500 actors: the old enemy-names pattern (list() and filter in JS) 690 us a frame, the filtered list 53 us; enemy-hud's 637 -> 134 us. tests/test_modrt.py: CPU time spun and wall time waited in native code, the hard cap, one fault a slow moment, the breakdown's parts, the queries and their errors, the same array, 500 actors; List rows. tests/modrt_test.c: spin:<ms>, positions, actors <n>, cost and uicost (ui.c's ModUiCost: stringify, parse, apply, snapshot builds). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtenemy-names: list({ typePrefix: "Enemy_", near: { position, within: 25 }, nearest: true, limit: 32 }), the host choosing the 32 nearest enemies before any object is made (was every actor, filtered and sorted in JS: its update listener faulted at 14.8 ms in a game run). enemy-hud: list({ typePrefix: "Enemy_" }). A fake-game test of 40 enemies among 300 other actors: 32 labels, enemies only. In the fake game with 500 actors, enemy-names' frame 9.7 -> 5.0 ms (the fake game's own work included). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtA new module, longshot/lifecycle, with one event: stopping (order 14 of the acquire phase, after dev.reloading), { reason: "disabled" | "dependency", mod }, fired when the player turns the mod off in the Mods tab while the game runs, or turns off a mod it needs. Not fired for a fault stop, a dev-mode reload or the game's quit. The fake game models it: game.turnOff({ reason, mod }) fires it and stops the mod (its listener's writes not made), game.turnOn() runs its entry module afresh with storage and settings kept. docs/modding/lifecycle.md says what a mod meets when it is turned off mid-game. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe reward a chest holds is the actor the game creates from the chest's placement (its dynamic parameter Drop__DropActor, or Drop__OverwriteDropActor), read by f_80bf1c00 into the drop's record as the chest's actor is created. Two inline table rules (reward_rules_drop), just after the reader's two calls (rewards.drop in f_82f145e0, rewards.dropOther in f_82f162f0), write a reward's item in place of the name when the dropping actor's placement id ([actor + 0x3d8] + 0x88, the key QueryActorGetIsRespawn looks up in the Bool64bitKey flags the checks scan) has one. One relaxed load while no reward is published. rules.rewards.add({ where: { location }, give: { item } }) of longshot/rules (state.write) keeps the rewards beside the damage rules (host/modapi/rules.c), its first takes the claim items.rewards and its last gives it back; the table is published at the rules' point after the frame's writes. The fake game's dropFor() and rewards; the chest-swap example; tests/test_game_rewards.py over made-up drops; docs/dev/reference/items.md says what was read and what a run confirms. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtworld.ray(from, to) -> RayHit? ({hit, position, normal?, distance}) against the game's own collision: the schema (modapi/schema/world.toml, RayHit in types.toml), its bindings, the reference and the d.ts made by generate.py. No game build answers it yet: services_game.c says false for world and world.ray, so a call throws NotAvailableError naming world.ray, and a mod written against it loads everywhere and works on the first build that answers. host/modapi/world.c's own answer, reached only by a stand-in game, is null. A read of the lifted code found the game's synchronous collision-query executor (it reaches Havok's hknpWorld::castRay through the physics manager's world). But it takes the physics world's lock, and whether the main thread may take that lock at the acquire phase has not been shown by a run; nor which filter preset is the scenery alone. docs/dev/reference/world.md says what a build needs before has("world.ray") says true. The fake game matches: world.ray absent unless a test gives a world (game.allowRay(cast)). tests/test_modrt.py checks the export, has() and the error; tests/mod_settings_fake.mjs the fake's absence and a hit against a test's floor, and a World's occlude as the host takes it. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtA script mod's own GLSL fragment shader over the picture (Modding API spec 10.3), with the permission gfx.shader (medium): gfx.effect({ shader, at, params }) gives an Effect handle with set(params), setEnabled(on), info() and release(). - The effect template, checked on the SPIR-V (gpu/vk/fx_spirv.h, plain C): one fragment main, the picture at set 0 binding 0, uv, one vec4 output, a push-constant params block read by name; no buffers, storage images, discard, atomics, barriers or specialization constants; counted loops only (1,024 turns through nesting and calls), no recursion, back edges only from a loop's continue block. The host checks it at the call (an ArgumentError saying why) and the renderer again before any driver sees it. - longshot-mod shaders compiles each .glsl with the pinned glslang (-V -g -S frag); -g keeps the source, which the host compares with the shipped .glsl. The game never compiles GLSL. - The host's list (host/modapi/gfx.c) and the renderer's passes (gpu/vk/vk_effects.cpp, shaders/fx_*): beforeUpscale on the gameplay upscale's input, afterUpscale and beforeHud on its output on every upscaler path, before frame generation's HUD-less copy; per-effect GPU timestamps, stopped over 2 ms (RX_VK_FX_BUDGET_US); RX_VK_FX=0 for an A/B. With no effect: fx_generation answers 0, nothing runs. - Render-target recipes (host/modapi/recipes.c): a gfx.textures mod's recipe.json sizes the renderer's own scalable targets (gpu/vk/mod_gfx.h: sunShadow, the Shadow resolution row's sizes) where the row is Auto. - MkwVkHost version 41 (fx_generation, fx_list, fx_code, fx_note, gfx_recipe): MKWVK_API_VERSION 40 -> 41. - The fake game's longshot/gfx (lib/fake-gfx.js), the example sepia-photo, docs/modding/gfx.md, the architecture's rules, gate 5's reserved names, tests/test_gfx_effects.py. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtgfx.effect and Effect.set took { amount: [1] } for a float param, as the fake game did: a float now takes a number alone and a vector a list of exactly its size, else ArgumentError (param "amount" is a number), in the host (host/modapi/gfx.c apply_params) and the fake game (lib/fake-gfx.js) alike. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtFrom the cold review of mods/sandbox: - host/json_keys.h: a strict JSON reader that decodes top-level keys, so a second "cmd" by any spelling ("\u0063md") or a trailing document is refused; the handshake must be exactly v and client_id, and the first application id is pinned for the broker's life. - own_scope serves the game (the broker's parent) and processes it started, by /proc's parent chain, at most four scopes a run. - The broker starts without LD_PRELOAD and sets PR_SET_DUMPABLE 0. - Discord streams are non-blocking; a zero-length datagram ends the channel and its fd is closed; logs/ and bug-reports/ are made before the broker realpaths them. - hos_broker_adopted: a restart's broker, so the sandbox is not applied a second time. - HOS_BROKER_TEST: tests/test_broker_frame.py now builds host/broker.c and drives open_thing, crash_send and own_scope with the programs only recorded, plus the JSON reader and the policy helpers. Co-Authored-By: Claude Opus 5.5 <[email protected]>M11 of the Modding API plan, the run-time half. The raw permissions are in the schema with their prompt words: memory.read, memory.write and hooks.unsafe of risk unsafe, romfs.read high; the manifest's rule that raw game data (romfs.read, memory.read) is never held with net: or session stays as it was, and now has users. - longshot/memory (host/modapi/memory.c): read(address, length) a frozen ArrayBuffer copy, write(address, data) queued and made after update with the flags' writes, regions(). Every range is checked against the game's memory map at the call, wholly in one part (host/hos_mem.c hos_mem_part: the image's segments by their permissions, the heap, the regions); Longshot's own objects and unmapped ranges are refused (MemoryError, reason and address), and writes into the game's code or read-only data too: the deny list's rule taken to memory. 64 writes and 256 KB a frame for a mod. - longshot/romfs: read(path, { offset, length }) and size(path) of the file the game is served (the RomFS layers, then the dump's folder), paths checked, 4 MiB a read. - longshot/hooks (host/modapi/hooks.c over host/game/modsites.c's slots): listen(site, fn), sites(), setValue(site, v) for a mod's own sites as mod_sites.txt says the game was built with them. A listener runs only at a serial site reached on the main thread while no script runs (an event frozen, a filter's sealed draft written back to the registers and its answer the site's); every other visit is recorded and told at the next frame (256 a frame); a data rule's value is the slot's, back to 0 when the mod stops. The Mods tab's line says "Unsafe" for a manifest with an unsafe permission, and the loader holds back a mod host/mods.c names (modrt_hold). - The generator's bytes parameters and results (an ArrayBuffer or a Uint8Array in, copied; a frozen ArrayBuffer out), in the C bindings, the adapter, the types and the fake game. - The fake game (lib/fake-unsafe.js): game.memory, game.romfs, game.sites with reach() and notBuilt(). - The example memory-viewer, docs/modding/unsafe.md for players and authors, and tests/test_modrt.py check_unsafe. Nothing runs with no mod using it: no thread, no read of mod_sites.txt, the slots off. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtM11 of the Modding API plan, the build's half. A manifest mod with the permission hooks.unsafe declares sites of its own in a sites.toml beside its mod.json: the rows of the game's own tables (docs/dev/reference/hooks.md), found by their signatures and hooked by the same compiler (nx2/mod_sites.py, after nx2/hooks.py's table in the lift). - The mods' rules (check_mod_site): no function, value, kind or module; `builds` maps build ids to the function in each (checked where the player's build is listed, and picking among several places); the forms entry, return, after, before, branch and allow; a worker site is an event or a data rule (mul_f32, scale_f32 over its slot's value), never a filter, a branch, an allow or a can_return; arguments named, at most 8; 32 sites a mod. - Found by signature in any game version; one site not found, or found several times and not settled, leaves its whole mod out ("not available for your game version"), not the build. A mod is placed whole or not at all: the lift's tables are put back when one of its sites does not fit. - A mod's site is a slot of host/game/modsites.h (256): the hook tests hos_modsite_on[k] and calls hos_modsite_call(c, k); a mod's data rule reads hos_modsite_value[k]. The engine's sites are emitted as before. - Code, as M0 has it: host/mods.c hashes a manifest mod's sites.toml (nx2/mod_sites.py code_hash the same), the mod is off until the player accepts its warning, the build takes it only as accepted (on or off), and the game holds it back whole while it was not built with the sites as they are now ("waits for a build"; hos_mod_build says a build is needed). The lift's key holds OOT_MOD_SITES_SHA1, the taken mods' ids, hashes and tables; none taken, nothing changes. - mod_sites.txt (the image folder, then the game folder with the mods the build left out) says what happened, a line a site, and is what host/modapi/hooks.c reads. - python -I nx2/mod_sites.py <mod folder> checks a table and finds it in an image on this PC without a lift. - The example site-event (a worker event site at the entry of the text panes' letter step, found by two instruction words, with builds), tests/test_mod_sites.py (the rules, one signature in two made-up game versions, builds, the emit, a mod placed whole or not at all, the list, collect and the key, the host's register reads and writes), and the contributors' and players' docs. Not built yet: longshot-mod sites port, a packaged mod's sites.toml, placing mods' new code in free space (M11 piece 4). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe unsafe tier's strongest step (Modding API spec 8.6, new; plan M11). A manifest mod folder with native/ sources and "native": {"entry", "std"} in mod.json, holding the permission native, is compiled on the player's PC by the game's own compiler, target and CPU level into mods_native/<owner>__<name>.so (.dll) beside the game, never into the game. - The ABI: modapi/native/longshot_native.h, C, usable from C++, versioned (LSN_API_VERSION 1.0). The mod exports lsn_mod_main through LSN_MOD_MAIN, which answers its version to a first call with NULLs: another major, or a newer minor, is refused before its code sees the table. The table: mod_id, mod_dir, log; on_frame, on_update, on_shutdown; export_fn; listen_site, listen_own_site and site_name, site_reg, site_nargs, site_arg, site_writable, site_set_arg, site_answer; mem_read, mem_write (one part of the map, never wrapping, never code or read-only data); setting_json. - The build (nx2/native_mods.py, called by nx2/make_game.py once the game folder holds the new game): each accepted mod's .c/.cc/.cpp/.cxx compiled with -O2 -fvisibility=hidden, only modapi/native/ and its own native/ on the include path, an undefined symbol failing the link, C++ runtimes static. One mod that fails is left out alone with the compiler's first error lines; a library built from the same code and commands is kept. native_mods.txt beside the game says what. - Accepted as code: host/mods.c hashes a manifest mod's code files (native/ and sites.toml, manifest_code_hash; nx2/mod_sites.py code_hash the same; a mod with sites.toml alone hashes as before), off until the player accepts its own warning, held back whole while its library is not built from its code as it is now. - The load (host/modapi/native.c over host/modapi/native_core.c): after the resolver, before any script, each native mod that loads is opened (dlopen; LoadLibraryExW with the UTF-8 path made wide) and its entry called; frame and update at orders 101 and 111 of the acquire phase, right after the scripts'; shutdown callbacks at exit. Each callback is timed and warned about past the script budgets (5 ms, 2 ms a frame). The Mods tab's switch stops and resumes its callbacks at once. - Sites: a named site is tapped (host/game/sites.c hos_site_tap: a dispatcher told before the site's own callback, whose answer stands; read-only, any thread); a mod's own site is given to its native listener (host/modapi/hooks.c), written back and answered only at a serial site reached on the main thread (host/game/modsites.c hands it the visit's context). - longshot/native (modapi/schema/native.toml): call(name, args), the mod's own functions or "<owner>/<name>:<fn>" of a dependency, values as JSON's plain data without objects; a failure is a ModCallError. The fake game's game.native (lib/fake-native.js) stands in for the C. - The example native-hello (a C entry that logs, counts frames, hears actors.update and exports add(), and a script that calls it), docs/modding/native.md, and tests/test_native_mods.py: the example's exports, one failure left out alone, the game's hash against the build's, the real loader over a fake table (version refusal, frames, the switch, values both ways, refusals, memory ranges with wrapping, shutdown), and the loader and the example compiled for Windows with llvm-mingw. Not built yet: native code in a packed .lsmod, the launcher's own prompt for native, storage through the table. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThree more kinds of typed patch file beside "ops" (host/mod_patch.h), the ones the content stage needs and a mod may ship too: - "rows": rows of a data table (the RSDB tables: an array of dictionaries sorted by __RowId, or the column "column" names). add puts a row in at its sorted place, whole or copied from another key with paths set or added (a copied ActorName that names the row copied names the new one); set changes a path inside a row; remove. - "placements": a map's placed actors by their 64-bit Hash ("0x..."). add appends one with its Hash and Phive/Placement/ID as uint64, its Translate, Rotate and Scale as floats and its SRTHash as a uint; set and remove by hash. - "texts": labels of a message file inside a language's text archive. A bounded MSBT reader and writer of Longshot's own (host/mod_text.c: LBL1 and TXT2, labels in their hash slots, UTF-8 or UTF-16; a file with another section is not written); set adds or replaces a label's plain text, remove takes it out; the archive written again with restbl_sarc_put. Each op has a path made of its key, so conflicts are found and named as for keys, and only between patches of one kind (and one message file). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtModding API spec 6.2, milestone M5 piece 6. mod.json's "content" names a module run once while the game starts, before its first file is opened (hos_mods_init), in a runtime of its own: context "content" (api.toml), importing only longshot, longshot/log, longshot/content and the mod's files. longshot/content's item, actor, model, place and text (content.toml; their shapes as TypeScript in the namespace's new ts_types) declare; the host makes the game's own kinds of files of them on the player's PC (host/mod_content.c), served through the RomFS layers as the mod's own: - a new actor: a copy of the pack of the actor it copies, as the layers serve it, with a new ActorParam whose $parent is the copied one and its changed components under the new name (host/mod_content_pack.c, made in the merged-file step, romfs_content_pack), and copies of its ActorInfo and GameActorInfo rows; - an item: an actor, its PouchActorInfo row, and its name, description and get message in every language's ActorMsg/PouchContent.msbt; - a model: the mod's own .bfres.zs and .bntx.zs files at Model/ and Tex/; - a placement: added to Banc/<map>/<map>_<age>_<layer>.bcett.byml.zs; - texts by label in every language's archive. Mod-owned names: a mod's word is M and the FNV-1a 32 of its id, a new actor <category>_<word>_<id>, a placement's id the FNV-1a 64 of its mod, map file and id: the same on every start and PC, and no game name has that form. Cached by content in modcache/content/ (the plan by the mod's script files, the outputs by the plan); the new packs in modcache/files/ by what they copy; the size table follows by itself. The permission content.add (medium), which also keeps a mod off "local" multiplayer; a mod with content and no entry loads with its content only. items.grant, items.held and actors.list take "owner/name:id" (":id" the mod's own). A text archive's patches build on host/texts.c's PC wording. The fake game runs the content module too (lib/fake-content.js, the same rules written again; game.content: names, outputs, problems against a fake RomFS), and tests/mod_vectors/content.json holds both sides to the same results and files (tests/test_mod_content.py, with the rows, placements, texts and pack builder on made-up files). Research and what a game run has to confirm: docs/dev/reference/content.md; authors: docs/modding/content.md. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe content stage's example (docs/modding/content.md): content.js declares Rupee7, a copy of the blue rupee worth seven (its bundle of green ones) in the purple rupee's colour frame, named in three languages, and LuckyPot, a copy of the game's pot, placed in Kokiri Forest for the child to drop it; main.js grants one by its id, items.grant(":Rupee7", { key: "welcome" }). Its tests read game.content's names, packs, rows, texts and placement, and the grant, in the fake game. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe branches each counted the examples they knew of ("twenty", "nineteen"); thirty are in modapi/examples. The guide's index names every one, and the examples page says thirty and lists all twenty plain JavaScript ones. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtA mod's entry imports longshot/content for read.row(table, key), read.text(file, label, { language }) and read.actorName(actor, { language }), behind the new low-risk permission content.read (facts of play: allowed with the network). Each answers with a Promise settled by a reader thread of the host's (host/modapi/content_read.c), which reads the file the RomFS layers serve after every mod's changes, decompresses and indexes it at its first read and keeps it for the session (64 MiB at most), so no table is parsed in a mod's callback; nothing runs with no call (gate 5). The formats are host/mod_read.c's: a table's rows by __RowId made JSON from the bytes, a message text made plain with the game's control tags left out. The fake game reads what game.contentData gives, the content stages' rows and texts applied over it; seven-rupee reads its own item's name back. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe setup API on the fake game (lib/game-test.js, the twin of the game's runner), a test entry's options ({ run, fake, game, timeout, skip }, game.skip), the tests built for the game (test/ to dist/test/) and longshot-mod test --game <game folder> [--save NAME], which starts the game's test mode (inside a Longshot checkout: dev.py game-tests) and prints its results as a fake-game run. docs/modding/testing.md for mod authors. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtWith a script mod on the game runs confined: the game folder (or the user folder) takes no new file, and mods.json is given alone, written in place. host/mods.c wrote it as mods.json.new moved over it, which the folder refused ("mods: cannot write <game>/mods.json: the change is kept and written at the next one"), so every switch was lost at quit (game run 5). longshot_options.ini goes through host/hos_atomic_file.h, which writes in place there. - host/mods.c write_file: when the new file beside it is refused (EACCES, EPERM) and the file is there, the file is written in place, as the settings are; logged once. A file that is not there is not made: the sandbox makes it. - The sandboxes (host/sandbox_linux.c, host/sandbox_windows.c): mods.json is HOS_MODS_LIST's list when the launcher names one, as host/mods.c has it (it was the user folder's: the rule named a file the game does not write, and a script mod switched off in the launcher's list still confined the game); nothing is carried into that list. - The other files script mods write at the top of a folder the game may not write: the items journal (longshot_mod_items.txt, beside the settings: host/modapi/items.c) is made at the start when missing and written in place, on Linux and Windows. The mods' stores, their data and settings (<user>/modstore/: host/modapi/storage.c), were outside every written folder: modstore/ joins the user folder's written folders on both. - Checked and left as they are: the content stage's outputs are in modcache/ (written); the system mods' switches are in mods.json; exefs_patches.txt and native_mods.txt are written by the build, never by the game. - docs/dev/reference/sandbox.md says so. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtA rows patch's add with "from" and no "set" (what actor({ from }) with nothing changed makes) has no value; apply_row read its member count through NULL (ModJson.n, +0x38) and the game crashed in mod_patch_apply at the start, for any mod with such a patch. The copy is now made as it is. tests/test_mod_content.py's rows check has the case. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt- Window x, y (its frame's top-left, kept on the screen), resizable with a grip, onMove and onResize: the renderer keeps where the player dropped it and its size until the mod gives other props, and tells the mod as the drag ends. Canvas onPointer ({x, y, kind: move|down|up|leave}) in its own coordinates, only in the window with the input, moves capped at 30/s by the renderer and coalesced to one a frame by the host. MKWVK_UI_SNAPSHOT_VERSION 6: MkwVkUiSurface.placed/x/y/resizable appended, the move/resize/pointer events and point/pointer values appended; MKWVK_API_VERSION stays 36. - inspect()'s lastSlow: the mod's last frame over the 2 ms warning (warned or faulted) as numbers from the budget's own ModRtCost (cpuMs, wallMs, apiMs, apiCalls, calls: the costliest 8 by name, gcMs, gcRuns, ownMs, pageFaults), copied at the frame's end only on a slow frame; kept by the loader's row once the runtime goes. - Types (longshot-ui.d.ts, longshot-together.d.ts: SlowFrame), the fake game (move/resize/pointer, modStats lastSlow), tests (modui_test.c, test_modui_layout.py, test_modui.py source checks, test_modrt.py check_system), docs (ui.md, ui-channel.md, system-mods.md's API, architecture.md rule 4). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtLayer A, typed component editing (content.actor): - components: a copied actor's components changed by reference (Life, LifeRef, CppExecutorParam), a path going on through the files a component names ("LifeParameters/MaxLife"): each file on the way copied under the new actor's name, the change made there, the references renamed. Relative numbers ({ $add }, { $mul }) against the copied file's value or its parents'. add (a member of the pack, or another actor's component copied with the files it needs: the donor's pack hashed into the cache key), remove (refused when one of the actor's own trees uses it). host/mod_content.c, host/mod_content_pack.c, host/romfs_merge.c. - content.read.component: a component as the actor has it, parents and named files filled in (host/modapi/content_read.c, host/mod_read.c). - longshot-mod types --game: every actor pack of the player's RomFS read (zstd, SARC, BYML) into longshot-components.d.ts and .json beside mod.json (never committed: .gitignore), which augment ContentComponents; the fake game checks a mod's components against the .json (lib/components.js). Layer B, scripted components (longshot/behaviour): - component(name, { rate, state, onSpawn, onUpdate, onDamaged, onDied, onLifted, onRemoved }), attach(type, component), each actor with a state of its own, run inside the mod's runtime over longshot/actors and longshot/game, with their permissions. content.actor's scripts attach them to the mod's new actors (native.attached(): host/modapi/content.c modrt_content_scripts). modapi/behaviour/runtime.js is the source of both the game's (host/modapi/behaviour_js.h, evaluated at the first import by host/modapi/ui_module.c) and the fake game's copy. Nothing is listened to until a component is attached; caps of 256 actors, 64 types, 16 components a type and 512 onUpdate calls a frame. Layer C, behaviour trees as data (content.tree): - host/mod_ainb.c reads AINB 0x408 with bounds, shows it as JSON, and changes it in place: node parameters, inputs' defaults, blackboard defaults, child links; bound parameters, fed inputs and new nodes refused. A tree is a copy of one of the pack's, renamed, in the new actor's pack. Schema: content.tree, content.read.component, ContentComponents and the tree types, the longshot/behaviour module; generated files, longshot.d.ts, the reference and the permission table regenerated. MKWVK_API_VERSION stays 36. Gate 5: with no mod using them, nothing of this runs (the module is made at its first import; packs without the new lines are built as before). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt- custom-enemy: the Brave Octorok, a copy of the Octorok with three times its life ({ $mul: 3 } through LifeParameters), a drop of its own, a copy of its main behaviour tree (tree(), no tweaks committed: a tree's nodes are the player's game's), its name in two languages, and the scripted component custom-enemy.Flee: below half its life it runs from Link. - magic-item: the Shock Stone, a named copy of the bomb placed in Kokiri Forest, whose component magic-item.Shockwave throws back the enemies near it when Link lifts it and counts its uses. TypeScript (tsc 7.0.2 --noEmit: no errors), dist/ built by longshot-mod build and committed; tests in the fake game. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtA new module, longshot/ipc (spec 9.4.1, docs/modding/ipc.md): ipc.connect(endpoint) gives a Connection at once (a mod's resource: close() and [Symbol.dispose] release it, StaleHandleError after) with send(bytes), connected(), and the events data (Uint8Array) and closed ({ reason, error }). Only endpoints mod.json's "ipc" declares (unix:<path> or pipe:<name>, {a-b} ranges, $XDG_RUNTIME_DIR, $TMPDIR, $HOME: host/ipc_endpoint.h); another is PermissionError. Limits: 4 connections, 64 KiB a send, 256 KiB/s each way, 40 attempts in 10 s. It runs on the network engine of longshot/net (host/broker_net.c, kind BNET_IPC, GRANT carrying the patterns, BNET_VERSION 2): in the broker under the Linux and Windows sandboxes, a thread of the game's otherwise, without libcurl or WinHTTP's WebSockets, and nothing starts until a mod connects. The engine checks the grant again and opens only endpoints a system mod this build ships declares (modrt_system_ipc in the generated system_mods.h). The permission ipc is system-only (it takes presence's bit); a player's mod naming it or "ipc" is refused by the manifest reader. The engine has no Discord code left (tests/test_no_discord_engine.py): host/discord_rpc.c, discord_activity.c, longshot/presence and its permission, the "with-presence" start (flag 8 reserved), modrt_presence_*, the broker's Discord relay (BROKER_DISCORD_OPEN, 3, reserved), the Insert menu's Discord status row (key discord_status retired, option 43 reserved) and HOS_DISCORD / HOS_DISCORD_APP_ID are gone. HOS_SYSTEM_MODS_OFF=<name>[,...] or * keeps system mods from being looked at (the parity gates, the pipeline tour and dev.py ab set *). system/discord (TypeScript) does all of it: Discord's frames, the handshake with the app id, SET_ACTIVITY with a nonce and ipc.pid, Ping/Pong and Close, discord_rpc.c's endpoints in its order, a sweep every 15 s and nothing else while disconnected, a change sent at once but never sooner than 15 s after the last, the 60 s keep-alive, and discord_activity.c's text rules. It is "always" (Safe start loads the "always" system mods). Its switch and texts are its settings; a setting's new "legacyOption" (system mods only) has the engine take the old longshot_options.ini line once as its first value, so discord_status=0 carries over. time.gameStarted() gives the game's start. Tests: test_modrt check_ipc (a fake Unix-socket program) and check_discord_idle (625 KB heap, 0 ns of script CPU and ~0.4 us of frame step per idle frame), test_broker_net's local connections in-process and through a broker child, and the mod against a fake Discord in the fake game (lib/fake-ipc.js). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtOther mods call into system mods as they call any library: - a system mod lists "exports"; a mod names it in "dependencies" ("system/discord", "? system/discord >= 0.3.0": a range is against the system mod's own version). The resolver takes the build's system mods as installed: nothing is fetched. Switched off, a required dependent does not load (dependency-disabled); an optional one runs and, unlike another mod's optional dependency, is imported (the trusted manifest gives the exports while it is off: modrt_system_manifest), its calls refused not-running. An export runs with the system mod's own permissions: the caller never holds ipc by calling Discord. - system mods' dist/mod.d.ts are included in @longshot/api (modapi/generate.py), so a dependent's types need no portal and no path; longshot-mod add system/<name> writes the mod.json entry alone. - system/discord 0.3.0 exports setActivity and clearActivity: a slot per calling mod keyed by caller(), the highest priority shown (latest on a tie), else its own status; callers set the two lines, the small picture and its text and startTimestamp, never the large picture, its text or the application; Discord's 128-byte rules, one send queue, at most 10 calls a mod in 10 s (LimitError); answers { shown, reason }; a stopped mod's slot dropped (running() at each look); the setting "Let mods set my Discord status"; the log says which mod sets it. - one switch: the "enabled" setting is gone; discord_status= is the mod's "system"."legacySwitch", which host/mods.c takes once when mods.json has no entry and writes as its entry. mods.json is read for system mods' switches with no mod of the player's and in Safe start (never written there). - the fake game runs the checkout's system mod beside a dependent (game.systemMod, off: true, game.switches, notLoaded), steps frames while the test's mod is off, and passes the API's own errors through calls as the host does. - example modapi/examples/discord-status (a speedrun split in the status), tests: resolve vectors (system mods), test_mods_together check_system_lib, test_mods_list system_switch, test_modrt check_discord_idle, the discord mod's slots, priority, stop, limits, switches. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe feature suite's first game run (2026-11-20): game.flags.set("PlayerStatus.Life", 8) was taken and flagChanged said 12 -> 8, but a frame later the flag was 12 again: the game copies Link's life component into the flag each frame. player.set's life and a write of PlayerStatus.Life by name now also queue his life component's write (by his address, under state.write, as player.setPosition does), made at his next update by the actors' site. tests/test_modrt.py's check_player_life checks both writes are handed over, and nothing with no Link. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtattach(child, parent, { bone, offset?, rotation?, mode? }), detach and attached (actors.write) are the game's own model bind: the request its action OneShotModelBindSetModelBind (f_829108c0) builds, handed to f_808b01e0 at the child's own update (the new inline site actors.bind at GameActor's entry, after actors.write), the parent's link made with the engine's setter f_802dc440, cleared with f_80980340 only while the component still names the parent (host/game/attach.c). Link is never a child; an actor the game holds (liftable bound, component bound) is refused with false, one another mod attached with ArgumentError; 16 a mod, 64 in all; NotAvailableError in a co-op room; undone when either actor dies or goes, the game rebinds the child, or the mod stops. Bind types 0-4 and 6 by the game's names; MultiBone and the physics joint are not offered. answer(query, filter, fn) answers QueryDeathIsDead, QueryLiftableIsThrownState and QueryLiftableIsPutState for the actors a filter names: each hook is called at the frame's serial point for each matching listed actor (32 at most, 1 ms a call), and its true or false goes into the query's table, read by an inline rule (query_answer, the generalised actor_lights) just before the query's store (sites actors.answers.*, host/game/queries.c). No hook, no table: one load. The fake game models both (game.attached, holdActor, answers()). API stays 36. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe feature suite's game run of 2026-11-20 17:02 still failed flags' life test ("12 !== 8") after 4dfcad04: its log has flagChanged 12 -> 8, then 8 -> 12, then 12 -> 8. The game copies Link's life component into PlayerStatus.Life before his update, where the component's write (handed over for him) is made, so the frame after the write the flag held his old life again, and the test read it then. tests/modrt_test.c's "lifecopy" makes the game's frame between two acquire phases that (the component copied into the flag, then his update making the write handed over), and test_modrt's check_player_life writes 8 and reads the flag each frame after. Fails here: the first read is 12. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe game copies his life component into PlayerStatus.Life before his update, where the component's write is made (a write is never made from the main thread), so the frame after a write of his life the flag read his old life: in the game run of 2026-11-20 17:02, flagChanged 12 -> 8, 8 -> 12, 12 -> 8 and flags' life test read 12. For 4 frames after such a write, at the start of the acquire phase before any script runs (modrt_writes_frame, from on_frame), the flag is set to his life component's value when that is the value written and the flag is not: the game's own copy, made before anything reads. host/game/actors.c's game_actor_life_now reads the component (bounded reads). Each of those frames is logged at info for the first 3 writes ("Link's life written 8, frame +1: PlayerStatus.Life 12, his life component 8 ..."), so the next run says what the game did if it still does not hold. Nothing without a write. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtmodrt_service_has named none of them and the game's functions do not either, so in the game has("ipc") was false and time.gameStarted(), memory.*, romfs.* and hooks.* threw NotAvailableError (lsapi_enter). They are the host's own: true. ipc answers bnet_ipc_available (new): a confined game's broker, else always, since the in-process engine's local connections need no libcurl (net.* still needs it). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtAn actor's type is its life parameters' name, which many share: every pot is "Pot" whatever its file, every character "NpcCommon", many objects "Obj_Invincible". Its file is now its own field: the name of its actor file ("Obj_Pot_A_01"), what actors.spawn takes, read where the type's fallback read it ([actor + 0x260], the pointer a spawn checks its actor by). ActorInfo, ActorEvent, ActorLiftEvent and ActorDamage carry `file`; list() takes `{ file }` (or `:id` for the mod's own), the actor events' filter takes it, and so does answer()'s (a hook may name a file alone). The damage and actor-life rules' `where.target` stays a type: a rule is applied where the game writes a life, which has the life component, not the actor. Gate 5: nothing is read while no mod reads actors (the service is off). With one, the text is read once an actor and again only when its pointer changes: a poll costs one 8-byte load an actor more, and the type's fallback is a copy of it (it read the text every poll before). An actor whose file is another, or readable for the first time, is a new actor, as for its type. The fake game, longshot.d.ts and the reference follow (modapi/schema); pot-hat and the attach and spawn feature tests find their pots by file. API version unchanged. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtEvery game starts hot reload's watch, with no mods too (host/mods.c hot_begin_empty), so that a mod the launcher adds while the game runs is found; gate 5 failed every lsmod- thread, so it could not pass. It now allows exactly that one thread, and only idle: the log says the watch waits on the system's notices (not "walked every 2 s", which the watch does where it can have none), and at the run's end /proc says it sleeps (state S), has used at most 0.1 s of CPU and been switched in at most 64 times. Two of it, its state unread, or any other lsmod- thread, still fails. From the code: the thread blocks in poll() on its inotify descriptor and an eventfd with no timeout (host/mod_watch.c; WaitForMultipleObjects with INFINITE on Windows) and wakes only for a notice of the mods folder or of a file written in mods.json's folder. parity-gates.md and mods.md ("A game with no mods") say what it costs: the thread and its 256 KiB stack, two watches and about 68 KB, 6 us of CPU in 10 s, one load a frame at the acquire phase. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtattach.h named 0x84c81388, an address 0x38 into the ModelBind's vtable that no object holds, so every actor was refused ("its components' +0x18 is not a ModelBind (class 0x84c81350)" for a spawned pot in the first game run). The class is 0x84c81350: its constructor f_83b3d8a0 stores it and sets the fields the attacher reads (+0x38 the bone pair 0xffff, the link at +0x70 with id -1, the name's buffer at +0x88/+0x94 of capacity 0x100, +0x1a0..+0x1a8), and its slots +0x68 (f_8097f570, the set-up) and +0xf8 (f_83b3dea0, the calc) are the ones the notes read at 0x84c81388 +0x30 and +0xc0. A subclass such as 0x84b6f1d8 overrides both and stays refused. The reference says so, and item 20 that the first run was refused for it. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtAn answer is the query's output in the trees that ask it, and nothing more: the first game run answered isDead true for an Octorok, the site took the mod's answer in place of the game's 1199 times, and the Octorok fought on. The docs, the schema and keese-ko promised a death ("told it is dead, an enemy plays its death", "an enemy told it is dead is gone"); they now say that answering isDead does not kill an actor and that what a tree does with an answer is its own. With the site's counts in the log, the host now also tells each mod with a hook on that query, in its own log (what its tests and logs() read), how often the trees asked it of an answered actor and took an answer not the game's. The reference records the run, gives the bomb's tree (QueryDeathIsDead beside OneShotDeathRequestDeath) as an unconfirmed example of one that may act on it, and item 21 asks for the count, not a death. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtTested in game: Linux (CachyOS, kernel 7.3.3), NVIDIA GeForce RTX 3090, driver 620.70.06, on the branch before its rebase onto main: three runs of dev.py game-tests (tests/game-features, kokiri-start save). Joined branch: 22 passed, 4 failed, 40 skipped; the 4 fixed since. With spawn/attach/answers: a start crash (loader use-after-free with >16 mods, fixed), then 25 passed, 4 failed (new feature mods' flags, Link's life read a frame early), both fixed since, not yet seen in the game. Seen working: the hooked title skip (in play ~11 s after the first controller read), Discord as a system mod from src/, actors, audio, camera, content, timers, input replay, rules, storage, HUD and windows, text, teleport. This PR's rebased head has not run in the game yet: next.
Since then, on the rebased head (this branch), Linux, RTX 3090, driver 620.70.06,
dev.py game-testsheadless (kokiri-start):7484bf59: 27 passed, 2 failed, 45 skipped. Spawn confirmed in the game (an Octorok asked, made in 284 ms, listed, removed; an unknown type settles with null); Link's life write holds; title skip in play 12.0 s after the first controller read.a426bf10: 28 passed, 1 failed. Answers confirmed: the game's trees took the mod's isDead answer (312 times by the end); the Octorok's tree doesn't act on it (now documented). Attach: the game's bind is made (ModelBind class fixed), but a pot bound into Link's hand broke.422ede7e(this head): the attach test now binds a Deku stick and a pot kept 0.6 m clear, and the host says why an attachment ends. Not yet run in the game.Recommendation: Request changes. The Modding API adds useful capabilities, but packaged scripts can start without the promised sandbox, CircleCI release packages omit the TypeScript compiler, and the new hook table contains instruction words taken from the game. Hot reload and save handling also have correctness issues that need fixing before merge.
Adds TypeScript and JavaScript mods, permissions and settings, built-in mods, hot reload, custom actors, graphics and audio APIs, and in-game tests. The shared API and loader give mod authors a consistent way to extend the game. The cost includes a compiler and runtime in player builds, additional startup and frame work, and new interactions with saves, input, Vulkan, and the launcher.
Does it help: Unproven at
422ede7e79. The description reports 22 passed, 4 failed, and 40 skipped on the earlier joined branch, then 25 passed and 4 failed after spawn and attach were added. It also reports reaching play about 11 seconds after the first controller read on one PC. There is no matching base run, repeatable frame-time comparison, or build, startup, memory, and VRAM comparison. The reported fixes after those runs still need evidence from the rebased head.Other systems: Both release pipelines, the Vulkan renderer, input and title flow, save storage, existing file and ExeFS mods, and launcher-owned mod lists are affected. The earlier Linux NVIDIA run provides some feature evidence. Windows, AMD, Intel, Steam Deck, controller navigation, and rendering with and without each upscaler and frame generation still need coverage where affected.
Switches: HOS_MODS_DEV defaults off. HOS_MODS_LIST defaults to mods.json beside the settings file, with a game-folder fallback. HOS_MODS_WATCH defaults on with notification or polling fallback. HOS_MOD_TESTS and HOS_MOD_TESTS_SAVE default unset, HOS_MOD_TESTS_ONLY defaults to all candidates, and HOS_MOD_TESTS_TIMEOUT defaults to 3600 seconds. HOS_NO_MODS defaults off. HOS_QUERY_MEMORY_OLD defaults off, selecting the new module-aware query. HOS_SANDBOX defaults to automatic, but its discovery and failure handling need fixing before that default can be relied on. HOS_SYSTEM_MODS_OFF defaults unset, so built-in mods follow their own rules. LONGSHOT_BROKER_FD, LONGSHOT_BROKER_PIPE, and LONGSHOT_SANDBOX_NOTE default unset and are internal. RX_VK_FX, RX_VK_TEX_PACKS, and RX_VK_WORLD default on where the corresponding mod feature is used. RX_VK_FX_BUDGET_US defaults to 2000, and RX_VK_LOG_TEX_HASH defaults off. HOS_DISCORD and HOS_DISCORD_APP_ID are removed without GONE rows. The former defaults enabled and the latter defaults to the saved or built-in app ID on base. The new --mod-tests, game-tests, and --sandbox-revoke modes require an explicit invocation or their documented environment equivalent where applicable. --window is opt-in. LONGSHOT_TS_A and --longshot-ts are unset by default in packaging, which currently permits incomplete release artifacts. The test and diagnostic defaults are reasonable in intent, but the player-facing runtime and renderer defaults lack measurements.
Reviewed:
422ede7e79against51f5f9da56: Read the base AGENTS.md, CONTRIBUTING.md, and Forgejo template in full, plus the applicable sections of docs/dev/standards.md. docs/review-checklist.md is absent. Read host/game/camera.c, host/game/modsites.c, host/game/phases.c, host/game/flags.c, and host/mod_switch.c in full. Inspected selected changes and callers in startup, sandbox discovery, loader and workers, attachment, save hooks, mod-list watching, the Mods tab, texture logging and crash reports, CI packaging, and the game and runtime test harnesses. Skimmed commit subjects and trailers, generated bindings and shader checks, vendored provenance, modding documentation, and the reported pre-rebase runs. The supplied discussion was empty. Coverage is incomplete across the 4,627 changed files, including the vendored source, the rest of the host and renderer, the mod tools and examples, translations, and much of the test suite.; nothing run (a code review).Checked and fine:
Blocking (to change before merge)
Waiting on the author (a run, a measurement or a decision; no edit does it)
c1bfc0d6b,57e55aa3b,00f7c1e9c,1c61d3190, and31c612120have neither trailer. Confirm their attribution and add the required trailers wherever assistance was used, including the squash message.Testing: Static review only. No build, test, or project script was run. The PR description contains the only runtime evidence and describes runs before the rebase. The reported strict suite result does not name the failures shared with main.
Overlaps and merge order: #1937 is the predecessor. Confirm with snaildev99 whether #961, #984, #1036, and #1089 are superseded before merging either stack. Coordinate #1577 and #659 because they share the title-to-save path, and keep shared-world spawning gated until #68 lands. The launcher companion PR needs a compatibility run with this game's mod-list and Safe start behavior. Merge order for the title and launcher work is unverified.
Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.
@ -0,0 +207,4 @@## Gate 5: nothing startedWith no mods, and the built-in ones kept off as the gates' runs keep them (`HOS_SYSTEM_MODS_OFF=*`), the game startsMeasure the shipped no-player-mod configuration with Discord enabled as well as the gate configuration.
@ -0,0 +17,4 @@at = "after"offset = 0x74 # (ldrh w9, [x19, #0x6e]; then cbz w9 to the return)signature_offset = 0x74signature = "7940de69 34000009/ff00001f 37200008/fff8001f" # (ldrh w9, [x19, #0x6e]; cbz w9, *; tbnz w8, #4, *)This commits instruction words from the game. Derive and verify signatures locally from the player's copy.
@ -35,4 +35,2 @@SW(HOS_DAV1D_THREADS, hw, int, "dav1d's own (one per logical core); 2 on a PC with 4 or fewer", "Sets dav1d's decoder thread count.")SW(HOS_DISCORD, kill, bool, "on: the Discord presence thread starts", "=0 starts no Discord rich presence thread at all.")SW(HOS_DISCORD_APP_ID, player, string, "the options file's discord_app_id=, else the built-in id", "Sets the Discord application id used for rich presence, over the options file's.")SW(HOS_DISPLAY_MODES, diag, string, "the screen's own display modes", "Gives a list of WxH display modes in place of the screen's, to check the menu's size rows for a screen you lack.")Keep users' Discord opt-out and app-ID preferences across the update, and add GONE rows for any retired switches.
@ -1704,0 +1966,4 @@const uint64_t hash = size == total && tex.astc && tex.blocks_hash ? tex.blocks_hash : texture_pack::full_hash(size, bytes);char of[48] = "";if (size != total) snprintf(of, sizeof of, " of %llu", (unsigned long long)total);logf("vk: texture hash #%u gpu %#llx NVN %#x %ux%u levels %u%s size %llu%s xxh64 %016llx sig %016llx", tex.id,The normal log feeds crash reports. Write game-derived texture hashes to a separate local diagnostic file.
@ -0,0 +253,4 @@if (e->slot < 1 || e->slot > GAME_ATTACH_SLOTS) continue;Slot *s = &bind_slots[e->slot - 1];int want = e->op ? S_ASKED : S_UNBINDING;if (!__atomic_compare_exchange_n(&s->state, &want, S_BUSY, 0, __ATOMIC_ACQ_REL, __ATOMIC_RELAXED)) continue;An old table can claim a recycled slot for a different child. Include the generation in the claim or wait for old readers before reuse.
@ -0,0 +338,4 @@int game_attach_busy(void) { return busy; }void game_attach_counts(GameAttachCounts *out) { *out = counts; }Copying the struct races with atomic counter updates from actor threads. Load the shared counters atomically.
@ -0,0 +30,4 @@const unsigned a = __atomic_load_n(&last_seq, __ATOMIC_ACQUIRE);if (a & 1u) continue;GameCamera copy;memcpy(©, &last, sizeof copy);The sequence counter does not make these plain payload accesses race-free. Synchronize both snapshots and the matrix reset.
@ -0,0 +25,4 @@}void *game_guest_at(uint64_t base, uint64_t off, size_t n) {if (off > UINT64_MAX - base) return NULL; /* (base + off would wrap: never p + off <= end, which wraps too) */return base + off >= 0x100000 ? hos_guest_range(base + off, n) : NULL;The reserved-window check accepts decommitted addresses. Check backing and lifetime through the copy, and check offsets before adding them.
@ -0,0 +428,4 @@fn(user, MOD_WATCH_OVERFLOW, ""), told++;continue;}if (e->wd == w->parent_wd && w->parent_wd >= 0) { /* (the root made, or moved in?) */The parent and list watches can share one inotify descriptor. Dispatch both roles and preserve the list watch when mods/ appears.
@ -0,0 +1052,4 @@modstore_attach(r->id, man->version.major, man->version.minor, man->version.patch);modrt_settings_attach(r->id, man); /* (its declared settings' values: host/modapi/settings.c, no permission) */if (r->system) modrt_settings_migrate(r->id, man); /* (a setting that was a line of the options file, once) */ModRt *m = modrt_create(r->id, r->root, r->start_grants, MODRT_HEAP_LIMIT, why, sizeof why);Require confirmed confinement here and for scripted content. The preflight misses enabled script packages and can disagree on manifest IDs.
@ -0,0 +1068,4 @@r->start_origins = NULL, r->nstart_origins = 0;}}if (m && !modrt_run_entry(m, man->entry, why, sizeof why)) {Default Discord synchronously compiles on the game thread every launch. Prepare verified code before the frame or ship build-bound compiled modules.
@ -0,0 +79,4 @@int part;const lsapi_status st = check(ctx, address, length, 0, &part);if (st != LSAPI_OK) return st;hos_mem_copy_out((uint64_t)address, read_buf, (uint64_t)length);The logical heap check does not guarantee backed pages or protect the mapping through the copy. Return an API error when access cannot be completed.
@ -0,0 +113,4 @@#ifdef _WIN32if (!GetFullPathNameA(asked, sizeof whole, whole, NULL)) snprintf(whole, sizeof whole, "%s", asked);#elseif (!realpath(asked, whole)) snprintf(whole, sizeof whole, "%s", asked);realpath can write past this buffer. Also check the Windows required-size return and reject long paths before applying test settings.
@ -0,0 +268,4 @@"failures=\"%d\">\n", T.passed + T.failed + T.skipped, T.failed);for (int i = 0; i < T.n; i++) put(&x, "%s\n", T.junit[i] ? T.junit[i] : "");put(&x, "</testsuites>\n");const int wrote = j.s && x.s && write_text("results.json", j.s) && write_text("junit.xml", x.s);A failed report write or dropped result must make the run incomplete.
@ -0,0 +343,4 @@}started = 1;wgive();if (!mod_watch_thread(watch_main, NULL, "lsmod-watch")) {Roll back the watcher and started flag on partial startup failure, including failure to register the frame phase.
@ -1043,0 +3025,4 @@/* (longshot, version 37) a script mod's page: its header, its declared settings and its permissions (host/modapi/modrt.h);0 for an emulator mod or past the end */int hos_mod_page(int i, MkwVkModPage *out) { return i >= 0 && i < nmods && mods[i].id && modrt_page(mods[i].id, out); }The renderer reads mutable loader rows and strings while the game thread updates them. Publish an owned snapshot and use stable IDs for edits.
@ -1076,0 +3332,4 @@static int known_path(const char *path) {for (int i = 0; i < nmods; i++)if (hot_same(mods[i].path, path)) return 1;A removed folder still counts as known, so reinstalling it at the same path does not restart it. Reconcile the tombstoned row.
@ -530,6 +555,7 @@ HLE(_ZN2nn2fs9WriteFileENS0_10FileHandleElPKvmRKNS0_11WriteOptionE) {wrote_now();WriteFile(fh->h, GP(ARG(2)), (DWORD)ARG(3), &put, &ov);wrote_now();fh->wrote = 1;Failed or short writes still cause a save commit at close. Publish the storage event only for a completed save.
@ -178,0 +253,4 @@if (count != wait_seen) {const int screen = __atomic_load_n(&told_screen, __ATOMIC_RELAXED);const int64_t begun = __atomic_load_n(&told_ms, __ATOMIC_RELAXED);if (__atomic_load_n(&told_count, __ATOMIC_ACQUIRE) != count) return; /* (another began meanwhile: the next read) */A writer can change the fields before incrementing the count. Publish the screen and timestamp as one coherent event.
@ -0,0 +733,4 @@const int fs = plan.abi >= 1 ? apply_landlock(&plan, &in, threads) : 0;if (plan.abi < 1) say("sandbox: no Landlock in this kernel (%s): files and folders are not confined", abi_raw < 0 ? strerror(abi_err) : "ABI 0");const int net = apply_seccomp(threads);confined = fs, network_closed = net;Require both Landlock and seccomp before allowing player scripts. This currently treats files-only confinement as success.
@ -0,0 +136,4 @@"--mode", "shared", "--desc", plan["desc"], "--"]if not quiet:say("queued (shared); %s" % plan["desc"])session = longshot_bridge.start_session(An empty env file still leaves inherited switches such as HOS_MOD_TESTS_ONLY and HOS_HEADLESS. Scrub them before starting the run.
@ -0,0 +152,4 @@breaktime.sleep(2)info = session.info()for name in ("results.json", "junit.xml"):A failed launch can reuse the previous run's passing JSON. Use per-run report paths and validate the process exit.
@ -73,0 +85,4 @@# (scripts/longshot_ts.py build --target linux) and named by LONGSHOT_TS_A, which a player's build links into the game# (nx2/build.py ts_library). Its crates' licences go with it; the crates themselves (third_party/oxc/vendor) stay out.# Without it the game runs JavaScript mods only)if [ -n "${LONGSHOT_TS_A:-}" ]; thenCircleCI release jobs supply no compiler archive on either platform. Make the release input required and wire it into both pipelines.
@ -0,0 +270,4 @@# (the tracked source copied out of the tree, with a cargo home of its own that replaces crates.io by the vendored# crates: target/ and the cargo home are never written into host/ or third_party/. One fixed folder, emptied first)work = os.path.join(cache, "work-longshot_ts")shutil.rmtree(work, ignore_errors=True)Concurrent builds sharing this cache delete each other's work directory. Give each invocation a separate directory.
@ -0,0 +291,4 @@"RUSTC": os.path.join(bin_dir, "rustc" + exe),"CARGO_HOME": home,"CARGO_TARGET_DIR": os.path.join(work, "target"),"CARGO_ENCODED_RUSTFLAGS": "\x1f".join(flags.split(" ")),Splitting on spaces breaks remap arguments for checkout and cache paths containing spaces.
@ -0,0 +3749,4 @@p.add_argument("--cc", default="gcc")p.add_argument("--only", help="run only the checks whose name holds this (check_source_maps: source_maps)")a = p.parse_args()if os.name == "nt" or not shutil.which(a.cc):Run this suite on Windows, honor CC, and make successful TypeScript compilation a required case with a target-matched archive.
longshot/content's read.placements(map, { param }) answers the actors placed in one of the game's maps, from its Banc/<folder>/<map>_Dynamic and _Static files as the RomFS layers serve them: each { id, actor, layer, position, params }, the id being the placement id items.checked names a check by and rules.rewards takes. A randomizer or a tracker then learns the game's checks at run time from the player's game, with no table of ids (game data) in the mod. host/mod_read.c mod_read_placements_json (bounded BYML reading, 8 MiB at most), host/modapi/content_read.c's reader thread (the Banc folders listed once; each call reads the files again), the schema (content.read.toml, PlacementsOptions) and the generated files, services.c's feature, the fake game's contentData({ placements }). Tests: tests/test_mod_content.py (the reader over made-up files, both byte orders, the filter, refusals), tests/test_modrt.py check_content_read (the call in the real runtime). API version stays 37. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtGap 3 of the randomizer's: a content module may import longshot/settings and call get (read only; set and changed stay the entry's). The content plan's key (host/modapi/content.c plan_key) now holds the values of the mod's settings marked restart, so a change of one runs the content module again at the next start: the randomizer's gossip stones can carry the seed's hints. generate.py allows settings.get alone of the game namespaces in the content context. Gap 7: items.remove(item, { count }) takes from Link at the call, in play only: a pouch content through the add's own action, OneShotAddOrRemovePouchContent (f_828d4a70), with a negative count, as the Debug tab's remove; a song by its IsGet flag through the game's setter, marked so the poll does not take the flag back to 0 for a load. Permission items.grant; nothing queued or kept; has("items.remove") with the give. Fake game, docs and generated files follow. API version stays 37. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtGap 5 of the randomizer's. The host's own map change (host/hos_main.c oot_teleport: the event request an entrance sends, built by the host) and its age switch (oot_toggle_age: Sequence_IsChildhood set, the map loaded again for that age), which the Debug tab's Teleport and Switch age and the control bridge already use, become the mod API's: - world.destinations(): the host's table of the game's maps (child's, adult's), names only (state.read). - world.travel(map) and player.setAge(age) (state.write): asked into the host's one queue (taken at Link's next update in play), settled { done, map, why } at the acquire phase after update by host/modapi/travel.c (modrt_travel_frame); a later ask replaces one not taken, 30 s untaken is cancelled. One load a frame while nothing waits (gate 5). - has() true in Ocarina of Time builds; the fake game models it (setDestinations, travels); docs/modding/writes.md. API version stays 37. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtGap 10 of the randomizer's. The three sites Skip opening already uses (opening.request f_80d9a820, opening.timeline f_83b5bfb0, opening.skipQuery f_80de6cb0) call host/game/skips.c first: while the latest one-shot event a sequence asked for is one a mod named, its timelines are left unstarted (the player's hold bit cleared, as for the opening's) and the event's script is told it was skipped, so it takes its own branch for a skip. The arm goes at another request and once no event plays (reset with Skip opening's in Link's update). rules.skips.add({ event }) returns a Rule (state.write, 64 a mod); host/modapi/rules.c publishes the running mods' names once each as the HOS_TABLE events.skips at the rules' point. With no skip the sites read one pointer (gate 5). The fake game models it (skips, requestEvent), docs/modding/rules.md#skips. No event names ship: a mod names them, and the log says when a skipped one is asked for. API version stays 37. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtGap 2 of the randomizer's (with content.change for freestanding items and scrubs' stock). Every give of an event flow ends in the event action OneShotAddOrRemovePouchContent (f_828d4a70), which copies the item's name into a buffer of its own frame before it turns the name into a category and adds it. A new inline site, rewards.gift (+0x254, where its four paths join; template reward_rules_gift), writes a gift's item into that buffer, within its capacity, when the name, the map and the giver (the action's owner's placement id) match: rules.rewards.add({ where: { gives, map?, giver? }, give }) beside the drops' where.location, under the same claim. host/game/rewards.c publishes the gifts' own table only once a gift is added (a mod of drops alone costs nothing more: gate 5); with none the site is one load. Not covered and said so: the event's text and shown item stay the game's, shops' prices, cows' milk, tokens. The site's signature is unique in build e0f3ccfa (nx2/hooks.py); the lift key changes with the table. Fake game (giftFor), docs (rules.md#rewards, items.md: what a run must confirm). API version stays 37. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtread.placements(map, { actor }) keeps one actor's placements (its Gyaml), filtered on the reader's thread, so a mod asks a map for its Gossip Stones (Obj_GossipStone_A_01, whose placements have no parameters to filter by) without the whole map's placements crossing into its script. Fake game, schema. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtactor({ id, from, skin: { "<texture name>": "x.png" | { file, format } } }): the content stage gives the copy its own model project (<word>_<id>: ModelInfo's ModelProjectName and the ActorInfo row's, FmdbName kept) and copies the images into its folder; the merged-file step, once the copy's pack is served, reads the copied actor's model as the layers serve it and makes, in modcache/files on the player's PC: - Model/<project>.<fmdb>.bfres.zs: the game's model with each skinned texture's references in every material renamed <project>_<n> (host/bfres_edit.c: strings added in the room after the pool, or after everything with the relocation table moved; nothing else changed; checked over 200 of the game's models on this PC, made from the game and kept off the repository); - Tex/<project>_<n>.bntx.zs: the PNG as a BNTX of the Switch 2's (host/bntx_write.c: 4.1.1, Ounc, block-linear in the Switch 2 GOB, mips down to 1x1, BC7 by bc7enc or RGBA8), in the game texture's colour space and channels. The writer's frame re-creates 373 of 373 sampled game textures byte for byte from their data, on this PC. The makers are hooks the content stage sets (romfs_merge_assets), so the merged-file step still links without the encoders. Keyed by the spec, the model's, the images' and the game textures' bytes. Not yet run in the game: docs/dev/reference/assets.md (next) lists what a first run has to confirm. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEttests/test_mod_assets.py: mod_assets_model_check on made-up BFRES files and a made-up pack: a model used, the bones its actor's components name that its skeleton lacks said (strings under keys with "Bone", FmdbNameForRepresentativeBone and paths aside); refused: a model named otherwise than its file, a texture neither the mod nor the game has, version 9, two models, no bones, not a BFRES. tests/mod_vectors/content.json: content.model's textures as .png images (a string, or { file, format, srgb }) made BNTX files, a .bntx.zs kept, and the refusals. Fails until the next commit. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt- textures may be .png images ("<word>_<name>.png", or { file, format: "bc7" | "rgba8", srgb }): the content stage makes each Tex/<word>_<name>.bntx.zs on the player's PC (host/bntx_write.c, keyed by the image's size and last write), as the skins' are; - the merged-file step checks the model before it serves the actor's pack (host/mod_assets.c mod_assets_model_check, a hook the content stage sets): a BFRES 10 of one model named as its file (the game finds it by FmdbName), each texture its materials name served by the mod or the game; a model that fails leaves the actor out, with why in the log. The bones the actor's components name (Phive, ModelBind, LookIK, FootIK...: every string under a key with "Bone" in its pack) that the model's skeleton lacks are said, kept in the pack's record so a start from the cache says them too; - the model's bytes are part of the pack's key, so a changed model is checked again. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt- content.actor({ animations: ["anims/x.anim.bfres" | { file, order: "first" | "last" }] }): each file served as Model/<word>_<id>_A<n>.anim.bfres.zs (a plain .anim.bfres made a zstd frame on the player's PC) and named in the copy's Animation component's AnimationResources, before the game's (first) or after; an animation named as one the actor plays can take its place (which one the game picks across several resources is a game run's to say). The pack builder copies a list the parent gives into the component before it adds to it. - The merged-file step checks each file (host/mod_assets.c mod_assets_anim_check: a BFRES 10 of FSKA and no model, every field inside the file) against the model the new pack names, and says what it holds and the bones it moves that the model lacks (never refused: the game binds bones by name). - longshot-mod anim <gltf|glb>: a glTF's named animations sampled at 30 frames a second and written as the game's animation file (lib/assets.js: FSKA with quaternion rotations, 16-bit frames, float keys: Hermite values and slopes, quaternion keys; the names' dictionary as nn::util::ResDic builds it, which gives the same nodes as all 252 dictionaries of 60 animation files and 200 models of the game read on this PC, kept off the repository). The author's curves only: the file ships with the mod. - longshot-mod skeleton --game DIR --model <project>.<fmdb>: the skeleton of a model of the author's own game as a glTF to animate against (never shipped: pack leaves *.skeleton.gltf out). - longshot-mod check: the mod's PNGs (at most 4096 a side, not interlaced) and glTF files (as anim takes them). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEt2749e506722233d622aeWebsite preview: https://pr-1958-longshot-website.hckr-5e0.workers.dev
This commit (
5702ebc5e0) on its own: https://f769b7cb-longshot-website.hckr-5e0.workers.dev5702ebc5e01297f8701bView command line instructions
Checkout
From your project repository, check out a new branch and test the changes.