Init
This commit is contained in:
259
content/world/entities/entity-hierarchy.fr.md
Normal file
259
content/world/entities/entity-hierarchy.fr.md
Normal file
@@ -0,0 +1,259 @@
|
||||
---
|
||||
title: Hiérarchie des Entités
|
||||
type: docs
|
||||
weight: 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 | |
|
||||
|
||||
```java
|
||||
// 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 |
|
||||
|
||||
```java
|
||||
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 |
|
||||
|
||||
```java
|
||||
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 |
|
||||
|
||||
```java
|
||||
// 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:
|
||||
|
||||
```java
|
||||
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:
|
||||
|
||||
```java
|
||||
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 >}}
|
||||
|
||||
Reference in New Issue
Block a user