RunicGateway/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(runicnpc): stage 5 built, tested and walked; API 4; protocol 13 §19.13

Browse Source 
- runicnpc/PLAN.md: stage 5 as built, what the build found that the spike
  did not (Rust's CanSeeTarget is no line of sight for an NPC target; a
  destroyed escort target compares equal to null; a rocket's line of
  sight), the harness results on both rigs, and the site walk;
- runicnpc/API.md: API 4 (the faction table, escort, ally, tether, the
  profile's stage 5 fields, a placement's tether, OnRunicNpcEscortEnded,
  the new rows of RunicNpc_List, rnpc.faction, /rnpc follow, tether=);
- rust-link/PROTOCOL.md §19.13: the faction table on npc.profiles and
  npc.profiles.set, world.place's escort, ally and tether, the three new
  world.error reasons; the bridge needs RunicNPC API 4. Joins protocol 13
  (D253).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
This commit is contained in:
claude
2026-10-05 01:16:34 -05:00
parent eb729f7dd4
commit 8ef7da034f
3 changed files with 209 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
runicnpc/API.md
View File

@@ -1,9 +1,12 @@
# RunicNPC — the API
**API version 3** (RunicNPC stage 4, 2026-09-30). This is the reference for other plugins. Why it has this
shape is in [PLAN.md](PLAN.md) §4 and the decisions D221–D238 and D249. **API 3 added** `RunicNpc_AddPlacement`,
`RunicNpc_RenamePlacement`, `RunicNpc_RespawnPlacement` and the hook `OnRunicNpcPlacementChanged`, for a
website that lists, edits and creates placements (PLAN.md stage 4); nothing of API 2 changed.
**API version 4** (RunicNPC stage 5, 2026-10-01). This is the reference for other plugins. Why it has this
shape is in [PLAN.md](PLAN.md) §4 and the decisions D221–D238, D249 and D253–D272. **API 4 added** the faction
table (`RunicNpc_Factions`, `RunicNpc_SetFactions`), orders for one NPC (`RunicNpc_Escort`, `RunicNpc_Ally`,
`RunicNpc_Tether`), the hook `OnRunicNpcEscortEnded`, the profile's stage 5 fields, a placement's `tether`, and
more in `RunicNpc_List` (PLAN.md stage 5). Nothing of API 3 changed shape. **API 3 added**
`RunicNpc_AddPlacement`, `RunicNpc_RenamePlacement`, `RunicNpc_RespawnPlacement` and the hook
`OnRunicNpcPlacementChanged` (stage 4).
RunicNPC is called by name through `Call`, like any Oxide or Carbon plugin API. Every call is prefixed
`RunicNpc_`, so no hook of another plugin is ever matched by accident. Every call is a non-public method, which is
@@ -13,7 +16,7 @@ what Oxide's `Call` reaches by name (PLAN.md §1.2).
[PluginReference] private Plugin RunicNPC;
int api = RunicNPC?.Call<int>("RunicNpc_ApiVersion") ?? 0;
if (api < 3) { /* too old for this caller: say so */ }
if (api < 4) { /* too old for this caller: say so */ }
BasePlayer npc = RunicNPC.Call("RunicNpc_Spawn", position, "warden", "plugin:MyPlugin", null) as BasePlayer;
```
@@ -43,7 +46,7 @@ Every NPC has an owner, and the owner decides its lifetime (PLAN.md §2).
### `RunicNpc_ApiVersion()` → `int`
The API version: `3`.
The API version: `4`.
### `RunicNpc_Spawn(Vector3 at, string profile, string owner, JObject overrides)` → `BasePlayer`
@@ -85,11 +88,20 @@ The live NPCs of `owner`; null lists them all. Each has:
| `state` | `string` | Rust's AI state: `Idle`, `Roam`, `Chase`, `Combat` and so on. |
| `leashes` | `int` | How many times it has given up a chase at its chase range. |
| `regrounded` | `int` | How many times its ground went from under it and it was put on the nearest navmesh (D239). |
| `faction` | `string` | API 4. Its faction, or `profile:<name>` when its profile has none (D256). |
| `target` | `string` | API 4. The prefab of the NPC, animal or turret it is fighting itself, or null (players are Rust's design's). |
| `engaged` | `bool` | API 4. Whether it is fighting that target now (Rust's design fights players first). |
| `escort` | `string` | API 4. Whom it escorts: a player's Steam id, or an entity's prefab; null for none. |
| `ally` | `string` | API 4. `clan:<id>`, `team:<id>` or `player:<steam id>`, or null. |
| `tether` | `string` | API 4. The ZoneManager zone it is held in, or null. |
| `shotsMarked` | `int` | API 4. Shots it made at an NPC target (each marks the target `Horror` for that shot only). |
| `kitUsed` | `object` | API 4. `heals`, `throws`, `rockets` and `meleeHits`: the kit's extras it has used (D260). |
### `RunicNpc_Profiles()` → `JObject`
`{"managed": bool, "profiles": {name: profile, …}, "refused": {name: reason, …}}`. A refused profile is kept in
the file but never spawns (a kit the server lacks, for example).
`{"managed": bool, "profiles": {name: profile, …}, "factions": [pair, …], "refused": {name: reason, …}}`. A
refused profile is kept in the file but never spawns (a kit the server lacks, for example). `factions` is the
faction table (API 4).
### `RunicNpc_SetProfiles(JObject all)` → `Dictionary<string, string>`
@@ -165,6 +177,40 @@ Whether `entity` is one of RunicNPC's NPCs.
Its profile's name, or null.
### `RunicNpc_Factions()` → `JArray`
API 4. The faction table (D254): `[{"a": "bandits", "b": "guards", "relation": "hostile"}, …]`, one row per pair,
both ways (D268). A pair not listed is neutral, and a faction is always allied to itself.
### `RunicNpc_SetFactions(JArray pairs)` → `string`
API 4. Replaces the faction table, as a site does with every profile push, and **marks the server managed**
(D221). Null on success; otherwise the first problem, and the old table is kept. Refused: a pair of one faction
with itself, a pair of `scientists` and `animals` (RunicNPC does not change how Rust's NPCs treat each other), a
relation other than `hostile`, `neutral` or `allied`, and a pair given twice in either order.
### `RunicNpc_Escort(ulong netId, BaseEntity target)` → `string`
API 4 (D258, D269). One of ours escorts `target`: a player, or any other entity (a crate it guards, a vehicle).
It keeps within a few metres, never targets it, and fights whoever damages it. **When the target dies, is
destroyed, or (a player) leaves the server, it walks back to its spot**, carries on as its profile does there, and
`OnRunicNpcEscortEnded` is raised. A null `target` stops it. Null on success; refused for a sentry (it never
moves) and for a player who is not on the server.
### `RunicNpc_Ally(ulong netId, string kind, string id)` → `string`
API 4 (D257, D270). One of ours is allied to `clan` (the game's own clan id), `team` (a Rust team id), or
`player` (a Steam id: that player, and their team if they have one), or to nobody with `none`. It **never
targets** the ally's people, and **defends them and what they own** (building blocks, doors, deployables): whoever
damages one of them within its leash is fought. Rust's own clans and teams only. Null on success; refused for a
clan or team the server does not have.
### `RunicNpc_Tether(ulong netId, string zone)` → `string`
API 4 (D272). Holds one of ours inside a ZoneManager zone: it never chases or wanders out, and if it ends up
outside (pushed, or the zone moved) it forgets the fight and walks home. Null frees it. Refused for a sentry, on a
server without ZoneManager, for a zone the server does not have, and for a zone that does not hold the NPC.
### `RunicNpc_CostWarning(int adding)` → `string`
The cost warning (D227) for the NPCs the server plans, plus `adding`. It is built from stage 1's measurements
@@ -184,6 +230,7 @@ All are called on every plugin, and **none of them answers**: a return value is
| `OnRunicNpcDied(BasePlayer npc, string profile, string owner, HitInfo info, Dictionary<ulong, float> contributors)` | When it dies. `contributors` maps each player's Steam id to the health that player took from it, the killing blow included, after Rust's protection. It never adds up to more than its health. |
| `OnRunicNpcDespawned(BasePlayer npc, string owner)` | When it is removed without dying. Not raised as RunicNPC itself unloads. |
| `OnRunicNpcPlacementChanged(string id, string change, string previous)` | API 3. Whenever a placement is set, removed or renamed, through the API or in game. `change` is `set`, `removed` or `renamed`; `previous` is the old name for a rename and null otherwise. |
| `OnRunicNpcEscortEnded(BasePlayer npc, string profile, string owner)` | API 4. Whom it escorted died, was destroyed or left the server, and it is walking back to its spot (D269). |
---
@@ -205,7 +252,14 @@ All are called on every plugin, and **none of them answers**: a return value is
"ranges": { "sense": 30, "loseTarget": 40, "chase": 40, "attack": 30 },
"visionCone": -0.8,
"sleepDistance": 160,
"healthThresholds": [0.5]
"healthThresholds": [0.5],
"faction": "bandits",
"relations": { "scientists": "hostile" },
"alertRadius": 40,
"turrets": "default",
"hurtByPlayers": true,
"hurtsPlayers": true,
"kitUse": { "heal": false, "grenades": false, "melee": false, "rockets": false, "flamethrower": false }
}
```
@@ -214,7 +268,7 @@ All are called on every plugin, and **none of them answers**: a return value is
| `names` | at least one | One is picked for each NPC. |
| `kits` | at least one; each must exist in Kits | One is picked for each NPC, and it is equipped with it (D217). |
| `prefab` | a Rust `scientistnpc_*` prefab that is a plain scientist | What it is built from. |
| `role` | `roamer` or `sentry` | A sentry never moves, and may stand off the navmesh. |
| `role` | `roamer`, `sentry` or `guard` | A sentry never moves, and may stand off the navmesh. A guard (API 4) holds its spot facing the way it was placed, chases within its chase range, and walks back. |
| `movement.mode` | `wander`, `monument` or `route:<name>` | D233. A placement may override it. |
| `movement.radius` | above 0 for `wander` | How far from home it wanders. |
| `health` | above 0 | Its health, and its maximum. |
@@ -228,6 +282,17 @@ All are called on every plugin, and **none of them answers**: a return value is
| `visionCone` | −1 to 1 | Rust's vision cone. |
| `sleepDistance` | 0 or more | D235: with no player this close it walks home, then sleeps. 0: it never sleeps. |
| `healthThresholds` | fractions between 0 and 1 | Where `OnRunicNpcHealth` is raised. |
| `faction` | API 4. null, or 1–40 of a-z, 0-9, _ and -, not `scientists` or `animals` | D254. Profiles of one faction are allies. With none, its allies are its own profile's NPCs (D256). |
| `relations` | API 4. keys: a faction, `scientists`, `animals` or `profile:<name>`; values `hostile`, `neutral` or `allied` | Its own exceptions, which win over the faction table (D254). **A profile with no faction settings fights players only** (D255). |
| `alertRadius` | API 4. 0 or more; default 40 | D256. Allies this close learn whoever attacked one of them, seen or not. 0 is off. |
| `turrets` | API 4. `default`, `ignore` or `always` | D259, D264, D267. `default`: as Rust's scientists (player turrets shoot it, safe-zone sentries do not). `ignore`: no turret targets it. `always`: Outpost's and Bandit Camp's sentries too, through a Harmony patch that answers for these NPCs only. It shoots back at a turret that shoots it. |
| `hurtByPlayers`, `hurtsPlayers` | API 4. true or false; default true | D261, D271. Off makes it unkillable by players, or harmless to them. RunicNPC enforces both itself, and answers TruePVE's and NextGenPVE's `CanEntityTakeDamage` the same way. Turrets, fire and other NPCs are not affected. |
| `kitUse` | API 4. `heal`, `grenades`, `melee`, `rockets`, `flamethrower`, each true or false | D260. The kit's extras it uses, each only if true and each used up from its inventory. The main weapon (the belt's first slot) is always used and never runs out (D265). |
**Whom it fights besides players** is its own sensing (stage 5): only the factions it is hostile to, within its
sense range of itself **and its chase range of its spot** (D263), so it never walks into a monument to look for
scientists. Rust's scientists never fight back (Rust's own rule); they take cover. Whoever shoots one of ours, it
fights back, whatever the table says (D268).
### A placement
@@ -247,6 +312,9 @@ All are called on every plugin, and **none of them answers**: a return value is
- `respawn` is in seconds, at least 1. `respawnMode` is `each` (every NPC returns `respawn` after its own death)
or `group` (none returns until all are dead, then all return together) (D236).
- `movement` is optional and overrides the profile's.
- `tether` (API 4) is optional: a ZoneManager zone its NPCs never leave (D272). Setting a placement with a tether
the server does not have, or one that does not hold the spot, is refused; a placement whose zone later goes waits,
as one whose profile has gone does (D237).
### A route
@@ -261,7 +329,7 @@ route is walked back and forth. An NPC joins the route at its nearest point.
## Files and config
- `data/RunicNPC/profiles.json` (`managed` and `profiles`), `placements.json` and `routes.json`, under `oxide/`
- `data/RunicNPC/profiles.json` (`managed`, `profiles` and, from API 4, `factions`), `placements.json` and `routes.json`, under `oxide/`
or `carbon/`. On a standalone server profiles are edited in the file, then `rnpc.reload` reads them again. On a
managed one the site pushes them.
- `config/RunicNPC.json`:
@@ -269,4 +337,10 @@ route is walked back and forth. An NPC joins the route at its nearest point.
sets it** (D227).
- `spawnBudgetMs`: how many milliseconds of each server frame placements may spend spawning. The default is 8.
- `rnpc.status` at the console reports the swap's field check, the NPCs by owner and rest, profiles refused,
placements waiting, the caps, and the cost warning.
placements waiting, the caps, and the cost warning; from API 4 also the faction pairs, the scientists and animals
it tracks, how many of ours are fighting an NPC, the alarms and defences raised, what its own fight costs a
think, and whether the sentries are patched (`turrets: always`).
- `rnpc.faction list | set <a> <b> hostile|neutral|allied | clear <a> <b>` (console) edits the faction table on a
standalone server; refused while a site manages it. `/rnpc follow <placement> <player|me|off>` makes a
placement's live NPCs escort a player, for trying it out (in memory only: a respawn or reload ends it).
`/rnpc place … tether=<zone>` holds a placement inside a zone.