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

title, type, weight

title	type	weight
Hiérarchie des Entités	docs	1

Hytale utilise une architecture Entity Component System (ECS). Contrairement à la POO traditionnelle où les entités ont des méthodes directement sur elles, les entités Hytale sont composées de composants stockés dans un EntityStore.

{{< callout type="warning" >}} Architecture ECS: Les classes d'entités comme Player et LivingEntity sont elles-mêmes des instances de Component<EntityStore>. Les données sont accessibles via la recherche de composants, pas via des appels de méthodes directs sur les entités. {{< /callout >}}

Aperçu de la Hiérarchie de Classes

{{< 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 (Classe de Base)

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

La classe de base pour toutes les entités. Entity implémente Component<EntityStore> - elle est stockée comme composant dans le système ECS.

Méthodes Disponibles

Méthode	Type de Retour	Description	Notes
getWorld()	World	Le monde où se trouve l'entité
getUuid()	UUID	Identifiant unique	Dépréciée
wasRemoved()	boolean	Si l'entité a été supprimée
remove()	boolean	Supprimer l'entité du monde
getNetworkId()	int	ID réseau de l'entité	Dépréciée
getTransformComponent()	TransformComponent	Données de position/rotation	Dépréciée
getReference()	Ref<EntityStore>	Référence ECS

// Exemple: Accéder aux données d'entité
Entity entity = ...; // obtenue depuis un événement ou une recherche

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

    // Accès à la position (dépréciée mais fonctionne)
    TransformComponent transform = entity.getTransformComponent();
    Vector3d position = transform.getPosition();

    // Référence ECS pour l'accès aux composants
    Ref<EntityStore> ref = entity.getReference();
    if (ref != null && ref.isValid()) {
        Store<EntityStore> store = ref.getStore();
        // Accéder à d'autres composants via le store
    }
}

---

LivingEntity

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

Étend Entity avec des capacités d'inventaire. Classe de base pour les entités qui peuvent porter des objets.

Méthodes Disponibles

Méthode	Type de Retour	Description
getInventory()	Inventory	Inventaire de l'entité
setInventory(Inventory)	Inventory	Définir l'inventaire
getCurrentFallDistance()	double	Distance de chute actuelle
getStatModifiersManager()	StatModifiersManager	Modificateurs de stats

LivingEntity living = (LivingEntity) entity;

// Accès à l'inventaire
Inventory inventory = living.getInventory();

// Suivi de la distance de chute
double fallDistance = living.getCurrentFallDistance();

// Modificateurs de stats
StatModifiersManager stats = living.getStatModifiersManager();

{{< callout type="info" >}} La santé, les dégâts et les effets sont gérés via le système ECS, pas directement sur LivingEntity. Voir [Composants d'Entité]({{< relref "entity-components" >}}) pour l'accès aux données basé sur les composants. {{< /callout >}}

---

Player

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

Étend LivingEntity avec des fonctionnalités spécifiques aux joueurs.

Méthodes Disponibles

Méthode	Type de Retour	Description
sendMessage(Message)	void	Envoyer un message au joueur
hasPermission(String)	boolean	Vérifier une permission
hasPermission(String, boolean)	boolean	Vérifier avec valeur par défaut
getDisplayName()	String	Nom d'affichage du joueur
getGameMode()	GameMode	Mode de jeu actuel
getInventory()	Inventory	Inventaire du joueur
getPlayerRef()	PlayerRef	Référence thread-safe (dépréciée)
getWindowManager()	WindowManager	Gestion des fenêtres
getPageManager()	PageManager	Gestion des pages
getHudManager()	HudManager	Gestion du HUD
getHotbarManager()	HotbarManager	Gestion de la barre d'action

Player player = event.getPlayer();

if (player != null) {
    // Envoyer des messages (nécessite un objet Message)
    player.sendMessage(Message.raw("Bienvenue !"));
    player.sendMessage(Message.translation("greeting.key")
        .param("name", player.getDisplayName()));

    // Vérifier les permissions
    if (player.hasPermission("admin.teleport")) {
        // A la permission
    }

    // Obtenir le nom d'affichage
    String name = player.getDisplayName();

    // Obtenir l'inventaire
    Inventory inventory = player.getInventory();

    // Obtenir la position via TransformComponent (dépréciée)
    TransformComponent transform = player.getTransformComponent();
    Vector3d position = transform.getPosition();
}

---

PlayerRef (Référence Thread-Safe)

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

PlayerRef fournit un accès thread-safe aux données du joueur. Utilisez-le pour les opérations async ou pour stocker des références.

Méthodes Disponibles

Méthode	Type de Retour	Description
getUsername()	String	Nom d'utilisateur du joueur
getUuid()	UUID	UUID du joueur
getWorldUuid()	UUID	UUID du monde actuel
sendMessage(Message)	void	Envoyer un message
getReference()	Ref<EntityStore>	Référence ECS (peut être null)
getPacketHandler()	PacketHandler	Gestionnaire réseau

// Obtenir PlayerRef depuis l'événement
PlayerRef playerRef = event.getPlayerRef();

// Accès thread-safe aux données du joueur
String username = playerRef.getUsername();
UUID uuid = playerRef.getUuid();

// Envoyer un message (thread-safe)
playerRef.sendMessage(Message.raw("Bonjour, " + username + " !"));

// Obtenir la référence ECS pour l'accès aux composants
Ref<EntityStore> ref = playerRef.getReference();
if (ref != null && ref.isValid()) {
    Store<EntityStore> store = ref.getStore();

    // Accéder au composant Player
    Player player = store.getComponent(ref, Player.getComponentType());

    // Accéder au TransformComponent pour la position
    TransformComponent transform = store.getComponent(ref, TransformComponent.getComponentType());
    if (transform != null) {
        Vector3d position = transform.getPosition();
    }
}

---

Pattern d'Accès aux Composants ECS

La bonne façon d'accéder aux données d'entité dans l'ECS de Hytale:

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

    // Obtenir la référence ECS
    Ref<EntityStore> ref = playerRef.getReference();
    if (ref == null || !ref.isValid()) {
        return;
    }

    // Obtenir le store pour l'accès aux composants
    Store<EntityStore> store = ref.getStore();

    // Accéder à divers composants
    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("Vous êtes à : " + position.toString()));
    }
});

---

Vérification de Type & Cast

Utilisez le pattern matching pour une vérification de type sûre:

public void handleEntity(Entity entity) {
    if (entity instanceof Player player) {
        player.sendMessage(Message.raw("Vous êtes un joueur !"));

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

---

Bonnes Pratiques

{{< callout type="info" >}} Directives de Gestion des Entités:

• Toujours vérifier wasRemoved() avant d'utiliser des références d'entités stockées
• Utiliser PlayerRef pour stocker des références de joueurs entre les ticks
• Accéder à la position via TransformComponent (les méthodes dépréciées fonctionnent mais l'ECS est préféré)
• Vérifier ref.isValid() avant d'accéder aux composants ECS {{< /callout >}}

{{< callout type="warning" >}} Sécurité des Threads: Les objets Entity ne sont pas thread-safe. Utilisez PlayerRef pour les opérations async. Ne stockez jamais de références directes d'entités dans des structures de données à longue durée de vie sans nettoyage approprié. {{< /callout >}}

{{< callout type="error" >}} Critique: Ne stockez jamais de références Entity ou Player dans des champs statiques ou des maps sans nettoyage approprié. Utilisez les UUID et recherchez les entités quand nécessaire. {{< /callout >}}