HyCitizens provides a fully in-game workflow for creating and managing Citizen NPCs. Every Citizen is configured through the Citizens Manager UI — no files need to be edited manually. Citizens spawn immediately when created, and any edits take effect the moment you save.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.
Creating a Citizen
Open the Citizens Manager
Run
/citizens in-game. The Citizens Manager opens on the Manage tab. You need the hycitizens.admin permission to access this UI.Navigate to the Create Tab
Click the Create button at the top of the UI to switch to the Create tab, then click Start Creating to open the full creation form.
Set the Citizen's Name
Enter a display name in the Citizen Name field. This name appears as a nametag floating above the NPC in-world. To create a multi-line nametag, separate lines with
\n — for example, Guard\nTown Square.Additional nametag options (offset, hide, model nametag) are available via the Nametag Settings button.Choose an Entity Type
Select Player Model to use a player skin, or Other Entities to use any Hytale entity or custom model ID.
- Player Model — configure a skin by entering a username in the Skin Username field, clicking Use My Skin to copy your current skin, or clicking Random Skin to generate one automatically.
- Other Entities — choose from the dropdown list of loaded model assets, or type an entity/model ID directly (for example,
PlayerTestModel_V,Sheep, or any custom model ID registered on your server).
Set Position and Rotation
The Citizen will spawn at your current position and rotation when you click Create. Stand at the exact spot where you want the NPC to appear before saving. The position and rotation can be updated later from the edit form.
Set Scale
Enter a value in the Scale Factor field. The default is
1.0 (normal size). The valid range is 0.01 to 100.0. For example, 2.0 doubles the NPC’s size.Assign a Group (Optional)
To organize the Citizen, select an existing group from the Select Existing Group dropdown, or type a new group name in the Or Enter New Group Name field. Group names support slash-delimited hierarchy — for example,
Town/Guards. Leave blank to place the Citizen at the root level.Editing a Citizen
To modify an existing Citizen, open the Citizens Manager (/citizens), navigate to the Manage tab, find the Citizen in the list, and click its Edit button. You can also use Edit Closest Citizen to open the edit form for the nearest NPC within 75 blocks.
The edit form contains the same fields as the creation form, plus additional sections:
- Nametag Settings — fine-tune the nametag text, offset, visibility, and optional model nametag.
- Update Position — teleports the Citizen’s spawn point to your current location instantly.
- Commands — configure commands that run when a player interacts with the Citizen.
- Messages — set messages sent to players on interaction.
- Behaviors — control movement type (Idle, Wander, Patrol, Follow Citizen), animations, attitudes, and combat settings.
- Schedule — define a daily routine with time-based location and activity entries.
- Set Items — copy your currently equipped armor and held items to the Citizen.
- First Interaction — configure one-time actions that only trigger the first time each player interacts.
Deleting a Citizen
To permanently remove a Citizen, open the Manage tab, find the Citizen, and click Remove. The Citizen is deleted immediately — this action cannot be undone. You can also remove a Citizen from inside its edit form using the Remove button in the Quick Actions section.Grouping Citizens
Groups let you organize Citizens into a hierarchical folder structure displayed in the Manage tab.- Group paths use forward slashes as separators:
Town,Town/Guards,Town/Guards/Elite. - Assign a group when creating a Citizen, or update it at any time from the edit form using the Group section.
- From the Manage tab, click New Group to create a root group, or navigate into an existing group and click New Child Group to create a nested sub-group.
- Groups support Rename, Move (change parent), and Respawn Group operations from the Manage tab.
- Deleting a group does not delete its Citizens — their group field is cleared.
Citizen Properties Reference
| Property | Description |
|---|---|
| Name | The display name shown as a nametag above the NPC. Supports \n for multi-line nametags and color codes. |
| Model ID | The entity or model asset used to render the NPC. Use Player for a player-model Citizen. Common examples: PlayerTestModel_V, Sheep. |
| Position (x/y/z) | The world coordinates where the Citizen spawns. Set by standing at the desired location and saving, or updated via Update Position. |
| Rotation (x/y/z) | The yaw, pitch, and roll of the Citizen in degrees. Captured from your current rotation when creating or updating position. |
| Scale | A multiplier for the Citizen’s size. Default is 1.0. Valid range: 0.01 – 100.0. |
| Group | An optional slash-delimited group path used to organize Citizens in the Manage tab (e.g., Town/Guards). |