How do I install the Hytale Events skill?

Run npx skillmds@latest add jburlison/hytale-events in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Hytale Events skill do?

Documents Hytale's event system for handling game events in plugins. Covers IEvent (global events), IAsyncEvent (async events), and EcsEvent (ECS entity/block events). Use when listening to player join/disconnect, chat, crafting, damage, block break/place, entity death, or any server event. Triggers - event, IEvent, IAsyncEvent, EcsEvent, CancellableEcsEvent, EntityEventSystem, EventRegistry, registerGlobal, registerAsync, PlayerReadyEvent, PlayerDisconnectEvent, PlayerChatEvent, BreakBlockEvent, PlaceBlockEvent, Damage, CraftRecipeEvent, DropItemEvent, DeathSystems, OnDeathSystem, event handler, event listener. It is listed under Coding & Dev Tools on SkillMD.

Is Hytale Events safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Hytale Events?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Hytale Events free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Hytale Events?

JBurlison (@jburlison) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Hytale Events by jburlison — Agent Skill

Name: Hytale Events
Author: JBurlison

Hytale Events Skill

Use this skill when working with events in Hytale plugins. This covers the three event categories: IEvent (global synchronous events), IAsyncEvent (asynchronous events), and EcsEvent (ECS-based entity/block events).

Related skills: For chat-specific event handling, see hytale-chat-formatting. For ECS system fundamentals, see hytale-ecs. For entity effects triggered by events, see hytale-entity-effects.

Quick Reference

Task	Approach
Listen to player join	`registerGlobal(PlayerReadyEvent.class, handler)` in `setup()`
Listen to player disconnect	`registerGlobal(PlayerDisconnectEvent.class, handler)` in `setup()`
Listen to chat messages	`registerAsync(PlayerChatEvent.class, handler)` in `setup()`
Cancel block break	Extend `EntityEventSystem<EntityStore, BreakBlockEvent>`, call `setCancelled(true)`
Cancel crafting	Extend `EntityEventSystem<EntityStore, CraftRecipeEvent.Pre>`
Handle entity damage	Extend `EntityEventSystem<EntityStore, Damage>`
Handle player death	Extend `DeathSystems.OnDeathSystem`
Handle block placement	Extend `EntityEventSystem<EntityStore, PlaceBlockEvent>`
Register global event	`this.getEventRegistry().registerGlobal(EventClass.class, Handler::method)`
Register async event	`this.getEventRegistry().registerAsync(EventClass.class, Handler::method)`
Register ECS event system	`this.getEntityStoreRegistry().registerSystem(new MyEventSystem())` in `start()`

Event Categories

Hytale has three distinct event types, each with different registration patterns:

Category	Interface	Registration	Cancellable	Use Case
IEvent	`IEvent`	`registerGlobal()`	No	Player join, disconnect, world events, plugin lifecycle
IAsyncEvent	`IAsyncEvent`	`registerAsync()`	Yes (some)	Chat messages, asset loading
EcsEvent	`EcsEvent` / `CancellableEcsEvent`	`registerSystem()`	Yes (Cancellable)	Block break/place, damage, crafting, item drops

IEvent — Global Events

Global events are fired for server-wide occurrences. Register them in your plugin's setup() method.

Registration Pattern

@Override
protected void setup() {
    this.getEventRegistry().registerGlobal(PlayerReadyEvent.class, MyEventHandler::onPlayerReady);
    this.getEventRegistry().registerGlobal(PlayerDisconnectEvent.class, MyEventHandler::onPlayerDisconnect);
    this.getEventRegistry().registerGlobal(ShutdownEvent.class, MyEventHandler::onShutdown);
}

Handler Class

public class MyEventHandler {
    public static void onPlayerReady(PlayerReadyEvent event) {
        Player player = event.getPlayer();
        player.sendMessage(Message.raw("Welcome " + player.getDisplayName()));
    }

    public static void onPlayerDisconnect(PlayerDisconnectEvent event) {
        // event.getRef() returns a Ref<EntityStore> for the disconnecting player
    }

    public static void onShutdown(ShutdownEvent event) {
        // Clean up resources on server shutdown
    }
}

Required Imports (IEvent)

import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.server.core.entity.entities.Player;
import com.hypixel.hytale.server.core.event.events.ShutdownEvent;
import com.hypixel.hytale.server.core.event.events.player.PlayerDisconnectEvent;
import com.hypixel.hytale.server.core.event.events.player.PlayerReadyEvent;

Available IEvent Types

Player Events

Event	Description	Key Methods
`PlayerReadyEvent`	Player finished joining (fully loaded)	`getPlayer()`
`PlayerDisconnectEvent`	Player disconnecting	`getRef()` → `Ref<EntityStore>`
`PlayerConnectEvent`	Player beginning connection	-
`PlayerSetupConnectEvent`	Player setup phase start	-
`PlayerSetupDisconnectEvent`	Player setup phase disconnect	-
`PlayerMouseButtonEvent`	Player mouse button input	-
`PlayerMouseMotionEvent`	Player mouse motion	-

World Events

Event	Description
`AddWorldEvent`	A world is being added
`RemoveWorldEvent`	A world is being removed
`StartWorldEvent`	A world is starting
`AddPlayerToWorldEvent`	Player added to a world
`DrainPlayerFromWorldEvent`	Player removed from a world
`AllWorldsLoadedEvent`	All worlds finished loading

Lifecycle Events

Event	Description
`BootEvent`	Server boot
`ShutdownEvent`	Server shutting down
`PluginSetupEvent`	Plugin setup phase
`AllNPCsLoadedEvent`	All NPCs finished loading
`LoadedNPCEvent`	Individual NPC loaded

Asset Events

Event	Description
`AssetPackRegisterEvent`	Asset pack registered
`AssetPackUnregisterEvent`	Asset pack unregistered
`RegisterAssetStoreEvent`	Asset store registered
`RemoveAssetStoreEvent`	Asset store removed
`GenerateAssetsEvent`	Assets being generated
`LoadedAssetsEvent`	Assets finished loading
`RemovedAssetsEvent`	Assets removed
`LoadAssetEvent`	Individual asset loading

Other Events

Event	Description
`EntityRemoveEvent`	Entity removed from world
`LivingEntityInventoryChangeEvent`	Entity inventory changed
`ItemContainerChangeEvent`	Item container changed
`GenerateDefaultLanguageEvent`	Default language generation
`GenerateSchemaEvent`	Schema generation
`GenerateServerStateEvent`	Server state generation
`ChunkPreLoadProcessEvent`	Chunk pre-load processing
`TreasureChestOpeningEvent`	Treasure chest opened
`WindowCloseEvent`	Window closed
`WorldPathChangedEvent`	World path changed
`MessagesUpdated`	Messages updated

IAsyncEvent — Asynchronous Events

Async events run off the main tick thread. Register in setup() using registerAsync().

Registration Pattern

@Override
protected void setup() {
    this.getEventRegistry().registerAsync(PlayerChatEvent.class, MyEventHandler::onPlayerChat);
}

Handler Example

public static void onPlayerChat(PlayerChatEvent event) {
    PlayerRef sender = event.getSender();
    String content = event.getContent();

    // Cancel the message
    if (content.contains("badword")) {
        event.setCancelled(true);
        sender.sendMessage(Message.raw("That word is not allowed!"));
        return;
    }

    // Modify content
    event.setContent(content.toUpperCase());

    // Set custom formatter
    event.setFormatter((playerRef, message) ->
        Message.join(
            Message.raw("[Server] ").color(Color.GOLD),
            Message.raw(sender.getUsername()).color(Color.WHITE),
            Message.raw(": " + message).color(Color.GRAY)
        ));
}

Available IAsyncEvent Types

Event	Description	Cancellable
`PlayerChatEvent`	Player sends a chat message	Yes
`SendCommonAssetsEvent`	Common assets being sent	No
`AssetEditorFetchAutoCompleteDataEvent`	Editor autocomplete data	No
`AssetEditorRequestDataSetEvent`	Editor data set request	No

EcsEvent — ECS Entity/Block Events

ECS events are fired within the ECS tick loop and operate on entities matching a query. They use EntityEventSystem and are registered as systems.

Key Difference from IEvent

IEvent: Simple handler function, registered in setup()
EcsEvent: Full ECS system class extending EntityEventSystem, registered in start() via registerSystem()
EcsEvent receives Store, CommandBuffer, and ArchetypeChunk — giving full ECS access

EntityEventSystem Pattern

import com.hypixel.hytale.component.ArchetypeChunk;
import com.hypixel.hytale.component.CommandBuffer;
import com.hypixel.hytale.component.Store;
import com.hypixel.hytale.component.system.EntityEventSystem;
import com.hypixel.hytale.component.query.Archetype;
import com.hypixel.hytale.component.query.Query;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import javax.annotation.Nonnull;

class MyCraftHandler extends EntityEventSystem<EntityStore, CraftRecipeEvent.Pre> {

    public MyCraftHandler() {
        super(CraftRecipeEvent.Pre.class);
    }

    @Override
    public void handle(int index,
                       @Nonnull ArchetypeChunk<EntityStore> archetypeChunk,
                       @Nonnull Store<EntityStore> store,
                       @Nonnull CommandBuffer<EntityStore> commandBuffer,
                       @Nonnull CraftRecipeEvent.Pre event) {
        // Access entity ref
        var ref = archetypeChunk.getReferenceTo(index);

        // Access event data
        CraftingRecipe recipe = event.getCraftedRecipe();

        // Cancel if needed (CancellableEcsEvent only)
        event.setCancelled(true);
    }

    @Override
    public Query<EntityStore> getQuery() {
        // Return which entities this system processes
        // Archetype.empty() = all entities that receive this event
        return Archetype.empty();
    }
}

Registration

@Override
protected void start() {
    this.getEntityStoreRegistry().registerSystem(new MyCraftHandler());
}

Required Imports (EcsEvent)

import com.hypixel.hytale.component.ArchetypeChunk;
import com.hypixel.hytale.component.CommandBuffer;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.component.Store;
import com.hypixel.hytale.component.query.Archetype;
import com.hypixel.hytale.component.query.Query;
import com.hypixel.hytale.component.system.EntityEventSystem;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import javax.annotation.Nonnull;

CancellableEcsEvent Types

These events extend CancellableEcsEvent and support setCancelled(true):

Event	Sub-Events	Description
`BreakBlockEvent`	—	Player breaking a block
`PlaceBlockEvent`	—	Player placing a block
`ChangeGameModeEvent`	—	Game mode change
`ChunkSaveEvent`	—	Chunk saving
`ChunkUnloadEvent`	—	Chunk unloading
`CraftRecipeEvent`	`.Pre`, `.Post`	Recipe crafted (Pre = before, Post = after)
`Damage`	—	Entity taking damage
`DamageBlockEvent`	—	Block being damaged
`DropItemEvent`	`.Drop`, `.PlayerRequest`	Item dropped
`InteractivelyPickupItemEvent`	—	Player picking up an item
`PrefabPasteEvent`	—	Prefab being pasted
`SwitchActiveSlotEvent`	—	Active hotbar slot switch

Non-Cancellable EcsEvent Types

Event	Sub-Events	Description
`DiscoverInstanceEvent`	`.Display`	Instance discovered
`DiscoverZoneEvent`	`.Display`	Zone discovered
`MoonPhaseChangeEvent`	—	Moon phase changed
`UseBlockEvent`	`.Pre`, `.Post`	Block used (Pre = before, Post = after)

Special Pattern: Death Events

Player/entity death uses a specialized system extending DeathSystems.OnDeathSystem (a RefChangeSystem under the hood).

Death System Example

import com.hypixel.hytale.component.CommandBuffer;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.component.Store;
import com.hypixel.hytale.component.query.Query;
import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.server.core.entity.entities.Player;
import com.hypixel.hytale.server.core.modules.entity.damage.Damage;
import com.hypixel.hytale.server.core.modules.entity.damage.DeathComponent;
import com.hypixel.hytale.server.core.modules.entity.damage.DeathSystems;
import com.hypixel.hytale.server.core.universe.Universe;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import javax.annotation.Nonnull;

public class PlayerDeathHandler extends DeathSystems.OnDeathSystem {

    @Nonnull
    @Override
    public Query<EntityStore> getQuery() {
        // Only process player deaths
        return Query.and(Player.getComponentType());
    }

    @Override
    public void onComponentAdded(
            @Nonnull Ref ref,
            @Nonnull DeathComponent component,
            @Nonnull Store store,
            @Nonnull CommandBuffer commandBuffer) {

        Player playerComponent = (Player) store.getComponent(ref, Player.getComponentType());
        assert playerComponent != null;

        Universe.get().sendMessage(
            Message.raw("Player died: " + playerComponent.getDisplayName()));

        // Access death damage info
        Damage deathInfo = component.getDeathInfo();
        if (deathInfo != null) {
            Universe.get().sendMessage(
                Message.raw("Damage amount: " + deathInfo.getAmount()));
        }
    }
}

Death System Registration

@Override
protected void start() {
    this.getEntityStoreRegistry().registerSystem(new PlayerDeathHandler());
}

Complete Plugin Example

A full plugin demonstrating all three event categories:

import com.hypixel.hytale.server.core.event.events.player.PlayerChatEvent;
import com.hypixel.hytale.server.core.event.events.player.PlayerDisconnectEvent;
import com.hypixel.hytale.server.core.event.events.player.PlayerReadyEvent;
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
import javax.annotation.Nonnull;

public class MyPlugin extends JavaPlugin {

    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
    }

    @Override
    protected void setup() {
        // IEvent — global events
        this.getEventRegistry().registerGlobal(PlayerReadyEvent.class,
            EventHandlers::onPlayerReady);
        this.getEventRegistry().registerGlobal(PlayerDisconnectEvent.class,
            EventHandlers::onPlayerDisconnect);

        // IAsyncEvent — async events
        this.getEventRegistry().registerAsync(PlayerChatEvent.class,
            EventHandlers::onPlayerChat);
    }

    @Override
    protected void start() {
        // EcsEvent — ECS event systems
        this.getEntityStoreRegistry().registerSystem(new CraftBlocker());
        this.getEntityStoreRegistry().registerSystem(new PlayerDeathHandler());
    }
}

Common Patterns

Cancel an Event Conditionally

// CancellableEcsEvent pattern
@Override
public void handle(int index,
                   @Nonnull ArchetypeChunk<EntityStore> archetypeChunk,
                   @Nonnull Store<EntityStore> store,
                   @Nonnull CommandBuffer<EntityStore> commandBuffer,
                   @Nonnull BreakBlockEvent event) {
    // Check condition, then cancel
    if (shouldPreventBreak(event)) {
        event.setCancelled(true);
    }
}

Block Crafting by Ingredient

class BlockFibreCrafting extends EntityEventSystem<EntityStore, CraftRecipeEvent.Pre> {

    public BlockFibreCrafting() {
        super(CraftRecipeEvent.Pre.class);
    }

    @Override
    public void handle(int index,
                       @Nonnull ArchetypeChunk<EntityStore> archetypeChunk,
                       @Nonnull Store<EntityStore> store,
                       @Nonnull CommandBuffer<EntityStore> commandBuffer,
                       @Nonnull CraftRecipeEvent.Pre event) {
        CraftingRecipe recipe = event.getCraftedRecipe();
        if (recipe.getInput() != null) {
            for (MaterialQuantity mq : recipe.getInput()) {
                if (Objects.equals(mq.getItemId(), "Ingredient_Fibre")) {
                    event.setCancelled(true);
                    break;
                }
            }
        }
    }

    @Override
    public Query<EntityStore> getQuery() {
        return Archetype.empty();
    }
}

Filter Events by Entity Type

@Override
public Query<EntityStore> getQuery() {
    // Only process for entities with the Player component
    return Query.and(Player.getComponentType());
}

Access Entity Ref from EcsEvent

@Override
public void handle(int index,
                   @Nonnull ArchetypeChunk<EntityStore> archetypeChunk,
                   @Nonnull Store<EntityStore> store,
                   @Nonnull CommandBuffer<EntityStore> commandBuffer,
                   @Nonnull Damage damageEvent) {
    Ref<EntityStore> ref = archetypeChunk.getReferenceTo(index);
    // Use ref with store to access components
    Player player = (Player) store.getComponent(ref, Player.getComponentType());
}

Choosing the Right Event Type

Need	Event Category	Registration
Player joins / leaves	IEvent	`registerGlobal()` in `setup()`
Chat messages	IAsyncEvent	`registerAsync()` in `setup()`
Block break / place	EcsEvent	`registerSystem()` in `start()`
Damage / combat	EcsEvent	`registerSystem()` in `start()`
Crafting	EcsEvent	`registerSystem()` in `start()`
Item drops / pickups	EcsEvent	`registerSystem()` in `start()`
Entity death	Special (DeathSystems)	`registerSystem()` in `start()`
Server shutdown	IEvent	`registerGlobal()` in `setup()`
World lifecycle	IEvent	`registerGlobal()` in `setup()`

Best Practices

Register IEvent/IAsyncEvent in setup() and EcsEvent systems in start()
Use method references for cleaner registration: EventHandler::onPlayerReady
Keep event handler classes separate from the main plugin class for organization
Use Archetype.empty() for the query when you want to process all entities receiving the event
Use Query.and() to filter which entities your EcsEvent system processes
Check setCancelled() only on CancellableEcsEvent subclasses — non-cancellable events will not have this method
Use Pre/Post sub-events when available (e.g., CraftRecipeEvent.Pre vs .Post) to choose timing
Access entity data via Store and Ref in EcsEvent handlers — never cache entity references
Use CommandBuffer for mutations inside EcsEvent handlers (add/remove components)
Death handling uses DeathSystems.OnDeathSystem (a RefChangeSystem), not EntityEventSystem

Hytale Events

File contents

Hytale Events Skill

Quick Reference

Event Categories

IEvent — Global Events

Registration Pattern

Handler Class

Required Imports (IEvent)

Available IEvent Types

Player Events

World Events

Lifecycle Events

Asset Events

Other Events

IAsyncEvent — Asynchronous Events

Registration Pattern

Handler Example

Available IAsyncEvent Types

EcsEvent — ECS Entity/Block Events

Key Difference from IEvent

EntityEventSystem Pattern

Registration

Required Imports (EcsEvent)

CancellableEcsEvent Types

Non-Cancellable EcsEvent Types

Special Pattern: Death Events

Death System Example

Death System Registration

Complete Plugin Example

Common Patterns

Cancel an Event Conditionally

Block Crafting by Ingredient

Filter Events by Entity Type

Access Entity Ref from EcsEvent

Choosing the Right Event Type

Best Practices

Resources

Frequently asked questions