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.

HyCitizens fires four events that other plugins can listen to via CitizensManager. Every listener interface is annotated @FunctionalInterface, so you can register lambdas directly without implementing a named class. Listeners are invoked synchronously on the same thread that fires the event.

​
Registering a Listener

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

manager.addCitizenInteractListener(event -> {
    // handle event
});
Store the listener reference if you need to unregister it later: 
CitizenInteractListener myListener = event -> {
    // handle event
};

manager.addCitizenInteractListener(myListener);

// When your plugin shuts down:
manager.removeCitizenInteractListener(myListener);
CitizenInteractEvent and CitizenDeathEvent are cancellable. Once any listener calls event.setCancelled(true), the event loop breaks and subsequent registered listeners do not receive the event. Register order-sensitive listeners first.

​
CitizenInteractEvent

CitizenInteractEvent is fired whenever a player interacts with a Citizen — either by left-clicking the NPC or pressing the F-key when prompted. Cancellable: calling event.setCancelled(true) prevents the Citizen’s commands and messages from executing. The interaction is consumed but no actions are taken.

​
Methods

Returns the CitizenData of the Citizen that was interacted with.
Returns the PlayerRef of the player who triggered the interaction.
Returns true if the event has been cancelled.
Set to true to suppress all commands and messages that would normally fire from this interaction.

​
Registration

manager.addCitizenInteractListener(listener);
manager.removeCitizenInteractListener(listener);

​
Example

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

manager.addCitizenInteractListener(event -> {
    // Block interaction for Citizens named "Guard"
    if (event.getCitizen().getName().contains("Guard")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage(Message.raw("The guard ignores you.").color(Color.GRAY));
    }
});

​
CitizenAddedEvent

CitizenAddedEvent is fired immediately after a new Citizen is registered in the manager via CitizensManager.addCitizen(...). The NPC entity may not yet be spawned in the world at the moment this event fires. Not cancellable.

​
Methods

Returns the CitizenData of the newly added Citizen.

​
Registration

manager.addCitizenAddedListener(listener);
manager.removeCitizenAddedListener(listener);

​
Example

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

manager.addCitizenAddedListener(event -> {
    System.out.println("New citizen created: " + event.getCitizen().getName());
});

​
CitizenRemovedEvent

CitizenRemovedEvent is fired after a Citizen has been fully removed from the manager — the NPC and hologram are already despawned and the config entry has been deleted by the time this event fires. Not cancellable.

​
Methods

Returns the CitizenData of the Citizen that was removed. The object is still populated with its last known state, but the Citizen is no longer accessible through the manager.

​
Registration

manager.addCitizenRemovedListener(listener);
manager.removeCitizenRemovedListener(listener);

​
Example

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

manager.addCitizenRemovedListener(event -> {
    System.out.println("Citizen removed: " + event.getCitizen().getId());
});

​
CitizenDeathEvent

CitizenDeathEvent is fired when a Citizen’s NPC entity health reaches zero. This event only fires for Citizens that have takesDamage set to true. Cancellable: calling event.setCancelled(true) prevents the full death sequence — loot drops, death commands/messages, and respawn scheduling are all suppressed. The NPC entity will still have taken lethal damage in the ECS.

​
Methods

Returns the CitizenData of the Citizen that died.
Returns the PlayerRef of the player who delivered the killing blow, or null if the Citizen was killed by the environment or a non-player source.
Returns true if the death event has been cancelled.
Set to true to suppress drops, death commands, death messages, and respawn scheduling.

​
Registration

manager.addCitizenDeathListener(listener);
manager.removeCitizenDeathListener(listener);

​
Example

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

manager.addCitizenDeathListener(event -> {
    CitizenData citizen = event.getCitizen();
    PlayerRef killer = event.getKiller();

    if (killer != null) {
        System.out.println(killer.getUsername() + " killed " + citizen.getName());
    }

    // Prevent death processing for boss Citizens
    if ("Boss".equals(citizen.getGroup())) {
        event.setCancelled(true);
    }
});

​
Event Summary

CitizenInteractEvent

Fired on player interaction (left-click or F-key). Cancellable — prevents commands and messages from executing.

CitizenAddedEvent

Fired when a new Citizen is registered via addCitizen. Not cancellable.

CitizenRemovedEvent

Fired after a Citizen is permanently deleted. Not cancellable.

CitizenDeathEvent

Fired when a damageable Citizen’s NPC dies. Cancellable — prevents drops, death commands, and respawn scheduling.

Build docs developers (and LLMs) love

Get started for freeTalk to us