# Getting Started

# Getting Started

This guide walks you through installing the Citizens system, understanding the default setup and spawning your first NPC.

## Installation

The Citizens system is part of the **KyuubiSoft Core** mod. No separate installation is required.

1. Place `KyuubiSoftCore-<version>.jar` in your Hytale server's `mods/` folder.
2. Start (or restart) your server.
3. The plugin automatically creates its data folder and extracts default citizen definitions.

:::tip
On first start the plugin generates `mods/kyuubisoft_core/citizens.json` with a set of pre-configured NPCs. Example NPCs that are not spawned ship in `custom/citizens_examples.json.example` and can be used as templates.
:::

## Folder Structure

After the first start, the citizen-related files are located here:

```
mods/kyuubisoft_core/
├── citizens.json              # Main citizen definitions (base content)
├── citizen-backups/           # Last 10 timestamped backups of the NPC files
├── custom/                    # Your custom citizens (never overwritten)
│   ├── custom_citizens.json.example     # Template for custom citizens
│   ├── citizens_examples.json.example   # Example NPCs
│   └── custom_citizens.json             # Your custom definitions
└── dialogs/                   # Dialog tree JSON files
    ├── example_dialog.json
    └── ...
```

:::info Base + Custom System
The main `citizens.json` file is **base content** managed by the plugin. Your own NPCs should go into `custom/custom_citizens.json`, which is **never overwritten** on updates. Custom citizens override base citizens by ID. A file that fails to load is never overwritten either: Core keeps it, makes a `.corrupt-<time>` copy and writes nothing to it until it loads again.
:::

## Default Citizens

The plugin ships with several pre-configured NPCs spread across the `default` and `Forgotten_Temple` worlds. Run `/kscitizen list` in-game to see them:

```
=== Citizens (18) ===
• oasis_healer [quest_npcs] (-21, 0, 3)
• desert_scout [quest_npcs] (-65, -10, 4)
• guide_finn (12, 65, -4)
...
```

A green dot means the NPC is currently spawned. A red dot means it is not spawned (its world is not loaded, or it is hidden).

New installs no longer spawn the old example NPC `example_npc`. Finn (`guide_finn`) stays, because the Quests tutorial needs him. Existing `citizens.json` files are not touched.

## Creating Your First NPC

There are three ways to create a new citizen.

### Option A: NPC Management Window

Run `/kscitizen edit` and press **New NPC**. Pick one of 7 templates; ID, name and group are suggested. Set skin, equipment, behaviour and dialogs on the tabs and press **Save**. See [NPC Admin Windows](https://wiki.kyuubisoft.com/hytale/citizens/admin-windows/).

### Option B: In-Game Command

Stand at the position where you want the NPC to appear and run:

```
/kscitizen create my_merchant
```

This creates a basic citizen at your current position with default settings (player model, idle). The NPC spawns immediately.

### Option C: JSON Configuration

Add a new entry to `custom/custom_citizens.json`:

```json
{
  "citizens": [
    {
      "id": "my_merchant",
      "name": "Merchant Bob",
      "worldName": "default",
      "posX": 100.0,
      "posY": 65.0,
      "posZ": -50.0,
      "isPlayerModel": true,
      "skinUsername": "SomePlayer",
      "scale": 1.0,
      "movementType": "IDLE",
      "fKeyInteractionEnabled": true,
      "shopId": "my_shop",
      "takesDamage": false
    }
  ]
}
```

Then reload in-game:

```
/kscitizen reload
```

:::warning
After editing JSON files, always run `/kscitizen reload` to apply changes. The server does **not** load file changes by itself, but it also never saves over a file you changed: admins get a chat warning until they reload.
:::

## Basic Workflow

The typical workflow for setting up NPCs on your server:

1. **Plan** -- Decide where each NPC should stand, what they look like and what they do (dialog, shop, quest giver).
2. **Position** -- Walk to the spawn location and note the coordinates, or use `/kscitizen create` to capture your position automatically.
3. **Configure** -- Use the NPC management window, or edit the JSON to set skin, equipment, animations and interaction behavior.
4. **Save or reload** -- Press Save in the window, or run `/kscitizen reload` after editing JSON.
5. **Test** -- Walk up to the NPC and press **F** to interact. Verify dialog, shop or quest assignment works correctly.
6. **Iterate** -- Adjust position, appearance or behavior as needed and reload again.

## Permissions

Citizen management needs `ks.citizen.admin` or `ks.admin`; the old `citizen.admin` still works. Commands that run as the server console also need `ks.core.admin.dialog.console`. Regular players can interact with NPCs but cannot create, remove or modify them. See [Permissions](https://wiki.kyuubisoft.com/hytale/citizens/permissions/).

## Next Steps

- [NPC Admin Windows](https://wiki.kyuubisoft.com/hytale/citizens/admin-windows/) -- Edit NPCs, skins and dialogs in game
- [Citizen Configuration](https://wiki.kyuubisoft.com/hytale/citizens/citizen-config/) -- Full reference for all citizen JSON fields
- [Dialog System](https://wiki.kyuubisoft.com/hytale/citizens/dialog-system/) -- Dialog trees with choices, conditions and actions
- [Commands](https://wiki.kyuubisoft.com/hytale/citizens/commands/) -- Complete command reference