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.
- Place
KyuubiSoftCore-<version>.jarin your Hytale server’smods/folder. - Start (or restart) your server.
- 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:
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
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 [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
Section titled “Creating Your First NPC”There are three ways to create a new citizen.
Option A: NPC Management Window
Section titled “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.
Option B: In-Game Command
Section titled “Option B: In-Game Command”Stand at the position where you want the NPC to appear and run:
/kscitizen create my_merchantThis creates a basic citizen at your current position with default settings (player model, idle). The NPC spawns immediately.
Option C: JSON Configuration
Section titled “Option C: 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": "SomePlayer", "scale": 1.0, "movementType": "IDLE", "fKeyInteractionEnabled": true, "shopId": "my_shop", "takesDamage": false } ]}Then reload in-game:
/kscitizen reloadAfter 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
Section titled “Basic Workflow”The typical workflow for setting up NPCs on your server:
- Plan — Decide where each NPC should stand, what they look like and what they do (dialog, shop, quest giver).
- Position — Walk to the spawn location and note the coordinates, or use
/kscitizen createto capture your position automatically. - Configure — Use the NPC management window, or edit the JSON to set skin, equipment, animations and interaction behavior.
- Save or reload — Press Save in the window, or run
/kscitizen reloadafter editing JSON. - Test — Walk up to the NPC and press F to interact. Verify dialog, shop or quest assignment works correctly.
- Iterate — Adjust position, appearance or behavior as needed and reload again.
Permissions
Section titled “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.
Next Steps
Section titled “Next Steps”- NPC Admin Windows — Edit NPCs, skins and dialogs in game
- Citizen Configuration — Full reference for all citizen JSON fields
- Dialog System — Dialog trees with choices, conditions and actions
- Commands — Complete command reference