NPC Studio

NPC Studio is an all-in-one NPC plugin creator studio that you can use fully by the interface. No editing configs or data files! It's all done from the in-game UI!

You can create NPCs and,

• give them names
• create extensive dialogue trees
• use player and server commands from dialogue
• place them anywhere
• save them for repeated use
• and much much more.

You can view the entire documentation by clicking the docs tab. It has everything you will need to begin using NPC Studio.

Permissions
npcstudio.admin | Nobody automatically | Entire studio, editing, placements, exchange, variables and settings
npcstudio.use | Not required with default settings | Conversation access when RequireUsePermission is enabled

Commands
Every chat command below requires npcstudio.admin.

| Syntax | Behavior | Example |
|---|---|---|
| /npcstudio | Open the studio | /npcstudio |
| /npcstudio help | Show concise syntax | /npcstudio help |
| /npcstudio list | Open the profile browser | /npcstudio list |
| /npcstudio create <name> | Create a profile with a welcome node and goodbye response | /npcstudio create Harbour Guide |
| /npcstudio spawn <name/id> | Place a profile on the ground being looked at | /npcstudio spawn Harbour Guide |
| /npcstudio info | Select and identify the NPC being looked at | /npcstudio info |
| /npcstudio move | Move the looked-at or previously selected placement to the ground being looked at | Select with info, look at the destination, then /npcstudio move |
| /npcstudio rotate <degrees> | Rotate the looked-at or selected placement | /npcstudio rotate 90 |
| /npcstudio remove | Confirm deletion of the looked-at or selected placement | /npcstudio remove |
| /npcstudio clone | Place another copy of the looked-at or selected profile at the look point | /npcstudio clone |
| /npcstudio refresh | Recreate eligible saved placements | /npcstudio refresh |
| /npcstudio export <profile> <file> | Write a profile and its dialogue into the exchange folder | /npcstudio export "Harbour Guide" harbour-guide |
| /npcstudio import <file> | Import an exchange file as a disabled profile | /npcstudio import harbour-guide |

Duplicate names require the full profile ID. Exchange names exclude the .json extension and permit letters, digits, underscores and hyphens. The plugin deliberately does not register the commonly used /npc command.

npcstudio.ui <nonce> <callback> [input] and npcstudio.reply <nonce> <choice> are private player-console callbacks generated by the interface. They are not general admin/server commands; their current session, permissions or conversation range must match. Ordinary players use Rust's USE key to talk, usually E.

Configuration

The exact generated defaults are:

| Setting | Default | Valid range/type | Meaning and recommended use |
|---|---|---|---|
| Schema | 1 | 1 | Data-model compatibility marker; leave unchanged |
| RequireUsePermission | false | Boolean | Restrict conversations to npcstudio.use or studio admins; leave off for public NPCs |
| EnableEconomics | true | Boolean | Enable optional Economics calls; no dependency is installed automatically |
| EnableServerRewards | true | Boolean | Enable optional reward-point calls |
| SuspendWorldPlacementsOnWipe | true | Boolean | Suspend world-coordinate placements on a detected map change; recommended on procedural servers |
| AuditActions | true | Boolean | Record executed non-navigation actions in the plugin's action log |
| Debug | false | Boolean | Additional condition/API failure diagnostics; enable while troubleshooting |
| MaximumInteractionDistance | 6 | 1 - 15 metres | Upper bound for each profile's interaction distance; existing profiles must remain within it |
| DialogueTimeoutSeconds | 120 | 10 - 1800 seconds | Maximum duration of an open conversation, measured from opening |
| SaveIntervalSeconds | 60 | 10 - 3600 seconds | Periodic dirty-data flush; timer changes take effect on plugin reload |
| MaintenanceIntervalSeconds | 2 | 1 - 30 seconds | Spawn/schedule/range/greeting maintenance interval; timer changes take effect on plugin reload |
| PlacementRayDistance | 100 | 3 - 300 metres | Maximum editor look ray; use modest distances for accurate placement |
| MonumentSearchRadius | 200 | 10 - 1000 metres | Maximum distance from placement to the closest monument origin when anchoring |
| MaximumProfiles | 200 | 1 - 2000 | Content limit; do not lower below existing content |
| MaximumPlacements | 500 | 1 - 2000 | Placement limit, including disabled placements |
| MaximumNodesPerTree | 100 | 1 - 500 | Maximum nodes in one dialogue tree |
| MaximumResponsesPerNode | 30 | 1 - 100 | Maximum responses in one node; player choices paginate |
| MaximumRulesPerList | 30 | 1 - 100 | Maximum actions or conditions in one list |
| MaximumImportKilobytes | 512 | 1 - 4096 KiB | Maximum exchange-file size |
| DefaultHealth | 100 | 1 - 100000 | Initial and maximum health for newly created profiles |
| DefaultInteractionDistance | 3 | 1 - MaximumInteractionDistance | New-profile interaction range |
| DefaultRespawnSeconds | 60 | 1 - 86400 seconds | New-profile death-to-respawn delay |
| AccentColor | 0.19 0.48 0.96 1 | Four RGBA numbers, each 0 - 1 | Editor accent; leave default for the supplied theme |
| AllowedPlayerCommands | vehicles, info | List of command names without slash/arguments | Explicit player-chat command allowlist; add names in Settings before using other commands |
| AllowedServerCommands | Empty | List of command names without arguments | Explicit powerful console-command allowlist; enable only commands you intend NPCs to execute |

Settings are editable in the Settings tab. Missing settings receive defaults; an invalid configuration is preserved and must be corrected. Per-character content belongs in the editor rather than the global config. Commands are restricted to letters, digits, dots and underscores, starting with a letter.

Under oxide/data/NPCStudio:

• content.json: profiles, placements, dialogue trees, stable IDs, and map identity. Profile/tree/placement edits are committed together.
• runtime.json: global and profile-scoped variables and cooldowns. Created when this state first changes.
• players/STEAM_ID.json: that player's variables, cooldowns, visited nodes and playtime tracked while NPC Studio is loaded.
• exchange/NAME.json: exported profile plus tree. Exports contain no live placements or player progress.
• .bak beside overwritten files: the preceding saved version. .tmp is the temporary write used for replacement, not a file to import.

Configuration lives in oxide/config/NPCStudio.json; English messages live in oxide/lang/en/NPCStudio.json. Editor and action audit files appear under oxide/logs/NPCStudio.

Back up the whole data folder and configuration before upgrades or wipes. One rolling backup is not a historical backup system. Edit customer content in the UI. If restoring a file manually, unload only NPCStudio, copy the desired backed-up data, then load NPCStudio. Editing an active data file can be overwritten by the in-memory state. Malformed data is preserved; the plugin or affected player data fails closed instead of replacing it with empty data.

On plugin reload or server restart, non-saving live NPC entities are cleaned up and eligible placements are reconstructed. The startup cleanup scans only NPCs bearing this plugin's owner marker. Map identity is the Rust save creation timestamp. A map change preserves every reusable profile and tree. World placements are suspended by default until moved/replaced. Monument placements rematch their monument; missing or ambiguous matches remain saved but unspawned. Blueprint-only wipes do not affect NPC Studio data if the map save identity stays the same. Player progress is retained across map wipes. Cooldowns store UTC expiry timestamps.

Six walkthroughs

1. Welcome NPC

• Profiles → CREATE NPC. Set Name to Welcome Guide and Subtitle to Getting started.
• Character → Appearance → LIVE DRESSING VIEW. Add clothing or COPY MY CLOTHING; choose DONE.
• Dialogue → Nodes → Welcome. Set Text to Welcome, {player.name}! Press USE whenever you need help.
• Responses → Goodbye. Set Text to Thanks! and keep Close enabled.
• Close the studio, face clear ground, reopen /npcstudio, then Placements → PLACE AT LOOK POINT.
• Close the studio, walk within three metres and press USE while looking at the NPC.

2. Vehicle dealer

• Create Flight Instructor. Dress it with hazmatsuit.pilot in the live dressing room.
• Set the Welcome text to Ready to fly? Choose a vehicle below.
• Responses → ADD RESPONSE. Set Text to Show me the vehicles. and keep Close enabled.
• Open its Actions → ADD ACT. Choose Action → Run a player chat command. Enter /vehicles in the command field and press Enter.
• /vehicles is already allowed. Place the NPC and test the response. This opens the existing vehicle plugin, which remains responsible for spawning, ownership, fuel and passive behavior.
• For a second response, add Show server information. with the player command /info. Put each menu-opening command on its own response.

3. Bring 500 scrap for a reward

• Create Supply Officer. Welcome text: Bring me 500 scrap and I will give you 1,000 wood.
• Add a response Trade 500 scrap for 1,000 wood.
• Response Conditions → Rules → ADD CONDITION. Type Item, Item scrap, Skin 0, Compare Greater Or Equal, Amount 500.
• Response Actions → ADD ACT. Action → Trade items for a reward. Item scrap, Amount 500, Skin 0, Reward Item wood, Reward Amount 1000, Reward Skin 0.
• Keep Close enabled. Place and test with 499 and 500 scrap, then with insufficient empty main-inventory slots. Failed delivery restores the escrowed cost.
• To make the trade periodic, add a Player Cooldown Ready condition named supplies.trade, then a Start Cooldown action with that name and Duration 3600 after the trade.

4. VIP dialogue option

• Create a guide and add a response Show me the VIP service.
• Response Conditions → Rules → ADD CONDITION. Type Permission. Key is the exact permission registered by your VIP/service plugin, for example its actual VIP-use permission.
• Leave Invert and Require Any disabled. Add the desired permitted action or select a target node.
• Grant that existing permission to your test player through Oxide, test the choice, then revoke it and confirm the choice disappears. NPC Studio does not invent or register a third-party VIP permission.

5. A character who remembers you

• Create Billy. Keep Welcome as the root, with text Hello, {player.name}.
• Add nodes named First meeting and Old friend. Set their texts to Nice to meet you! and Good to see you again, {player.name}.
• Welcome → Responses: add Introduce yourself. Set Close off and Target Node First meeting. Add a Variable condition: Scope Player, Key billy.met, Value Type Boolean, Value true, Compare Equal, Invert on.
• First meeting → On Open: add Set Variable, Scope Player, variable name billy.met, Value Type Boolean, Value true. Add a closing goodbye response.
• Welcome → Responses: add Say hello again. Set Close off and Target Node Old friend. Add the same Variable equality condition with Invert off. Add a closing response in Old friend.
• Place and interact twice. Use Variables → Player → delete billy.met to retest the first meeting. A missing variable fails equality, so its inverted condition allows the introduction.

6. Monument-relative character

• Create and save a character such as Harbour Guide.
• Stand near the intended monument and look at suitable ground within Monument Search Radius of its origin.
• Placements → PLACE RELATIVE TO MONUMENT. Open MANAGE and verify its mode through /npcstudio info while looking at it.
• Move/rotate as needed; both changes remain relative to the monument.
• Leave Allow Monument Ordinal After Wipe disabled for strict matching. On a future map with one matching monument, the placement relocates automatically. With several matching instances, inspect the warning and move/re-anchor it or explicitly opt into ordinal matching.
• Test a map wipe only on a separate test server.