docs/runicnpc/COMMANDS.md

# 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, a metre in front of you and facing you. If something is in the way, or there is no ground or navmesh there, it stands where you do and the reply says so. Like `place`, it makes a placement that respawns until you remove it. | `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.