WIP: feat(modapi): apply scripted actor damage through native life processing #2175
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
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!2175
Loading…
Reference in a new issue
No description provided.
Delete branch "snaildev99/Longshot:feat/actors-native-damage"
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
Mods can currently change an actor's health directly, but that does not register a hit with the game's damage processing. Add
actors.damage(actor, amount)andactor.damage(amount)so scripted attacks can cause native health loss, damage/death events, death behavior and drops.This targets
mod-apiatcc776c67f, depends on #1958, and contains only the damage feature. Amounts are integer quarter-hearts (1–65535), attributed to the player. Calls requireactors.write, a living non-player actor and active play. Each hit stays a separate bounded request, applied at the actor's own update through native life processing. This is direct scripted damage; it does not simulate weapon collision, shield contact or hit locations.Start with
host/game/actors.c(native registration and request lifetime),host/modapi/actors.c(validation/queue), andmodapi/schema/actors.toml(public contract). Includes generated bindings/docs, fake-game support and regression/game tests. In-flight write slots remain owned until their guest call returns.Testing
Tested:
mod-api. The three native implementation files (host/game/actors.c,host/modapi/actors.c,host/modapi/services_game.c) are unchanged by the rebase; a complete in-game run of the rebased build is still pending.tests/test_game_actors.pyandtests/test_modapi_damage.py, compiled with llvm-mingw Clang, pass. Coverage includes distinct consecutive hits, independent health setters, request limits, invalid amounts, stale/dead targets and play-state validation.modapi/generate.py --checkandgit diff --checkpass.Still to test:
Measurements
Performance measurements are pending: compare frame time and memory with no damage requests and sustained scripted hits, using interleaved runs on the same scene and settings. No performance improvement is claimed. Request capacity remains bounded; each damage request consumes an existing per-frame write-budget slot. No build, cache or loading behavior is intentionally changed.
Risks
Native life processing and write-slot lifetime are sensitive to actor lifecycle and guest-call ownership. Actor identity and life are rechecked at application, damage entries never merge, and in-flight entries are not recycled. Actor-specific immunity/reactions still need broader testing. No save format, settings or cache migration; disabling a consuming mod stops scripted damage. Revert the feature to remove the API.
Checklist
Ready for review
mod-apibecause this extends #1958 rather than standalonemain.mise run testpasses: full-suite failures have not yet been triaged against the base.third_party/untouched.Ready to merge
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_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_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_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_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 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_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_017vw8e3nBDxBnhodLguFyEtlongshot/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_017vw8e3nBDxBnhodLguFyEtA confined game writes mods.json in place, and acceptance ("accepted") and grants of native, memory.read, memory.write and hooks.unsafe were read from it, so a game taken over could accept its own code, or grant itself native, for the next start, which with no script mod on is not confined. They are now kept in mods-trust.json beside the list (the game folder's own for a list in its user/ folder, which the game may write; host/mods_trust.c), which Landlock and the AppContainer give the game read alone. A confined game asks the broker to keep the player's yes (BROKER_TRUST: id, key, value, checked for form, written in place in the file the game named before it was confined, at most 256 a run, said on stderr, shown to nobody); an unconfined one writes it itself. host/mods.c and the build (nx2/exefs_patches.py, native_mods.py, mod_sites.py) read acceptance from it alone, and the loader is told the unsafe tier's grants from it alone: an "accepted" or an unsafe "granted" in mods.json counts for nothing, and its mod asks once more. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtA pointer a mod writes into the game's memory, which the game then follows, reaches any host address: the lifted game follows guest pointers unchecked (host/hos.h). So memory.write amounts to native code in the game's process, and its prompt ("Full access to the running game") understated that (audit M6). It is worded as native's now, and docs/modding/unsafe.md says it is native-equivalent, with no code to accept and no build step: the prompt is the only question. It is not put behind code acceptance: it has no code of its own to hash (its writes are made by the mod's script at run time), so an acceptance would be of the script, asked again at every update, and would add nothing the prompt's grant does not. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe UI had nothing to keep a view at its newest: a log's List stayed where it was as lines came, so the mod inspector's Log tab showed old lines while new ones arrived below (a player's "doesn't follow scroll"). follow="end" on a Scroll or a List keeps it at its end while it is at its end, the usual log view: it starts at its end, stays there as items are added, stays where the player leaves it once they scroll back (the wheel, or the focus moved to an earlier item), and follows again once they scroll to the end. "none", the default, stays where it is. - host/modapi/ui.c: the follow prop ("none", "end"; a Scroll's or a List's only), MKWVK_UI_FLAG_FOLLOW_END in the snapshot (a flag: the snapshot's layout and version are the same, and a renderer without it ignores it). - gpu/vk: modui::follow_offset, from where it was left and the most it scrolled the last frame it was laid out; the renderer keeps both for each node that follows and lets go of them with the node. - The fake game takes follow and refuses it elsewhere; the types (Follow, ScrollProps, ListProps.follow) and docs/modding/ui.md and ui-channel.md say it; the inspector's Log List follows, 0.5.1. - Tests: tests/modui_test.c (the prop, set, "none" and taken off, refused on a Column and for "start"), tests/test_modui_layout.py (a log List kept at its end as lines come, left where the player scrolled back, following again at the end, and still without follow), the inspector's Log test (its List follows). Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtEnemy Names said "enemies: listed ..., near ..., labels ..." once a second whether or not anything changed: in a player's run at the title screen it was 46 of the mod inspector's last 50 lines ("(no position for Link)" each time). The tests now want the line when what it says changes (checked once a second: five seconds of the same say nothing more), and a new one when an enemy comes near; with no Link (game.toTitle(): the title screen) no labels and one line saying Link is not in play; and with Link back in play, labels by his position (game.setPlayer: an enemy 4 m from him labelled, then none once he is 34 m from it). Both fail here: the line is said every second, and its words are "(no position for Link)". Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtThe world layer draws on the gameplay upscale's picture after the upscale wrote it (upscale_written), but temporal_world_scene read the chain's s.cam, which DLSS, FSR, XeSS and Off's stretch each mark used (valid = false) as they draw. With one of them drawing the upscale, a World root of occlude "depth" was never drawn ("no 3D scene this frame" in the log); only the game's own network left the camera to it. Fails here: it reads cam, the camera they take. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017vw8e3nBDxBnhodLguFyEtca5b262f8ftoc943ed27b8Rebased the damage-only commit onto mod-api
cc776c67fafter its upstream history rewrite. Native damage implementation and focused test inputs are unchanged; generated schema check still passes. The PR remains WIP for the validation listed in its description.@review
Recommendation: Request changes. Repeated damage requests can fill the shared pending-write table and silently discard accepted hits and other actor writes. The new test also hard-codes GCC, so it does not honor the configured compiler.
Adds player-attributed scripted damage through native actor life processing, with generated API bindings, documentation, fake-game support and tests. It enables native death behavior without directly setting health, at the cost of additional queued writes and unmeasured work during actor updates.
@fixwill do (3)host/game/actors.c:761: When the 256 pending slots are full, this silently discards requests that already returned true to their mods. (more on the line)tests/test_modapi_damage.py:11: The suite always passes gcc to this test, ignoring CC. (more on the line)tests/game-features/damage/test/damage.test.ts:7: The probe accepts any health decrease and any damage event, then passes if the enemy dies and is removed; a player or another game event could cause those outcomes even if the scripted hit did nothing. (more on the line)Before merging: testing (2) (runs on the systems it can change; it doesn't hold the recommendation)
host/game/actors.c:664: Run the rebased head through scripted nonlethal and lethal hits, repeated waves and transitions on Windows and Linux, including enemies with different immunity and death behavior. (more on the line)host/game/actors.c:677: Measure frame time and memory on the same scene and settings against the base, with no requests and sustained scripted hits, using interleaved runs. (more on the line)Checks: Still running:
Guide screenshots / Guide images and local UI source review (pull_request),Third-party parts / As their notes say (pull_request),Third-party parts / The same as upstream (pull_request),Website / Website on Cloudflare (pull_request).More: does it help, other systems, switches, what was read
Does it help: Unproven on this head. A Windows run of the unchanged native implementation before rebasing showed a Tektite lose health, emit damage and death events, drop a rupee and be removed 74 frames after death. The rebased build and broader enemy behavior have not yet been run in game.
Other systems: The write table also carries actor setters and player position writes, so damage traffic can affect those requests. Native registration runs on actor-update workers and can interact with enemy-specific immunity, reactions, death and drops; only one enemy on Windows has reported game evidence. Linux and transitions remain untested.
Switches: None.
Reviewed:
c943ed27b8againstcc776c67fa: Read AGENTS.md, CONTRIBUTING.md, the pull request template, relevant standards, the diff, commit trailers, actor write and mod queue code, the fake damage path, and the new tests. Skimmed generated bindings and documentation. The requested review checklist and adjacent Tooling checkout were absent. Large combined file output was truncated, so not every changed code file was read in full.; nothing run (a code review).Checked and fine:
Testing: Read-only review; no builds, tests or project scripts were run. The description reports focused tests passing on the head and an earlier Windows game run; the full suite, Linux build and rebased game run remain pending.
Overlaps and merge order: The PR states it depends on #1958 and targets mod-api. No other overlap information was available.
Automated code review by BeanBot (gpt-6.1-terra), asked for by HumanBean. Nothing was run; a maintainer decides.
@ -724,1 +758,4 @@if (pending[i].used && !((pending[i].e.what | w[k].what) & GAME_ACTOR_WRITE_DAMAGE) &&(pending[i].age < 0 || (__atomic_load_n(&tickets[i], __ATOMIC_ACQUIRE) & 3) == T_WAITING) &&pending[i].e.actor == address && pending[i].e.components == components) slot = i;else if (!pending[i].used && free_slot < 0) free_slot = i;L1: When the 256 pending slots are full, this silently discards requests that already returned true to their mods. For example, two mods can submit 128 separate hits per frame to actors that do not update; by the third frame the earlier requests have not yet expired and the new hits, including unrelated setters sharing the table, are dropped. Reserve capacity when accepting requests or propagate exhaustion to the caller, and cover sustained requests across frames.
@ -640,0 +661,4 @@record[8] = 1;record[9] = 1;HOS_WRITTEN(record, 0x28);return game_call(c, GAME_ACTOR_REGISTER_DAMAGE, arg, 3,L4 (minor): Run the rebased head through scripted nonlethal and lethal hits, repeated waves and transitions on Windows and Linux, including enemies with different immunity and death behavior. Check events, attribution, drops and stale requests.
@ -647,3 +675,3 @@else hi = mid;}if (lo >= t->n || t->e[lo].actor != actor) return;for (; lo < t->n && t->e[lo].actor == actor; lo++) {L5 (minor): Measure frame time and memory on the same scene and settings against the base, with no requests and sustained scripted hits, using interleaved runs. The change adds per-hit queue entries and native calls but supplies no cost measurements.
@ -0,0 +4,4 @@game: true, timeout: 3600,run: async (game, assert) => {await game.waitFor(() => game.logs.some((e) => e.text.startsWith("native probe PASS")), 3000);assert.ok(game.logs.some((e) => e.text.startsWith("native probe nonlethal life")));L3 (minor): The probe accepts any health decrease and any damage event, then passes if the enemy dies and is removed; a player or another game event could cause those outcomes even if the scripted hit did nothing. Assert the expected health change and player attribution for the submitted hits, and distinguish the lethal request's outcome.
@ -0,0 +8,4 @@import sysimport tempfileRUN_ALL_ARGS = ["--cc", "gcc"]L2: The suite always passes gcc to this test, ignoring CC. A Windows or Linux setup configured with Clang but without GCC cannot run the suite. Use the runner's {cc} placeholder so it honors the selected compiler.
View command line instructions
Manual merge helper
Use this merge commit message when completing the merge manually.
Checkout
From your project repository, check out a new branch and test the changes.Merge
Merge the changes and update on Forgejo.Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.