Init

content/world/entities/flocking-behavior.fr.md

@@ -0,0 +1,302 @@
+---
+title: Comportement de Groupe
+type: docs
+weight: 10
+---
+
+Le systeme de groupe (flock) permet aux NPCs de former et se comporter comme des unites coordonnees.
+
+**Package:** `com.hypixel.hytale.server.flock`
+
+## Apercu
+
+Les groupes sont des ensembles bases sur des entites qui permettent aux NPCs de:
+- Se deplacer et agir comme une unite coordonnee
+- Partager les informations de degats entre membres
+- Apparaitre en tailles de groupe configurables
+- Avoir des leaders designes
+
+## Architecture
+
+```
+Systeme Groupe
+├── Composants
+│   ├── Flock - Composant entite groupe
+│   ├── FlockMembership - Reference membre
+│   └── PersistentFlockData - Donnees groupe sauvegardees
+├── Assets
+│   ├── FlockAsset - Configuration groupe
+│   ├── RangeSizeFlockAsset - Taille par plage
+│   └── WeightedSizeFlockAsset - Taille ponderee
+├── Systemes
+│   ├── FlockSystems - Logique groupe principale
+│   ├── FlockMembershipSystems - Gestion membres
+│   └── FlockDeathSystems - Gestion mort
+└── Composants NPC
+    ├── BodyMotionFlock - Comportement mouvement
+    ├── ActionFlockJoin/Leave - Actions joindre/quitter
+    └── SensorFlockLeader - Detection leader
+```
+
+## Composant Flock
+
+L'entite groupe contient l'etat partage:
+
+```java
+public class Flock implements Component<EntityStore> {
+    // Donnees degats partagees pour coordination combat
+    private DamageData currentDamageData;
+    private DamageData nextDamageData;
+
+    // Donnees degats specifiques leader
+    private DamageData currentLeaderDamageData;
+    private DamageData nextLeaderDamageData;
+
+    // Configuration groupe persistante
+    private PersistentFlockData flockData;
+
+    // Statut de suppression
+    public enum FlockRemovedStatus {
+        NOT_REMOVED,
+        DISSOLVED,
+        UNLOADED
+    }
+}
+```
+
+## Composant FlockMembership
+
+Chaque NPC membre a un composant d'appartenance:
+
+```java
+public class FlockMembership implements Component<EntityStore> {
+    // Reference vers l'entite groupe
+    private Ref<EntityStore> flockRef;
+}
+```
+
+## Creation de Groupes
+
+### Spawn avec Groupe
+
+```java
+// Faire apparaitre un NPC avec son groupe
+Ref<EntityStore> flockRef = FlockPlugin.trySpawnFlock(
+    npcRef,           // Reference NPC initial
+    npc,              // Composant NPC
+    store,            // Store entite
+    roleIndex,        // Index role NPC
+    position,         // Position spawn
+    rotation,         // Rotation spawn
+    flockDefinition,  // Config FlockAsset (determine taille)
+    postSpawnCallback // Appele pour chaque membre spawne
+);
+```
+
+### Creer Groupe Vide
+
+```java
+// Creer entite groupe pour gestion manuelle des membres
+Ref<EntityStore> flockRef = FlockPlugin.createFlock(store, role);
+
+// Ou avec configuration explicite
+Ref<EntityStore> flockRef = FlockPlugin.createFlock(
+    store,
+    flockAsset,       // Configuration FlockAsset
+    allowedRoles      // Roles pouvant rejoindre
+);
+```
+
+### Rejoindre Groupe Existant
+
+```java
+// Ajouter NPC a groupe existant
+FlockMembershipSystems.join(npcRef, flockRef, store);
+```
+
+## Assets de Groupe
+
+### FlockAsset
+
+Configuration de base pour groupes:
+
+```java
+public class FlockAsset {
+    // Identifiant asset
+    private String id;
+
+    // Choisir taille groupe pour spawn
+    public abstract int pickFlockSize();
+}
+```
+
+### RangeSizeFlockAsset
+
+Groupe avec taille aleatoire dans plage:
+
+```json
+{
+  "Type": "RangeSize",
+  "Id": "wolf_pack",
+  "MinSize": 3,
+  "MaxSize": 8
+}
+```
+
+### WeightedSizeFlockAsset
+
+Groupe avec taille aleatoire ponderee:
+
+```json
+{
+  "Type": "WeightedSize",
+  "Id": "deer_herd",
+  "Sizes": [
+    { "Size": 2, "Weight": 1 },
+    { "Size": 4, "Weight": 2 },
+    { "Size": 6, "Weight": 1 }
+  ]
+}
+```
+
+## Composants Core NPC
+
+### BodyMotionFlock
+
+Controle comportement mouvement de groupe:
+
+```json
+{
+  "Type": "Flock",
+  "SeparationWeight": 1.5,
+  "AlignmentWeight": 1.0,
+  "CohesionWeight": 1.0
+}
+```
+
+### ActionFlockJoin
+
+Rejoindre un groupe:
+
+```json
+{
+  "Type": "JoinFlock",
+  "FlockId": "wolf_pack"
+}
+```
+
+### ActionFlockLeave
+
+Quitter groupe actuel:
+
+```json
+{
+  "Type": "LeaveFlock"
+}
+```
+
+### SensorFlockLeader
+
+Detecter leader du groupe:
+
+```json
+{
+  "Type": "FlockLeader",
+  "Output": "leader_ref"
+}
+```
+
+### EntityFilterFlock
+
+Filtrer entites par appartenance groupe:
+
+```json
+{
+  "Type": "Flock",
+  "IncludeSelf": false,
+  "OnlyMembers": true
+}
+```
+
+## Partage de Degats
+
+Les groupes partagent informations de combat:
+
+```java
+// Obtenir donnees degats du groupe
+Flock flock = store.getComponent(flockRef, Flock.getComponentType());
+DamageData damageData = flock.getDamageData();
+
+// Suivre kills pour le groupe
+flock.onTargetKilled(componentAccessor, targetRef);
+```
+
+### Double Buffering
+
+Les donnees de degats utilisent double buffering pour eviter conditions de course:
+
+```java
+// Appele chaque tick
+flock.swapDamageDataBuffers();
+// currentDamageData contient donnees du tick precedent
+// nextDamageData accumule donnees du tick actuel
+```
+
+## Conditions
+
+### FlockSizeCondition
+
+Verifier taille groupe dans prise de decision:
+
+```json
+{
+  "Type": "FlockSize",
+  "Min": 2,
+  "Max": 10
+}
+```
+
+## Acces au Plugin
+
+```java
+FlockPlugin flockPlugin = FlockPlugin.get();
+
+// Types de composants
+ComponentType<EntityStore, Flock> flockType =
+    flockPlugin.getFlockComponentType();
+ComponentType<EntityStore, FlockMembership> membershipType =
+    flockPlugin.getFlockMembershipComponentType();
+ComponentType<EntityStore, PersistentFlockData> dataType =
+    flockPlugin.getPersistentFlockDataComponentType();
+```
+
+## Methodes Utilitaires
+
+```java
+// Verifier si entite dans un groupe
+boolean isMember = FlockPlugin.isFlockMember(npcRef, store);
+
+// Obtenir reference groupe depuis entite
+Ref<EntityStore> flockRef = FlockPlugin.getFlockReference(npcRef, store);
+
+// Obtenir composant groupe depuis entite
+Flock flock = FlockPlugin.getFlock(store, npcRef);
+```
+
+## Comportement de Spawn des Groupes
+
+Lors du spawn d'un groupe:
+1. NPC initial est cree
+2. Entite groupe est creee avec appartenance
+3. Membres additionnels spawn au meme emplacement
+4. Membres se dispersent avec leger offset aleatoire
+5. Chaque membre rejoint le groupe
+
+```java
+// Membres spawn avec offset aleatoire
+memberTransform.getPosition().assign(
+    x + RandomExtra.randomRange(-0.5, 0.5),
+    offsetY,
+    z + RandomExtra.randomRange(-0.5, 0.5)
+);
+```