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

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