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