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 §5 and stage 3, and installing RunicNPC is in 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.