Skip to main content

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 kyuubisoft_core.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 configs/kyuubisoft_core/citizens.json with a set of pre-configured example NPCs. You can use these as templates for your own citizens.

Folder Structure​

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

configs/kyuubisoft_core/
├── citizens.json              # Main citizen definitions (base content)
├── citizens.json.backup       # Automatic backup before each save
├── custom/                    # Your custom citizens (never overwritten)
│   ├── custom_citizens.json.example   # Template for custom citizens
│   └── custom_citizens.json           # Your custom definitions (create this)
└── dialogs/                   # Dialog tree JSON files
    ├── example_dialog.json
    └── ...
Base + Custom System

The main citizens.json file is base content managed by the plugin and may be updated when you install a new version (a backup is created automatically). Your own NPCs should go into custom/custom_citizens.json, which is never overwritten on updates. Custom citizens override base citizens by ID.

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     (Zara)           - Forgotten_Temple
● desert_scout     (Kira)           - Forgotten_Temple
● guide_finn       (Finn)           - default
● merchant_sol     (Sol)            - Forgotten_Temple
...

A green dot means the NPC is currently spawned. A red dot means it is not spawned (usually because you are in a different world).

Creating Your First NPC​

There are two ways to create a new citizen.

Option A: 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, passive). The NPC spawns immediately.

Option B: JSON Configuration​

Add a new entry to custom/custom_citizens.json:

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

Then reload in-game:

/kscitizen reload
warning

After editing JSON files, always run /kscitizen reload to apply changes. The server does not detect file changes automatically.

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 -- Edit the JSON to set skin, equipment, animations and interaction behavior.
  4. Reload -- Run /kscitizen reload to apply changes.
  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​

All citizen management commands require the citizen.admin permission. Regular players can interact with NPCs but cannot create, remove or modify them.

Next Steps​