Introduction to NPCs

Intermediate40-60 minutesWindowsUnturned ServerNotepad++

NPCs are the gateway to authored gameplay experiences in Unturned™. A fully functional NPC encounter can present dialogue, start quests, open vendor inventories, reward the player with items and currency, and remember the player's progress across sessions, all without a single line of compiled code. The system is entirely data-driven: every NPC behavior, conversation branch, quest objective, and vendor price is defined in plain-text .dat files that the engine reads at load time. Modders who understand the architecture that connects these files can author story-driven content, roleplay encounters, and progression systems that match or exceed the depth of the vanilla quest lines.

This article is the architectural introduction to the Unturned™ NPC system. It establishes how the four asset layers, NPC character assets, Dialogue assets, Quest assets, and Vendor assets, relate to each other, what each layer is responsible for, and how the layers connect through GUID and ID references. The article also documents the NPC character asset in detail, including the clothing slot system that accepts a mixture of numeric item IDs and GUID references, the pose and equipment system, the seasonal outfit override mechanism, and the localization features available to NPC dialogue text. This is the foundation article for the server-config section of the 57 Studios™ Modding Knowledge Base, and it is the recommended starting point before reading the per-type reference articles that follow.

57 Studios™ has validated every field and behavior documented in this article against Unturned™ version 3.x, using the Horizon Life RP server as the primary testing context and the Smartly Dressed Games modding documentation as the authoritative source. Fields and behaviors that are not documented in the official source are noted where the cohort has validated them through empirical testing.

Documentation source: This article references the official Smartly Dressed Games modding documentation for field definitions and game behavior. Community-validated notes are marked where the official documentation is silent on a detail or where the cohort has discovered behavior through empirical testing on the Horizon Life RP server.

Who this article is for

This article is written for Unturned™ server operators and mod authors who want to add interactive NPCs to their server or Workshop mod. If you are new to Unturned™ modding, start with Project Folder Structure and GUIDs and How to Install Notepad++ before returning here. If you have already authored item mods (guns, clothing, melee weapons) and are comfortable with .dat authoring, GUID generation, and the master bundle pipeline, this article provides everything you need to understand the NPC system architecture before diving into per-type reference articles.

What you'll learn

• How Unturned's NPC system organizes into four distinct asset layers: NPC character, Dialogue, Quest, and Vendor
• How the four layers connect through GUID and ID references to form a complete NPC encounter
• The NPC character asset's complete property set: clothing slots, appearance, pose, equipped items, and seasonal overrides
• The documented mixed clothing-reference system: when to use numeric item IDs and when to use GUIDs for NPC clothing
• How NPC pose configuration affects character stance, head position, and item display
• The localization features available to NPC dialogue text: colored text, name substitution, line breaks, and timed pauses
• The NPC condition system at a high level, and where to find the complete conditions reference
• How to place NPCs in a map and how NPC placement differs from spawning items at runtime

NPC system architecture

The Unturned™ NPC system is built on four distinct asset types, each defined in its own .dat file with its own GUID. The layers connect through direct GUID and ID references, forming a directed graph that the engine traverses at runtime in response to player interaction.

The four layers are:

1. NPC Character Asset, the visible character that the player interacts with. Defines appearance (clothing, face, hair, skin color), pose (stance, equipment carried, head offset), and the reference to the Dialogue asset that opens when the player presses the interact key. The NPC asset is the entry point: it is placed in the world by the level editor, and every NPC encounter begins when the player walks up to the character and presses the interact key.

2. Dialogue Asset, the conversation tree. Defines one conversation node containing one or more messages (text the NPC displays to the player) and one or more responses (choices the player can select). Each response can advance to another Dialogue node, start a Quest, open a Vendor, play an effect, or close the dialogue window. Dialogue nodes can show different messages and responses depending on quest flag conditions, allowing a single NPC to have different conversations with different players depending on their quest progress.

3. Quest Asset, the objective system. Defines what the player must do (conditions), when the quest is considered complete (completion trigger), and what the player receives when it completes (rewards). Quests can require the player to kill a number of zombies, visit a location, deliver items, or meet flag-based conditions. Quest completion sets quest flags that persist in the player's save file, which Dialogue assets then read to show progress-aware conversation text.

4. Vendor Asset, the trading interface. Defines what items the NPC will buy from the player and what items the NPC will sell to the player, including per-item costs in the configured currency. Vendors can set conditions on individual buying and selling slots, so that specific items are only available for purchase after a quest flag is set. The vendor interface is opened by a Dialogue response that references the Vendor asset's ID.

As shown in the flowchart above, the NPC system is a directed graph with the NPC asset as the entry point and the player's dialogue choices as the branching mechanism. Quest flags are the system's memory: they persist across sessions and allow the dialogue system to present different text depending on what the player has already accomplished.

The relationship between the layers

The four layers are authored independently but connected at runtime through reference fields. The critical reference chains are:

From	Field	Points to	Purpose
NPC Asset	Dialogue (GUID)	Dialogue Asset GUID	Opens this dialogue on interact
Dialogue Asset	Response_N_Dialogue (GUID)	Dialogue Asset GUID	Advances to another dialogue node
Dialogue Asset	Response_N_Quest (uint16)	Quest Asset ID	Starts this quest on response select
Dialogue Asset	Response_N_Vendor (uint16)	Vendor Asset ID	Opens this vendor on response select
Vendor Asset	Currency (GUID)	Currency Asset GUID	Uses this custom currency instead of experience

Each reference chain is a hard requirement at runtime. If a referenced GUID or ID does not resolve to a loaded asset, the reference silently fails, the dialogue response does nothing, the quest does not start, or the vendor does not open. The absence of a visible error message for broken references is one of the documented frustrations of NPC authoring, which is why the cohort-recommended workflow includes a validation pass that tests every reference chain before publishing.

Comparison with the item asset system

Modders familiar with the item asset system will recognize structural similarities and important differences. Like item assets, NPC, Dialogue, Quest, and Vendor assets each have a unique GUID, a numeric ID, and a folder containing a .dat file and English.dat localization. Unlike item assets, these assets do not require a Unity prefab or a master bundle, they are pure data definitions with no 3D model component. The NPC character asset uses the game's built-in human character model, and the clothing items it wears are references to existing item assets that supply their own models.

The GUID discipline that applies to item assets applies identically to NPC system assets. Every asset must have a unique GUID. Never reuse a GUID from another asset, even one in a different category. A GUID collision between a Quest asset and a Dialogue asset will cause one or both to fail to load, and the failure will produce no visible error message, the NPC simply will not work.

The sequence diagram above traces a complete NPC interaction from the interact key press through dialogue display, player response, and the branching outcomes. The engine acts as the dispatcher, reading reference fields from each asset and loading the next asset in the chain. The quest flags store is the only persistent state in the system, everything else is stateless configuration read at the moment of interaction.

The NPC character asset

The NPC character asset is the Type NPC .dat file that defines a single non-player character. It controls every visible aspect of the character: what clothing they wear, what their face and hair look like, how they stand, what item they hold in their hands, and what dialogue opens when the player interacts with them.

Identity fields

Every NPC asset begins with identity fields that identify the asset to the engine and to other assets that reference it.

Field	Type	Required	Example	Purpose
GUID	uint128 hex	Yes	a1b2c3d4e5f6478aab1c2d3e4f5a6b7c	128-bit globally unique identifier. Generate a new GUID for every NPC.
Type	enum	Yes	NPC	Must be NPC for character assets.
ID	uint16	Yes	50100	Unique numeric ID. Use IDs in the 50000+ range to avoid collision with vanilla and established community mods.
PlayerKnowsNameFlagID	uint16	No	20	If non-zero, the NPC's name is displayed as ??? until the specified bool flag is set to True by a quest reward.

The PlayerKnowsNameFlagID field enables the "mysterious stranger" pattern: an NPC whose name is hidden until the player completes a specific action. When the flag is set (typically through a Flag_Bool quest reward), the NPC's display name changes from ??? to the character name defined in the English.dat Character field. This is a commonly used pattern for quest-gated NPC encounters where the NPC's identity is itself a narrative reveal.

Clothing slots

The clothing slot fields define what the NPC wears. Each slot accepts either a numeric item ID (referring to a vanilla Unturned™ clothing item) or a GUID (referring to a custom Workshop clothing item). This mixed reference system, in which the same field accepts two fundamentally different identifier formats, is a documented design characteristic of the NPC clothing system and one of the recurring points of confusion for new NPC authors.

Field	Accepted format	Purpose
Shirt	uint16 or GUID	Shirt worn on the torso slot.
Pants	uint16 or GUID	Pants worn on the legs slot.
Hat	uint16 or GUID	Hat worn on the head slot.
Backpack	uint16 or GUID	Backpack worn on the back slot.
Vest	uint16 or GUID	Vest or jacket worn over the shirt.
Mask	uint16 or GUID	Mask worn over the face.
Glasses	uint16 or GUID	Glasses or eyewear.

The mixed clothing-reference system

NPC clothing fields accept either a numeric item ID or a GUID, but not both in the same field, and there is no explicit type marker to distinguish which format a given value represents. The engine determines the format by inspecting the value at load time: if the value is a short integer that matches a vanilla item ID in the loaded item registry, the engine resolves it as a numeric ID reference; if the value is a 32-character hexadecimal string, the engine resolves it as a GUID reference.

The practical consequence of this mixed system is that a numeric value in a clothing slot field is ambiguous until the engine resolves it. A value of 300 could be the numeric ID of a vanilla vest item, or it could be the first three digits of a much larger number the author intended as a custom ID, but because the engine interprets short numbers as vanilla IDs, a value of 300 will always resolve as the vanilla vest with ID 300 if one exists in the loaded item registry. To reference a custom Workshop clothing item from an NPC clothing slot, always use the item's GUID rather than its numeric ID, unless the custom item's ID is in a range that does not collide with any loaded vanilla item.

The 57 Studios™ cohort recommendation for NPC clothing is to use GUID references for all custom Workshop clothing items and numeric ID references only for vanilla clothing items. This eliminates the ambiguity and makes the .dat file self-documenting, because a 32-character hex string is visually distinct from a short integer and immediately communicates to any future reader that the reference targets a custom item.

Did you know?

The clothing items equipped on an NPC are purely visual. The NPC does not receive any gameplay benefit from the clothing it wears, a vest with armor properties does not make the NPC more durable in combat, and a backpack does not expand the NPC's inventory (NPCs do not have inventories in the player sense). The clothing fields exist solely to define the character's visual identity. This is a common point of confusion for new NPC authors who expect clothing mechanics to apply to NPCs in the same way they apply to players.

Holiday and seasonal outfit overrides

NPC characters can have event-specific outfits that replace the base clothing during seasonal events. The seasonal outfit system supports Halloween and Christmas (Festive) events.

Field	Type	Purpose
Has_Halloween_Outfit	flag	Presence of this flag enables Halloween outfit overrides during the Halloween event period.
Halloween_Shirt	uint16 or GUID	Shirt worn during the Halloween event.
Halloween_Pants	uint16 or GUID	Pants worn during the Halloween event.
Halloween_Hat	uint16 or GUID	Hat worn during the Halloween event.
Halloween_Backpack	uint16 or GUID	Backpack worn during the Halloween event.
Halloween_Vest	uint16 or GUID	Vest worn during the Halloween event.
Halloween_Mask	uint16 or GUID	Mask worn during the Halloween event.
Halloween_Glasses	uint16 or GUID	Glasses worn during the Halloween event.
Has_Christmas_Outfit	flag	Presence of this flag enables Christmas outfit overrides during the Festive event period.
Christmas_Shirt	uint16 or GUID	Shirt worn during the Festive event.
Christmas_Pants	uint16 or GUID	Pants worn during the Festive event.
Christmas_Hat	uint16 or GUID	Hat worn during the Festive event.
Christmas_Backpack	uint16 or GUID	Backpack worn during the Festive event.
Christmas_Vest	uint16 or GUID	Vest worn during the Festive event.
Christmas_Mask	uint16 or GUID	Mask worn during the Festive event.
Christmas_Glasses	uint16 or GUID	Glasses worn during the Festive event.

Each seasonal outfit is a complete parallel set of clothing slots. When the server clock enters the event period, the engine checks for the Has_Halloween_Outfit or Has_Christmas_Outfit flag on each NPC. If the flag is present, the seasonal clothing fields override the base clothing fields for the duration of the event. When the event period ends, the NPC reverts to its base clothing. If the seasonal flag is not present, the NPC wears its base clothing during the event as well, there is no automatic seasonal variation.

Seasonal outfit fields are optional

Only the clothing slots that are defined in the seasonal set are overridden. If Has_Halloween_Outfit is set but only Halloween_Hat is defined, only the hat changes during the Halloween event; the remaining clothing slots continue to use the base values. This allows for minimal seasonal variations, a Santa hat during Christmas without a complete outfit redesign.

Appearance fields

The appearance fields define the NPC's face, hair, beard, and skin and hair colors.

Field	Type	Example	Purpose
Face	int	5	Index of the face image from the vanilla face palette. Valid range is 0 through the maximum face index in the loaded game version.
Hair	int	3	Index of the hair mesh.
Beard	int	0	Index of the beard mesh. 0 means no beard.
Color_Skin	hex triplet	FFDDBB	Six-digit hexadecimal RGB color for the NPC's skin tone.
Color_Hair	hex triplet	4A2A0A	Six-digit hexadecimal RGB color for the NPC's hair.
Backward	flag	,	If present, the character is left-handed. Affects weapon-holding hand and animation mirroring.

The appearance fields can be authored by using the in-game Appearance menu: press Page Down to copy the player's current appearance to the clipboard as a formatted block of field values suitable for pasting into an NPC .dat file. This is the cohort-recommended workflow for quickly prototyping an NPC's visual identity, customize a player character in-game, copy the appearance block, paste it into the NPC .dat, and then tune the clothing, pose, and dialogue fields manually.

Pose and equipment fields

The pose and equipment fields control how the NPC stands, what items are visible on their body, and how their head and body are positioned.

Field	Type	Example	Purpose
Primary	uint16 or GUID	50001	ID or GUID of a weapon carried on the character's back, parallel to the spine.
Secondary	uint16 or GUID	50002	ID or GUID of a weapon carried on the character's hip, perpendicular to the spine.
Tertiary	uint16 or GUID	50010	ID or GUID of a non-weapon item to carry in a visible slot.
Equipped	enum	Primary	The item in the specified slot (Primary, Secondary, or Tertiary) is held in the character's hands rather than carried on the body.
Dialogue	uint16 or GUID	d4e5f6a7...	ID or GUID of the Dialogue asset to open when the player interacts with this NPC.
Pose	enum	Stand	Idle animation to play while the NPC is not interacting.
Pose_Head_Offset	float	0.1	Offset of the NPC's head from their body, in meters. Positive values offset forward; negative values offset backward.
Pose_Lean	float	0.0	How far the NPC leans left or right, as a number from -1 to 1. Positive values lean to the NPC's left. Negative values lean to the NPC's right.
Pose_Pitch	float	90	How far the NPC leans forward or backward, in degrees. Values greater than 90 lean forward. Values less than 90 lean backward.

The Pose enum accepts the following values: Asleep, Crouch, Passive, Prone, Rest, Sit, Stand, Surrender, and Under_Arrest. Each value maps to a baked-in animation clip in the Unturned™ engine. The Sit pose is the most commonly used for static vendor NPCs (the NPC sits at their stall or desk), while Stand is the default for patrolling or quest-giver NPCs. The Asleep and Rest poses are used for environmental storytelling, NPCs that are part of the scene but not interactive at a given time.

The Pose_Head_Offset, Pose_Lean, and Pose_Pitch fields allow fine-tuning of the NPC's posture beyond what the base Pose enum provides. These fields are particularly useful for NPCs placed in cramped environments (a trader sitting behind a counter needs a forward head offset to face the player over the counter) or for NPCs that need to appear to look in a specific direction (a guard NPC leaning slightly to peer around a corner).

Conditions on NPC appearance

An NPC character can be configured to appear only when certain conditions are met by the player. The condition system uses the same condition types documented in the conditions reference (see the Conditions Reference article in this section). Conditions are specified on the NPC asset through the Conditions field, and they behave identically to dialogue and quest conditions: if the condition is not met, the NPC does not render for that player.

The most common use of NPC appearance conditions is quest-gated NPC spawning: an NPC that only appears after the player has completed a specific quest. This is implemented by setting a quest flag condition on the NPC asset that checks for the completion flag. Until the flag is set, the NPC is invisible and non-interactive to that player. Once the flag is set (by the quest reward system), the NPC appears on the player's next visit to the area.

NPC localization fields

Field	Type	Purpose
Name	string	Internal name used in level editors and debug output. Not displayed to players.
Character	string	The display name shown above the NPC's head and in the dialogue window header when the player interacts with the character.

The Character field is the player-facing name. The Name field is the internal identifier, it should be descriptive and match the folder name of the NPC asset for diagnostic clarity, but it is never shown to players. When PlayerKnowsNameFlagID is set to a non-zero value, the Character field value is replaced with ??? in the UI until the specified flag is set.

NPC dialogue localization features

Unturned™ provides a set of rich-text formatting tags for NPC dialogue and response text. These tags allow dialogue to display text in different colors, insert the NPC's name or the player's character name dynamically, add line breaks, and insert timed pauses for dramatic effect.

Localization tags

Tag	Purpose	Example
<color=*enum*>	Changes the text color to a rarity color or a custom hex color. Rarity values: common, uncommon, rare, epic, legendary, mythical, gold, red, orange, yellow, green, blue, purple. Hex format: a six-digit hexadecimal RGB value.	<color=red>Danger!
<name_npc>	Inserts the NPC character's name (from the Character field) into the dialogue text.	Hello, my name is <name_npc>.
<name_char>	Inserts the player character's name into the dialogue text.	Good to see you again, <name_char>.
<br>	Inserts a line break in the dialogue text.	First line.<br>Second line.
<pause>	Pauses the dialogue display for 0.5 seconds before continuing to the next message or response block. Produces a brief pause for dramatic timing between sentences.	Wait... <pause> actually, I have a better idea.

Dialogue localization best practice

Use <name_npc> and <name_char> instead of hardcoding the NPC or player name into dialogue text. The dynamic substitution ensures that the dialogue reads correctly regardless of the player's character name and regardless of whether the NPC's Character field is later changed. Hardcoded names in dialogue text become incorrect the moment the NPC is renamed or the player changes their character name.

The <pause> tag is particularly effective for quest-giver NPCs delivering narrative information. A 0.5-second pause between sentences emulates the natural pacing of spoken dialogue and makes the text feel authored rather than mechanically dumped. Overusing <pause>, inserting it between every sentence, has the opposite effect and makes the dialogue feel stilted. The cohort recommendation is to use one or two <pause> tags per dialogue message, placed at natural sentence breaks that signal a shift in topic.

Rich-text formatting in dialogue messages

The color tag supports both pre-defined rarity color names and custom hexadecimal RGB values. Using rarity color names (<color=rare>) produces text colored with the standard rarity highlight color that players recognize from the inventory UI. Using a custom hex value (<color=#FF6600>) allows arbitrary color choices for branding, faction identification, or thematic consistency with a custom UI mod.

When multiple color tags appear in the same dialogue message, the most recently opened tag takes effect. There is no explicit </color> closing tag, the color persists until the next <color=...> tag or the end of the message. This means that coloring a single word in the middle of a sentence requires placing a second color tag after the word to revert the color.

Example of a dialogue message with color formatting:

<color=rare>Quest Item:<color=common> Bring me three wolf pelts and I'll make it worth your while.

In this example, the words "Quest Item:" appear in the rare (blue/purple) color, and the rest of the message appears in the common (white/gray) color. The second <color=common> tag reverts the text color back to the default for the remainder of the message.

NPC placement and spawn behavior

NPCs are not spawnable at runtime through console commands in the same way that items are. An NPC cannot be spawned with @give or an equivalent command, the NPC character asset must be placed in the world through the Unturned™ level editor or through a map's Objects.dat file. This is a fundamental difference from the item system and is frequently encountered as a blocker by new NPC authors who expect to test NPCs by spawning them at their current location.

Placement workflow

The cohort-validated placement workflow is:

1. Author the NPC .dat file and its companion English.dat in the mod folder structure.
2. Open the Unturned™ level editor and load the target map.
3. Place an NPC object at the desired world location.
4. Configure the placed NPC object to reference the NPC asset by its GUID or ID.
5. Save the map.
6. Load the map on the server to test the NPC encounter.

For server operators who are adding NPCs to an existing community map, the workflow requires creating a custom map that copies the original layout and adds the NPC placements. Modifying a community map's Objects.dat directly is possible only if the map's license permits modification and the server operator has the map source files. See the Custom NPCs, Dialogues, and Quests article for the complete placement workflow including level editor configuration.

NPC placement requires map authoring

NPC placement is a map-level operation, not a server-configuration operation. The NPC .dat file defines what the NPC looks like and how it behaves, but the level editor (or Objects.dat) defines where the NPC is in the world. Without a map that includes NPC placements, the NPC assets exist in the mod folder but are never instantiated in the game world. Server operators who are uncomfortable with level editing should partner with a map author or use Workshop maps that include pre-placed NPCs.

The NPC system in the broader server-config context

The NPC system interacts with several other server-configuration domains. Understanding these interactions prevents configuration conflicts and enables richer NPC encounters.

Domain	Interaction with NPC system
Item system	NPC clothing, equipped items, quest rewards, and vendor inventories reference item assets by GUID or ID. Every item an NPC references must be loaded on the server.
Currency system	Vendors can use a custom Currency asset instead of the default experience-point currency. Quest rewards can grant currency amounts. See the Currency Asset Reference.
Conditions system	NPC appearance, dialogue message visibility, dialogue response visibility, quest eligibility, and vendor slot availability are all governed by the conditions system. See the Conditions Reference.
Workshop content	NPC mods are distributed through the Steam Workshop alongside item mods. The same Workshop subscription and loading rules apply. See Workshop Content on Dedicated Servers.
Plugin frameworks	RocketMod and OpenMod plugins can extend NPC behavior beyond what the .dat system supports, custom quest types, server-side reward scripts, and dynamic NPC spawning. See RocketMod and OpenMod Plugin Basics.

The NPC system is the most interconnected domain in the server-config section. A complete NPC encounter touches item assets (for clothing, equipped weapons, quest rewards, and vendor stock), currency assets (for vendor pricing), and the conditions system (for visibility and progression gating). Understanding any one of these domains in isolation is insufficient for authoring a complete NPC encounter; the domains are designed to work together, and the cohort recommendation is to read the full server-config section before attempting a complex NPC quest chain.

The graph above shows the complete dependency web of the NPC system. Every arrow represents a reference that must resolve correctly for the NPC encounter to function. A broken reference at any point in the graph, a missing GUID, an incorrect quest ID, an undefined currency, produces a silent failure that is difficult to diagnose without systematic testing.

Frequently asked questions

What is the difference between an NPC asset and a Dialogue asset?

The NPC asset defines the visible character, its appearance, clothing, pose, and the dialogue that opens when the player presses the interact key. The Dialogue asset defines the conversation, the messages the NPC displays and the responses the player can choose. They are separate .dat files connected by the Dialogue GUID field on the NPC asset. A single NPC can reference one Dialogue asset (the root of its conversation tree), and that Dialogue asset can reference many more Dialogue assets through response fields, forming a branching conversation tree.

Can an NPC wear custom Workshop clothing?

Yes. NPC clothing slots accept both numeric item IDs (for vanilla clothing) and GUIDs (for custom Workshop clothing). To reference a custom Workshop clothing item on an NPC, use the clothing item's GUID in the relevant clothing slot field. The GUID must be the full 32-character hexadecimal value without hyphens. The 57 Studios™ cohort recommendation is to use GUIDs for all custom item references on NPCs to avoid ambiguity with vanilla item IDs.

Why does my NPC show as "???" instead of a name?

The PlayerKnowsNameFlagID field is set to a non-zero value, and the corresponding quest flag has not been set to True for this player. The NPC's name is hidden until a Flag_Bool quest reward with the matching ID sets the flag. To disable this behavior and always show the NPC's name, set PlayerKnowsNameFlagID to 0 in the NPC .dat file.

Can I spawn an NPC with a console command?

No. NPCs must be placed through the Unturned™ level editor or through a map's Objects.dat file. There is no console command to spawn an NPC at the player's current location. To test an NPC, place it in a map, load the map, and interact with it in-game. For quick testing during authoring, place the NPC in a small test map with a single spawn point rather than in the full production map.

How do I make an NPC appear only after a quest is completed?

Set a condition on the NPC asset that checks for the quest completion flag. The condition type should be Quest_Flag_Bool (to check a boolean flag) or Quest_Status (to check the status of a specific quest). When the condition is satisfied, the quest is marked as Completed or the flag is set to True, the NPC renders for that player. Until the condition is met, the NPC is invisible and non-interactive. This is the standard pattern for quest-gated NPC encounters and progression-gated vendor access.

Can I use HTML tags in NPC dialogue?

The NPC dialogue system supports a specific set of tags: <color=...>, <name_npc>, <name_char>, <br>, and <pause>. These are Unturned™-specific formatting tags, not HTML tags, though the angle-bracket syntax is similar. Standard HTML tags (such as <b>, <i>, <u>) are not supported and will appear as literal text in the dialogue window if included.

How many clothing slots does an NPC have?

Seven base clothing slots: Shirt, Pants, Hat, Backpack, Vest, Mask, and Glasses. Additionally, the Primary, Secondary, and Tertiary slots control visible carried items, and the Equipped field determines which slot's item the NPC holds in its hands. The holiday outfit system adds fourteen additional seasonal slots (seven for Halloween, seven for Christmas). The clothing in all slots is purely visual, it does not affect the NPC's gameplay properties.

What happens if an NPC's Dialogue GUID does not match any loaded Dialogue asset?

The interact key produces no response when pressed on the NPC. The NPC renders and plays its idle pose animation, but no dialogue window opens. There is no error message logged to the console. This silent failure is one of the most common bugs in NPC authoring and is typically caught during the first round of testing. The cohort recommendation is to test the dialogue connection for every NPC immediately after the first placement by interacting with the NPC and confirming the dialogue window opens with the expected text.

Do NPC clothing items need to be loaded as Workshop mods on the server?

Yes. If an NPC references a clothing item by GUID (a custom Workshop item) or numeric ID (a vanilla item), that item must be loaded on the server. For vanilla items, the item is always available because vanilla content is always loaded. For custom Workshop items, the Workshop mod containing the clothing item must be subscribed to and loaded on the server. If the referenced item is not loaded, the clothing slot renders as empty, the NPC wears nothing in that slot, with no error message.

Can I change an NPC's dialogue after the map is published?

Yes. The NPC asset references the Dialogue asset by GUID, and the Dialogue asset is a separate .dat file in the mod folder structure. Updating the Dialogue asset's .dat file (changing message text, response text, or adding new responses) and republishing the mod updates the dialogue for all players on servers that update their Workshop subscription. The NPC asset itself does not need to change. This separation of the visual character (NPC asset) from the conversation content (Dialogue asset) is a deliberate design feature that allows dialogue to be iterated on without republishing the map or repositioning the NPC.

Best practices

• Generate a fresh GUID for every NPC, Dialogue, Quest, and Vendor asset. Never reuse GUIDs across any asset type.
• Use GUIDs for all custom Workshop clothing items referenced on NPC clothing slots. Use numeric IDs only for vanilla clothing items.
• Test every reference chain before publishing: NPC to Dialogue, Dialogue to Quest, Dialogue to Vendor, Vendor to Currency.
• Use the <name_npc> and <name_char> tags in dialogue text instead of hardcoding names.
• Place one or two <pause> tags per dialogue message at natural sentence breaks for pacing, but do not overuse them.
• Set the last message in every Dialogue asset to have zero conditions, this acts as the fallback message if no conditional message's criteria are met.
• Use PlayerKnowsNameFlagID only when the name reveal is a narrative beat in the quest chain. For standard vendors and quest-givers, set it to 0.
• Test NPC interactions with a fresh player save to confirm that all default (non-conditional) dialogue paths work before testing quest-gated paths.
• Document every custom flag ID you use in a project-level flag registry to avoid flag collisions between different quest chains.
• Use the in-game Appearance menu's Page Down copy feature to prototype NPC faces and hair quickly, then paste the values into the NPC .dat.
• Write NPC Character names that are distinct from their Name field values, the Name field is the internal identifier used for debugging, and having a different Character field value makes it clear which field is being referenced when troubleshooting.
• Place NPCs at least two meters apart in the level editor to prevent interaction collision, when two NPCs are placed too close together, the interact key may target the wrong NPC.
• Test NPC dialogue with at least three distinct quest-flag states: no flags set (new player), some flags set (player mid-quest-chain), and all flags set (player completed chain). Each state should produce correct dialogue.

Authoring checklist

• [ ] NPC GUID is unique, generated fresh, not copied from another asset
• [ ] NPC ID is in the 50000+ range
• [ ] Type NPC is present
• [ ] Dialogue GUID references a valid, loaded Dialogue asset
• [ ] All clothing references (GUID or numeric ID) resolve to loaded items
• [ ] Seasonal outfit flags (Has_Halloween_Outfit, Has_Christmas_Outfit) are set only when seasonal clothing fields are defined
• [ ] Pose enum value is one of the valid values: Asleep, Crouch, Passive, Prone, Rest, Sit, Stand, Surrender, Under_Arrest
• [ ] English.dat is authored with Name (internal) and Character (display) fields
• [ ] NPC is placed in the level editor and the reference to the NPC asset resolves correctly
• [ ] Dialogue opens when the player interacts with the NPC
• [ ] All conditional dialogue paths work correctly after the relevant quest flags are set
• [ ] PlayerKnowsNameFlagID is 0 unless the name-reveal pattern is intentionally used

Appendix A: NPC pose enum quick reference

Pose value	Visual behavior	Typical use
Stand	Character stands upright, idle animation.	Default pose for generic NPCs, patrolling guards.
Sit	Character sits on the ground or on a nearby surface.	Vendor NPCs behind a desk, resting quest-givers.
Rest	Character reclines or rests against a surface.	Non-interactive environmental NPCs, sleeping guards.
Asleep	Character lies down, sleeping animation.	NPCs that are only available during certain hours; use with time-of-day conditions.
Crouch	Character crouches low to the ground.	Hiding NPCs, NPCs in cover positions.
Prone	Character lies flat on the ground.	Injured NPCs, NPCs that need to be revived as a quest objective.
Passive	Character stands with a non-threatening posture, hands visible.	Unarmed civilians, quest-givers in safe zones.
Surrender	Character raises hands in surrender.	Captured NPCs, hostage scenarios for quests.
Under_Arrest	Character assumes a restrained posture.	NPCs in detention scenarios.

Appendix B: NPC clothing field format decision guide

The table below provides the cohort-validated decision logic for choosing between numeric ID and GUID format for each NPC clothing slot.

Clothing source	Recommended format	Example	Rationale
Vanilla Unturned™ clothing item	Numeric ID	Shirt 15	Vanilla IDs are stable across game versions and shorter to author.
Custom Workshop clothing item	GUID	Shirt abc123def456...	GUIDs are unambiguous and avoid collision with vanilla IDs.
Item from a different Workshop mod (dependency)	GUID	Hat fedcba987654...	GUIDs survive ID reallocation in the dependency mod.
Item from the same Workshop mod	GUID	Vest 1234abcd5678...	Self-referencing by GUID avoids ID collision with other loaded mods.

Appendix C: NPC system diagnostic table

Symptom	Most likely cause	Resolution
NPC renders but dialogue does not open on interact	Dialogue GUID on NPC does not match any loaded Dialogue asset	Confirm the GUID in the NPC's Dialogue field exactly matches the GUID field of the target Dialogue asset
NPC is invisible	NPC has conditions that are not met for this player; or NPC was not placed in the level editor	Check NPC's Conditions field; confirm NPC placement in level editor
NPC name shows as ???	PlayerKnowsNameFlagID is set to a non-zero value and the flag is not yet True	Set PlayerKnowsNameFlagID to 0 to disable name hiding, or ensure the quest flag is set before the player meets this NPC
NPC clothing slot is empty	Clothing item reference does not resolve to a loaded item	Confirm the numeric ID or GUID references a loaded item on the server
Seasonal outfit does not appear during event	Has_Halloween_Outfit or Has_Christmas_Outfit flag is missing	Add the flag to the NPC .dat
NPC stands in wrong pose	Pose enum value is misspelled or is an unsupported value	Confirm the value is one of the nine valid pose enum values
NPC name displays incorrectly in dialogue	Character field in English.dat is missing or misspelled	Add or correct the Character field in the NPC's English.dat
Quest flag condition does not affect NPC visibility	Condition type or flag ID is incorrect	Confirm the condition type, flag ID, and expected value match what the quest reward sets
NPC placed in level editor but not visible in game	NPC asset is not loaded (mod not subscribed, wrong folder, or GUID conflict)	Confirm the mod is loaded; check the server log for asset loading errors
Two NPCs placed close together cause interaction targeting issues	NPC interaction radius overlaps with adjacent NPC	Separate NPCs by at least two meters in the level editor

Appendix D: Dialogue localization pattern reference

The NPC dialogue localization system supports several recurring formatting patterns that the 57 Studios™ cohort uses on the Horizon Life RP server. These patterns are validated through empirical testing and are reusable across any NPC dialogue configuration.

The faction-color identity pattern

A common pattern for faction-based RP servers is to color-code NPC dialogue by faction affiliation. An NPC affiliated with a police faction displays dialogue in blue; an NPC affiliated with a hostile faction displays dialogue in red. This is implemented by wrapping dialogue message text in a color tag:

Message_0_English <color=blue>Officer Martinez looks up from her desk.</color> Can I help you, citizen?

The color tag applies from the point it opens until the end of the message or until another color tag changes it. Players learn to associate colors with factions, which makes multi-NPC environments navigable at a glance.

The quest-reminder pattern

Dialogue messages that remind the player of their current quest objective use <name_char> for personalization and <color=yellow> for objective emphasis:

Message_1_English <name_char>, I'm still waiting for those pelts. <color=yellow>Three wolf pelts, delivered to this desk.</color>

The player's character name is inserted dynamically, and the objective text is highlighted in yellow, a color that players learn to associate with actionable quest information.

The dramatic-reveal pause pattern

For narrative NPCs where a piece of information is a dramatic reveal, the <pause> tag creates a 0.5-second gap before the reveal text:

Message_0_English I've tracked the bandit leader for weeks. His name...<pause> <color=red>is Viktor.</color>

The pause separates the setup text from the reveal, and the red color tag draws attention to the revealed name. This pattern works for any narrative beat where the dialogue should pause for dramatic effect before delivering a key piece of information.

The multi-speaker conversation pattern

For servers that want to simulate a conversation between two NPCs, two NPC assets are placed near each other, and dialogue messages alternate between the two speakers with color tags distinguishing which NPC is speaking:

Message_0_English <color=blue>Guard 1:</color> Did you hear about the supply shipment?
Message_1_English <color=green>Guard 2:</color> The one that went missing near the dam? I heard it was bandits.

The player interacts with one of the two NPCs, and the dialogue tree presents messages that simulate a conversation overheard between the two characters. This pattern requires careful authoring but creates the impression of a living world where NPCs interact with each other independently of the player.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. NPC system architecture, character asset field reference, clothing mixed-reference system, pose and equipment fields, seasonal outfits, dialogue localization features, NPC placement overview, and diagnostic reference.

Cross-references

• Custom NPCs, Dialogues, and Quests, the complete end-to-end authoring tutorial for NPC, Dialogue, Quest, and Vendor assets with worked examples.
• Vendor Asset Reference, the next article in this section; complete vendor .dat field reference.
• Currency Asset Reference, custom currency configuration for NPC vendors.
• Conditions Reference, the complete conditions system governing NPC visibility and dialogue branching.
• Project Folder Structure and GUIDs, GUID generation and folder layout conventions.
• Item Asset Anatomy, the shared field reference for all item types, including the clothing items referenced by NPC clothing slots.
• Workshop Content on Dedicated Servers, server-side Workshop mod loading, relevant for NPC mod distribution.
• RocketMod and OpenMod Plugin Basics, plugin frameworks that extend NPC behavior beyond .dat capabilities.
• Smartly Dressed Games modding documentation, official field reference for the NPC system.
• Unturned on Steam, game page and changelog; changelog notes NPC system updates.