Skip to content
KyuubiSoft Wiki
News & Patchnotes

Getting Started

Getting Started

Section titled “Getting Started”

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

Installation

Section titled “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.

Folder Structure

Section titled “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
    └── ...

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

Section titled “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

Section titled “Creating Your First NPC”

There are two ways to create a new citizen.

Option A: In-Game Command

Section titled “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

Section titled “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

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

Basic Workflow

Section titled “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

Section titled “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

Section titled “Next Steps”