wtclaude
eec8e6e698
- runicnpc/PLAN.md: 9b built and measured; D315 (the performance check records today's cost, the warning says it, idle overhead is runicnpc-rust#13) and D316 (the picker keeps Rust's own; a step on a server without RunicNPC is refused on save). - runicnpc/INSTALL.md (new): requirements, the installer and egg, by hand without Runic Gateway, Kits and ZoneManager reported not installed, its files, the cost warning with stage 9's numbers, caps, and after a Rust update. - runicnpc/COMMANDS.md (new): every /rnpc verb and console command with its permission, options and defaults, and how to read rnpc.status. - rust-link/INSTALL.md: RunicNPC is required; the installer refuses a bundle without it and doctor fails. (The plan named modules/rust/OPERATING.md, which is a verbatim uMod mirror; this is the operator guide that lists Kits.) - rust-link/PROTOCOL.md: §19.16, every NPC placement needs RunicNPC; no message changes shape. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
110 lines
7.2 KiB
Markdown
110 lines
7.2 KiB
Markdown
# RunicNPC — command reference
|
|
|
|
Every command RunicNPC answers, with the permission it needs. This page is the reference; how the commands came
|
|
to be is in [PLAN.md](PLAN.md) §5 and stage 3, and installing RunicNPC is in [INSTALL.md](INSTALL.md).
|
|
|
|
## How commands are reached
|
|
|
|
- **In chat:** `/rnpc <verb> ...`. `/rnpc` alone lists the verbs you are allowed to use.
|
|
- **In a console:** `rnpc.<verb> ...`, in a player's F1 console, the server console or RCON. The same code answers
|
|
both, with the same permissions.
|
|
- **Console-only verbs** (`profile`, `faction`) answer only in a console. In chat they tell you to open F1.
|
|
- **The server console has every permission.** It has no position, so `place`, `here` and `path point` take
|
|
`at=x,y,z` (and `yaw=`) there. In game those two options are refused.
|
|
|
|
## Permissions
|
|
|
|
| Permission | Grants |
|
|
|---|---|
|
|
| `runicnpc.place` | Placing, removing, renaming and inspecting NPCs, recording routes, and `follow`. |
|
|
| `runicnpc.admin` | Everything, `runicnpc.place` included: teleporting, respawning, clearing an owner, and the console-only verbs. |
|
|
|
|
On a Runic Gateway server, both permissions show in Admin → Rust → Permissions like any plugin's, and the site
|
|
grants them there.
|
|
|
|
## Placements
|
|
|
|
A **placement** is a spot where a profile's NPCs stand and come back after they die. It is saved on the server
|
|
(`data/RunicNPC/placements.json`) and survives restarts. Placements made in game are named after their profile and
|
|
a number (`bandit-1`) and can be renamed.
|
|
|
|
| Command | Does | Permission |
|
|
|---|---|---|
|
|
| `/rnpc place <profile> [options]` | Places the profile's NPCs where you are looking, and answers with the placement's name and the cost warning. | `runicnpc.place` |
|
|
| `/rnpc here <profile> [options]` | The same, where you stand. | `runicnpc.place` |
|
|
| `/rnpc remove [placement]` | Removes a placement and its NPCs: the one you name, or the one the NPC you are looking at belongs to. | `runicnpc.place` |
|
|
| `/rnpc rename <placement> <new name>` | Renames a placement. Its live NPCs stay where they are. | `runicnpc.place` |
|
|
| `/rnpc near [radius]` | Lists the placements and live NPCs around you, with distances and any note (waiting, off the navmesh). | `runicnpc.place` |
|
|
| `/rnpc info` | The NPC you are looking at: name, profile, placement or owner, health, state and target. | `runicnpc.place` |
|
|
| `/rnpc profiles` | The profiles this server has, and any it refuses with the reason. | `runicnpc.place` |
|
|
| `/rnpc follow <placement> <player\|me\|off>` | The placement's live NPCs escort a player. They fight whoever attacks that player, and walk back to their spot if the player dies or leaves. `off` ends it. | `runicnpc.place` |
|
|
| `/rnpc tp <placement>` | Teleports you to a placement. | `runicnpc.admin` |
|
|
| `/rnpc respawn <placement\|all>` | Respawns a placement's NPCs now, or every placement's. | `runicnpc.admin` |
|
|
| `/rnpc clear <owner>` | Removes every NPC an owner has, for example a stuck event run (`run:42`) or another plugin (`plugin:Name`). | `runicnpc.admin` |
|
|
|
|
**Options for `place` and `here`,** in any order:
|
|
|
|
| Option | Means | Default |
|
|
|---|---|---|
|
|
| `count=<n>` | How many NPCs stand there. | 1 |
|
|
| `respawn=<seconds>` | How long after a death before the NPC comes back. | 300 |
|
|
| `mode=each\|group` | `each`: every NPC comes back on its own timer. `group`: none comes back until all are dead, then all at once. | `each` |
|
|
| `move=wander\|monument\|route:<name>` | How the NPCs move: wander around the spot, roam the monument they stand in, or walk a recorded route. | the profile's |
|
|
| `radius=<m>` | How far a wanderer strays. | the profile's |
|
|
| `tether=<zone>` | A ZoneManager zone the NPCs never leave. Needs ZoneManager. | none |
|
|
|
|
**Every placement is checked against Rust's navmesh.** A roamer must stand on it. Only a sentry may stand off it.
|
|
On a player-built floor the placement is made with a warning: if the floor is destroyed, the NPCs fall back to the
|
|
nearest navmesh, and return to their spot once it is rebuilt.
|
|
|
|
## Routes
|
|
|
|
A route is a line of points an NPC walks. It is recorded in game where you walk, one point at a time.
|
|
|
|
| Command | Does | Permission |
|
|
|---|---|---|
|
|
| `/rnpc path record <name>` | Starts recording a route. | `runicnpc.place` |
|
|
| `/rnpc path point` | Adds the spot you stand on. A point the previous one has no walkable path to is refused. | `runicnpc.place` |
|
|
| `/rnpc path undo` | Drops the last point. | `runicnpc.place` |
|
|
| `/rnpc path save [loop\|back]` | Saves the route: `loop` walks back to the first point and round again, `back` walks it back and forth. | `runicnpc.place` |
|
|
| `/rnpc path cancel` | Abandons the recording. | `runicnpc.place` |
|
|
| `/rnpc path list` | The saved routes. | `runicnpc.place` |
|
|
| `/rnpc path delete <name>` | Deletes a route. A placement that walks it waits until a route of that name exists again. | `runicnpc.place` |
|
|
|
|
A recording is kept in memory only: a reload of RunicNPC discards it.
|
|
|
|
## Console only
|
|
|
|
| Command | Does | Permission |
|
|
|---|---|---|
|
|
| `rnpc.profile list` | The same as `/rnpc profiles`. | `runicnpc.admin` |
|
|
| `rnpc.profile show <name>` | A profile in full, as JSON, and why it is refused if it is. | `runicnpc.admin` |
|
|
| `rnpc.profile create <name> [from=<profile>]` | A new profile, empty or copied from another. | `runicnpc.admin` |
|
|
| `rnpc.profile set <name> <field> <value>` | Sets one field of a profile. | `runicnpc.admin` |
|
|
| `rnpc.profile delete <name>` | Deletes a profile. Placements that use it wait until a profile of that name exists again. | `runicnpc.admin` |
|
|
| `rnpc.faction list` | The faction table: which factions fight, ignore or help each other. | `runicnpc.admin` |
|
|
| `rnpc.faction set <a> <b> hostile\|neutral\|allied` | Sets one pair, both ways. | `runicnpc.admin` |
|
|
| `rnpc.faction clear <a> <b>` | Removes a pair. | `runicnpc.admin` |
|
|
| `rnpc.status` | The version and API, the hooks that have fired, the navmesh, the swap's field list, NPC counts by owner, profiles, placements, routes, what fighting costs a think, the caps, and the cost warning. | server console, RCON, or an admin's F1 |
|
|
| `rnpc.reload` | Re-reads profiles and routes after a hand edit of their files. | server console, RCON, or an admin's F1 |
|
|
| `rnpc.help` | The same list as `/rnpc` alone. | anyone; it lists only what they may use |
|
|
|
|
**On a Runic Gateway server the website manages the profiles and the faction table** (Admin → Rust → NPC
|
|
profiles). There, `rnpc.profile create|set|delete` and `rnpc.faction set|clear` are refused with "managed by its
|
|
website", and `show` and `list` still answer. On a server without a website they are how profiles are made.
|
|
|
|
## Reading `rnpc.status`
|
|
|
|
```
|
|
RunicNPC 1.0.0 api=6 hooks=12 fired=12 silent=0
|
|
framework=oxide navmesh=ready swap fields: npc=55/55 brain=32/32 missing=- added=-
|
|
npcs=14 awake=9 goingHome=0 asleep=5 owners: placement:bandit-1=3 run:42=11
|
|
```
|
|
|
|
- **`silent`** names a hook that has never fired. After a Rust or framework update, a hook that stays silent is the
|
|
first sign it was renamed: neither framework reports a hook that matches nothing.
|
|
- **`navmesh=building`** after a Rust update means Rust is still building the map's navmesh (about ten minutes on a
|
|
large map). Placements wait for it.
|
|
- **`swap fields`**: `missing` or `added` other than `-` means Rust's scientist has changed since this RunicNPC was
|
|
released. Update RunicNPC.
|