Citizen Configuration
Every citizen is defined as a JSON object inside citizens.json or custom/custom_citizens.json (in mods/kyuubisoft_core/). This page documents the fields. Most of them can also be set in game in the NPC management window, which writes the same files.
Full Example
Section titled “Full Example”{ "id": "desert_scout", "name": "Kira", "group": "quest_npcs", "worldName": "Forgotten_Temple",
"posX": -64.9, "posY": -10.0, "posZ": 4.0, "rotX": 0.0, "rotY": 0.0, "rotZ": 0.0, "spawnRelative": true,
"isPlayerModel": true, "skinUsername": "Awwi", "useLiveSkin": false, "scale": 1.0,
"chest": "Armor_Thorium_Chest", "mainHand": "Weapon_Sword_Thorium",
"attitude": "PASSIVE", "rotateTowardsPlayer": true, "movementType": "WANDER", "movementRadius": 8.0, "walkSpeed": 1.0,
"animations": [ { "type": "PROXIMITY", "animationName": "Wave", "animationSlot": 2, "interval": 15.0, "proximityRange": 8.0, "stopAfterTime": true, "stopTime": 3.0 } ],
"hideNametag": false, "nametagOffset": 0.0, "fKeyInteractionEnabled": true, "messageSelectionMode": "RANDOM",
"hideNpc": false, "takesDamage": false, "invulnerable": true, "respawnOnDeath": true, "respawnDelay": 5.0}Field Reference
Section titled “Field Reference”Identity
Section titled “Identity”| Field | Required | Default | Description |
|---|---|---|---|
id | Yes | — | Unique identifier. Used to link quests, shops and markers to this NPC. |
name | Yes | — | Display name shown above the NPC. Can be a plain string or an i18n key. Per-language names are stored as the language key citizen.name.<id>; name tags and NPC chat lines then show the name in each viewer’s language, with name as the fallback. |
group | No | null | Optional group tag for filtering with /kscitizen list <group>. |
Position
Section titled “Position”| Field | Required | Default | Description |
|---|---|---|---|
worldName | Yes | — | World where the NPC spawns. Names match exactly (default does not match default_flat). Instance copies (instance-<template>-<id>) match their template name, and an NPC created or moved inside an instance copy is saved with the template name. |
posX, posY, posZ | Yes | 0.0 | Spawn coordinates. |
rotX, rotY, rotZ | No | 0.0 | Initial rotation (radians). rotY controls horizontal facing direction. |
spawnRelative | No | false | When true, coordinates are offsets relative to the world spawn point instead of absolute positions. |
:::tip Relative Positioning
Use spawnRelative: true when you want NPCs to work regardless of the exact world spawn point. This is especially useful for instance worlds where the spawn might shift between server configurations.
:::
Appearance
Section titled “Appearance”| Field | Required | Default | Description |
|---|---|---|---|
isPlayerModel | No | false | true = human player model with a skin. false = entity model (see entityTypeId). |
skinUsername | No | null | Hytale player name whose skin is applied to the NPC. The skin is fetched from an online skin database and cached; /kscitizen skinreload <id> fetches it again. Only used when isPlayerModel: true. |
customSkin | No | null | Skin parts set by the in-game skin editor. Wins over skinUsername. |
useLiveSkin | No | false | Kept for old files; it has no effect at the moment and is no longer shown in the window. |
scale | No | 1.0 | Model scale. 0.8 = smaller, 1.5 = larger. |
entityTypeId | No | null | Entity type for non-player models (e.g. Trork_Guard, Skeleton). Only used when isPlayerModel: false. |
Player model example (human NPC with custom skin):
{ "isPlayerModel": true, "skinUsername": "SomePlayer", "scale": 1.0}Entity model example (creature NPC):
{ "isPlayerModel": false, "entityTypeId": "Trork_Guard", "scale": 1.0}Equipment
Section titled “Equipment”| Field | Default | Description |
|---|---|---|
mainHand | null | Item ID for the main hand (e.g. Weapon_Sword_Iron). |
offHand | null | Item ID for the off hand. |
helmet | null | Armor helmet slot. |
chest | null | Armor chestplate slot. |
leggings | null | Armor leggings slot. |
gloves | null | Armor gloves slot. |
Equipment uses Hytale item IDs. The NPC management window has an item picker with search for all 6 slots; /ksdev items exports all registered items.
Behavior
Section titled “Behavior”| Field | Default | Description |
|---|---|---|
attitude | PASSIVE | PASSIVE (never attacks), NEUTRAL (attacks if provoked), AGGRESSIVE (attacks on sight). Not shown in the NPC window since 2.9.0; the value stays in the file. |
rotateTowardsPlayer | false | NPC faces the nearest player when idle. |
movementType | IDLE | How the NPC moves. See table below. |
movementRadius | 0.0 | Wander radius in blocks (only for wander types). |
walkSpeed | 1.0 | Movement speed multiplier. |
Movement types:
| Type | Description |
|---|---|
IDLE | Stands still at the spawn position. |
WANDER | Walks randomly within the configured radius. |
WANDER_CIRCLE | Walks in a circular pattern. |
WANDER_RECT | Walks in a rectangular area. |
PATH | Follows a predefined path. |
Interaction
Section titled “Interaction”| Field | Default | Description |
|---|---|---|
fKeyInteractionEnabled | false | Shows the “Press F” interaction prompt when a player is nearby. |
permission | null | Permission string required to interact. Players without this permission are blocked. |
noPermissionMessage | null | Message shown when a player lacks the required permission. |
shopId | null | Opens this shop when the player interacts (requires the Shop system). |
sellShopId | null | Opens this shop directly in sell mode. |
itemUpdateEnabled | false | Opens the item update window on interaction. |
dialogs | null | Conditional dialog list. See the Dialog System page. |
messages | null | Simple chat messages sent on interaction (alternative to full dialogs). |
messageSelectionMode | RANDOM | How messages are selected: RANDOM, SEQUENTIAL (cycles through), or ALL (sends every message). |
Command Actions
Section titled “Command Actions”Execute commands when a player interacts with the NPC:
{ "commandActions": [ { "command": "give {player} Food_Apple 3", "runAsServer": true }, { "command": "{SendMessage}Welcome, {player}!", "runAsServer": false } ]}| Field | Default | Description |
|---|---|---|
command | — | The command to execute. Supports the placeholders below. |
runAsServer | true | true = execute as console, false = execute as the player. |
Use the {SendMessage} prefix to send a chat message instead of running a command. deathCommands uses the same fields and always runs as the console.
Placeholders (interact commands, chat messages, proximity reactions and death commands):
| Placeholder | Value |
|---|---|
{player} | Player name (death commands: the killer if it was a player, else empty) |
{player_uuid} | UUID of that player |
{npc} | NPC name (in the reader’s language in chat, the server language in commands) |
{npc_id} | NPC ID |
{world} | World name |
{x} {y} {z} | Block position of the player (death commands: where the NPC died) |
{killer} | Death commands only: who killed the NPC (player name or creature type) |
The old forms {PlayerName}, {CitizenName}, {citizenname}, {CitizenId} and {citizen} (= ID) keep working. Placeholders are not case-sensitive. Values are escaped in commands, so a player name can never change the shape of a command.
Visibility and Survival
Section titled “Visibility and Survival”| Field | Default | Description |
|---|---|---|
hideNpc | false | true = NPC is not spawned (hidden). A hidden NPC does not respawn after it dies. Hide/show in the NPC window sets this and survives restarts. |
hideNametag | false | true = hides the floating name above the NPC. |
nametagOffset | 0.0 | Vertical offset for the nametag (useful for scaled NPCs). |
takesDamage | false | true = NPC can take damage from players and mobs. |
invulnerable | false | true = NPC cannot be killed. Not shown in the NPC window since 2.9.0; the value stays in the file. |
respawnOnDeath | true | Automatically respawn after being killed. |
respawnDelay | 5.0 | Seconds before respawning after death. |
Custom Citizens File
Section titled “Custom Citizens File”To add your own NPCs without modifying the base citizens.json, create custom/custom_citizens.json:
{ "configVersion": 1, "disabled_base_ids": ["merchant_sol"], "citizens": [ { "id": "my_guard", "name": "Guard Captain", "worldName": "default", "posX": 50.0, "posY": 65.0, "posZ": 100.0, "isPlayerModel": true, "skinUsername": "Steve", "fKeyInteractionEnabled": true, "attitude": "PASSIVE" } ]}disabled_base_ids— List of base citizen IDs to remove from your server.- Override by ID — If your custom citizen has the same
idas a base citizen, it replaces the base definition entirely.