# Citizen Configuration

# 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](https://wiki.kyuubisoft.com/hytale/citizens/admin-windows/), which writes the same files.

## Full Example

```json
{
  "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. 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

| 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

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

```json
{
  "isPlayerModel": true,
  "skinUsername": "SomePlayer",
  "scale": 1.0
}
```

**Entity model example** (creature NPC):

```json
{
  "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. |

:::info
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

| 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

| 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](https://wiki.kyuubisoft.com/hytale/citizens/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:

```json
{
  "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.

:::caution[Console commands]
Adding, changing or removing commands that run as the console (interact commands with `runAsServer: true`, death commands, proximity commands) in the NPC window needs `ks.core.admin.dialog.console`. Web editor imports without that node keep the current console commands. Hand-edited files are not checked, so protect access to the server files.
:::

**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

| 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

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

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