Init
This commit is contained in:
193
content/core-concepts/events/event-reference/entity-events.en.md
Normal file
193
content/core-concepts/events/event-reference/entity-events.en.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
title: Entity Events
|
||||
type: docs
|
||||
weight: 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](../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 >}}
|
||||
```java
|
||||
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 >}}
|
||||
```java
|
||||
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 >}}
|
||||
```java
|
||||
// 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](../block-events#useblockevent) 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
|
||||
|
||||
```java
|
||||
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](../player-events)
|
||||
- For block and item interactions, see [Block Events](../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 >}}
|
||||
Reference in New Issue
Block a user