Compare commits
36 Commits
docs/rust-
...
docs/runic
| Author | SHA1 | Date | |
|---|---|---|---|
| 0324e3e626 | |||
| e3ae1905cb | |||
| 23c2a5a5cf | |||
| ced4755ebb | |||
| 216bbf9c54 | |||
| aec01342d5 | |||
| 97be4fb5ab | |||
| 71ab0c01af | |||
| d7b178fb8b | |||
| 3bd7a22bc6 | |||
| 637a11326e | |||
| 75a45b51a1 | |||
| 6ed4021c12 | |||
| 381d8ee5b6 | |||
| baef8f27eb | |||
| 4056e5a14d | |||
| 7f9026c9e7 | |||
| e8f0ff2407 | |||
| e3c5d7128c | |||
| 18a4a561e3 | |||
| 664d2b2144 | |||
| a34b5fdbf0 | |||
| 6684ea5c60 | |||
| 5328ff35b5 | |||
| 52658ce2c1 | |||
| 4c996e270f | |||
| 23ce47c6ad | |||
| a9981f59bc | |||
| fa53526079 | |||
| a430666f94 | |||
| 180d6a85d9 | |||
| 1891f4f6fd | |||
| 9aba725ca2 | |||
| 383f3bdbe5 | |||
| a199823513 | |||
| 1a7f52743f |
11
README.md
11
README.md
@@ -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 |
|
||||
|---|---|
|
||||
|
||||
@@ -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).
|
||||
|
||||
1171
modules/rust/PLAN_REDESIGNS.md
Normal file
1171
modules/rust/PLAN_REDESIGNS.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -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
653
runicnpc/PLAN.md
Normal 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.**
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user