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

title, type, weight

title	type	weight
Comportement de Groupe	docs	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:

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:

public class FlockMembership implements Component<EntityStore> {
    // Reference vers l'entite groupe
    private Ref<EntityStore> flockRef;
}

Creation de Groupes

Spawn avec Groupe

// 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

// 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

// Ajouter NPC a groupe existant
FlockMembershipSystems.join(npcRef, flockRef, store);

Assets de Groupe

FlockAsset

Configuration de base pour groupes:

public class FlockAsset {
    // Identifiant asset
    private String id;

    // Choisir taille groupe pour spawn
    public abstract int pickFlockSize();
}

RangeSizeFlockAsset

Groupe avec taille aleatoire dans plage:

{
  "Type": "RangeSize",
  "Id": "wolf_pack",
  "MinSize": 3,
  "MaxSize": 8
}

WeightedSizeFlockAsset

Groupe avec taille aleatoire ponderee:

{
  "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:

{
  "Type": "Flock",
  "SeparationWeight": 1.5,
  "AlignmentWeight": 1.0,
  "CohesionWeight": 1.0
}

ActionFlockJoin

Rejoindre un groupe:

{
  "Type": "JoinFlock",
  "FlockId": "wolf_pack"
}

ActionFlockLeave

Quitter groupe actuel:

{
  "Type": "LeaveFlock"
}

SensorFlockLeader

Detecter leader du groupe:

{
  "Type": "FlockLeader",
  "Output": "leader_ref"
}

EntityFilterFlock

Filtrer entites par appartenance groupe:

{
  "Type": "Flock",
  "IncludeSelf": false,
  "OnlyMembers": true
}

Partage de Degats

Les groupes partagent informations de combat:

// 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:

// 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:

{
  "Type": "FlockSize",
  "Min": 2,
  "Max": 10
}

Acces au Plugin

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

// 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

// Membres spawn avec offset aleatoire
memberTransform.getPosition().assign(
    x + RandomExtra.randomRange(-0.5, 0.5),
    offsetY,
    z + RandomExtra.randomRange(-0.5, 0.5)
);