Compare commits

...

36 Commits

Author SHA1 Message Date
0324e3e626 docs(runicnpc): the death-screen name check, deferred to the org lead
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 23:27:09 -05:00
e3ae1905cb docs(runicnpc): stage 1 measured, D231
The harness answered all six stage 1 questions on both rigs, on one 6000 world:
the swap needs AwakeFromInstantiate; unsaved NPCs never return; Rust's brain
honours sense values only before it starts, roams only in AI zones and never
attacks NPCs; placement checks use Rust's Gen2 navmesh (89% of monument points,
never a player-built floor); the cost table for 1/10/100 idle and fighting on
Oxide and Carbon; the death screen needs an AttackerInfo override, and the
bridge's frames still name the prefab.

D231: each profile or group decides whether its NPCs target NPCs, and which
kinds, which needs our own combat state and sensing (stage 5 spike).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 23:23:35 -05:00
23c2a5a5cf Merge pull request 'docs(runicnpc): stage 0 as built, D229–D230' (#299) from docs/runicnpc-stage0 into main
Reviewed-on: #299
2026-09-30 02:05:26 +00:00
ced4755ebb docs(runicnpc): stage 0 as built, D229-D230
Records what runicnpc-rust#1 built for stage 0 and the two decisions taken with
it: the empty repository seeded by one chore commit to main, then edge and PRs
(D229); plugin/RunicNPC.cs + plugin.toml rather than an overlay tree (D230).
Notes the Oxide floor that differs from the bridge's (2.0.7726, what the rig
runs), the three checks added over the bridge's checker, the manifest's `api`
field, and con.js renamed console.js because CON is a reserved device name on
Windows. PLAN_REDESIGNS' pointer now reads D214-D230.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 21:04:47 -05:00
216bbf9c54 Merge pull request 'docs(runicnpc): plan RunicNPC, our own Rust NPC plugin (D214–D220)' (#298) from docs/runicnpc-plan into main
Reviewed-on: #298
2026-09-30 01:47:49 +00:00
aec01342d5 docs(runicnpc): record the org lead's answers, D221-D228
Standalone use too (D221), placements live on the server (D222), our own
scientist subclass and brain (D223), installer and egg ship it plus a
Gitea release and possibly other download sites (D224), per-profile
kills public and in titles (D225), edge to main (D226), no default caps
but a measured cost warning wherever NPCs are added (D227), and the
names RunicNPC, /rnpc, runicnpc.* (D228). The sections they change are
updated: standalone profiles, the console profile verb, cost warnings,
stage 1's measurements, and publishing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 20:38:28 -05:00
97be4fb5ab docs(runicnpc): plan RunicNPC, our own Rust NPC plugin (D214-D220)
The PLAN_REDESIGNS §6 spike ran on the Oxide rig on 2026-09-30. Route A
kept its kit and fought with it but cannot be named; HumanNPC counted its
NPCs as players in the killfeed and tallies; NpcSpawn worked but costs a
boot hitch, a phone-home and an unbundleable dependency. The org lead
chose to write our own API-style plugin in runicnpc-rust.

runicnpc/PLAN.md records the spike, the decisions, the features, the API,
the chat commands, and stages 0-10 with how each is tested, plus eight
questions. PLAN_REDESIGNS §6, §9 and §10 point at it; the index lists it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 20:31:57 -05:00
71ab0c01af Merge pull request 'docs(rust): the map's monument labels as built and walked — PLAN_REDESIGNS 4.1, D213' (#297) from docs/rust-map-markers into main
Reviewed-on: #297
2026-09-30 00:17:04 +00:00
d7b178fb8b docs(rust): the map marker labels as walked
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 18:19:31 -05:00
3bd7a22bc6 docs(rust): the minor labels read from a 6000 map, and D213
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 18:12:08 -05:00
637a11326e docs(rust): the map's monument labels as built (PLAN_REDESIGNS §4.1, D196)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 12:10:47 -05:00
75a45b51a1 Merge pull request 'docs(rust): the chat-title conditions as built — PROTOCOL 19.10, PLAN_REDESIGNS 5.8 and D209' (#295) from docs/rust-title-conditions into main
Reviewed-on: #295
2026-09-29 17:00:40 +00:00
6ed4021c12 Merge main into docs/rust-title-conditions: §3's docs
PROTOCOL.md: §19.10 (titles) and §19.11 (zones) both kept, in order.
PLAN_REDESIGNS: the D210-D212 table moved from the end of the file, where
docs#296 appended it by mistake, into §10 after D209.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 11:36:45 -05:00
381d8ee5b6 Merge pull request 'docs(rust): zones and the dome as built and walked — PROTOCOL 19.11, PLAN_REDESIGNS 3.4, D210-D212' (#296) from docs/rust-zones-domes into main
Reviewed-on: #296
2026-09-29 16:27:52 +00:00
baef8f27eb docs(rust): §3's site half as walked — the presets page, a step from a preset, a run on Carbon
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 09:54:53 -05:00
4056e5a14d docs(rust): §3 walked on the rigs, and D212 (the full dome is the default)
PLAN_REDESIGNS §3.4: the rig rows as walked 2026-09-29 without a player,
the dome types, D212, and the in-game rows deferred to the later in-game walk.
PROTOCOL §19.11: dome type 0 when absent; walk status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 09:42:25 -05:00
7f9026c9e7 docs(rust): zones and the dome as built — PROTOCOL 19.11, PLAN_REDESIGNS 3.4, D210, D211
PROTOCOL §19.11: world.zone's seven new fields, bad-option and
dome-unavailable, the bridge-said zone messages, the domes helper and
OnRgDomesReady, hello's zoneManager and integrations.zoneDomes.

PLAN_REDESIGNS: §0.6 corrected (ZoneFieldListRaw exists), §3.4 as built,
D210 (flags ticked on a presets page, the step copies a preset's line) and
D211 (the bridge reads the flag list). INSTALL names the new helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 05:25:45 -05:00
e8f0ff2407 docs(rust): §5 compiled on both rigs, and what the item-list probe corrected
PLAN_REDESIGNS 5.8 records the probe's lists and the three members it corrected; PROTOCOL 19.10 names the crafter, the mission assignee and the heal target as built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-29 02:07:30 -05:00
e3c5d7128c docs(rust): the chat-title conditions as built — PROTOCOL 19.10, PLAN_REDESIGNS 5.8 and D209
PROTOCOL.md §19.10 documents player.tally's new fields and the ten hooks
behind them. PLAN_REDESIGNS §5.8 records what the build settled (the
category ids, where each is read from, the empty-text rule, the admin
API, the plugin's counting choices) and what is left before the walk.
D209: a title rule's "NPC kills" ranks human NPCs only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-28 23:32:59 -05:00
18a4a561e3 Merge pull request 'docs(rust): the RaidableBases spikes, and D203-D208' (#294) from docs/rust-raidablebases-spike into main
Reviewed-on: #294
2026-09-29 00:18:35 +00:00
664d2b2144 docs(rust): D206-D208, the org lead's answers to the helper spike
Lock-to-first-attacker per event via a BypassUseOwners patch; a step places
its base where RaidableBases picks or at an admin-given spot with a height
adjustment or exact height; a blocked spot is refused with the reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-28 12:20:30 -05:00
a34b5fdbf0 docs(rust): record the RaidableBases helper spike (§11.4.4)
One base despawns alone; overrides go in at OpenEvent through a deep copy;
lock-to-first-attacker is main-config only; an admin-given spot and height
work through a copied profile (Clone() is shallow and leaked); the area
check misses water; reloads drop Harmony patches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-28 12:18:33 -05:00
6684ea5c60 docs(rust): the RaidableBases spike, and D203-D205
The free edition (3.2.0) on both rigs with CopyPaste: its public API, the
17-argument lifecycle hooks, spawning only through `rbevent` at a spot the
plugin picks, base ids always "0", despawn only all-at-once, the boot
hitch and grid wait, and the profile options. Section 11.4.2 is left for
the paid edition the org lead supplies later in the week.

D203 RaidableBases picks where; D204 a helper despawns only the event's
base; D205 profile + difficulty + per-event overrides, and the site edits
RaidableBases' profiles as a named exception.

Refs RunicGateway/Module-Rust#21

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-28 11:56:38 -05:00
5328ff35b5 Merge pull request 'docs(rust): perm.inventory in PROTOCOL 19.9, and the permission manager as built' (#293) from docs/rust-perm-manager into main
Reviewed-on: #293
2026-09-28 16:38:28 +00:00
52658ce2c1 docs(rust): perm.inventory in PROTOCOL 19.9, and the permission manager as built
PROTOCOL.md 19.9 specifies perm.inventory (owners, groups with parents,
holders, leased pairs; sliced, paged, one snapshot) and perm.sync's
protocol-13 changes (parents, titles and ranks written, absent means
leave it, managed and foreign gone). PLAN_REDESIGNS 1.9 records what the
build settled and the walk on both rigs.

Refs RunicGateway/Module-Rust#21

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-28 11:25:58 -05:00
4c996e270f Merge pull request 'docs(rust): first-class optional plugins in the redesign plan (D199-D202)' (#292) from docs/rust-optional-plugins into main
Reviewed-on: #292
2026-09-28 11:37:11 +00:00
23ce47c6ad docs(rust): first-class optional plugins in the redesign plan (D199-D202)
Economics, Backpacks and RaidableBases become optional, supported
integrations; Kits stays required. PLAN_REDESIGNS.md gains section 11 with
what each plugin exposes, what the site does with it, the spikes each build
starts with, and the org lead's four answers.

Refs RunicGateway/Module-Rust#21

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-28 06:35:04 -05:00
a9981f59bc Merge pull request 'docs(rust): plan the six step-3 redesigns, and D188-D198' (#291) from docs/rust-step3-plan into main
Reviewed-on: #291
2026-09-27 08:58:52 +00:00
fa53526079 docs(rust): record the org lead's answers to the step-3 plan (D188-D198)
Groups are per server unless an admin shares them (D189); an in-game
change affects that server only, as an exception or a split (D190);
ZoneDomes stays, made safe by a domes helper (D194); presets are the
admins' own (D195); zone and reward messages get the popup choice
(D193); the NPC spike tries both routes (D197). The rest confirm the
plan: D188, D191, D192, D196, D198.

Refs RunicGateway/Module-Rust#21

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-27 03:56:43 -05:00
a430666f94 docs(rust): plan the six step-3 redesigns in one document
PLAN_REDESIGNS.md plans PLAN_FIXES §6 step 3 in detail, before any code:
the permission manager, the event step editor and kit weekend, zones and
domes, map marker types, the 23 title conditions, and NPCs. Checked on
both rigs first: the public owner lookup for permissions, the mission
hooks both frameworks already raise, and ZoneDomes' null-player throw.
Eleven questions for the org lead (§10) become D188 onward.

Refs RunicGateway/Module-Rust#21

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-27 03:45:44 -05:00
180d6a85d9 Merge pull request 'docs(rust): the step-2 player walk, and D186-D187' (#290) from docs/rust-step2-player-walk into main
Reviewed-on: #290
2026-09-27 08:26:29 +00:00
1891f4f6fd docs(rust): the step-2 player walk, and D186-D187
PLAYER_WALK's step-2 rows 3-9 walked with the org lead in the game on
both rigs (2026-09-27). Records the results, corrects four rows (the
helper is unloaded, not deleted; no enter message can show; sleepers do
not score; ZoneManager's own entry counted the player anyway), and adds
D186 (a link code's second pass skips servers known down) and D187 (no
permission sync to a server the poll saw go away) with F6, F7 and F12's
as-walked notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-27 03:18:40 -05:00
9aba725ca2 Merge pull request 'docs(rust): protocol 13 step 2 — expiry, plugin loads, the zone helper, the tally (§19.4-19.8, MODULE_API 1.11.0)' (#289) from docs/rust-protocol-13-step2 into main
Reviewed-on: #289
2026-09-27 06:09:43 +00:00
383f3bdbe5 docs(rust): the step-2 site walk, and the run it found stuck pending
Walked on a core running Module-Rust#22 on website#209 against rust-oxide:
F8, F13/F14, F7, F5/F6 and the helper's state all pass. The expiry walk found
a run left cleanup-pending for ever when its last resource expires while it
runs; website#209 now settles it, and EVENTS.md §L says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-27 01:05:35 -05:00
a199823513 docs(rust): say which half of the step-2 walk rows was walked
Rows 1-2 of PLAYER_WALK's step-2 section had their game side walked on both
rigs; their site side (the servers-page warning, a grant landing within a
minute) needs a walk core running Module-Rust#22 on website#209, which the
first commit claimed as walked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-26 21:48:18 -05:00
1a7f52743f docs(rust): protocol 13 step 2 — expiry, plugin loads, the zone helper, the tally (§19.4-19.8, MODULE_API 1.11.0)
The spec for PLAN_FIXES §6 step 2, as built (D181-D185):

- PROTOCOL.md §19.4 world.expired's `what` and the website recording an
  expiry (amends §15's "maps it to nothing"); §19.5 plugin.loaded /
  plugin.unloaded with the permission diff; §19.6 the ZoneManager helper and
  `zoneHelper` at hello; §19.7 what the tally counts (F1, F3, F4); §19.8 the
  website (F7 hold, F5/F6 link fleet, F2 names).
- MODULE_API.md 1.11.0 and ctx.events.expired; EVENTS.md §L the `expired`
  status, terminal and green, and `resource.expired`.
- rust-link/INSTALL.md: the helper in the tarball, by hand, and in doctor.
- PLAYER_WALK.md: events step 6 can pass now; a step-2 section whose rows 1-2
  were walked on both rigs without a player and 3-9 need one.
- PLAN_FIXES §6: step 2 as built, with its PRs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-09-26 21:47:42 -05:00
10 changed files with 2269 additions and 15 deletions

View File

@@ -11,6 +11,7 @@ website/ docs from the website core (Node/Express + MariaDB + React/Vite)
modules/ docs for installable game modules — one directory per module id
link/ docs from the ServUO bridge (C# plugin + Rust sidecar + Node WS)
rust-link/ docs from the Rust bridge (Oxide plugin + Rust sidecar)
runicnpc/ docs for RunicNPC, the Rust NPC plugin (runicnpc-rust)
android/ docs from the native Android client (Kotlin + Jetpack Compose)
installer/ docs for the installer that deploys a shard's bridge components
ci/ cross-cutting CI/quality notes
@@ -89,6 +90,16 @@ share a shape and nothing else, so neither document is a fallback for the other.
| [INTEGRATION.md](rust-link/INTEGRATION.md) | Standing the bridge up by hand, and which of the three components is wrong when it does not work |
| [PLAYER_WALK.md](rust-link/PLAYER_WALK.md) | The half of the read path a console cannot reach: ten minutes on a rig with a player, step by step, with what each hook should produce |
### `runicnpc/`
RunicNPC, Runic Gateway's own NPC plugin for Rust (Oxide and Carbon), in its own repository. Admins place NPCs
with it in game, events place them through the bridge, and other plugins drive it through its API. `module-rust`
requires it once it releases (D220).
| Doc | What it covers |
|---|---|
| [PLAN.md](runicnpc/PLAN.md) | **The plan** — what the 2026-09-30 spike found (route A, HumanNPC, NpcSpawn), the org lead's decisions D214–D220, the features, the API, the chat commands, and stages 0–10 with how each is tested |
### `android/`
| Doc | What it covers |
|---|---|

View File

@@ -70,6 +70,8 @@ Taken by the org lead during and straight after the walk.
| **D183** | **F14's expiry is core's to record: the resource ledger gains an `expired` status, and a module reports one with `ctx.events.expired({ kind, ref })`.** `expired` is terminal like `reverted` — teardown never tries to take it back — and the run log says `resource.expired`. It is a MODULE_API minor (1.10.0 → 1.11.0), and it must not disturb Module-uo, which is already built against 1.10.0: additions only, no existing status changes meaning. Rejected: asking core to reconcile, which files an expected expiry as `orphaned` (a fault, and still claimable for a revert); and core marking rows expired from `lease_until` on its own clock. |
| **D184** | **F8's signal is `plugin.loaded` / `plugin.unloaded`, carrying the permissions that plugin added or removed.** The plugin diffs the registered permission list around each load and unload, emits only once the world is ready (a boot is the restart sync's), and the site marks the permission sync dirty when the list is not empty. The same list is §4.1's first evidence of which plugin owns a permission. Rejected: every load, names only. |
| **D185** | **F2 is the site's: NPC attackers are labelled by the killfeed**, which trims a prefab's variant digits (`wolf2` → wolf) and names the NPC families that read badly otherwise (scientists, bandits, animals). No wire change. Rejected: the plugin sending a display name Rust may not have. |
| **D186** | **F6, as walked: a link code's second pass skips the servers the site already knows are down.** Asking the non-issuers in parallel was not enough: while any server was down, a code no issuer held — every made-up one — still waited out that server's whole timeout (12 s on both rigs, the step-2 walk). A server the board poll last saw without a connected game is not an issuer, so it cannot hold the code: it counts as offline without the wait. Issuers are asked whatever their state, so a good code on a down server still answers "unsure". Rejected: dropping the second pass (a code typed before its mint is ingested would be refused once); a short timeout on it (still a wait, and a guess at the number). |
| **D187** | **F7, as walked: no permission sync goes to a server the poll saw go away until a fresh hello says its world is ready.** The `worldReady` hold reads the stored hello, which is the old boot's until the poll reads the new one — and on Carbon a due audit went out in that gap, 80 s before "Server startup complete". The poll already writes `online: 0` the moment a server goes away, so the hold reads that too (titles already did). A human's "sync now" is still not held. |
## 2. Fixes
@@ -118,6 +120,11 @@ to, that is D168's case (a helper), or the tally measures distance itself for zo
Carbon too. Settled by D181 and D182: ZoneManager has no public way (its `UpdatePlayerZones` is private and
runs only for a connecting player), so a helper patches `Zone.InitializeZone` with Harmony; without the helper the
bridge scores its own zones by `IsPositionInZone`.
*As walked, 2026-09-27, both rigs:* narrower than it reads. Without the helper, ZoneManager 3.1.14 counted the
player every time we tried — a zone opened around them, a zone re-created by a ZoneManager reload, and a rejoin
after a restart (its `UpdatePlayerZones` runs on connect) — only late: with the helper in, its sweep one tick after
`InitializeZone` found the player not yet counted. So the helper makes entry immediate, and its flags apply at
once; the score never depended on it. What the first walk saw may need a busier server than one player to recur.
**F13 — the `world.expired` frame leaves with its kind overwritten.** *(Rust-Plugins, protocol)*
Three zones expired in the game exactly on time; all three frames were filed as `kind: "zone"`. Line ~7310
@@ -149,6 +156,8 @@ issued a code in the last five minutes, and answer "unsure" only when one of *th
**F6 — redeeming a code waits on every dead server in turn.** *(Module-Rust)* About 21 seconds, four per dead
server; the rig sorts last, so a successful link waited too. F5's fix usually leaves one server to ask; failing
that, ask in parallel with a short timeout.
*As walked, 2026-09-27:* the parallel fleet still took 12 s for a made-up code whenever a server was down —
one whole timeout on the second pass. Settled by D186; 338 ms after it, 360 ms with a rig stopped as well.
**F8 — loading a missing plugin does not re-sync permissions.** *(Rust-Plugins, Module-Rust)* PopupNotifications
came back at about 18:44; the grant that had been unresolved landed at 18:57, on the fifteen-minute audit. The
@@ -168,6 +177,8 @@ deliberately wiped, the site restored its group, membership and grant — R2's c
restart sync ran 35 s before "Server startup complete", timed out with no warning in the log (the titles push
at the same moment did log one), and the retry 2.5 minutes later recorded "0 applied", so nothing says what the
restart restored. *Fix:* hold the restart sync until the hello says `worldReady: true`; log a failed sync.
*As walked, 2026-09-27:* the restart sync waited on both rigs, but on Carbon a due *audit* went out the moment
the sidecar reconnected — the stored hello was still the old boot's. Settled by D187.
**F2 — NPC killers are named by prefab.** *(Rust-Plugins or Module-Rust)* "killed by `wolf2`". Send a display name,
or map prefab to label on the site — whichever the killfeed page already expects. The site's, by D185.
@@ -395,9 +406,30 @@ in Rust-Plugins, Rust-Link and Module-Rust, and the three cut over to `main` tog
(D176, D177).
2. **Protocol 13 with the remaining fixes:** F13, F14, F12, F1, F3, F8, F7, F2, F4 in the bridge and the module,
and F5/F6 in the module.
*As built, 2026-09-27* (decisions D181–D185): Rust-Plugins#18, Module-Rust#22, Rust-Link#19 (the egg),
installer#35 and website#209 (core's `expired` status, MODULE_API 1.11.0). The spec is
[`PROTOCOL.md`](../../rust-link/PROTOCOL.md) §19.4–19.8. Walked on both rigs without a player: the
bridge and the ZoneManager helper compile and load, the helper patches ZoneManager 3.1.14, the hello
carries its state, and `plugin.loaded` / `plugin.unloaded` carry the right permissions. The site side
was walked the same night on a walk core running Module-Rust#22 on website#209, against `rust-oxide`: the
servers list shows the helper `patched`; a Kits unload and load was synced as `dirty` 24 s later (F8);
a 3-minute zone expired into `expired` with `resource.expired` and teardown never touched it (F13, F14)
— which found a run left `pending` for ever when its last resource expires while it runs, fixed in
website#209; a restart's sync waited for `worldReady` and went after it (F7); and `ZZZZZZ` with five
servers down answered "unknown or has expired", once, in one timeout (F5, F6). The rows of
[`PLAYER_WALK.md`](../../rust-link/PLAYER_WALK.md)'s step-2 section that need somebody in the game (3–9)
were walked with the org lead in the game on 2026-09-27, on Oxide and then Carbon, and all passed but row 8's timing: the gather
tally matched the inventory to the unit, a player's own wall was not a raid, a zone scored a player who stood
still through its opening, a restart and a ZoneManager reload, with the helper and without it, and the killfeed
read Bear, Wolf, Boar and Scientist. The walk found two gaps, both fixed in Module-Rust on `edge` and walked on
the walk core: a made-up code still waited one timeout on a dead server (D186), and a due audit went to a
restarting Carbon before its hello was read (D187). F12 turned out narrower than written (see F12). Not walked:
a player killed by another player — there was no second player.
3. **The redesigns**, each planned in detail before code and walked on both frameworks: the permission manager
(§4.1), the event step editor with the kit-weekend template (§4.2, §4.3), zones and domes (§4.4), the map's
marker types (§4.5), the chat title conditions (§4.6), and the NPC research (§4.7).
*Planned 2026-09-27:* all six are in one document, [`PLAN_REDESIGNS.md`](PLAN_REDESIGNS.md), as the org
lead chose. Its eleven questions were answered the same day as D188–D198 (its §10).
4. **The cutover**, once the re-walk (§8) passes on Oxide and Carbon.
## 7. Helper plugins (D168)
@@ -434,7 +466,9 @@ The four questions this plan first asked were answered on 2026-09-26: the gate (
(D171) and the title conditions (D172) — then quests (D173), the title rules (D174) and admin-owned title names
(D175).
Left for the detailed plans of §6 step 3, none of them blocking the fixes:
Left for the detailed plans of §6 step 3, none of them blocking the fixes. Each is settled in
[`PLAN_REDESIGNS.md`](PLAN_REDESIGNS.md): 1 by a framework hook (its §0.4), 2 by D196, 3 on the rig during the
build (§3.2), and 4 by a spike of both routes (D197).
1. How a completed mission is detected — the spike in §4.6 (D173).
2. Whether the plugin or the site filters monument types (§4.5).

File diff suppressed because it is too large Load Diff

View File

@@ -24,7 +24,8 @@ differ.
for actually building `module-rust`. Everything else in this directory is copied from uMod; those two
are written by this project and are where the phases, the settled decisions and the local test rig are
recorded. [`PLAN_FIXES.md`](PLAN_FIXES.md) is its companion: the first player walk's fixes and decisions
D159–D175, all to land before the Module-Rust cutover.
D159–D187, all to land before the Module-Rust cutover. [`PLAN_REDESIGNS.md`](PLAN_REDESIGNS.md) plans that
document's six redesigns (its §6 step 3) in detail.
> **This is a mirror, not a specification we own.** uMod is upstream and wins any disagreement; the
> point of copying it is availability and grep-ability, not authority. Nothing here may be cited as a

653
runicnpc/PLAN.md Normal file
View File

@@ -0,0 +1,653 @@
# RunicNPC — the plan
**Status:** plan, written 2026-09-30. Its eight questions (§11) were answered the same day: D221–D228 (§0).
**Stage 0 closed 2026-09-30** (runicnpc-rust#1/#2, §9): v0.1.0 released and loaded on both rigs. D229–D230 were
decided with it. **Stage 1 measured 2026-09-30** (§9): six answers on both rigs; D231 was decided with it.
RunicNPC is Runic Gateway's own NPC plugin for Rust servers, in its own repository,
[`RunicGateway/runicnpc-rust`](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust). It runs on Oxide and
Carbon. Other plugins drive it through an API, as NpcSpawn is used, and admins use it directly in game through chat
commands. **It is a prerequisite of the rest of the Rust plan:** the redesigns resume only after its stage 9
(§9), and from then on `module-rust` requires it, as it requires Kits.
It replaces [`PLAN_REDESIGNS.md`](../modules/rust/PLAN_REDESIGNS.md) §6's "two routes". That section's spike was
run on 2026-09-30, and the org lead chose neither route (D214). What the spike found is §1 here, because every
choice below rests on it.
Its decisions continue the Rust workstream's numbering at **D214** ([`PLAN_REDESIGNS.md`](../modules/rust/PLAN_REDESIGNS.md) §10).
The repository carries the same conditions as every Runic Gateway repository: **GPL-3.0-or-later**, Conventional
Commits, AI-assisted work disclosed, branches cut from an up-to-date base, and the org lead's approval before any
architectural or design decision is implemented.
---
## 0. The direction, in the org lead's words (2026-09-30)
| # | Decision | Rejected |
|---|---|---|
| **D214** | **Runic Gateway writes its own NPC plugin**, an API-style plugin like NpcSpawn, in its own repository. It may borrow *behaviours* the other plugins implement, never their code. | Extending `rust.npc.place` on Rust's scientists alone (route A); HumanNPC (route B); depending on NpcSpawn. |
| **D215** | **It is not only for events.** Admins place NPCs in game, where they want them, for normal play, so it has chat commands. | NPCs only as event steps. |
| **D216** | **No visual editor.** Profiles are authored on the website; in game there are commands only. | NpcSpawn's in-game GUI (and the 22 images it needs). |
| **D217** | **Kits is how an NPC is equipped, and Kits is required.** A profile names kits; it has no item lists of its own. | Wear and belt lists in the profile. |
| **D218** | **Loot tables are RunicNPC's own for now.** Links to other loot plugins can come later. | AlphaLoot, CustomLoot, Loottable or LootManager as a dependency. |
| **D219** | **Rust's own navmesh is used. A custom navigation mesh is a later stage, built only if a real need appears** (§8, stage 10). | Shipping NpcSpawn-style point meshes from the start. |
| **D220** | **The plugin is built and tested in stages before the Rust plan resumes, and it then becomes a plugin `module-rust` requires.** | Building it alongside the remaining redesigns. |
| **D221** | **RunicNPC works without Runic Gateway too** (Q1). Standalone, its profiles live in its data file and console commands edit them. On a Runic Gateway server, the site's profiles replace that file on every push, and in-game profile edits are refused with "this server's profiles are managed by its website". | Runic Gateway only. |
| **D222** | **Placements live on the server** (Q2). They keep respawning while the site is offline; the site catches up when it returns, and lists and edits them from then on. | The site as the only record. |
| **D223** | **Our NPC is its own subclass of Rust's scientist, with its own brain** (Q3). The brain is kept small and tested on Rust's `staging` branch before each forced wipe. | Rust's scientist plus patches. |
| **D224** | **The installer and the egg ship it from the bundle, pinned and checksummed** (Q6). It is also published as a release on Gitea, and possibly on other sites for anyone to download. | Operators installing it themselves. |
| **D225** | **Per-profile kills are public and usable in titles** (Q4), like the NPC kills column today. | Admins only. |
| **D226** | **`edge` → `main`**, like the other Rust repositories (Q5, D18). | PRs straight to `main`. |
| **D227** | **No default caps.** Instead, a realistic warning of what a number of NPCs costs and its impact on the server, measured in stage 1, shown wherever NPCs are added (Q7). Caps exist only when an admin sets them. | 100 / 50 / 10 per second by default. |
| **D228** | **`RunicNPC.cs`, console name `RunicNPC`, chat command `/rnpc`, permissions `runicnpc.*`** (Q8). | — |
| **D229** | **The empty repository was seeded by one `chore:` commit straight to `main`** (the licence and a stub README), `edge` was branched from it, and everything after goes by PR (stage 0). It is the only direct push. | You seeding it in the Gitea UI; the whole scaffold straight to `main`, unreviewed. |
| **D230** | **The layout is `plugin/RunicNPC.cs` and a root `plugin.toml`**: `api`, the framework floors, `requires_plugins` (stage 0). RunicNPC is one file, not an overlay of a server tree. | Mirroring Rust-Plugins' `overlay/oxide/plugins/` and `overlay.toml`. |
| **D231** | **Each profile (or group) decides whether its NPCs target other NPCs, and which kinds**: Rust's scientists, animals, other profiles, and so on (stage 1; the org lead's words). Rust's AI cannot do this (§9, stage 1, Q3), so it is our own combat state and sensing, and stage 5 opens with a spike for it. | Our NPCs fighting players only, as Rust's scientists do. |
**Borrowing, not copying.** NpcSpawn states no licence at all, so its source grants us nothing and is read only as a
description of *what* can be done in Rust. HumanNPC is MIT on uMod, which is GPL-compatible, but §1.2 rules out its
design, so there is nothing of it worth carrying. RunicNPC's code is written from how Rust's own classes behave (the
HOOKS and OXIDE_API mirrors, and rig probes), and every borrowed idea is credited in §3 by what it is, not by copied
text.
---
## 1. What the spike found (2026-09-30, the Oxide rig)
The probe was a throwaway plugin, `RgNpcSpike.cs`. It spawned NPCs by each route, watched them for minutes, made
them fight, killed them, and read what the bridge published through the sidecar's `/events`. The org lead stopped
the Carbon half: one server was enough to see that HumanNPC does not behave as needed.
### 1.1 Rust's own scientist, stripped and given a kit (route A)
| Question | Answer |
|---|---|
| Does the kit stick? | **Yes.** `Strip()`, Kits' `GiveKit`, then `EquipWeapon()`: after three minutes of combat it still wore the kit. Rust does not re-dress it. |
| Does it fight with the kit's weapon? | **Yes.** Every hit it landed was `pistol_revolver.entity`, from a revolver kit. Its prefab loadout was an LR-300. |
| Can it be named? | **No.** `ScientistNPC` overrides `displayName` with a get-only property that answers "Scientist". Setting `_displayName` stores the name and changes nothing. |
| Is it counted correctly? | Yes. `IsNpc` is true, so every bridge path treats it as an NPC. |
| Cost | Under Oxide's slow-call warning; no measurable hitch. |
### 1.2 HumanNPC 0.6.8 (route B) — ruled out
- **Its NPCs are counted as players.** It spawns `player.prefab` with a made-up user id and Harmony-patches
`BasePlayer.IsBot` for every player on the server. `IsNpc` stays **false**, and that is what the bridge tests. The
sidecar recorded a `player.death` for "Hobb" (`steamId` 11419803648) and a `player.tally` crediting "Hobb2" with an
NPC kill: a fake player in the public killfeed, the leaderboard and the titles.
- **The API the old plan named does not exist.** There is no `SpawnHumanNPC` or `SetHumanNPCInfo`: only
`CreateNPCHook(position, rotation, name, clone, saved)`. Kit, hostility and invulnerability can be set only by
reflection into its private types. Its `RefreshNPC` and `RemoveNPC` are public without `[HookMethod]`, so Oxide's
`Call` cannot reach them either.
- **Its combat is simulated.** Its hits carried no weapon and a flat ~7 "Bullet" damage, even with a bow.
- **Its persistence leaks.** `saved: false` holds only until anything else saves: one saved NPC wrote every unsaved
one to its data file. A dead NPC came back on the next reload. `RemoveNPC` never marks the file dirty, so removed
NPCs return at the next restart.
- **It is slow.** ~250 ms to create, ~250 ms to apply settings, ~250–320 ms to remove, each on the main thread.
- **It breaks on Rust updates.** Nearly every release since 2023 is "fix for Rust update"; 0.6.0 fixed servers that
failed to load.
### 1.3 NpcSpawn 3.4.8 (the org lead's suggestion)
It worked, and it is the model RunicNPC borrows from:
- It **replaces the scientist's component with its own subclass**, `CustomScientistNpc : ScientistNPC`, copying the
serialised fields across (`EntityManager.CopySerializableFields`). No Harmony. `IsNpc` is true, so the bridge
counts it correctly unchanged.
- **The name sticks**, and it is written into the victim's death screen (`AttackerInfo`).
- **Kits work**, and it fought with the kit's revolver (with `NpcAttackMode: 1`; its default only attacks a whitelist).
- **It is never saved** (`enableSaving = false`). After a hard kill and restart, none of three came back. Reloading
NpcSpawn kills all of its NPCs.
- Spawning took 4–106 ms.
Its costs, which RunicNPC avoids by design: a 2.1–2.8 s main-thread hitch at every boot (it scans ten million
candidate ids and generates spawn points); a version check over plain HTTP to a bare IP on every boot; it
**unloads itself** if any of its 22 GUI images is missing; it is not on uMod and states no licence, so it cannot be
bundled; and it has had 78 releases.
### 1.4 Two corrections to the old plan
- **"`displayName` already flows into the killfeed" is wrong for every route.** The bridge names an NPC attacker by
`initiator.ShortPrefabName` (`RunicGateway.cs`, `DescribeAttacker`), so the feed says `scientistnpc_roam`. Stage 4
fixes it.
- **HumanNPC's API, as described, does not exist** (§1.2).
### 1.5 A rig trap found on the way
A data directory created by the panel's file API is **not writable by the game** (`IOException: Permission denied`
from `Directory.CreateDirectory`). Let a plugin create its own data directory, then write files into it. The
installer and the egg must do the same with any data RunicNPC ships.
---
## 2. What RunicNPC is
**One plugin file, `RunicNPC.cs`**, compiled by Oxide or Carbon from source, like the bridge. It declares
`// Requires: Kits`, so neither framework loads it without Kits (D217).
**Its NPC is its own type,** a subclass of Rust's `ScientistNPC` with its own brain. This follows NpcSpawn's approach
(§1.3), because only a subclass can:
- override `displayName`;
- override the aim cone;
- write its name into the victim's death screen;
- carry behaviours Rust's brain does not have (guard, escort, boss phases).
Stage 1 proves the swap on both frameworks before anything is built on it.
**It owns nothing it is not asked for.** Every NPC has an **owner**, and the owner decides its lifetime:
| Owner | Who | Survives a restart? |
|---|---|---|
| `run:<runId>` | An event run, through the bridge | **No.** Never saved; the bridge's registry reverts it, as `world.place` does today. |
| `placement:<id>` | An admin's placement in game, or one made from the site | **Yes, as a placement:** RunicNPC stores the spot, profile and respawn delay, and spawns a fresh NPC there at boot. The NPC itself is never saved. |
| `plugin:<name>` | Any other plugin using the API | No. It is killed when that plugin unloads. |
This split is what HumanNPC got wrong: the *placement* is persistent data, the *NPC* never is. There is exactly one
save path, a flag marks it dirty on every change (including removal), and nothing else is written.
**Standalone or managed (D221).** Without a site, RunicNPC reads its profiles from its own data file and console
commands edit them. With a site, the bridge pushes the site's profiles, which replace the file; the file records that
it is managed, and in-game profile edits are refused with "this server's profiles are managed by its website".
Placements stay the server's either way (D222): the site reads them and edits them through the bridge.
**A profile is a named description of an NPC:**
- **Appearance:** name (or a list to pick from), the kits it wears, body type, and the prefab it starts from.
- **Combat:** health, damage scales (overall, and by head, body, legs and melee), aim spread, and ranges (sense,
chase, roam, attack).
- **Behaviour:** its role and AI states (§6).
- **Loot:** its loot table (§7).
The kit list is required and non-empty; one kit is picked at random per spawn, for variety within a profile. A kit
the server does not have refuses the profile when it is saved, not when an NPC spawns.
---
## 3. Features
Borrowed ideas are marked with their source; everything else is new. Stage numbers are §9's.
### 3.1 From NpcSpawn (behaviour only)
| Feature | Stage |
|---|---|
| A scientist subclass with its own brain; never saved | 2 |
| Names, a random name from a list; body type and skin tone chosen by the NPC's id | 2 |
| Health, overall and per-body-part damage scales, aim cone, headshot rule | 2 |
| Sense, listen, chase, roam and attack ranges; a vision cone; hostile-only; ignore safe-zone, sleeping or wounded players | 2, 5 |
| Sleep when no player is within a distance, and walk home | 2 |
| States: roam, chase, combat, idle, stationary combat | 2, 5 |
| NPC-versus-NPC and NPC-versus-animal rules, with allow and deny lists | 5 |
| Group alert: nearby allies join a fight | 5 |
| Turrets may target them, and they fight back | 5 |
| Healing with syringes; grenades, smoke, rockets, flamethrowers, melee (by the weapon the kit gives) | 5 |
| Parenting to a moving entity | 10 |
| Loot tables, a crate on death, removing the corpse | 7 |
| TruePVE / NextGenPVE compatibility (`CanEntityTakeDamage`) | 5 |
### 3.2 From HumanNPC (behaviour only)
| Feature | Stage |
|---|---|
| Press E to talk: an NPC says a line, or opens a message, when used | 6 |
| Lines on greet, hurt and kill | 6 |
| Follow a player, and walk a recorded path | 5 |
### 3.3 Runic Gateway's own
| Feature | Stage |
|---|---|
| **Profiles authored on the website** and pushed to each server, per server, shared, or fleet-wide (the zone-presets pattern, D210). The site checks every kit exists before it saves. | 4 |
| **Admin placement in game** by chat command (§5), persistent, with respawn delays; the site lists and edits the placements | 3, 4 |
| **Correct accounting**: an NPC is never counted as a player; its name reaches the killfeed, event log and death screen; kills are counted per profile | 2, 4 |
| **Per-profile stats and titles**: "Warden kills", boss kills; the killing blow and every player who did damage | 4 |
| **Cost warnings, not default caps (D227)**: what N NPCs cost the server, measured in stage 1, shown when an admin places them, on the site's profile and placement pages, and in `doctor`. Caps (per server, owner or profile, and a spawn rate) exist only when an admin sets them | 2, 4 |
| **Event ownership**: run-owned NPCs with the bridge's restart and teardown guarantees | 4 |
| **Waves and phases** without a core change: a phase advances on "n NPCs of profile X died", and on "the boss fell below 50%" | 4, 6 |
| **Zone tethering**: an NPC held inside a ZoneManager zone (from redesign §3) | 5 |
| **Guard and escort**: hold a point or an entity; follow a convoy or a player | 5 |
| **Factions**: profiles hostile or allied to each other; allied to a team or clan, for defend-your-base events | 5 |
| **Bosses**: an on-screen health bar, phases at health thresholds, announcements (popup, chat, Discord and the app through engagement), a reward on the kill | 6 |
| **Quest-giver or vendor**: passive, press E for a site-written message | 6 |
| **The live map and the app**: markers for event NPCs and bosses, "guards left: 3/8" | 8 |
| **Operator-friendly**: shipped in the bundle, no phone-home, no image files, no boot scan; `doctor` reports it; RunicNPC's permissions appear in the site's permission manager like any plugin's | 2, 4 |
| **An API for other plugins**, versioned, documented, and usable without Runic Gateway at all (D221) | 2, 9 |
---
## 4. The API
Other plugins call RunicNPC by name through `Call`, which on Oxide reaches **non-public** methods and public ones
marked `[HookMethod]` (§1.2 is what happens otherwise). Every name is prefixed, so no hook of another plugin is ever
matched by accident. The first draft, fixed in stage 2 and published as `docs/runicnpc/API.md`:
| Call | Does |
|---|---|
| `RunicNpc_ApiVersion()` → `int` | The API's version. The bridge refuses a RunicNPC older than it needs, and says so in hello. |
| `RunicNpc_Spawn(Vector3 at, string profile, string owner, JObject overrides)` → `BasePlayer` | Spawns one NPC, or returns null and logs why. `overrides` may change any profile value for this NPC only. |
| `RunicNpc_Despawn(ulong netId)` / `RunicNpc_DespawnOwner(string owner)` → `int` | Removes one, or all of an owner's. |
| `RunicNpc_List(string owner)` → `List<Dictionary<string, object>>` | The owner's live NPCs: id, profile, name, position, health. |
| `RunicNpc_Profiles()` / `RunicNpc_SetProfiles(JObject all)` | Reads, or replaces, the profile set. Replacing marks the server as managed by a site (D221). |
| `RunicNpc_Placements()` / `RunicNpc_SetPlacement(...)` / `RunicNpc_RemovePlacement(string id)` | The persistent placements (§2). |
| `RunicNpc_IsRunicNpc(BaseEntity e)` → `bool`, `RunicNpc_ProfileOf(BaseEntity e)` → `string` | Lets another plugin tell our NPCs apart. |
**Hooks it raises** (void; a returning hook can cancel a death, see PROTOCOL.md §8.7):
`OnRunicNpcSpawned(npc, profile, owner)`, `OnRunicNpcDied(npc, profile, owner, HitInfo, contributors)`,
`OnRunicNpcHealth(npc, profile, fraction)` (at the thresholds a profile names), `OnRunicNpcDespawned(npc, owner)`,
`OnRunicNpcUsed(npc, player)`.
**The bridge is its only link to the site.** RunicNPC never talks to the sidecar. The bridge calls the API and
listens to the hooks, which keeps "the sidecar is a dumb forwarder" true.
---
## 5. In game: the chat commands (D215, D216)
`/rnpc` (and the same verbs in the server console as `rnpc.<verb>`), each behind a RunicNPC permission. Those
permissions reach the site's permission manager through the inventory, like any plugin's.
| Command | Does | Permission |
|---|---|---|
| `/rnpc place <profile> [count] [respawn]` | Places at the spot you are looking at, persistent | `runicnpc.place` |
| `/rnpc here <profile> [count]` | The same, where you stand | `runicnpc.place` |
| `/rnpc remove` | Removes the placement of the NPC you are looking at | `runicnpc.place` |
| `/rnpc near [radius]` | Lists placements and live NPCs near you | `runicnpc.place` |
| `/rnpc info` | The NPC you are looking at: profile, owner, health, target, state | `runicnpc.place` |
| `/rnpc profiles` | The profiles this server has | `runicnpc.place` |
| `rnpc.profile <create\|set\|delete> ...` (console) | Edits a profile on a standalone server; refused when the site manages them (D221) | `runicnpc.admin` |
| `/rnpc tp <placement>` | Teleports you to a placement | `runicnpc.admin` |
| `/rnpc respawn [placement\|all]` | Respawns a placement's NPC now | `runicnpc.admin` |
| `/rnpc clear <owner>` | Removes every NPC of an owner (e.g. a stuck run) | `runicnpc.admin` |
**Every placement is checked against Rust's navmesh (D219).** Every placement also answers with the
cost warning (D227): how many RunicNPC NPCs the server now has and what stage 1 measured that number to cost.
On the navmesh, the NPC roams, chases and fights
normally. Off it (a roof, inside a base, a pasted structure), a **stationary** profile is placed and a roaming one
is refused with the reason. An event step gets the same answer, as a blocked RaidableBases spot does (D208).
---
## 6. Behaviour
Each profile has a **role**, which sets its AI states and defaults:
| Role | Behaviour |
|---|---|
| **Roamer** | Wanders within its roam range of home, chases and fights. Rust's default. |
| **Sentry** | Stationary: turns and shoots, never walks. The only role allowed off the navmesh. |
| **Guard** | Holds a point or an entity; chases only to its leash, then returns. |
| **Patrol** | Walks a path recorded in game (`/rnpc path record`); fights and resumes. |
| **Escort** | Follows an entity or player; defends it. |
| **Boss** | Any of the above, plus a health bar, phases and announcements (§3.3). |
| **Passive** | Never fights; press E to talk. Quest-givers and vendors. |
**Factions** are a relation table between profiles, plus optional ties to a team or clan: *hostile*, *neutral*
or *allied*. Rust's scientists are one more faction, so a profile can be told to leave them alone.
**Zone tethering** keeps an NPC inside a ZoneManager zone. At the edge it turns back, and if it ends up outside (it
was pushed, or the zone moved) it is returned home. ZoneManager is already required by `module-rust`; to RunicNPC it
is optional, and a profile that asks for a tether on a server without it is refused at save.
---
## 7. Loot (D218)
A profile's loot table: items with chances and amounts, optionally clearing the corpse's default loot, dropping a
crate, or removing the corpse. Tables are authored on the site with the profile. Adapters to AlphaLoot and the
others are a later stage and not planned in detail here.
---
## 8. Navigation (D219)
**Rust's navmesh is the only one in stages 1–9.** Every spike NPC walked and fought on it, and NpcSpawn itself
shipped no custom mesh. Where it does not reach, a profile is a sentry (§5).
**Stage 10, only if needed:** a point graph recorded in game. An admin walks the route, `/rnpc mesh record <name>`
samples it, and NPCs move between the points directly, as NpcSpawn's custom meshes do, for:
- pasted or player-built bases, and roofs;
- custom map prefabs Rust's mesh does not cover;
- moving platforms, together with parenting.
Stage 10 starts only when a real event or placement needs one, and its own spike decides the file format and cost.
---
## 9. The stages
Each stage is built, then tested on the **Oxide rig**, then on the **Carbon rig**, then PR'd with its docs. A stage
that touches the site also has a browser walk, signed in as an admin, on every new page. A stage whose acceptance
needs a player in game writes that walk down, and it is done before the stage closes.
### Stage 0 — The repository
- `LICENSE.md` (GPL-3.0-or-later), `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md` (with the AI-disclosure rule),
`SECURITY.md`, `README.md`, PR template.
- Branches `main` and `edge` (D226).
- **CI on every PR:** a static reader like Rust-Plugins' `checkPlugin.js`: every hook it declares is known, none
returns a value where one would cancel a game action, and the API version in the source equals the manifest's.
- **Release on `main`:** `runicnpc-<ver>.tar.gz` holding `runicnpc/RunicNPC.cs` and a `manifest.json` (version, API
version, sha256), plus `SHA256SUMS`, using the same release engine as Rust-Plugins.
- `tools/`, never shipped: the rig harness (stage 1) and the panel scripts (`rig.js`, `con.js`), reading tokens at
call time.
- Workspace and org updates: the `CLAUDE.md` repository table and the org landing page (`.profile`), because the
project's shape changes.
**Done when** an empty plugin releases through CI and loads on both rigs.
**As built (2026-09-30, runicnpc-rust#1):**
- **The plugin** has `// Requires: Kits` and `[Info("RunicNPC", "Runic Gateway", "0.0.0")]`, whose version the
release replaces. It answers `RunicNpc_ApiVersion()` (API 1) and `rnpc.status` (version, API version, which
hooks have fired). It spawns nothing.
- **`plugin.toml`** (D230) declares `api = 1`, `requires_plugins = ["Kits"]` and the floors it was loaded on:
**Oxide 2.0.7726** and **Carbon 2.0.259**. The Oxide floor is newer than the bridge's 2.0.7585, because the rig
runs 7726 and RunicNPC has never run on anything older.
- **`scripts/checkPlugin.js`** runs the bridge's checks (every hook listed in `ExpectedHooks` and void unless
listed in `ANSWERS_DELIBERATELY`; chat-command signatures). It adds three of its own:
- no `RunicNpc_*` call may be public without `[HookMethod]`, because `Call` cannot reach it (the trap in §1.2);
- `// Requires:` must equal `requires_plugins`, and Kits must be in it;
- there must be exactly one `[Info]` line, because the release stamps that line.
It has 23 self-tests, including the real plugin and a CRLF checkout: on Windows, an attribute pattern that
only knew `\n` stopped seeing `[HookMethod]`.
- **The release** reuses Rust-Plugins' release engine unchanged. Its packaging step ships
`runicnpc-<ver>.tar.gz`, holding `runicnpc/RunicNPC.cs` and `manifest.json`, whose fields are component,
version, commit, repo, **`api`**, the floors, `requires_plugins` and `files` with each file's sha256. It ships
`SHA256SUMS` beside it. It does not ask the installer to rebuild its bundle until stage 4 makes RunicNPC part of
that bundle.
- **`tools/`**: `rig.js` and **`console.js`**, not `con.js`. `CON` is a reserved device name on Windows, so git
there cannot open a file of that name, even with an extension. The panel address and server ids moved into
a git-ignored `tools/rigs.json`.
- **Loaded from the branch on both rigs:** `rnpc.status` answered `api=1 hooks=1 fired=1` on Oxide and on Carbon
(Carbon compiled it in 217 ms).
- Also updated: the workspace `CLAUDE.md` repository table, which now lists every org repository, and the org
landing page (`.profile#7`).
### Stage 1 — The spike
A harness plugin (`tools/RunicNpcHarness.cs`) answers, on **both** rigs, what stage 2 depends on:
1. The subclass swap (`CopySerializableFields` into our `ScientistNPC` subclass and brain) spawns, walks, fights
and dies cleanly on Oxide **and Carbon**.
2. `enableSaving = false` holds across a hard kill and restart (§1.3 did this for NpcSpawn only).
3. Which ranges and scales hold on the brain without our own states, and which need them.
4. Navmesh coverage: a placement check at every monument of the 6000 map, and on a roof.
5. The cost of spawning 1, 10 and 100, and of 100 idle and 100 fighting, as the server's frame time. These numbers
are the cost warning's (D227), so they are measured on both rigs and on the 6000 map.
6. The name in the death screen, and what the bridge publishes for a kill by and of our NPC.
**Done when** each has a measured answer written into this plan, and the org lead has picked anything the answers
leave open.
**Measured (2026-09-30, `tools/RunicNpcHarness.cs`, runicnpc-rust#3).** Both rigs ran the same world for this:
the Oxide rig was regenerated to the Carbon rig's **6000 map, seed 981448696, 12 GB**. Costs were measured on one rig
at a time, with the other stopped, because they share the node's CPU. Nobody was connected. Each answer below held on
**both** frameworks unless it says otherwise.
*How the harness makes a player.* Q6 and the fighting load need a player, and the rigs have none. At the org lead's
suggestion, the harness spawns **stand-ins**: `player.prefab` with a made-up user id above Rust's bot range
(11400000001 and up). `IsNpc` is false, so Rust's AI and the bridge treat one exactly as a player. This is §1.2's
HumanNPC lesson, used on purpose. A stand-in never connects, and only the harness makes one.
**1. The swap works, with one step the plan did not know about.**
- **`CreateEntity(prefab, pos, rot, startActive: false)` must be followed by `gameObject.AwakeFromInstantiate()`
before `Spawn()`.** That is the call `GameManager.CreatePrefab` makes itself when `active` is true. Without it the
entity still spawns, is networked and even thinks. But Unity never starts the brain, so it has no AI design, no
navigator and no state. It stood still for 90 s.
- With that call, the swap takes **9–16 ms**. The NPC is our type (`RnhNpc`, `RnhBrain`), `IsNpc` is true, it is
not saved, it keeps its name, and it wears and holds its kit (`pistol_revolver.entity`).
- It walks, chases and **fights a player with its kit's weapon**: it killed a stand-in from 12–13 m in 14–20 s, every
hit a `pistol_revolver.entity`. It dies cleanly. Its corpse, an `NPCPlayerCorpse`, carries its name.
- **The field copy differs between frameworks.** The rule "public and not `[NonSerialized]`, or `[SerializeField]`"
copied 64 NPC and 32 brain fields on Carbon, but **124 and 36 on Oxide**. Oxide's patcher makes private fields
public, so on Oxide the rule also carries runtime state across. It worked on both, but stage 2 needs a rule that
selects the same fields on both, for example a list read from Carbon's result and checked on Oxide.
**2. `enableSaving = false` holds.** Five of ours were never saved and one was, as a control. After `server.save`, a
hard kill and a restart, **none of the five came back, on either rig**, matched by net id. The control came back,
but as a plain `ScientistNPC` named "Scientist": a saved subclass loses its type and its name when the server loads
it. That is the other reason our NPC must never be saved (§2).
**3. What holds on Rust's brain, and what needs our own states.**
| Setting | Result |
|---|---|
| Health, name, aim cone | Hold: set on the NPC and read back (400/400, the name, 0.5). |
| Sense range, target-lost range, vision cone, listen range, hostile-only, sense types | **Only if set before the brain starts.** `Senses.Init` copies them once. At 35 m, a range of 50 set before the start saw the target, and the same range set afterwards did not. |
| The prefab's own values | Sense 30 m, lose target 40 m, vision cone −0.8, listen 10 m, memory 10 s, line-of-sight checks on, hostile-only off, senses players only, health 150, aim cone 2. |
| Roaming | **Rust's roam only follows an AI zone's move points.** In a monument's zone (Desert Military Base) ours roamed 36–47 m in 60 s. In an open field it stood still (0 m). **A roamer anywhere but a monument needs our own roam state, so stage 2's roamer role includes one.** |
| Sleep | An NPC outside an AI zone is never put to sleep, and `ai_dormant` does not apply to this AI. So an idle NPC keeps thinking with nobody near, which is what the costs below measure. |
| **Fighting NPCs** | **Rust's scientist AI never attacks an NPC.** `HumanNPC.IsTarget` is true only for non-NPC players, pets and scarecrows. `IsFriendly` means "same prefab id", which the swap copies, so every stock scientist counts ours as a friend. Re-implementing Rust's internal `IAISenses` puts a scientist in our NPC's target list. But Rust's AI design never runs its attack event for an NPC target. Calling `AttackTick` directly passed line of sight every time and still fired no shot, because the design's cover and facing states win. **NPC-versus-NPC combat needs our own combat state, and sensing NPCs needs our own sensing** (see the cost below). D231 makes it a profile setting, so stage 5 opens with its own spike. |
**4. Navmesh.** Rust's scientists walk **Rust's own navmesh** (its Gen2 `RustNavMeshAgent`), not Unity's: a Unity
`NavMesh` query found nothing in the open world. **The placement check is `Rust.Ai.Gen2.RustNavMeshHelpers.
SamplePosition`**, the same helper Rust's navigator uses. It answers false until `RustNavigation.Instance.
IsDefaultNavmeshBuilt()`. On a map's **first** boot that took 8–10 minutes (477 s on Carbon, 604 s on Oxide); later
boots load the saved `proceduralmap.<size>.<seed>.<n>.navmesh`. **Placements that respawn at boot must wait for it.**
| | Carbon | Oxide |
|---|---|---|
| Monuments probed (9 points each) | 144 | 144 |
| Points on the navmesh | 1,152 / 1,296 (89%) | 1,151 / 1,296 (89%) |
| Of those on a structure (a roof or raised floor) | 132 / 209 (63%) | 130 / 211 (62%) |
| A player-built floor 4 m up | **not on the mesh** | **not on the mesh** |
| One check | 13.6 µs | 8.3 µs |
Monument roofs (Launch Site, Airfield, Trainyard, the warehouses) are mostly walkable. Player-built floors and
roofs never are: that is §5's sentry rule, and stage 10.
**5. The cost (D227's numbers).** Seven 60 s phases on a field 400 m from any monument: a baseline, 1, 10 and 100
of ours idle, the same 100 shooting 20 stand-ins (whose damage the harness zeroes, so none die), a fresh 100 set to
fight NPCs beside 100 stock scientists, then empty again. Every phase also had one 1–3 s spike from the autosave, so
the table quotes the median frame rather than the worst.
| Phase | Oxide: median frame / fps | Oxide: time per think / each NPC thinks every | Carbon: median frame / fps | Carbon: time per think / each thinks every |
|---|---|---|---|---|
| Baseline, empty | 16.4 ms / 52.7 | — | 17.3 ms / 46.6 | — |
| 1 | 16.7 / 50.7 | 0.09 ms / 0.28 s | 17.3 / 48.1 | 0.05 ms / 0.29 s |
| 10 | 16.6 / 51.8 | 0.04 ms / 0.28 s | 17.7 / 47.4 | 0.03 ms / 0.29 s |
| 100 idle | 17.7 / 48.3 | 0.04 ms / 0.30 s | 18.9 / 41.8 | 0.03 ms / 0.33 s |
| 100 shooting 20 players | 21.6 / 44.5 | 2.5 ms / **2.5 s** | 22.1 / 43.1 | 2.4 ms / **2.6 s** |
| 100 sensing NPCs, beside 100 scientists | 26.4 / 33.9 | **17.7 ms** / **7.5 s** | 26.1 / 33.9 | **20.4 ms** / **8.2 s** |
| Spawning 100 at once | a **552 ms** hitch (5.5 ms each) | | a **483 ms** hitch (4.8 ms each) | |
What the numbers say:
- **The two frameworks cost the same.** Every row agrees within about 1 ms, so one warning serves both.
- **This rig is slow.** An empty server runs at about 50 fps, not its 240 target. The warning therefore reports
what NPCs **add**, not an absolute fps.
- **Idle NPCs are cheap:** 100 add about 1 ms to the median frame.
- **Fighting NPCs hit Rust's AI budget before they hit the frame rate.** Every human NPC's thinking shares
`aithinkmanager.framebudgetms`, 2 ms per frame. At 100 fighting, each NPC gets to think only every 2.5 s, so they
react sluggishly while the median frame rises by only about 5 ms. The warning has to say both things.
- **Sensing NPCs the way Rust does, with a line-of-sight test to every candidate, costs about 7× more per think than
fighting players.** 100 NPCs sensing each other make roughly 100² tests. D231's NPC targeting must sense
differently, for example by testing only the profiles it is hostile to, nearest first.
- **Spawn in batches.** 100 in one frame is a half-second hitch; stage 2 spreads a large placement over frames.
**6. The name on the death screen, and what the bridge publishes.**
- **`HumanNPC.AttackerInfo` writes the prefab's short name as the killer**, after `BasePlayer` has written the
display name. The death screen said "scientistnpc_roam" until our NPC overrode it. With the override it says
**"RnhWarden"**, and the weapon stays `pistol_revolver.entity`.
- **Deferred: the org lead checks it in game later (2026-09-30).** The client may use that string to pick the
killer's portrait, and only a real client shows it. To check: on a rig with the override loaded, be killed by a
named RunicNPC NPC and look at the death screen. Does it show the NPC's name, and does it still show the killer's
portrait? The result is written here. If the portrait is lost, stage 2 decides between the name and the portrait.
This is the only stage 1 item still open.
- **What the bridge publishes (protocol 13):**
- our NPC kills a player → `player.death` with `attackerType: "npc"`, **`attackerName: "scientistnpc_roam"`**
(the prefab name, as §1.4 said), the weapon and the distance;
- a player kills our NPC → **only** `player.tally` with `npcKills: 1` and the weapon. Nothing names the NPC or its
profile.
Both are stage 4's to fix: the NPC's name in the feed, and a death frame with its profile.
- **Left on the rigs:** each rig's sidecar store now has the stand-in "RnhDummy" (11400000001) as a player, with
one death and one tally row. It is test data on test rigs; a wipe clears it.
### Stage 2 — The NPC and its API
- The subclass, profiles (read from RunicNPC's own data file for now), kits (random pick), appearance, combat values,
roamer and sentry roles, sleep.
- Owners and lifetimes (§2); placements persisted with one dirty flag; standalone profiles and the managed flag
(D221); optional caps, off by default, and the cost warning from stage 1's measurements (D227).
- The API (§4) and its hooks; `docs/runicnpc/API.md`.
**Tested by** the harness asserting each call's result (PASS/FAIL lines read back over the panel), plus restart
and reload checks on both rigs: no NPC saved, every placement back, nothing left behind by an unloaded owner.
### Stage 3 — In game
The chat and console commands (§5), their permissions, the navmesh placement check, respawn delays, and `/rnpc
path record` for stage 5.
**Tested by** a written in-game walk: place, remove, look-at info, respawn, restart. **This is the first stage that
needs a player on a rig.**
### Stage 4 — Runic Gateway integration
Across four repositories, split into 4a–4c if it grows:
- **Rust-Plugins (the bridge):**
- hello reports RunicNPC's presence and API version;
- `world.place` for an NPC takes a profile, and the placing is RunicNPC's;
- the killfeed names NPCs by their name (§1.4);
- new frames: an NPC died, with profile, name, killer and contributors; a health threshold; placements changed;
- `player.tally` counts NPC kills per profile;
- profiles and placements pushed from the site, as the permission sync is.
- **Rust-Link:** routes for profiles and placements, and the frames forwarded.
- **Module-Rust:**
- an **NPC profiles** admin page (per server, shared or fleet-wide) with the kit check;
- a **placements** view per server;
- `rust.npc.place` takes a profile, through a new option source `rust.options.npc_profiles`;
- triggers `rust.npc.died` and `rust.npc.health`, so a phase can wait for "8 guards died" (waves) or "the boss
below 50%";
- per-profile stats and titles.
- **Installer and egg:**
- RunicNPC becomes a third artefact in the Rust bundle, pinned and checksummed like the plugin and the sidecar
(D224);
- `doctor` reports it missing or edited;
- the egg installs it.
The wire changes join protocol 13 if it is still unreleased, or open 14.
**Tested by** the usual trio: each repository's suites, both rigs through the site, and a browser walk of both new
pages. An event run places profile NPCs, waves advance on their deaths, and teardown removes them.
### Stage 5 — Behaviour
Guard, patrol and escort roles; factions (between profiles, with Rust's scientists, and with teams or clans); group
alert; zone tethering; turrets; the weapon behaviours a kit's items imply; TruePVE compatibility.
**Tested by** harness fights between profiles on the rig (who shoots whom, with what, and within which leash), and
an in-game walk for escort and faction ties to a clan.
### Stage 6 — Roles
Bosses (a health bar drawn with CUI, phases at thresholds that swap profile values, announcements through the bridge
to engagement, a reward on the kill through the existing reward verbs) and passive NPCs (press E, site-written lines).
**Tested by** an in-game walk (the bar, a phase change, the announcement arriving on Discord and in the app), and
the site's trigger firing at the threshold.
### Stage 7 — Loot
Loot tables authored on the site, the corpse's default loot cleared or kept, a crate on death, corpse removal.
**Tested by** harness kills whose corpses are read back, 100 times each, against the table's chances.
### Stage 8 — On the map and in the app
Event NPCs and bosses on the live map (protocol 11's `map.live`), a live "left: 3/8" on the event page, and the same
in the Android app.
**Tested by** a browser walk and an emulator walk.
### Stage 9 — Hardening and release
- **Performance to the budget stage 1 measured:** 100 NPCs on a 6000 map without the frame time crossing it.
- **An update drill:** a rig on Rust's `staging` branch loads the current RunicNPC before each forced wipe. The
subclass swap and the brain are what break when Rust changes, so they are kept small and listed in one place.
- **The whole acceptance walk on both rigs, with a player.**
- **Operator documentation:** `docs/runicnpc/` gets INSTALL and a command reference; `module-rust`'s OPERATING notes
list it as required.
- **Publishing (D224):** the Gitea release is the source of record. Other download sites (uMod, Codefling) are
decided then, each against its own rules, for example uMod's review guidelines.
- **v1.0.0 released, and `module-rust` then requires it:**
- the bundle lists it;
- the module refuses NPC steps on a server without it, saying why;
- the bridge reports it in hello.
**Then the Rust plan resumes** at PLAN_REDESIGNS §9 item 6 (the step editor and the kit weekend) and §11.
### Stage 10 — Custom navigation (only if needed)
§8. Not scheduled.
---
## 10. Maintenance, honestly
| What breaks | When | How we know | Cost |
|---|---|---|---|
| The subclass swap and the brain states | A Rust update that changes `ScientistNPC`, its brain, or `BaseNavigator` | The staging-branch rig, before the wipe | Our release timing, not an upstream author's. This is NpcSpawn's churn, but for the states we use, not all of its twenty. |
| Kits' API | A Kits release that renames `GiveKit` | Stage 2's harness | Low: one call. |
| ZoneManager's API | A ZoneManager release | Stage 5's harness | Low, and the tether is optional. |
| Carbon's compatibility layer | A Carbon release | The Carbon rig | Seen before; recorded in CARBON.md. |
A RunicNPC fix ships as its own release. It moves the bundle's pin only when the bridge needs it to, so an NPC fix
does not wait for a bridge release, or the reverse.
---
## 11. Questions for the org lead
**All eight were answered on 2026-09-30, as recommended except Q6 (D224 adds Gitea and other download sites)
and Q7 (D227: no default caps, a cost warning instead). They are kept as asked.**
**Q1. Can RunicNPC be used without Runic Gateway?** Picture a server owner who installs only RunicNPC, from uMod.
- **(a, recommended) Yes.** Without a site, profiles live in RunicNPC's data file and console commands edit them.
With a site, the site's profiles replace that file on every push, and in-game profile edits are refused with "this
server's profiles are managed by its website".
- **(b) No.** Profiles come only from a site, and the plugin is only ever installed by our installer.
**Q2. An admin places three guards with `/rnpc place`, then the site is offline for a day. What happens?**
- **(a, recommended)** The placements live on the server, so the guards keep respawning. The site catches up when it
returns, and shows and edits them from then on.
- **(b)** The site is the only record, so a placement made while it is offline is refused.
**Q3. What should our NPC be?**
- **(a, recommended)** Its own subclass of Rust's scientist with its own brain, as NpcSpawn does. It can be named,
and it can guard, escort and run boss phases. The brain is the part a Rust update can break.
- **(b)** Rust's scientist left as it is, plus small patches for the name and a few values. There is less to break,
but there is no guard, escort or boss behaviour.
**Q4. A player kills your "Warden" boss. Where does "Warden kills: 3" show?**
- **(a, recommended)** On their public profile and as a title condition, like the NPC kills column today.
- **(b)** Only to admins.
**Q5. Branches.** Like the other Rust repositories (D18), build on `edge` and cut over to `main` for releases?
**Recommended: yes.**
**Q6. How does RunicNPC reach a server?**
- **(a, recommended)** The installer and the egg install it from our bundle, pinned and checksummed like the bridge.
Kits and ZoneManager stay "report, don't install" (D153).
- **(b)** Operators install it themselves, like Kits, and `doctor` only reports it.
**Q7. How many NPCs by default?** Recommended defaults, each editable per server:
- 100 NPCs on a server in all;
- 50 per owner (one event run, or all of one admin's placements);
- 10 spawns per second.
**Q8. The name.** The plugin file is `RunicNPC.cs`, so its console name is `RunicNPC`, with the command `/rnpc` and
permissions `runicnpc.*`. **Recommended: yes.**

View File

@@ -11,7 +11,7 @@ speaks one protocol, never "the latest of each":
| Component | What it is | Released from |
|---|---|---|
| **The plugin** | `RunicGateway.cs`, one file that runs unchanged on Oxide and Carbon | [Rust-Plugins](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins/releases) |
| **The plugin** | `RunicGateway.cs`, one file that runs unchanged on Oxide and Carbon — and beside it, from protocol 13, the optional **ZoneManager helper** `RunicGatewayZones.cs` (PLAN_FIXES D181, D182), installed by default | [Rust-Plugins](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins/releases) |
| **The sidecar** | `rust-link-sidecar`, which the plugin dials on loopback and the website reaches over HTTP | [Rust-Link](https://gitea.whitlocktech.com/RunicGateway/Rust-Link/releases) |
The game server opens no port for the bridge: the plugin is the client and the sidecar the
@@ -156,7 +156,12 @@ history, and the token is unchanged.
plugin tarball, each with a `sha256`.
2. **Download and verify** both against those checksums (`sha256sum -c`, or `Get-FileHash`).
3. **The plugin:** copy `runicgateway-rust-plugin/RunicGateway.cs` from the tarball into
`oxide/plugins/` or `carbon/plugins/`. To name the server, create its config first —
`oxide/plugins/` or `carbon/plugins/`, and every other `.cs` the tarball's `manifest.json` lists
in `files` beside it — from protocol 13 that is `RunicGatewayZones.cs`, which lets ZoneManager count a
player already standing in a zone when it opens or comes back after a restart. It is optional: leave
it out and events still score everybody, but ZoneManager's own flags miss that player. The second is
`RunicGatewayDomes.cs`, which lets the bridge ask ZoneDomes for a dome over an event zone; leave it
out and zones open without one. To name the server, create its config first —
`oxide/config/RunicGateway.json` or `carbon/configs/RunicGateway.json` — holding
`{ "ServerId": "<id>", "Port": 7799 }`. Without it, the plugin calls the server `main`.
4. **The sidecar:** put the binary somewhere stable and give it a config:
@@ -215,7 +220,7 @@ With the installer:
| | |
|---|---|
| `doctor --game rust [--server-id <id>]` | Per server: the framework; whether the plugin file is still the one deployed; that the plugin's config names this server; the required uMod plugins; the service; and `/health` through to **plugin connected**. A stopped server is a warning; a running one whose plugin never connected is a failure, printed with the framework versions the plugin is known good on |
| `doctor --game rust [--server-id <id>]` | Per server: the framework; whether the plugin file is still the one deployed; each helper deployed beside it, as a **warning** when missing or edited (the bridge runs without one, and the row says what that costs); that the plugin's config names this server; the required uMod plugins; the service; and `/health` through to **plugin connected**. A stopped server is a warning; a running one whose plugin never connected is a failure, printed with the framework versions the plugin is known good on |
| `update --game rust` | Moves the sidecar and every server's plugin to the current bundle, and restarts the sidecars. Always all servers together — they share one binary |
| `uninstall --game rust [--server-id <id>] [--purge]` | Removes the service and the plugin file. **Keeps the plugin's config** — it is the website's, and it names the server. `--purge` also removes the sidecar config (the token) and the database. Removing the last server removes the shared binary too |

View File

@@ -289,7 +289,7 @@ start the run.
| 3 | **Leave step 2's run going and restart the server.** Rejoin, walk back into the zone and run `rgp.inzone` | `zone_list` shows the zone **back** after the restart, at the same place and with the same name, re-created from the bridge's own record because ZoneManager forgets temporary zones. `rgp.inzone` names you again. On the site the run's zone row still reads `confirmed` |
| 4 | **`rust.crate.place`**: `crate.hackable` ×1 and `crate.elite` ×3 at the same monument, spread 8. Loot one elite crate empty; start the hack on the locked crate. Then cancel the run | The crates are there and lootable, the hack timer runs. At teardown the untouched crates vanish, and the looted one is simply **gone** already — its row reads `reverted` all the same (§15.2: reverting something a player took is a success) |
| 5 | **`rust.npc.place`**: `npc.scientist` ×3 at the monument. Kill one; let the others see you | They are hostile and fight. The one you killed is just gone; at teardown the survivors vanish mid-fight. Every row reads `reverted`. If an NPC spawned **inside a wall or fell through the ground**, note the monument — some offsets land off the navmesh, and that is a finding about where to put things, not a bug to hide |
| 6 | **A zone for 3 minutes.** Stand inside it (`rgp.inzone` names you) and wait out the three minutes | The zone disappears around you **without anybody on the website doing anything**, because the game keeps the deadline (D96). `zone_list` no longer lists it, and the sidecar's `/events?kind=world.expired` shows the frame. Best done on the non-admin account, which is the view a real player has |
| 6 | **A zone for 3 minutes.** Stand inside it (`rgp.inzone` names you) and wait out the three minutes | The zone disappears around you **without anybody on the website doing anything**, because the game keeps the deadline (D96). `zone_list` no longer lists it, and the sidecar's `/events?kind=world.expired` shows the frame, with `what: "zone"` (protocol 13, F13 — before it, the frame was filed as `zone` and this check could not pass). On the run console the zone reads **`expired` — ended by the game on time**, not `confirmed` (F14). Best done on the non-admin account, which is the view a real player has |
| 7 | **If players can be arranged, a `core.lease` on `spawn.max_rate`** — these two scalars are left out of the catalogue today because they only matter with people online (§27.5) | With several players on, the population system's spawn rate moves (`spawn.report`) while the lease holds and returns after. If it does, the two `spawn.max_*` keys can be added to the allowlist; if nothing moves even with players, they stay out |
**Run steps 1–5 on both frameworks.** One thing is specific to Carbon: ZoneManager was only installed
@@ -407,3 +407,37 @@ above, and a staff member at the website.
**What counts as a pass:** a real chat line carries a site title and a site style, the voice speaks
without a sender, and a popup appears on a real screen.
## The step-2 fixes (protocol 13, PLAN_FIXES §6 step 2)
Added 2026-09-27. What [`PLAN_FIXES.md`](../modules/rust/PLAN_FIXES.md) §8 asks the re-walk to show for
step 2's fixes, in the order they are quickest to walk. Player A from the walks above; a staff member
at the website. **Run it on Oxide and on Carbon.** Rows marked *no player* need nobody in the game.
Their game side was walked on both rigs on 2026-09-27 (the helper patched, the hello carried its state,
the load frames carried Kits' permissions), and their site side on `rust-oxide` the same night (the servers
list showed the helper; the Kits load was synced 24 s later). Row 8's refusal and events step 6 were also
walked there without a player. The rest need somebody in the game.
| # | Do this | You should see |
|---|---|---|
| 1 | *No player.* `rgz.status` in the server console | `Runic Gateway Zones 0.1.0: patched`, and the servers page says nothing about the helper. Unload it (`oxide.unload RunicGatewayZones`; Carbon: `c.unload RunicGatewayZones`) and wait a minute: the servers page warns that ZoneManager's flags miss a player already inside a new zone (D182). Deleting or renaming the file does **not** unload it on either framework. Load it again (`oxide.load`, or `c.load` — Carbon only queues the compile, so allow a minute) |
| 2 | *No player.* `oxide.unload Kits` (Carbon: `c.unload Kits`), grant a site group `kits.admin`, then `oxide.load Kits` | The sidecar's `/events?kind=plugin.loaded` shows Kits with `["kits.admin","kits.rgreward"]`, and the grant lands **within a minute** — not on the fifteen-minute audit (F8) |
| 3 | A fells a tree and picks up a hemp plant | The next `player.tally` counts the wood the inventory shows — the final hit's bonus included — and the cloth from the hemp (F1, D159) |
| 4 | A breaks a wall of their own base | `entity.destroyed` arrives; the next tally's `structures` does **not** move (F3) |
| 5 | Staff open a zone with a timed event while A stands where it will be | ZoneManager counts A at once — `rgp.inzone` names A, and the helper may log `1 player(s) already inside were counted in` (on Carbon ZoneManager's own entry got there first) — and the run's tally gives A seconds without A walking out and back in (F12). No enter message shows: the bridge makes its zones without one |
| 6 | With A standing in a live event zone, restart the server. A sleeper can be killed while A is away, so stand in a small locked hut, and wake up at once on rejoining — asleep does not score | After the restart A is in the zone again (ZoneManager says so) and keeps scoring without moving (F12). The site's restart permission sync goes **after** "Server startup complete", not before, and says what it applied (F7) |
| 7 | Staff unload the helper (row 1), then repeat step 5, and reload ZoneManager with A still inside | A still scores, through the zone's re-creation too (the bridge measures the zone's shape, D182). On ZoneManager 3.1.14 its own entry counted A anyway, a moment late — the helper only makes that immediate |
| 8 | Stop another enabled server, then have A type a made-up code on the website | "That code is unknown or has expired" — not "one of the servers could not be reached … your code is still good" (F5) — in a second or two, not many (F6): a server the site already knows is down is not waited on (D186). A real code from A's server still links |
| 9 | A is killed by a wolf, then by a scientist | The killfeed says **Wolf** and **Scientist**, not `wolf2` or `scientistnpc full any` (F2) |
**What counts as a pass:** a zone counts somebody who was already standing in it, on both frameworks,
and an expired zone reads `expired` on the run console.
**Walked 2026-09-27, rows 3–9, on Oxide and then Carbon, with the org lead in the game.** Every row passed but row 8's timing.
The tallies matched the inventory exactly (653 and 654 wood, 10 cloth, a hemp seed); an own wall brought down
with C4 was an `entity.destroyed` and no raid; a zone scored a player who stood still through its opening, a
restart (128 s and 246 s, against the time actually spent inside) and a ZoneManager reload with the helper
unloaded (105 s and 90 s); a real code linked in under two seconds with the other rig stopped; and the killfeed
read Bear, Wolf, Boar and Scientist. Two findings were fixed the same day and walked on the walk core: a
made-up code still waited one timeout on a stopped rig, 12 s (D186 — now 360 ms), and on Carbon a due audit
went out before the restarted world's hello was read (D187). Not walked: a player killed by another player.

View File

@@ -461,7 +461,7 @@ Every kind protocol 2 defines, and the hook behind it. **`class` is not a field
| `player.respawned` | `OnPlayerRespawned` | **presence** | steamId |
| `player.death` | `OnPlayerDeath` | **presence** | victim, attacker, attackerType, weapon, distance, grid |
| `player.chat` | `OnPlayerChat` | **presence** | steamId, name, channel, message |
| `player.tally` | *aggregate* — see §8.6 | **presence** | steamId, gathered{}, npcKills, structures |
| `player.tally` | *aggregate* — see §8.6 | **presence** | steamId, gathered{}, npcKills, structures; from protocol 13 the chat-title counts (§19.10) |
| `entity.destroyed` | `OnEntityDeath` on owned building blocks — **and doors, external walls and the cupboard from protocol 7 (§13)** | **staff** | ownerId, prefab, grid, attacker; from protocol 7 also `structure`, `buildingId`, `authorized` |
| `player.reported` | `OnPlayerReported` | **staff** | reporter, target, subject, message, type |
| `player.banned` / `player.unbanned` | `OnUserBanned` / `OnUserUnbanned` | **staff** | id, name, **ip**, reason |
@@ -1436,7 +1436,7 @@ five routes.
| Command | Answers | |
|---|---|---|
| `world.monuments` | `world.monuments` | This map's monuments in one stable order (grouped by prefab short name, then by position). Each has `value` (`kind`, or `kind#n` when the kind repeats), `kind`, `instance`, `of`, `label` (the game's display phrase), `x`, `z` and `grid`. Also `worldSize`, the placeable `prefabs` (`key`, `kind`, `label`), `eventsEnabled`, `maxCrates`, `maxNpcs` and `zoneManager` |
| `world.zone` | `world.ok` or `world.error` | Opens a ZoneManager temporary zone owned by the bridge. Needs `runId`, `key`, a location, `radius` (5–150 m) and `holdMs` (1 minute to 7 days); `name` is optional |
| `world.zone` | `world.ok` or `world.error` | Opens a ZoneManager temporary zone owned by the bridge. Needs `runId`, `key`, a location, `radius` (5–150 m) and `holdMs` (1 minute to 7 days); `name` is optional. Protocol 13 adds `flags`, `settings`, `enterMessage`, `leaveMessage`, `delivery`, `format` and `dome` (§19.11) |
| `world.place` | `world.ok` or `world.error` | Places `count` of one allowlisted `prefab` at a location, scattered within `spread` m (0–50, 10 by default for a group). All or nothing: if the game refuses one, the ones already made are killed |
| `world.revert` | `world.ok` | Gives back what a run owns: the named `ids`, or else everything under `key`, or else everything the run owns. The answer lists `removed`, `gone` and `refused` |
| `world.owned` | `world.owned` | What the world still holds of what events made, **looked for** by net id or zone id, narrowed by `runId`. Anything gone is pruned from the registry as the walk passes it |
@@ -1511,8 +1511,11 @@ erases a zone whose `holdMs` has run out, whether or not the website is heard fr
{"kind":"world.expired","type":"event","id":"rg-13-35875416-1","runId":"13"}
```
The website maps it to nothing. Core learns about it through `reconcile` and `revert`, as with
`lease.expired`.
Until protocol 13 the website mapped it to nothing (D96), and core learned about it only through
`reconcile` and `revert`, as with `lease.expired`. **Protocol 13 changes both halves** (§19.4): the
frame carries the entity's kind as `what` — protocols 9 to 12 wrote it over the frame's own `kind`, so no
`world.expired` ever arrived as one — and the website records the run's resource as `expired`
(PLAN_FIXES D170, D183).
### 15.4 `EventsEnabled`, and the two bounds
@@ -1950,8 +1953,9 @@ untouched.
Planned in [`PLAN_FIXES.md`](../modules/rust/PLAN_FIXES.md): one bump for every wire change the org
lead's first walk with a player in the game found (§5 there). It is built on `edge` in Rust-Plugins,
Rust-Link and Module-Rust and released together (D177). **This section grows as the pieces land**;
the first is the configuration save.
Rust-Link and Module-Rust and released together (D177). **This section grows as the pieces land**:
the configuration save first (§19.1–19.3, step 1), then step 2's fixes (§19.4–19.8, decisions
D181–D185).
One fix rides in the same release without a wire change: **the plugin decodes what the sidecar sends
as UTF-8** (F15). Protocols 1 to 12 decoded each byte as a character — Latin-1 — so every non-ASCII
@@ -2073,3 +2077,309 @@ from `config.outcome` by `(server_id, write_id)`, and only while it is still `re
frame moves nothing and a late one still lands. A row past `settle_by` reads as **`lost`**. The page polls
`GET /api/v1/admin/rust/config/{serverId}/writes/{writeId}` every two seconds until the write settles
(D179).
### 19.4 `world.expired` is recognisable, and an expiry is recorded (F13, F14)
The frame gains **`what`**, the entity's kind — the name the website's resource rows already use:
```json
{"kind":"world.expired","type":"event","id":"rg-13-35875416-1","what":"zone","runId":"13"}
```
Protocols 9 to 12 wrote the entity's kind into `kind`, over the frame's own, so every expiry reached the
sidecar as `kind: "zone"` and nothing listening for `world.expired` ever heard one (F13). A website that
reads protocol 12 frames will find them filed under `zone`; nothing is re-filed.
**The website records it** (D170, D183). Module-Rust hands core the resource the zone step ledgered —
kind `world`, ref `<serverId>:<id>` (§15, the ref names the server) — through
`ctx.events.expired({ kind, ref })` (MODULE_API 1.11.0). Core marks that row **`expired`**: terminal,
never taken back at teardown, and distinct from `orphaned`, which `reconcile` uses for a thing that
vanished with nobody asking. An expiry for a zone no run ledgered is not an error.
`world.expired` and `lease.expired` are **staff** kinds (§8.5). Neither was classified before protocol
13 — default deny kept both off public pages — and both are an event's machinery; the public hears what
an event did from core's announcements.
### 19.5 `plugin.loaded` and `plugin.unloaded` (F8)
A grant the site made for a plugin that was not loaded stays unresolved until the plugin is back. The
first walk watched one land thirteen minutes after the plugin loaded, on the fifteen-minute audit. So
the bridge now announces a load or an unload of **another** plugin, with the permissions it registered
or dropped (D184):
```json
{"kind":"plugin.loaded","type":"event","name":"Kits","version":"4.4.9","permissions":["kits.admin","kits.rgreward"]}
```
- **`permissions`** is a diff of the framework's registered-permission list, taken **one tick after the
hook**, because the order of "drop an unloaded plugin's permissions" and "call `OnPluginUnloaded`"
is the framework's own. It is sorted, and it may be empty.
- **Only once the world is ready** (§15.5). A boot loads every plugin, and a boot is the restart sync's
job; the bridge takes its baseline list at `OnServerInitialized`.
- **A reload in one tick shows an empty list on both frames.** Carbon's `c.reload` unloads and loads in
the same tick, so by the next the list is what it was. That is the right answer: what a grant
resolves against did not change. Two plugins loaded in one tick share one diff, under the first name.
- Both are **staff** kinds. The website marks the server's permission sync dirty when `permissions` is
not empty, and the next tick (30 s) pushes. §4.1's permission manager will take plugin ownership from
its own inventory read, not from this.
Walked on both rigs, 2026-09-27: `oxide.unload Kits` / `oxide.load Kits` and Carbon's `c.unload` and
the queued load each carried `["kits.admin","kits.rgreward"]`; the ZoneManager helper's load carried `[]`.
### 19.6 The ZoneManager helper, and `zoneHelper` at hello (F12)
ZoneManager counts a player as inside a zone only when the zone's trigger fires on **entry**, so a zone
created, updated or re-created around somebody standing there holds nobody — its flags, messages and
`OnEnterZone` never happen for them, and the bridge's tally, which asks ZoneManager's membership, scored
nobody already in an arena after a restart. ZoneManager has no public way to look again.
**`RunicGatewayZones.cs`** (D181, D168) ships beside the bridge and is installed by default (D182). It
Harmony-postfixes ZoneManager's `Zone.InitializeZone` — the one method a zone passes through when it is
created, updated (`Zone.Reset`) or loaded from ZoneManager's data file — and one tick later enters every
connected player ZoneManager's own `IsPositionInZone` places inside, through ZoneManager's own
`OnPlayerEnterZone`. A player ZoneManager already counts is skipped, and ZoneManager refuses a second
entry anyway. It fixes **every** zone on the server, not only the bridge's. It sweeps all zones once when
it patches, and re-patches when ZoneManager reloads. `rgz.status` prints its state.
The bridge never depends on it. `server.hello` carries, whenever ZoneManager is loaded:
```json
"zoneHelper": { "state": "patched", "version": "0.1.0" }
```
`state` is `patched`, `unsupported` (loaded, but this ZoneManager lacks what it patches — `reason` says
what), `no-zonemanager`, or `missing` (the file is not there). **Anything but `patched` and the bridge
scores the zones it made by ZoneManager's public `IsPositionInZone`**, for the participation tally and
the kill credit alike — so a missing helper costs ZoneManager's flags for somebody already inside, never
their score. The website shows the cost on the servers page.
Walked 2026-09-27: it patched ZoneManager 3.1.14 on Oxide and on Carbon, and the site read
`{"state":"patched","version":"0.1.0"}` from both hellos. **Not yet walked with a player standing in a
zone** — that needs somebody in the game.
### 19.7 What the tally counts (F1, F3, F4)
- **`gathered` is everything a player harvests** (D159). `OnDispenserGather` is the swings;
`OnDispenserBonus` (the final hit's bonus), `OnCollectiblePickup` (hemp, mushrooms, stones off the
ground) and `OnGrowableGathered` (a farmed plant) now add to the same per-item counter. All three are
`void` (§8.7) and in `rg.hooks`. A pick-up another plugin vetoes is still counted — the hook fires
before the items move — which is rarer than a second hook is worth.
- **`structures` no longer counts your own base.** A building block the attacker placed, or one on a
cupboard they are authorised on, is not counted. The `entity.destroyed` frame still goes; the site
already skips the raid alert for an authorised attacker (D59).
- **Every Steam id comes from `userID`.** The thirteen frames that read `UserIDString` sent `null` for a
player another plugin spawned; they now use the same `SteamIdOf` as the map.
### 19.8 The website
- **The loading hold** (F7). Permission and title pushes wait while the last hello says
`worldReady: false` — the first walk's restart sync went 35 s before the save loaded, timed out, and
the retry reported "0 applied". A human's "sync now" is not held. A failed or refused sync logs a
warning.
- **Link codes** (F5, F6). A code is asked of the servers that minted one in the last six minutes (every
`/link` stores an `account.link.requested`) first, then of the rest, each group **in parallel**. The
answer is "a server could not be reached — your code is still good" only when one of the minting
servers is unreachable; a dead server that minted nothing no longer makes a wrong code look good.
- **NPC attackers** (F2, D185) are named by the killfeed: a family (`scientistnpc_*` → Scientist,
`bradleyapc` → Bradley APC) or the prefab without its variant digits (`wolf2` → Wolf). No wire change.
### 19.9 `perm.inventory` — the whole permission store (the permission manager)
The site owns every permission and group on a server, not just the ones it authored
(`docs/modules/rust/PLAN_REDESIGNS.md` §1, D160). So it has to read all of them. It does that with one
request/reply verb, through one new sidecar route:
POST /permissions/inventory ─── perm.inventory ───► {snapshotId?, page?}
◄── perm.inventory ──── one page
◄── perm.error ──────── busy · stale · too-large
**Page 0 without a `snapshotId` starts a fresh read.** The reply names the snapshot, and each later page
is asked for by `snapshotId` and `page`:
```json
{"kind":"perm.inventory","type":"reply","snapshotId":"62fe7e6cfac5","page":0,"pages":1,"more":false,
"permissions":[{"name":"kits.admin","owner":"Kits"},{"name":"adminmodule.greet"}],
"groups":[{"name":"default","title":"Default ","rank":0,"parent":"","permissions":[]}],
"users":[{"steamId":"76561198038695917","name":"whitlocktech","permissions":["kits.admin"],"groups":["site"]}],
"leased":[{"kind":"group-permission","subject":"default","object":"kits.vip"}],
"stats":{"permissions":85,"groups":4,"users":2,"buildMs":148}}
```
- **`permissions`** is every registered name, with **`owner`**, the plugin that registered it. The
owner comes from `permission.PermissionExists(name, plugin)` asked of each loaded plugin. That is
public API on both frameworks (Oxide takes a `Plugin`, Carbon a `BaseHookable`), never a guess from
the name's prefix. A name no plugin owns has no `owner`; on Carbon those are its built-in modules'
names (`adminmodule.*`).
- **`groups`** have their title **verbatim** (Carbon's own end in a space), rank, parent, and the
permissions the group itself carries, not what it inherits.
- **`users`** is every Steam id holding anything, with its direct permissions and its groups, **except
`default`**, which every connected player is in by framework rule. `name` is the store's last
recorded name, when it has one.
- **`leased`** is the group permissions an event lease holds (§14). The site does not take them for hand
edits.
- **Page 0 alone carries `permissions`, `groups`, `leased` and `stats`**, and every page carries
`users`. A page is at most 700 KiB of rows, inside the 1 MiB line cap (§3.1).
**Cost.** Neither framework can list its users, so holders come from `GetPermissionUsers` for every
permission and `GetUsersInGroup` for every group. Each of those walks every user. The read is therefore
built **25 sources per tick**, on the sync drain's 50 ms timer, and replied to when complete. It is taken
**once** and paged from memory for two minutes, so a grant made between two pages cannot tear it. A build
past **8 s** is abandoned and answered `too-large` — the sidecar's ten-second wait has already lost it.
A second read while one is building is `busy`; a page of a snapshot that is gone is `stale`, and the
site starts again from page 0 (once). `rg.inventory` runs the same build from the server console and
logs its summary instead of replying.
**`perm.sync`**, in the same bump:
- **Groups carry `parent`.** It is applied with `SetGroupParent` after every group exists and before any
retirement. A parent that will not set (missing, or a loop) is reported in `notLanded` as
`group:parent:name`.
- **An existing group's title and rank are written when they differ.** Until now a title was only set
when the sync created the group. **An absent `title` or `rank` means "leave it"**, and an empty title
is a title. The site omits them while a person decides about an in-game change (the `adopt` policy).
The report's `applied` gains **`groupsUpdated`**.
- **`managed` and the report's `foreign` are gone.** The foreign scan looked only at names the site
claimed. The site now reads the whole store and decides what an in-game change becomes itself
(PLAN_REDESIGNS §1.5, §1.6).
Walked on both rigs, 2026-09-27/28. Oxide gave 85 permissions, every one owned (`RustCore` owns
`oxide.*`), in 148 ms over four ticks. Carbon gave 104, the 30 `adminmodule.*` unowned, in 204 ms. On
both, **`zonemanager.ignoreflag.nokits` belongs to ZoneManager**.
### 19.10 What the tally adds for chat titles
The twenty-three chat-title conditions (`docs/modules/rust/PLAN_REDESIGNS.md` §5, D172–D174) ride on
`player.tally` (rule 2: aggregates, never a frame per shot, craft or swing). Every new field is
**absent when nothing moved**, as the existing three are, so a site on an older build ignores them and a
frame from an older plugin has none:
```json
{"kind":"player.tally","type":"event","steamId":"76561198038695917","name":"whitlocktech",
"npcKills":3,"animalKills":2,"weaponKills":{"bow_hunting.entity":2,"machete.weapon":1},
"headshots":1,"bestPvpM":187.5,"bestPveM":42.1,"apcKills":1,"heliKills":1,
"crafted":{"attire":3,"weapon":1},"built":12,"repaired":4,"healed":2,"rockets":6,
"explosives":3,"missions":1}
```
| Field | Counted from | Notes |
|---|---|---|
| `animalKills` | `OnEntityDeath`, victim a `BaseNpc` | **Also** counted in `npcKills`, which keeps meaning every NPC and animal so the public column does not change mid-wipe. Human NPCs are the difference (D209) |
| `weaponKills` | every credited kill, any victim | By the **same weapon short prefab name the killfeed carries** (`WeaponPrefab`, else `Weapon`). The site classifies them into bow, melee, blade and revolver lists it keeps (§5.3), so a new Rust weapon needs no plugin release |
| `headshots` | the killing blow's `HitInfo.isHeadshot`, any victim | |
| `bestPvpM`, `bestPveM` | the killfeed's distance | **This interval's maximum, not a sum.** The site keeps the running best with `GREATEST`. PvE is NPCs and animals |
| `apcKills`, `heliKills` | `OnEntityDeath`, victim `BradleyAPC`; `PatrolHelicopter` or `CH47Helicopter` | The killing blow's player (D174). A patrol helicopter usually dies by crashing and its blow names nobody, so **the last player who hurt it within 60 s** is credited instead, recorded by `OnEntityTakeDamage` for those three types only |
| `crafted` | `OnItemCraftFinished`, by `item.info.category` lower-cased | Every category is sent; the site reads `attire` and `weapon`. Counts `item.amount`. The crafter is `ItemCrafter.owner` (the task carries none) |
| `built` | `OnEntityBuilt` placing a `BuildingBlock` | A deployable is not a structure |
| `repaired` | `OnStructureRepair` | The hook fires on every hammer hit **before** the game decides there is anything to repair, the resources for it, or no recent attack. So the health is read then and again next tick, and only a hit that raised it counts |
| `healed` | `OnHealingItemUse` on **another** player; `OnPlayerRevive` | Yourself never counts (D174). A syringe on a downed player raises both hooks for one use; it counts once. The heal's target is an `IMedicalToolTarget` in current Rust, so the bridge takes it as `object` and counts only a player |
| `rockets` | `OnRocketLaunched` | |
| `explosives` | `OnExplosiveThrown`, `OnExplosiveDropped` | A `TimedExplosive` that deals damage: a supply signal and a smoke grenade go through the same hooks and do not count |
| `missions` | `OnMissionSucceeded(mission, instance, assignee)` | Rust's own NPC missions (D173), credited to the hook's `assignee`. A failed or abandoned one raises a different hook and never counts |
**All ten hooks are `void`** (§8.7). Four of them can veto — `OnStructureRepair`, `OnHealingItemUse`,
`OnPlayerRevive`, and `OnEntityTakeDamage`, which cancels the damage — and none returns anything. All ten
are in `ExpectedHooks`, so a framework that stops raising one shows as zero in `rg.hooks`.
No sidecar change: the sidecar stores and forwards `player.tally` whole, as it does every frame.
### 19.11 A zone's options, its messages and its dome (PLAN_REDESIGNS §3)
**`world.zone` gains seven optional fields.** A zone that sends none of them is opened exactly as before.
```json
{"cmd":"world.zone","reqId":"r-4","runId":"13","key":"9c1e…","monument":"airfield_1","radius":40,
"holdMs":1800000,"name":"Arena",
"flags":["NoBuild","PvpGod"],"settings":{"radiation":10,"safezone":false},
"enterMessage":"You entered the arena.","leaveMessage":"You left the arena.",
"delivery":"chat","format":"<color=#ffb400>[Event]</color> {message}",
"dome":{"type":1,"stack":2}}
```
- **`flags`** is a list of ZoneManager flag names, at most 80. Each is checked against the flags **this
server's ZoneManager** declares, case-insensitively, and passed on as ZoneManager spells it. An unknown
one is refused **`bad-option`**, never dropped: a zone that quietly lacks the "no building" its author
chose is worse than a step that fails and says why.
- **`settings`** is an object of five allowlisted keys: `radiation` (0–500), `comfort` (0–1), `temperature`
(−100–100), `safezone` (true/false) and `permission` (1–32 of `a–z`, `0–9`, `_`; ZoneManager registers it
as `zonemanager.<name>`). Anything else is `bad-option`, and a value out of range is `bad-option` with the
range. Every other ZoneManager field (rotation, parent, size, eject spawns) stays out, because each one
changes what the bridge believes the zone is.
- Both are passed to **`CreateOrUpdateTemporaryZone` as ZoneManager's own key/value arguments** (a setting
by its key, a flag as `"<Flag>", "true"`), kept on the zone's registry entry, and passed again whenever the
bridge re-creates the zone: at a restart, a hot reload of the bridge, and a ZoneManager reload. A flag a
newer ZoneManager no longer has is ignored by ZoneManager on re-creation rather than failing the zone.
- **`enterMessage` and `leaveMessage`** (up to 256 characters each) are said **by the bridge**, never given
to ZoneManager (D193): ZoneManager says a zone's messages as popups only when its own config turns
popups on for every zone on the server. The bridge handles `OnEnterZone(zoneId, player)` and
`OnExitZone(zoneId, player)` and speaks only for zones in its registry. A zone it has just re-created says
nothing for 5 s, because ZoneManager (with the zone helper, §19.6) re-enters whoever is standing in it.
- **`delivery`** is `chat` (the default) or `popup`. **A popup where PopupNotifications is missing falls back
to chat**; the zone is not refused for it, because the moment the message is said can be days after the
step ran. **`format`** is the chat voice (§33.2 of PLAN.md), one `{message}`, used only for chat.
- **`dome`** asks ZoneDomes for a dome over the zone: `type` is ZoneDomes' own sphere type (0 Standard,
1 Red, 2 Blue, 3 Green, 4 Purple; **0 when absent**, the one full dome, D212) and `stack` 1–10 spheres (1 when
absent). The coloured types show only where they meet terrain or a structure. It is refused
**`dome-unavailable`**, with which piece is missing, unless ZoneDomes is loaded and the domes helper has
patched it and seen ZoneDomes finish starting. A dome ZoneDomes does not make takes its zone with it:
the zone is erased and the step refused.
**The dome's lifecycle is the bridge's.** It adds the dome after the zone, because ZoneDomes reads the
zone's place and radius from ZoneManager. At expiry and at `world.revert` it calls `RemoveExistingDome`
**before** erasing the zone, so a dome never outlives its zone in ZoneDomes' data file. After re-creating
zones it calls `AddNewDome` again for each zone that had one; ZoneDomes answers false for a dome it
already has, so this is safe to repeat.
**The domes helper, `RunicGatewayDomes.cs`** (D194, D168), ships beside the bridge like the zone helper.
It does two things, both by Harmony:
- A **prefix on ZoneDomes' `TranslateMessage(BasePlayer, string, string)`** skips the message when the
player is null. ZoneDomes 2.0.2's `AddNewDome` and `RemoveExistingDome` end with that message and no null
check, so a call from a plugin made the dome, saved it, and then threw (PLAN_REDESIGNS §0.5).
- A **postfix on `InitializeDomes`**, ZoneDomes' own start, raises **`OnRgDomesReady`**. ZoneDomes' start
drops every dome whose zone does not exist yet and draws every one that does. A dome added **before**
it is drawn twice, and the first set of spheres stays in the world with nothing able to remove it. So the
bridge puts domes back only once the helper says ZoneDomes has started. A helper or ZoneDomes loaded into
a running server is ready on the next tick.
It patches at load (and when ZoneDomes loads), so at a real start the patch is in before ZoneDomes'
`OnServerInitialized`. `rgd.status` prints its state.
**Hello and status.** `server.hello` gains, wherever ZoneManager is loaded:
```json
"zoneManager": { "version": "3.1.14", "flags": ["AutoLights", "AlwaysLights", "NoKits", "…"] }
```
`flags` comes from ZoneManager's own API call **`ZoneFieldListRaw()`**, less the leading field names
(`name`, `radius`, `enter_message`, …). **Plan §0.6 said only a plugin that references ZoneManager's types
could read the list; that was wrong for 3.1.14** (D211), so the bridge reads it and a server without the
zone helper still reports every flag. It is in hello rather than every status frame because it changes only
when ZoneManager does, and **the bridge sends hello again when ZoneManager, ZoneDomes, or either helper
loads or unloads**.
`integrations` on `server.status` (and so on hello) gains `zoneDomes`:
```json
"zoneDomes": { "loaded": true, "version": "2.0.2",
"helper": { "state": "patched", "version": "0.1.0" }, "ready": true }
```
`helper.state` is `patched`, `unsupported` (with `reason`), `no-zonedomes` or `missing`, as §19.6's are.
**Hooks.** `OnEnterZone`, `OnExitZone` and `OnRgDomesReady` join `rg.hooks`' list.
**The sidecar** forwards `world.zone` whole, as before; nothing in it changed.
**The website** (Module-Rust): the zone step `rust.zone.open` gains `options` (one line, `NoBuild,
NoPlayerLoot, radiation=10`, read into `flags` and `settings`), `enterMessage`, `leaveMessage`, `delivery`,
`dome` (`standard`, `red`, `blue`, `green`, `purple`) and `domeStack`. Core's step editor holds single values
only, so the flags are ticked on a new page, **Admin → Rust zone presets**, and saved by name for one server,
several, or every server (D195, D210). The step's `options` field offers the presets (option source
`rust.options.zone_presets`); **a row's value is the preset's line itself**, so picking one copies it and a
preset edited later changes no published event. The step checks the line and the dome against the server's
last hello when it is saved and in a dry run; `bad-option` and `dome-unavailable` are permanent refusals.
**Compiled on both rigs and walked without a player, 2026-09-29** (PLAN_REDESIGNS §3.4): every refusal,
ZoneManager and ZoneDomes reloads, a server restart and the forced opposite boot order (exactly one set of
spheres each time), revert and expiry removing the dome, and a dome refused without the helper. The
in-game rows (flags on a player, the messages) wait for the later in-game walk.

View File

@@ -426,7 +426,7 @@ tables carry no module prefix. (The count said "nine" over a list of ten from th
| `event_run_steps` | `run_id`, `phase`, `seq`, `action_id`, `params` JSON, `action_version`, `status`, `due_at`, `attempts`, `on_failure`, `idempotency_key`, `claimed_by`, `claim_expires_at`, `last_error`. `INDEX (status, due_at)` | The work queue, claimed with the outbox's compare-and-set. |
| `event_action_settings` | `action_id` (the primary key), `enabled`, `caps` JSON (`{dimension: perRunCap}`), `updated_by`, `updated_at`. | **The deployment's switchboard, and the whole of the permission model beyond the role.** One row per action an admin has an opinion about; **a missing row is not "disabled", it is the default for the action's risk class** — see [§K](#k--security-model). Not a grant table — nobody is named, because the role check already answered who. Rows outlive their actions, so uninstalling a module and re-installing it restores the caps the operator chose. |
| `event_run_budget` | `run_id`, `dimension`, `consumed`, `cap` **nullable**, `effective_from`. `UNIQUE (run_id, dimension)` | Consumption is incremented with a conditional update — `… SET consumed = consumed + ? WHERE run_id=? AND dimension=? AND (cap IS NULL OR consumed + ? <= cap)` — so the cap holds under concurrent steps without a transaction. **A NULL cap is uncapped and still a row**, so the console's meter counts what nothing bounds, and a *missing* row keeps its one meaning: a step spending a dimension its own run's version never priced, which is refused. `effective_from` names the action whose cap won, so a number on the meter traces back to a switch. |
| `event_run_resources` | `run_id`, `step_id` **`SET NULL`**, `owner_module`, `kind` and `ref` (both module-opaque), `payload` JSON, `lease_until` nullable, `status` `ENUM('pending','confirmed','reverting','reverted','orphaned','drifted')`, `revert_attempts`, `last_error`, optional `member_key`. `UNIQUE (owner_module, kind, ref)` among the rows core still believes are ITS — see the amendment below | **The cleanup ledger, and it holds both kinds of thing an event owns** — objects it created (`kind: 'creature'`, `ref` = a serial) and values it leased (`kind: 'override'`, `payload` = baseline + applied). `drifted` is the compare-and-set refusal; the unique index is what stops two events leasing one target. `@step` is a reserved `kind` core owns (rule 1, below); a module reporting one is refused. |
| `event_run_resources` | `run_id`, `step_id` **`SET NULL`**, `owner_module`, `kind` and `ref` (both module-opaque), `payload` JSON, `lease_until` nullable, `status` `ENUM('pending','confirmed','reverting','reverted','orphaned','drifted','expired')` (`expired` from MODULE_API 1.11.0), `revert_attempts`, `last_error`, optional `member_key`. `UNIQUE (owner_module, kind, ref)` among the rows core still believes are ITS — see the amendment below | **The cleanup ledger, and it holds both kinds of thing an event owns** — objects it created (`kind: 'creature'`, `ref` = a serial) and values it leased (`kind: 'override'`, `payload` = baseline + applied). `drifted` is the compare-and-set refusal; the unique index is what stops two events leasing one target. `@step` is a reserved `kind` core owns (rule 1, below); a module reporting one is refused. |
| `event_run_participants` | `run_id`, `user_id` nullable `SET NULL`, `member_key` module-opaque **and NOT NULL**, `score` `DECIMAL(18,4)`, `rank_at`, `joined_at`, `meta` JSON. `UNIQUE (run_id, member_key)` | Results and profile history read it. `SET NULL` not `CASCADE`, matching `engagement_sends`: a record of what happened must survive an account deletion. The unique key is what makes a retried collect step an upsert rather than a doubled leaderboard, and `rank_at` carries the suffix because `rank` is a reserved word from MariaDB 10.2 — one forgotten pair of backticks away from a syntax error in a query nothing runs until a run completes at four in the morning. **Written only from an action's success envelope** (Phase 10): core stores what a module tells it and sources nothing, because a `member_key` → account mapping is one game's. |
| `event_run_phase_gates` | `run_id`, `phase`, `kind` `ENUM('after','on')`, `after_seconds`, `trigger_id`, `conditions` JSON, `needed`, `tally`, `entered_at`, `due_at`, `last_event` JSON, `satisfied_at`, `satisfied_by`, `forced_by`. `UNIQUE (run_id, phase)`, `INDEX (trigger_id, satisfied_at)` | **What a phase is waiting for, and how far it has got** (Phase 5). The one fact in this feature that is not derivable from a row somebody already wrote: `{ on: …, count: 3 }` counts things that happen *between* two ticks, and the runner is not running when they happen. The unique key is what makes opening a gate an `INSERT IGNORE`; the index is the emit path's only query and the one index here on a hot path. |
| `event_run_log` | `run_id`, `step_id` nullable, `kind` (closed set), `phase`, `detail` JSON, `at`. | `activity_log.detail` is `TEXT` and unqueryable. "Why didn't phase 3 start?" must be a query. |
@@ -1795,6 +1795,20 @@ through a revert — a revert that finds nothing there is a SUCCESS (§L, and wh
whereas a resource the module reports missing is a thing that vanished while nobody was looking.
Those are two different sentences to the operator reading the console the morning after.
**`expired` is the third sentence** (MODULE_API 1.11.0, amended 2026-09-27 for Rust PLAN_FIXES F14,
D170, D183). Some game objects carry their own deadline down the wire and the game ends them when it
passes, without being asked again — a Rust zone the plugin erases when its time is up. Reached only
through reconcile, that looked like `orphaned`: amber, "gone", and still claimable for a revert. So a
module that hears the game end one says so with `ctx.events.expired({ kind, ref })`, and core marks the
module's `pending`, `confirmed` or `orphaned` row for that target `expired` and logs `resource.expired`.
It is **terminal and green, like `reverted`**: it releases the target (it is not one of the three that
hold it), it is not "unreverted", and the sweep never tries to give it back. A row a revert has already
claimed (`reverting`) is left to that revert, which finds nothing and succeeds. A finished run whose last
unresolved row this was goes to `cleanup_status = 'complete'`, including from `incomplete`, which the
sweep no longer scans. A run still going when its last resource expires is settled by the sweep once it
ends: finished, `pending`, and no unresolved row is `complete` — the scan that joins on an unresolved row
could not see it, and the step-2 walk's run 46 sat `pending` until it could.
---
## Versioning, and editing a live event
@@ -1998,7 +2012,7 @@ Phase 3 — "The Boss" has not started.
| What a phase is waiting for, its tally and its last related firing | `event_run_phase_gates`, served already-rendered as a run's `gates` |
| A phase opening a gate, and a gate opening — on a firing, a deadline or a human | `event_run_log`, kinds `phase.gate` and `phase.advanced` |
| Module acknowledgement, or its absence with the budget exceeded | `event_run_steps.last_error` |
| Resources created, confirmed, leased, reverted, orphaned, drifted | `event_run_resources`, plus six `event_run_log` kinds: `resource.recorded`, `resource.orphaned`, `cleanup.reverted`, `cleanup.failed`, `cleanup.swept`, `cleanup.retry`. `resource.recorded` is written at the ANSWER rather than at the placeholder, because a placeholder is a promise and the operator's question is about the world |
| Resources created, confirmed, leased, reverted, orphaned, drifted | `event_run_resources`, plus seven `event_run_log` kinds: `resource.recorded`, `resource.orphaned`, `resource.expired` (1.11.0), `cleanup.reverted`, `cleanup.failed`, `cleanup.swept`, `cleanup.retry`. `resource.recorded` is written at the ANSWER rather than at the placeholder, because a placeholder is a promise and the operator's question is about the world |
One caution carried over from the engagement retention work: the run log is high-cardinality and grows per event, so it needs a
retention sweep from the start — `engagementRetentionPrune` is the pattern, and the rule it learned is

View File

@@ -26,13 +26,23 @@ here extends the contract first, in this file, before the module is written agai
Core exports a single integer-major semver string from `server/src/modules/version.js`:
```js
const MODULE_API_VERSION = '1.10.0'
const MODULE_API_VERSION = '1.11.0'
```
The client half carries the same number (`client/src/modules/version.js`) and a test asserts the two
agree. Duplicated rather than fetched because the value has to be on `window.__rg` before the first
module chunk evaluates, which is earlier than any network round trip could answer.
**1.11.0 — `ctx.events.expired({ kind, ref })`** (`website/EVENTS.md` §L; Rust
`modules/rust/PLAN_FIXES.md` F14, D183). One addition and no removal, so minor. A game that ends
something at its own deadline — a Rust zone the plugin erases when its time is up — tells core, and core
marks the calling module's live row for that target **`expired`**: terminal like `reverted`, never taken
back at teardown, and not `orphaned`, which `reconcile` uses for a thing that vanished with nobody
asking. The owner is bound, as `reconcile`'s is; it is fire-and-forget and returns `undefined`; a
`{ kind, ref }` no run ledgered is not an error. **Module-uo is unaffected**: it declares `^1.10.0`,
calls none of this and reads no ledger status, and its frozen-manifest job, server and client suites
passed against the 1.11.0 core before the bump merged (website#209).
**1.10.0 — the event contract opens to modules: `api.registerEventActions(...)`,
`api.registerEventBudgets(...)`, `api.registerEventLeases(...)` and
`api.registerEventOptionSources(...)`** (`website/EVENTS.md` §F, `EVENTS_PLAN.md` Phases 7 and 8).
@@ -100,6 +110,11 @@ api.registerEventActions([{
// claim about a world that no longer exists.
ctx.events.reconcile()
// 1.11.0. The game ended one of this module's resources at its OWN deadline —
// the same `{ kind, ref }` the action reported when it made it. Core files it
// `expired`: terminal, and not the `orphaned` a reconcile would have said.
ctx.events.expired({ kind: 'world', ref: 'srv-a:rg-13-35875416-1' })
api.registerEventOptionSources([{
id: 'uo.options.creatures', label: 'Creatures',
async resolve() { return [{ value: 'Orc', label: 'Orc', group: 'Humanoid' }] },
@@ -352,6 +367,11 @@ branches lacks — so it is the only place `permits` is true between two values
between `admin` and `owner`, `members` or `subscribers`. `permits`, `meet` and `meetAll` are otherwise
unchanged, and so is every rule about composition narrowing rather than widening.
**1.11.0 — `ctx.events.expired`** (`website/EVENTS.md` §L, Rust PLAN_FIXES D183). One addition, so
minor; see §1.1. The resource ledger gains an `expired` status, and nothing that existed changes
meaning — `expired` joins neither the statuses that hold a target nor the ones that leave a run's
cleanup unfinished. Module-uo's `^1.10.0` still resolves and was proved against it.
**1.10.0 — the event contract** (`website/EVENTS.md` §F). Four additions, no removals and no changed
signature, so minor; `module-uo`'s `coreApi: "^1.9.0"` still resolves and it registers no actions
until `EVENTS_PLAN.md` Phase 9. `api.registerEventActions([...])`, `api.registerEventBudgets([...])`,
@@ -636,6 +656,7 @@ module-uo does not need is on the list.
| `ctx.teams.reconcile` | `({ reason }) => void`, returns at once | `model/teams/teamSync` | after a fresh account link (1.6.0) |
| `ctx.teams.activity.push` | `(items) => Promise<void>`, fire-and-forget | `model/teams/teamActivity` | the Team provider's module (1.6.0) |
| `ctx.events.emit` | `(triggerId, envelope) => void`, fire-and-forget | `utils/engagementEmit` | `module-uo`'s `utils/shardEngagement.js`, off the shard feed (1.7.0) |
| `ctx.events.expired` | `({ kind, ref }) => void`, fire-and-forget, owner bound | `events/cleanup` `expireResource` | `module-rust`'s ingest of `world.expired` (1.11.0) |
| `ctx.inbox.push` | `(userId, item) => void`, fire-and-forget | the in-app channel (live since Phase 7) | `module-uo` reaches both through `server/core.js` (1.7.0) |
**`ctx.events.emit(triggerId, envelope)`** fires an event the module DECLARED with