HyCitizens is a full in-game NPC (Citizen) management plugin for Hytale servers. It solves the problem of needing external configuration files or custom code just to populate your world with life — instead, every Citizen can be created, positioned, and configured entirely through a clean in-game UI, with an optional developer API available for deeper integration.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ElectroGamesDev/HyCitizens/llms.txt
Use this file to discover all available pages before exploring further.
Key Features
In-Game UI
Open the Citizens management panel with
/citizens to create, edit, and delete NPCs without ever touching a config file.Interactions
Trigger messages and commands when players hit or interact with a Citizen, with per-action permission checks and configurable delays.
Movement
Configure idle, wander, patrol, and follow behaviors so Citizens feel like living parts of your world.
Developer API
Listen for Citizen events, spawn and update NPCs programmatically, and integrate HyCitizens into your own plugins.
How It Works
When HyCitizens loads, it reads all persisted Citizen data frommods/HyCitizensData/ on disk. Each Citizen’s properties — name, model, position, rotation, interactions, movement behavior, and more — are stored in that directory and reloaded automatically on every server start, so your NPCs survive restarts without any manual intervention.
HyCitizens bundles the HyUI UI framework directly inside its JAR, so no separate HyUI installation is required. At runtime, Citizens are tracked per-world and spawned into the correct chunks as they load. Position data is periodically saved back to disk so that wandering or patrolling NPCs resume from approximately where they were when the server stopped.
Requirements
| Requirement | Details |
|---|---|
| Hytale server | Version >=0.5.0-pre.9 <0.6.0 (see manifest.json) |
hycitizens.admin permission | Required to open /citizens and run management sub-commands |
HyUI is bundled inside the HyCitizens JAR — you do not need to install HyUI separately. Just place the HyCitizens JAR in your
mods/ folder and start the server.