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.

This guide walks you through creating a Hytale server plugin that integrates with HyCitizens. By the end you will have a working Gradle project that compiles against the HyCitizens JAR, obtains the CitizensManager at startup, and registers a listener for Citizen interaction events.

​
Prerequisites

Before you start, make sure you have the following available:
  • Hytale Server SDK (com.hypixel.hytale:Server) — available from the Hytale Maven repository.
  • Java 25 — HyCitizens is compiled with the Java 25 toolchain; your plugin must match.
  • Gradle — the build system used by HyCitizens and recommended for plugin development.
  • HyCitizens JAR — because HyCitizens is not published to a Maven repository, you need the compiled JAR file. Download it and place it in your project’s libs/ directory.

​
Gradle setup

1

Add the Hytale repository and HyCitizens as a dependency

Open (or create) your build.gradle.kts and add the Hytale Maven repository alongside mavenCentral(). Declare the Hytale server SDK and the HyCitizens JAR both as compileOnly dependencies — they will be provided at runtime by the server and by HyCitizens itself, so they must not be bundled into your plugin JAR.
build.gradle.kts
plugins {
    java
}

repositories {
    mavenCentral()
    maven("https://maven.hytale.com/release/")
}

dependencies {
    compileOnly("com.hypixel.hytale:Server:latest.release")
    compileOnly(files("libs/HyCitizens.jar"))  // place HyCitizens JAR in your libs/ folder
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25))
    }
}
2

Set the Java toolchain to Java 25

The java { toolchain { ... } } block shown above instructs Gradle to compile your plugin with the Java 25 toolchain, matching the version HyCitizens itself targets. If you also want to hard-pin the --release flag (recommended for reproducibility), add:
build.gradle.kts
tasks.withType<JavaCompile>().configureEach {
    options.release.set(25)
}
3

Declare HyCitizens as a plugin dependency in your manifest

Your plugin’s metadata file must list HyCitizens as a dependency. This guarantees the server loads and initialises HyCitizens before your plugin’s setup() method is called, making HyCitizensPlugin.get() safe to call at that point.The exact format depends on your plugin framework, but the dependency name to use is HyCitizens.

​
Accessing the API

Once your Gradle project is configured, you can obtain the CitizensManager inside your plugin’s setup() method. The static method HyCitizensPlugin.get() returns the singleton plugin instance; from there, getCitizensManager() gives you the central API object.
MyPlugin.java
import com.electro.hycitizens.HyCitizensPlugin;
import com.electro.hycitizens.managers.CitizensManager;
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;

public class MyPlugin extends JavaPlugin {
    public MyPlugin(JavaPluginInit init) {
        super(init);
    }

    @Override
    protected void setup() {
        // Access the CitizensManager after HyCitizens has loaded
        CitizensManager manager = HyCitizensPlugin.get().getCitizensManager();
    }
}

​
Listening to events

CitizensManager exposes add*Listener / remove*Listener methods for each event type. The example below registers a CitizenInteractListener that logs the interaction (using the interacting player’s UUID, which is the identifier available on PlayerRef) and shows how to cancel it when needed.
MyPlugin.java
import com.electro.hycitizens.HyCitizensPlugin;
import com.electro.hycitizens.events.CitizenInteractEvent;

// In your setup() method:
HyCitizensPlugin.get().getCitizensManager().addCitizenInteractListener(event -> {
    String citizenName = event.getCitizen().getName();
    String playerUuid = event.getPlayer().getUuid().toString();
    System.out.println(playerUuid + " interacted with " + citizenName);

    // Cancel the interaction if needed
    // event.setCancelled(true);
});
When event.setCancelled(true) is set, HyCitizens stops processing subsequent listeners for that interaction and skips executing the Citizen’s own commands and messages. The same cancellation pattern is available on CitizenDeathEvent.
HyCitizensPlugin.get() returns null if HyCitizens has not yet loaded. Always access it inside your setup() or start() method — never in your plugin’s constructor. Calling it too early will result in a NullPointerException.
Load order — ensure your plugin declares HyCitizens as a dependency in its manifest so the server loads HyCitizens first. Without this declaration the load order is undefined and HyCitizensPlugin.get() may still be null when your setup() runs.

​
Next steps

CitizensManager

Explore the full method reference: creating and removing Citizens, movement controls, group management, respawning, and more.

Events

Deep-dive into all four Citizen events, their available fields, and how cancellation works.

Build docs developers (and LLMs) love

Get started for freeTalk to us