Init

2026-01-20 20:33:59 +01:00
commit b16a40e431
583 changed files with 87339 additions and 0 deletions
--- a/content/world/entities/npc/npc-ai.fr.md
+++ b/content/world/entities/npc/npc-ai.fr.md
@@ -0,0 +1,373 @@
+---
+title: IA NPC
+type: docs
+weight: 3
+---
+
+Le système d'IA NPC fournit une prise de décision intelligente via les blackboards, decision makers, capteurs et instructions.
+
+**Packages:**
+- `com.hypixel.hytale.server.npc.blackboard`
+- `com.hypixel.hytale.server.npc.decisionmaker`
+- `com.hypixel.hytale.server.npc.sensorinfo`
+- `com.hypixel.hytale.server.npc.instructions`
+
+## Système Blackboard
+
+Le Blackboard est un espace mémoire partagé où les composants NPC communiquent via des paires clé-valeur.
+
+### Classe Blackboard
+
+```java
+public class Blackboard {
+    private Map<BlackboardKey<?>, Object> data;
+
+    // Stocker une valeur
+    public <T> void set(BlackboardKey<T> key, T value);
+
+    // Récupérer une valeur
+    public <T> T get(BlackboardKey<T> key);
+    public <T> T getOrDefault(BlackboardKey<T> key, T defaultValue);
+
+    // Vérifier l'existence
+    public boolean has(BlackboardKey<?> key);
+
+    // Supprimer une valeur
+    public void remove(BlackboardKey<?> key);
+
+    // Tout effacer
+    public void clear();
+}
+```
+
+### BlackboardKey
+
+Clés typées pour l'accès au blackboard :
+
+```java
+// Clés prédéfinies
+public class BlackboardKeys {
+    public static final BlackboardKey<Entity> TARGET =
+        new BlackboardKey<>("target", Entity.class);
+    public static final BlackboardKey<Vector3d> HOME_POSITION =
+        new BlackboardKey<>("home_position", Vector3d.class);
+    public static final BlackboardKey<Float> ALERT_LEVEL =
+        new BlackboardKey<>("alert_level", Float.class);
+    public static final BlackboardKey<Boolean> IN_COMBAT =
+        new BlackboardKey<>("in_combat", Boolean.class);
+}
+
+// Clés personnalisées
+BlackboardKey<String> CUSTOM_KEY = new BlackboardKey<>("custom_data", String.class);
+```
+
+### Utiliser le Blackboard
+
+```java
+NPCEntity npc = // obtenir le NPC
+Blackboard bb = npc.getBlackboard();
+
+// Définir la cible
+bb.set(BlackboardKeys.TARGET, targetEntity);
+
+// Obtenir la position d'origine
+Vector3d home = bb.getOrDefault(BlackboardKeys.HOME_POSITION, npc.getPosition());
+
+// Vérifier le statut de combat
+if (bb.getOrDefault(BlackboardKeys.IN_COMBAT, false)) {
+    // Gérer le combat
+}
+```
+
+## Système Decision Maker
+
+Le Decision Maker évalue les options et sélectionne la meilleure action pour le NPC.
+
+### Interface DecisionMaker
+
+```java
+public interface DecisionMaker {
+    // Évaluer et sélectionner la meilleure option
+    Option evaluate(NPCEntity npc, Blackboard blackboard);
+
+    // Obtenir toutes les options disponibles
+    List<Option> getOptions();
+
+    // Ajouter une option
+    void addOption(Option option);
+}
+```
+
+### Classe Option
+
+Les options représentent les actions possibles :
+
+```java
+public class Option {
+    private String id;
+    private Evaluator evaluator;
+    private Action action;
+    private float basePriority;
+
+    // Calculer le score selon le contexte
+    public float evaluate(NPCEntity npc, Blackboard blackboard);
+
+    // Exécuter l'action
+    public void execute(NPCEntity npc, Blackboard blackboard);
+}
+```
+
+### Interface Evaluator
+
+Les évaluateurs calculent les scores des options :
+
+```java
+public interface Evaluator {
+    // Retourne un score de 0.0 à 1.0
+    float evaluate(NPCEntity npc, Blackboard blackboard);
+}
+
+// Évaluateurs intégrés
+public class Evaluators {
+    // Retourne 1.0 si une cible existe
+    public static final Evaluator HAS_TARGET = (npc, bb) ->
+        bb.has(BlackboardKeys.TARGET) ? 1.0f : 0.0f;
+
+    // Retourne le pourcentage de vie
+    public static final Evaluator HEALTH_PERCENT = (npc, bb) ->
+        npc.getHealth() / npc.getMaxHealth();
+
+    // Retourne 1.0 si à la maison
+    public static final Evaluator AT_HOME = (npc, bb) -> {
+        Vector3d home = bb.get(BlackboardKeys.HOME_POSITION);
+        return npc.getPosition().distance(home) < 5.0 ? 1.0f : 0.0f;
+    };
+}
+```
+
+### Créer un Decision Maker
+
+```java
+DecisionMaker dm = new StandardDecisionMaker();
+
+// Ajouter option d'attaque
+dm.addOption(new Option(
+    "attack",
+    Evaluators.HAS_TARGET,
+    new AttackAction(),
+    10.0f  // Haute priorité
+));
+
+// Ajouter option de fuite
+dm.addOption(new Option(
+    "flee",
+    (npc, bb) -> npc.getHealth() < 20 ? 1.0f : 0.0f,
+    new FleeAction(),
+    15.0f  // Priorité plus haute quand déclenché
+));
+
+// Ajouter option d'errance
+dm.addOption(new Option(
+    "wander",
+    (npc, bb) -> 0.3f,  // Score constant bas
+    new WanderAction(),
+    1.0f   // Basse priorité par défaut
+));
+
+npc.setDecisionMaker(dm);
+```
+
+## Système de Capteurs
+
+Les capteurs collectent des informations sur le monde et mettent à jour le blackboard.
+
+### Interface Sensor
+
+```java
+public interface Sensor {
+    // Traiter l'entrée du capteur
+    void sense(NPCEntity npc, Blackboard blackboard, float deltaTime);
+
+    // Obtenir le type de capteur
+    String getSensorType();
+}
+```
+
+### Classes SensorInfo
+
+Conteneurs d'informations de capteurs :
+
+```java
+// Info de détection visuelle
+public class VisualSensorInfo {
+    private List<Entity> visibleEntities;
+    private float detectionRange;
+    private float fieldOfView;
+
+    public List<Entity> getVisibleEntities();
+    public boolean canSee(Entity entity);
+}
+
+// Info de détection audio
+public class AudioSensorInfo {
+    private List<SoundEvent> heardSounds;
+    private float hearingRange;
+
+    public List<SoundEvent> getHeardSounds();
+    public Vector3d getLoudestSoundPosition();
+}
+
+// Info de détection de menace
+public class ThreatSensorInfo {
+    private List<Entity> threats;
+    private Entity primaryThreat;
+    private float threatLevel;
+}
+```
+
+### Capteurs Intégrés
+
+```java
+// Capteur visuel - détecte les entités visibles
+public class VisualSensor implements Sensor {
+    private float range = 20.0f;
+    private float fov = 120.0f;  // degrés
+
+    @Override
+    public void sense(NPCEntity npc, Blackboard bb, float dt) {
+        List<Entity> visible = findVisibleEntities(npc);
+        bb.set(BlackboardKeys.VISIBLE_ENTITIES, visible);
+    }
+}
+
+// Capteur de proximité - détecte les entités proches
+public class ProximitySensor implements Sensor {
+    private float range = 5.0f;
+
+    @Override
+    public void sense(NPCEntity npc, Blackboard bb, float dt) {
+        List<Entity> nearby = findNearbyEntities(npc, range);
+        bb.set(BlackboardKeys.NEARBY_ENTITIES, nearby);
+    }
+}
+
+// Capteur de dégâts - réagit aux dégâts subis
+public class DamageSensor implements Sensor {
+    @Override
+    public void sense(NPCEntity npc, Blackboard bb, float dt) {
+        if (npc.wasRecentlyDamaged()) {
+            bb.set(BlackboardKeys.LAST_ATTACKER, npc.getLastAttacker());
+            bb.set(BlackboardKeys.ALERT_LEVEL, 1.0f);
+        }
+    }
+}
+```
+
+## Système d'Instructions
+
+Les instructions définissent des objectifs comportementaux de haut niveau.
+
+### Interface Instruction
+
+```java
+public interface Instruction {
+    // Vérifier si l'instruction doit s'activer
+    boolean shouldActivate(NPCEntity npc, Blackboard blackboard);
+
+    // Exécuter la logique de l'instruction
+    void execute(NPCEntity npc, Blackboard blackboard, float deltaTime);
+
+    // Vérifier si l'instruction est complète
+    boolean isComplete(NPCEntity npc, Blackboard blackboard);
+
+    // Obtenir la priorité
+    float getPriority();
+}
+```
+
+### Instructions Intégrées
+
+```java
+// Instruction d'errance
+public class WanderInstruction implements Instruction {
+    private float wanderRadius;
+    private float minWaitTime;
+    private float maxWaitTime;
+
+    @Override
+    public boolean shouldActivate(NPCEntity npc, Blackboard bb) {
+        return !bb.has(BlackboardKeys.TARGET);
+    }
+}
+
+// Instruction de garde
+public class GuardInstruction implements Instruction {
+    private Vector3d guardPosition;
+    private float guardRadius;
+
+    @Override
+    public void execute(NPCEntity npc, Blackboard bb, float dt) {
+        if (npc.getPosition().distance(guardPosition) > guardRadius) {
+            bb.set(BlackboardKeys.MOVE_TARGET, guardPosition);
+        }
+    }
+}
+
+// Instruction de suivi
+public class FollowInstruction implements Instruction {
+    private Entity followTarget;
+    private float followDistance;
+}
+
+// Instruction de patrouille
+public class PatrolInstruction implements Instruction {
+    private List<Vector3d> patrolPoints;
+    private int currentPoint;
+}
+```
+
+## Combiner les Systèmes d'IA
+
+```java
+public void setupNPCAI(NPCEntity npc) {
+    // Configurer le blackboard
+    Blackboard bb = npc.getBlackboard();
+    bb.set(BlackboardKeys.HOME_POSITION, npc.getPosition());
+    bb.set(BlackboardKeys.AGGRO_RANGE, 15.0f);
+
+    // Ajouter les capteurs
+    npc.addSensor(new VisualSensor(20.0f, 120.0f));
+    npc.addSensor(new ProximitySensor(5.0f));
+    npc.addSensor(new DamageSensor());
+
+    // Configurer le decision maker
+    DecisionMaker dm = new StandardDecisionMaker();
+    dm.addOption(new Option("attack", hasHostileTarget, attackAction, 10.0f));
+    dm.addOption(new Option("flee", lowHealth, fleeAction, 15.0f));
+    dm.addOption(new Option("patrol", isGuard, patrolAction, 5.0f));
+    dm.addOption(new Option("idle", always, idleAction, 1.0f));
+    npc.setDecisionMaker(dm);
+
+    // Ajouter les instructions
+    npc.addInstruction(new GuardInstruction(guardPost, 10.0f));
+    npc.addInstruction(new ReactToThreatInstruction());
+}
+```
+
+## Bonnes Pratiques
+
+{{< callout type="info" >}}
+**Directives IA :**
+- Utilisez le Blackboard pour toute communication inter-composants
+- Gardez les Évaluateurs simples et rapides - ils s'exécutent fréquemment
+- Utilisez des portées de capteurs appropriées pour équilibrer conscience vs performance
+- Concevez les Instructions pour être interruptibles
+- Testez le comportement IA avec différents scénarios
+{{< /callout >}}
+
+{{< callout type="warning" >}}
+**Performance :** Un grand nombre de NPCs avec une IA complexe peut impacter les performances. Considérez :
+- Réduire la fréquence de mise à jour des capteurs pour les NPCs distants
+- Utiliser le LOD (Level of Detail) pour la complexité IA
+- Limiter les requêtes de pathfinding
+{{< /callout >}}