Documentation/content/core-concepts/events/event-reference/entity-events.en.md

title, type, weight

title	type	weight
Entity Events	docs	2

Events triggered by entity actions and state changes. These events apply to entities in the game world.

{{< callout type="warning" >}} Note: Hytale's entity event system is minimal compared to other game APIs. Most entity-related logic is handled through the ECS (Entity Component System) rather than traditional events. For block interactions, item drops, and crafting, see Block Events. {{< /callout >}}

Entity Lifecycle Events

EntityRemoveEvent

Fired when an entity is removed from the world.

Package: com.hypixel.hytale.server.core.event.events.entity

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
entity	Entity	The entity being removed
{{< /tab >}}
{{< tab >}}

• getEntity() - Returns the Entity object being removed {{< /tab >}} {{< tab >}}

getEventRegistry().register(EntityRemoveEvent.class, event -> {
    Entity entity = event.getEntity();

    // Clean up any custom data associated with this entity
    if (trackedEntities.contains(entity.getUuid())) {
        trackedEntities.remove(entity.getUuid());
        getLogger().at(Level.INFO).log("Tracked entity removed: " + entity.getType().getId());
    }
});

{{< /tab >}} {{< /tabs >}}

---

Living Entity Events

LivingEntityInventoryChangeEvent

Fired when a living entity's inventory changes.

Package: com.hypixel.hytale.server.core.event.events.entity

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
entity	LivingEntity	The entity whose inventory changed
itemContainer	ItemContainer	The item container that changed
transaction	Transaction	The transaction that occurred
{{< /tab >}}
{{< tab >}}

• getEntity() - Returns the LivingEntity
• getItemContainer() - Returns the ItemContainer that changed
• getTransaction() - Returns the Transaction details {{< /tab >}} {{< tab >}}

getEventRegistry().register(LivingEntityInventoryChangeEvent.class, event -> {
    LivingEntity entity = event.getEntity();
    ItemContainer container = event.getItemContainer();
    Transaction transaction = event.getTransaction();

    // Log inventory changes for debugging
    getLogger().at(Level.INFO).log("Inventory changed for: " + entity.getType().getId());
    getLogger().at(Level.INFO).log("Container: " + container);
    getLogger().at(Level.INFO).log("Transaction: " + transaction);
});

{{< /tab >}} {{< /tabs >}}

---

LivingEntityUseBlockEvent

{{< badge "Deprecated" >}}

Fired when a living entity uses a block. This event is deprecated and marked for removal.

Package: com.hypixel.hytale.server.core.event.events.entity

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
ref	Ref<EntityStore>	Reference to the entity store
blockType	String	The type of block being used
{{< /tab >}}
{{< tab >}}

• getRef() - Returns the entity store reference
• getBlockType() - Returns the block type string {{< /tab >}} {{< tab >}}

// Note: This event is deprecated. Use UseBlockEvent instead.
getEventRegistry().register(LivingEntityUseBlockEvent.class, event -> {
    String blockType = event.getBlockType();
    Ref<EntityStore> ref = event.getRef();

    getLogger().at(Level.INFO).log("Entity used block: " + blockType);
});

{{< /tab >}} {{< /tabs >}}

{{< callout type="warning" >}} Deprecated: This event is marked for removal. Use UseBlockEvent.Pre and UseBlockEvent.Post from the ECS event system instead. See Block Events for the modern alternative. {{< /callout >}}

---

Working with Entities

Entity Component System (ECS)

Hytale uses an Entity Component System architecture. Instead of traditional entity events, much of the entity behavior is handled through components and the ECS event system.

For entity-related operations, consider using:

• ECS Events for block interactions, item management, and game mode changes
• Entity Components for entity state and behavior
• EntityStore for entity data persistence

Example: Tracking Entities

public class EntityTrackerPlugin extends JavaPlugin {

    private final Set<UUID> trackedEntities = new HashSet<>();

    @Override
    public void start() {
        // Track entity removal
        getEventRegistry().register(EntityRemoveEvent.class, event -> {
            Entity entity = event.getEntity();

            if (trackedEntities.remove(entity.getUuid())) {
                getLogger().at(Level.INFO).log("Tracked entity removed: " + entity.getUuid());
                onEntityRemoved(entity);
            }
        });

        // Track inventory changes
        getEventRegistry().register(LivingEntityInventoryChangeEvent.class, event -> {
            LivingEntity entity = event.getEntity();

            if (trackedEntities.contains(entity.getUuid())) {
                onInventoryChanged(entity, event.getTransaction());
            }
        });
    }

    public void trackEntity(Entity entity) {
        trackedEntities.add(entity.getUuid());
        getLogger().at(Level.INFO).log("Now tracking entity: " + entity.getUuid());
    }

    private void onEntityRemoved(Entity entity) {
        // Custom cleanup logic
    }

    private void onInventoryChanged(LivingEntity entity, Transaction transaction) {
        // React to inventory changes
    }
}

Best Practices

{{< callout type="info" >}} Entity Event Guidelines:

• Entity events in Hytale are minimal - prefer ECS patterns for complex behavior
• Use EntityRemoveEvent for cleanup when entities are removed
• LivingEntityUseBlockEvent is deprecated - migrate to UseBlockEvent
• For player-specific entity events, see Player Events
• For block and item interactions, see Block Events {{< /callout >}}

{{< callout type="tip" >}} Migration Note: If you're coming from Minecraft/Bukkit development, note that Hytale doesn't have traditional EntityDamageEvent, EntityDeathEvent, or EntitySpawnEvent. Entity lifecycle and combat are handled differently through the ECS architecture. {{< /callout >}}