Citizen Configuration

Citizen Configuration

Every citizen is defined as a JSON object inside citizens.json or custom/custom_citizens.json. This page documents all available fields.

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

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.
group	No	null	Optional group tag for filtering with /kscitizen list <group>.

Position

Field	Required	Default	Description
worldName	Yes	—	World where the NPC spawns. Supports exact names (default) and partial matching (Forgotten_Temple matches instance-Forgotten_Temple-uuid).
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

Field	Required	Default	Description
isPlayerModel	No	false	true = human player model with a skin. false = entity model (see entityTypeId).
skinUsername	No	null	Minecraft username whose skin is applied to the NPC. Only used when isPlayerModel: true.
useLiveSkin	No	false	Fetch the skin live from Mojang servers on every spawn (slower, always up-to-date).
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": "Notch",
  "scale": 1.0
}

Entity model example (creature NPC):

{
  "isPlayerModel": false,
  "entityTypeId": "Trork_Guard",
  "scale": 1.0
}

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. You can find valid IDs by checking the game’s content definitions or using /ksdev export to list all registered items.

Behavior

Field	Default	Description
attitude	PASSIVE	PASSIVE (never attacks), NEUTRAL (attacks if provoked), AGGRESSIVE (attacks on sight).
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

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

Execute commands when a player interacts with the NPC:

{
  "commandActions": [
    { "command": "give {PlayerName} Food_Apple 3", "runAsServer": true },
    { "command": "{SendMessage}Welcome, {PlayerName}!", "runAsServer": false }
  ]
}

Field	Default	Description
command	—	The command to execute. Supports {PlayerName}, {CitizenName} and {CitizenId} placeholders.
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.

Visibility and Survival

Field	Default	Description
hideNpc	false	true = NPC is not spawned (hidden).
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.
respawnOnDeath	true	Automatically respawn after being killed.
respawnDelay	5.0	Seconds before respawning after death.

Custom Citizens File

To add your own NPCs without modifying the base citizens.json, create custom/custom_citizens.json:

{
  "configVersion": 1,
  "disabled_base_ids": ["example_npc"],
  "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 (e.g. disable the example NPC).
• Override by ID — If your custom citizen has the same id as a base citizen, it replaces the base definition entirely.