Developer API

The HyCitizens API gives Java developers full programmatic control over citizens — spawn them from code, move them around, listen to what players do with them, fire animations, and deeply integrate them into your own plugin's logic.

🔧

Who is this for?

This section is for Java developers building Hytale server plugins who want to interact with HyCitizens programmatically. If you just want to configure citizens in-game, check out the User Guide instead.

Step 1 — Add HyCitizens as a Dependency

To use the HyCitizens API in your plugin, you need to declare HyCitizens as a dependency so it loads before your plugin. Add it to your plugin's manifest file:

{
  "Dependencies": {
    "electro:HyCitizens": "*"
  }
}

You'll also need to include the HyCitizens jar as a compile-time dependency in your build system (Gradle, Maven, etc.) so your IDE can resolve the classes. The jar is available from the GitHub repository.

Step 2 — Get the Manager

Everything in HyCitizens flows through CitizensManager. Access it from anywhere in your plugin:

CitizensManager manager = HyCitizensPlugin.get().getCitizensManager();

CitizensManager is the central hub for creating, querying, updating, and controlling citizens. See the CitizensManager reference for a full breakdown of everything it can do.

Step 3 — Create Your First Citizen

Here's a minimal example that spawns a citizen NPC in the world:

CitizensManager manager = HyCitizensPlugin.get().getCitizensManager();

// Build the citizen
CitizenData citizen = new CitizenData(
        "Unique_Town_Crier_ID", // ID
        "Town Crier", // Name
        "Player", // Model ID
        worldUuid, // World UUID
        new Vector3d(0, 70, 0), // Position
        new Vector3f(0, 0, 0), // Rotation
        1.0f, // Scale
        null, // NPC UUID - You should usually set this as null
        new ArrayList<>(), // Hologram UUIDs - You should usually leave this empty
        "", // Required Permission
        "", // No Permission Message - Leaving it empty sets a default message
        List.of(), // Command actions
        true, // Is Player Model
        false, // Use Live Skin
        "Simon", // Skin Username
        null, // Cached Skin - Usually set to null
        0L, // Last Skin Update - Usually set to 0L
        true // Rotate towards players
);

// Give them something to say on F key
CitizenMessage greeting = new CitizenMessage(
    "{GOLD}hello!! Welcome to {#FF4500}Ashenvale!",
    "F_KEY",
    0.0f
);
MessagesConfig messages = new MessagesConfig();
messages.setMessages(List.of(greeting));
citizen.setMessagesConfig(messages);

// Register, spawn, and save
manager.addCitizen(citizen, true);

How the API is Organized

The API is split into two categories: guides that explain how to accomplish specific tasks, and a model reference that documents every class and method in detail.

Guides

Guide	What it covers
CitizensManager	Creating, querying, updating, removing, and controlling citizens. The most important page in the API.
Moving Citizens	Moving citizens to positions, starting/stopping patrols, and managing patrol paths from code.
Events	Listening for player interactions and citizen deaths. Cancelling interactions conditionally.
Full Example	A complete example making use of a lot of features.

Model Reference

Class	What it represents
CitizenData	The full data model for a single citizen — all fields and runtime state.
CitizenInteraction	Static utilities for triggering interactions and parsing colored messages.
MessagesConfig	The message list and selection mode for a citizen.
CitizenMessage	A single message with trigger type and optional delay.
CommandAction	A command or message to run when a citizen is interacted with.
AnimationBehavior	An animation trigger rule — when to play an animation and what slot to use.
MovementBehavior	Idle, wander, or patrol movement settings.
PathConfig	Which patrol path a citizen follows and how it loops.
PatrolPath & PatrolWaypoint	A named patrol route with ordered world coordinates.
DetectionConfig	View distance, hearing, alert states, and search timers for hostile citizens.
CombatConfig	Full combat behavior — attack style, timing, blocking, movement in combat.
DeathConfig	What happens when a citizen dies — drops, messages, and commands.
DeathDropItem	A single item drop entry for a citizen's death loot.

Need help? Join the Discord community or browse the source code on GitHub to see real examples.