Init

content/world/entities/npc/npc-basics.fr.md

@@ -0,0 +1,217 @@
+---
+title: Bases NPC
+type: docs
+weight: 1
+---
+
+Ce guide couvre les fondamentaux de la création et de la configuration des NPCs dans Hytale.
+
+**Package:** `com.hypixel.hytale.server.npc`
+
+## Classe NPCEntity
+
+`NPCEntity` est la classe de base pour tous les personnages non-joueurs. Elle étend la hiérarchie d'entités et fournit des fonctionnalités spécifiques aux NPCs.
+
+```java
+public class NPCEntity extends LivingEntity {
+    // Fonctionnalités NPC de base
+    private Blackboard blackboard;
+    private Role role;
+    private DecisionMaker decisionMaker;
+    private MotionController motionController;
+}
+```
+
+### Créer un NPC
+
+Les NPCs sont généralement créés via le système d'assets ou générés programmatiquement :
+
+```java
+// Générer un NPC depuis un asset
+NPCEntity npc = world.spawnNPC("villager", position);
+
+// Configurer le NPC après génération
+npc.setRole(customRole);
+npc.getBlackboard().setHomePosition(position);
+```
+
+## Assets NPC
+
+Les définitions NPC sont configurées via des fichiers d'assets YAML :
+
+```yaml
+# npc/villager.yaml
+Type: NPC
+Id: villager
+DisplayName: "Villageois"
+Model: models/characters/villager
+Role: roles/villager_role
+Stats:
+  Health: 100
+  Speed: 3.0
+Components:
+  - Type: NPCBrain
+  - Type: Interactable
+  - Type: DialogueCapable
+```
+
+### Structure d'Asset
+
+| Propriété | Type | Description |
+|-----------|------|-------------|
+| `Type` | String | Doit être "NPC" |
+| `Id` | String | Identifiant unique |
+| `DisplayName` | String | Nom d'affichage |
+| `Model` | String | Référence asset modèle |
+| `Role` | String | Référence rôle par défaut |
+| `Stats` | Object | Statistiques de base |
+| `Components` | Array | Configurations de composants |
+
+## Rôles NPC
+
+Les rôles définissent le template comportemental d'un NPC. Ils spécifient quelles instructions, capteurs et actions le NPC peut utiliser.
+
+```yaml
+# roles/villager_role.yaml
+Type: Role
+Id: villager_role
+Instructions:
+  - Wander
+  - ReactToThreats
+  - Interact
+Sensors:
+  - Type: VisualSensor
+    Range: 15.0
+  - Type: AudioSensor
+    Range: 10.0
+Actions:
+  - Walk
+  - Run
+  - Talk
+  - Trade
+```
+
+### Composants de Rôle
+
+```java
+public class Role {
+    private List<Instruction> instructions;
+    private List<Sensor> sensors;
+    private List<Action> availableActions;
+
+    // Obtenir l'instruction active
+    public Instruction getCurrentInstruction();
+
+    // Vérifier si une action est disponible
+    public boolean hasAction(String actionId);
+}
+```
+
+## Systèmes NPC
+
+Le module NPC enregistre plusieurs systèmes ECS pour traiter le comportement des NPCs :
+
+| Système | Description |
+|---------|-------------|
+| `NPCBrainSystem` | Traite les décisions IA |
+| `NPCMovementSystem` | Gère les mises à jour de mouvement |
+| `NPCSensorSystem` | Traite les entrées des capteurs |
+| `NPCAnimationSystem` | Met à jour les animations |
+| `NPCInteractionSystem` | Gère les interactions |
+
+### Enregistrement des Systèmes
+
+```java
+public class NPCPlugin extends JavaPlugin {
+    @Override
+    public void start() {
+        // Les systèmes sont auto-enregistrés par NPCPlugin
+        // Des systèmes personnalisés peuvent être ajoutés :
+        getEntityStoreRegistry().registerSystem(
+            new CustomNPCSystem()
+        );
+    }
+}
+```
+
+## Utilitaires NPC
+
+Le package `util/` fournit des classes d'aide :
+
+### NPCUtils
+
+```java
+// Trouver le NPC le plus proche
+NPCEntity nearest = NPCUtils.findNearest(position, world, 50.0);
+
+// Obtenir tous les NPCs dans une zone
+List<NPCEntity> npcsInArea = NPCUtils.getNPCsInRadius(
+    position, world, 25.0
+);
+
+// Vérifier la ligne de vue
+boolean canSee = NPCUtils.hasLineOfSight(npc, target);
+```
+
+### NPCSpawner
+
+```java
+// Générer avec configuration
+NPCEntity npc = NPCSpawner.spawn(
+    world,
+    "villager",
+    position,
+    config -> {
+        config.setRole("merchant");
+        config.setFaction("town");
+    }
+);
+```
+
+## Patterns Courants
+
+### Configurer une Boutique NPC
+
+```java
+NPCEntity merchant = world.spawnNPC("merchant", shopPosition);
+merchant.getBlackboard().set("shop_inventory", inventory);
+merchant.getBlackboard().set("is_merchant", true);
+merchant.setRole(merchantRole);
+```
+
+### Créer un NPC Garde
+
+```java
+NPCEntity guard = world.spawnNPC("guard", guardPosition);
+Blackboard bb = guard.getBlackboard();
+bb.setPatrolPath(patrolWaypoints);
+bb.setHostileToFactions(List.of("bandits", "monsters"));
+guard.setRole(guardRole);
+```
+
+### NPC avec Comportement Personnalisé
+
+```java
+NPCEntity custom = world.spawnNPC("custom_npc", position);
+
+// Ajouter un composant personnalisé
+custom.getEntityStore().addComponent(new CustomBehaviorComponent());
+
+// Définir un decision maker personnalisé
+custom.setDecisionMaker(new CustomDecisionMaker());
+```
+
+## Bonnes Pratiques
+
+{{< callout type="info" >}}
+**Directives NPC :**
+- Définissez toujours un Rôle pour les NPCs pour définir leur comportement
+- Utilisez le Blackboard pour tout stockage d'état NPC
+- Configurez les capteurs appropriés pour les besoins de perception du NPC
+- Utilisez le système d'assets pour les définitions NPC quand possible
+- Considérez les performances avec un grand nombre de NPCs
+{{< /callout >}}
+
+{{< callout type="warning" >}}
+**Thread Safety :** Les opérations NPC doivent être effectuées sur le thread de tick du monde. Utilisez `world.isInThread()` pour vérifier avant de faire des changements.
+{{< /callout >}}