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 HyCitizens Developer API gives other Hytale server plugins direct, programmatic access to the NPC system at runtime. While the in-game UI is ideal for server operators who want to place and configure Citizens manually, the API is the right tool when your plugin needs to react to NPC events, generate Citizens dynamically from data, or drive NPC behaviour from your own game logic — such as quest systems, combat encounters, or procedural world generation.

​
What you can do with the API

The API exposes the full lifecycle of every Citizen managed by HyCitizens. At a high level your plugin can: Listen to Citizen events
  • CitizenAddedEvent — fired whenever a new Citizen is registered with the manager.
  • CitizenRemovedEvent — fired whenever a Citizen is deleted and de-spawned.
  • CitizenInteractEvent — fired when a player interacts with a Citizen. This event is cancellable: calling event.setCancelled(true) prevents HyCitizens from running the Citizen’s own commands and messages.
  • CitizenDeathEvent — fired when a Citizen dies. This event is also cancellable: cancelling it prevents HyCitizens from processing death drops, death commands, and respawn scheduling.
Create, update, and remove Citizens programmatically
  • Add a fully configured CitizenData instance at any position in any loaded world.
  • Update an existing Citizen’s appearance, nametag, equipment, or behaviour config and push those changes to the live NPC entity immediately.
  • Remove a Citizen by ID, de-spawning its NPC and hologram entities and cleaning up all persisted data.
Control NPC movement
  • Teleport a Citizen to an arbitrary position or back to its spawn point.
  • Start and stop named patrol paths on any Citizen whose movement type is PATROL.
  • Push a one-shot move-target position, or stop movement entirely.
Query Citizens
  • Look up a single Citizen by its string ID with getCitizen(id).
  • Retrieve every registered Citizen with getAllCitizens().
  • Find all Citizens within a radius of a world position with getCitizensNear(position, maxDistance).
Force-respawn Citizens
  • Immediately respawn every Citizen on the server via respawnAllCitizens(save).
  • Respawn only the Citizens belonging to a specific group (including child groups) via respawnCitizensInGroup(groupName, includeChildren, save).
Modify configs at runtime
  • Replace a Citizen’s CombatConfig, DetectionConfig, or PathConfig at any time with the corresponding setters. HyCitizens re-spawns the NPC entity to apply the new role configuration automatically.

​
Entry point

Everything flows from the static singleton HyCitizensPlugin.get(), which returns the running plugin instance: 
HyCitizensPlugin plugin = HyCitizensPlugin.get();
From there, call plugin.getCitizensManager() to obtain the CitizensManager — the central object for all API operations: 
CitizensManager manager = HyCitizensPlugin.get().getCitizensManager();

​
Architecture note

HyCitizens is built against the Hytale server SDK (com.hypixel.hytale:Server). Your plugin must compile against the same SDK version (and the same HyCitizens JAR) to ensure binary compatibility. HyCitizens itself targets Java 25 using the Gradle Java toolchain, so your plugin should target the same Java version.

​
Explore the API

CitizensManager

Full reference for every method on CitizensManager: CRUD operations, movement controls, group management, and more.

CitizenData

The data model that describes a single Citizen — position, model, equipment, combat config, detection config, and all other properties.

Events

Reference for CitizenAddedEvent, CitizenRemovedEvent, CitizenInteractEvent, and CitizenDeathEvent, including all available fields and cancellation behaviour.

Examples

Practical, copy-paste code examples covering common API use-cases.

Build docs developers (and LLMs) love

Get started for freeTalk to us