Skip to main content

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.

The Citizens UI is the primary way to manage NPCs in HyCitizens. Every aspect of a Citizen — its name, model, position, scale, behavior, and more — can be configured directly in-game through a clean, scrollable interface. No configuration files are required; everything is handled through the UI and saved automatically.

​
Opening the UI

Run /citizens in-game to open the Citizens Manager. You must have the hycitizens.admin permission. The following aliases are also accepted: /citizen, /hycitizens, /hycitizen. Once opened, the interface displays the total number of Citizens on your server and lets you switch between the Manage and Create tabs.

​
Main UI Sections

The Manage tab lists all existing Citizens along with their groups. Each entry shows the Citizen’s name, model ID, scale, and internal ID.From the Manage tab you can:
  • Search Citizens and groups by name, ID, or group path using the search bar.
  • Edit a specific Citizen by clicking its Edit button, which opens the full edit form.
  • Teleport to a Citizen’s location using the TP button.
  • Clone a Citizen to your current position using the Clone button.
  • Remove a Citizen permanently using the Remove button.
  • Edit Closest Citizen — instantly opens the edit form for the nearest Citizen within 75 blocks.
  • Respawn All — force-respawns every Citizen on the server (same as /citizens respawnall).
  • New Group — create a new top-level group from the Manage tab.
Groups are displayed as collapsible folder-style items. Clicking View on a group opens a filtered view of that group’s contents. Inside a group view, additional buttons appear to create child groups, move the group, or respawn all Citizens in the group.
The Create tab is the starting point for adding a new Citizen to your world. Clicking Start Creating opens the full creation form where you can configure:
  • Citizen Name — the display name shown above the NPC (supports multi-line via \n).
  • Entity Type — choose between a Player Model (with skin configuration) or any other Entity/Model ID.
  • Scale — how large the Citizen appears (default 1.0).
  • Group — assign the Citizen to an existing group or type a new group name.
  • Permissions — optionally restrict who can interact with the Citizen.
  • Map Marker — optionally display this Citizen as a marker on the world map.
When you click Create, the Citizen spawns immediately at your current position and rotation.
Groups let you organize Citizens into a hierarchical folder structure. Group paths use forward-slash delimiters, such as Town, Town/Guards, or Town/Guards/Elite.From the Manage tab you can:
  • Create a root group using the New Group button.
  • Create a child group from inside a group’s view using New Child Group.
  • Rename a group — all Citizens in the group are updated automatically.
  • Move a group under a different parent or back to root.
  • Delete a group (Citizens inside remain; their group field is cleared).
Each Citizen can be assigned a group when creating or editing it, either by selecting an existing group from the dropdown or by typing a new group name.

​
Special Items

Citizen Stick — a special in-game item that lets you interact with Citizens directly in the world. Hit a Citizen with the Citizen Stick to open its Edit form without needing to find it in the Manage list. Obtain it by clicking Get Citizen Stick in the Manage tab (requires hycitizens.admin). Patrol Stick — used to place patrol waypoints in the world when setting up patrol paths for Citizens. The Patrol Stick can be obtained from the Patrol Paths editor inside the Behaviors section of a Citizen’s edit form. Left-clicking opens the waypoint menu; right-clicking adds a waypoint at your current position.

​
Data Storage

All Citizens and their settings are stored automatically in the mods/HyCitizensData/ directory on your server. Citizens persist across server restarts — no manual saving is required.
Changes made through the Citizens UI take effect immediately. When you save a Citizen, the NPC despawns and respawns with the new configuration applied. You do not need to restart the server or run any additional commands.

Build docs developers (and LLMs) love

Get started for freeTalk to us