# 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.