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

title, type, weight

title	type	weight
Bases NPC	docs	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.

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 :

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

# 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.

# 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

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

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

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

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

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

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é

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