Skip to content

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.

{
"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
}
FieldRequiredDefaultDescription
idYes—Unique identifier. Used to link quests, shops and markers to this NPC.
nameYes—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.
groupNonullOptional group tag for filtering with /kscitizen list <group>.
FieldRequiredDefaultDescription
worldNameYes—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, posZYes0.0Spawn coordinates.
rotX, rotY, rotZNo0.0Initial rotation (radians). rotY controls horizontal facing direction.
spawnRelativeNofalseWhen 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. :::

FieldRequiredDefaultDescription
isPlayerModelNofalsetrue = human player model with a skin. false = entity model (see entityTypeId).
skinUsernameNonullHytale 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.
customSkinNonullSkin parts set by the in-game skin editor. Wins over skinUsername.
useLiveSkinNofalseKept for old files; it has no effect at the moment and is no longer shown in the window.
scaleNo1.0Model scale. 0.8 = smaller, 1.5 = larger.
entityTypeIdNonullEntity 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
}
FieldDefaultDescription
mainHandnullItem ID for the main hand (e.g. Weapon_Sword_Iron).
offHandnullItem ID for the off hand.
helmetnullArmor helmet slot.
chestnullArmor chestplate slot.
leggingsnullArmor leggings slot.
glovesnullArmor 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.

FieldDefaultDescription
attitudePASSIVEPASSIVE (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.
rotateTowardsPlayerfalseNPC faces the nearest player when idle.
movementTypeIDLEHow the NPC moves. See table below.
movementRadius0.0Wander radius in blocks (only for wander types).
walkSpeed1.0Movement speed multiplier.

Movement types:

TypeDescription
IDLEStands still at the spawn position.
WANDERWalks randomly within the configured radius.
WANDER_CIRCLEWalks in a circular pattern.
WANDER_RECTWalks in a rectangular area.
PATHFollows a predefined path.
FieldDefaultDescription
fKeyInteractionEnabledfalseShows the “Press F” interaction prompt when a player is nearby.
permissionnullPermission string required to interact. Players without this permission are blocked.
noPermissionMessagenullMessage shown when a player lacks the required permission.
shopIdnullOpens this shop when the player interacts (requires the Shop system).
sellShopIdnullOpens this shop directly in sell mode.
itemUpdateEnabledfalseOpens the item update window on interaction.
dialogsnullConditional dialog list. See the Dialog System page.
messagesnullSimple chat messages sent on interaction (alternative to full dialogs).
messageSelectionModeRANDOMHow messages are selected: RANDOM, SEQUENTIAL (cycles through), or ALL (sends every message).

Execute commands when a player interacts with the NPC:

{
"commandActions": [
{ "command": "give {player} Food_Apple 3", "runAsServer": true },
{ "command": "{SendMessage}Welcome, {player}!", "runAsServer": false }
]
}
FieldDefaultDescription
command—The command to execute. Supports the placeholders below.
runAsServertruetrue = 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):

PlaceholderValue
{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.

FieldDefaultDescription
hideNpcfalsetrue = 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.
hideNametagfalsetrue = hides the floating name above the NPC.
nametagOffset0.0Vertical offset for the nametag (useful for scaled NPCs).
takesDamagefalsetrue = NPC can take damage from players and mobs.
invulnerablefalsetrue = NPC cannot be killed. Not shown in the NPC window since 2.9.0; the value stays in the file.
respawnOnDeathtrueAutomatically respawn after being killed.
respawnDelay5.0Seconds before respawning after death.

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 id as a base citizen, it replaces the base definition entirely.