Documentation/content/world/entities/entity-hierarchy.en.md

title, type, weight

title	type	weight
Entity Hierarchy	docs	1

Hytale uses an Entity Component System (ECS) architecture. Unlike traditional OOP where entities have methods directly on them, Hytale entities are composed of components stored in an EntityStore.

{{< callout type="warning" >}} ECS Architecture: Entity classes like Player and LivingEntity are themselves Component<EntityStore> instances. Data is accessed through component lookup, not direct method calls on entities. {{< /callout >}}

Class Hierarchy Overview

{{< filetree/container >}} {{< filetree/folder name="Entity (Component)" state="open" >}} {{< filetree/folder name="LivingEntity" state="open" >}} {{< filetree/file name="Player" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}}

---

Entity (Base Class)

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

The base class for all entities. Entity implements Component<EntityStore> - it is stored as a component in the ECS system.

Available Methods

Method	Return Type	Description	Notes
getWorld()	World	The world this entity is in
getUuid()	UUID	Unique identifier	Deprecated
wasRemoved()	boolean	Whether entity was removed
remove()	boolean	Remove entity from world
getNetworkId()	int	Network ID for this entity	Deprecated
getTransformComponent()	TransformComponent	Position/rotation data	Deprecated
getReference()	Ref<EntityStore>	ECS reference

// Example: Accessing entity data
Entity entity = ...; // obtained from event or lookup

if (!entity.wasRemoved()) {
    World world = entity.getWorld();

    // Position access (deprecated but works)
    TransformComponent transform = entity.getTransformComponent();
    Vector3d position = transform.getPosition();

    // ECS reference for component access
    Ref<EntityStore> ref = entity.getReference();
    if (ref != null && ref.isValid()) {
        Store<EntityStore> store = ref.getStore();
        // Access other components via store
    }
}

---

LivingEntity

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

Extends Entity with inventory capabilities. Base class for entities that can hold items.

Available Methods

Method	Return Type	Description
getInventory()	Inventory	Entity's inventory
setInventory(Inventory)	Inventory	Set inventory
getCurrentFallDistance()	double	Current fall distance
getStatModifiersManager()	StatModifiersManager	Stat modifiers

LivingEntity living = (LivingEntity) entity;

// Inventory access
Inventory inventory = living.getInventory();

// Fall distance tracking
double fallDistance = living.getCurrentFallDistance();

// Stat modifiers
StatModifiersManager stats = living.getStatModifiersManager();

{{< callout type="info" >}} Health, damage, and effects are managed through the ECS system, not directly on LivingEntity. See [Entity Components]({{< relref "entity-components" >}}) for component-based data access. {{< /callout >}}

---

Player

Package: com.hypixel.hytale.server.core.entity.entities

Extends LivingEntity with player-specific features.

Available Methods

Method	Return Type	Description
sendMessage(Message)	void	Send message to player
hasPermission(String)	boolean	Check permission
hasPermission(String, boolean)	boolean	Check with default
getDisplayName()	String	Player display name
getGameMode()	GameMode	Current game mode
getInventory()	Inventory	Player inventory
getPlayerRef()	PlayerRef	Thread-safe reference (deprecated)
getWindowManager()	WindowManager	Window management
getPageManager()	PageManager	Page management
getHudManager()	HudManager	HUD management
getHotbarManager()	HotbarManager	Hotbar management

Player player = event.getPlayer();

if (player != null) {
    // Send messages (requires Message object)
    player.sendMessage(Message.raw("Welcome!"));
    player.sendMessage(Message.translation("greeting.key")
        .param("name", player.getDisplayName()));

    // Check permissions
    if (player.hasPermission("admin.teleport")) {
        // Has permission
    }

    // Get display name
    String name = player.getDisplayName();

    // Get inventory
    Inventory inventory = player.getInventory();

    // Get position via TransformComponent (deprecated)
    TransformComponent transform = player.getTransformComponent();
    Vector3d position = transform.getPosition();
}

---

PlayerRef (Thread-Safe Reference)

Package: com.hypixel.hytale.server.core.universe

PlayerRef provides thread-safe access to player data. Use it for async operations or storing references.

Available Methods

Method	Return Type	Description
getUsername()	String	Player username
getUuid()	UUID	Player UUID
getWorldUuid()	UUID	Current world UUID
sendMessage(Message)	void	Send message
getReference()	Ref<EntityStore>	ECS reference (may be null)
getPacketHandler()	PacketHandler	Network handler

// Get PlayerRef from event
PlayerRef playerRef = event.getPlayerRef();

// Thread-safe access to player data
String username = playerRef.getUsername();
UUID uuid = playerRef.getUuid();

// Send message (thread-safe)
playerRef.sendMessage(Message.raw("Hello, " + username + "!"));

// Get ECS reference for component access
Ref<EntityStore> ref = playerRef.getReference();
if (ref != null && ref.isValid()) {
    Store<EntityStore> store = ref.getStore();

    // Access Player component
    Player player = store.getComponent(ref, Player.getComponentType());

    // Access TransformComponent for position
    TransformComponent transform = store.getComponent(ref, TransformComponent.getComponentType());
    if (transform != null) {
        Vector3d position = transform.getPosition();
    }
}

---

ECS Component Access Pattern

The correct way to access entity data in Hytale's ECS:

getEventRegistry().register(PlayerConnectEvent.class, event -> {
    PlayerRef playerRef = event.getPlayerRef();

    // Get ECS reference
    Ref<EntityStore> ref = playerRef.getReference();
    if (ref == null || !ref.isValid()) {
        return;
    }

    // Get store for component access
    Store<EntityStore> store = ref.getStore();

    // Access various components
    Player player = store.getComponent(ref, Player.getComponentType());
    TransformComponent transform = store.getComponent(ref, TransformComponent.getComponentType());

    if (player != null && transform != null) {
        Vector3d position = transform.getPosition();
        player.sendMessage(Message.raw("You are at: " + position.toString()));
    }
});

---

Type Checking & Casting

Use pattern matching for safe type checking:

public void handleEntity(Entity entity) {
    if (entity instanceof Player player) {
        player.sendMessage(Message.raw("You're a player!"));

    } else if (entity instanceof LivingEntity living) {
        Inventory inv = living.getInventory();
    }
}

---

Best Practices

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

• Always check wasRemoved() before using stored entity references
• Use PlayerRef for storing player references across ticks
• Access position via TransformComponent (deprecated methods work but ECS is preferred)
• Check ref.isValid() before accessing ECS components {{< /callout >}}

{{< callout type="warning" >}} Thread Safety: Entity objects are not thread-safe. Use PlayerRef for async operations. Never store direct entity references in long-lived data structures without proper cleanup. {{< /callout >}}

{{< callout type="error" >}} Critical: Never store Entity or Player references in static fields or maps without proper cleanup. Use UUIDs and look up entities when needed. {{< /callout >}}