# Citizens & NPCs

> **Mod:** part of KyuubiSoft Core (2.9.9) | **Config:** `mods/kyuubisoft_core/citizens.json` and `custom/custom_citizens.json`

The Citizens system lets you spawn and manage custom NPCs across your Hytale server. Citizens have custom skins, dialog trees, animations and world map markers, and work together with the quest, achievement and shop systems.

## What's new in Core 2.8 and 2.9

These features have not been tested in game yet.

- **NPC admin windows:** NPC management (`/kscitizen edit`), a skin editor with a live 3D stage, the NPC viewer and a dialog editor. See [NPC Admin Windows](https://wiki.kyuubisoft.com/hytale/citizens/admin-windows/).
- **New dialog window** at the bottom of the screen with the speaker on a 3D stage, up to 4 numbered answers with tags, "Continue", "Show all", a conversation history and "Step back".
- **Dialog actions without commands:** give or take items or coins, start a quest, open a shop or a window, teleport, play a sound, set a fact; with repeat rules (every time, once, once per hour, day or week). See [Dialog System](https://wiki.kyuubisoft.com/hytale/citizens/dialog-system/).
- **New dialog conditions:** `has_item`, `fact` and, with the Quests mod, `quest_ready`.
- **Per-language NPC names** and one documented set of placeholders (`{player}`, `{npc}`, `{world}`, ...).
- **NPCs in several worlds:** animations, healing, effects, proximity reactions and schedules run in every world that has players. Admin actions act in the NPC's own world. World names match exactly; instance copies still match their template name.
- **Safer NPC files:** a file that fails to load is never overwritten, the 60-second save never reverts hand edits, and the last 10 backups are kept in `citizen-backups/`.
- **One permission rule:** `ks.citizen.admin` or `ks.admin`. Console commands need `ks.core.admin.dialog.console`. See [Permissions](https://wiki.kyuubisoft.com/hytale/citizens/permissions/).

## Features

- **Custom NPCs** - Spawn NPCs with unique skins, equipment and names
- **In-game editing** - NPC management window, skin editor, NPC viewer and dialog editor
- **Dialog System** - Multi-node dialog trees with choices, conditions, actions and commands
- **Proximity Detection** - NPCs react when players approach (animations, messages, sounds, commands)
- **World Map Markers** - Show NPCs on the world map with quest status indicators
- **F-Key Interaction** - Players interact with NPCs using the interact key
- **Animations** - Timed, proximity, on interact, on attack and default idle animations
- **Multi-World** - NPCs work in all server worlds at the same time
- **Quest Integration** - NPCs serve as quest givers with offer/active/complete states

## Quick Start

1. The Core mod JAR includes the citizen system; install it in `mods/`.
2. Default citizens are created in `mods/kyuubisoft_core/citizens.json`.
3. Use `/kscitizen list` to see all NPCs, or `/kscitizen edit` to open the NPC management window.
4. Create NPCs in the window, or add them to `custom/custom_citizens.json` and run `/kscitizen reload`.

## Commands

| Command | Description |
|---------|-------------|
| `/kscitizen edit [id]` | Open the NPC management window |
| `/kscitizen list [group]` | List all citizens |
| `/kscitizen create <id>` | Create a new citizen at your position |
| `/kscitizen remove <id>` | Remove a citizen |
| `/kscitizen tp <id>` | Teleport to a citizen, also into other worlds |
| `/kscitizen respawn <id>` | Respawn a single citizen |
| `/kscitizen respawnall` | Despawn and respawn all citizens |
| `/kscitizen reload` | Reload citizen configs |
| `/kscitizen info <id>` | Show citizen details |
| `/kscitizen marker <id> [type]` | Set/remove quest marker |
| `/kscitizen viewer` | Open the NPC viewer |
| `/kscitizen skinreload <id>` | Fetch an NPC's skin again and respawn it |
| `/kscitizen repair` | Open the item repair window (player command) |
| `/kscitizen wprecord <id>` | Start waypoint recording |
| `/kscitizen wpadd` | Add waypoint at current position |
| `/kscitizen wpundo` | Remove last waypoint |
| `/kscitizen wpdone` | Stop recording and save |

See [Commands](https://wiki.kyuubisoft.com/hytale/citizens/commands/) for details.

## Documentation

<DocCardList />