Init

content/gameplay-systems/npc-objectives.fr.md

@@ -0,0 +1,202 @@
+---
+title: Objectifs NPC
+type: docs
+weight: 3
+---
+
+Le systeme d'objectifs NPC etend le systeme d'objectifs de base avec des taches liees au combat.
+
+**Package:** `com.hypixel.hytale.builtin.adventure.npcobjectives`
+
+## Architecture
+
+```
+NPCObjectivesPlugin
+├── Types de Taches
+│   ├── KillSpawnBeaconObjectiveTask - Tuer NPCs de spawn beacons
+│   ├── KillSpawnMarkerObjectiveTask - Tuer NPCs de spawn markers
+│   ├── BountyObjectiveTask - Chasser des cibles NPC specifiques
+│   └── KillNPCObjectiveTask - Tuer NPCs par type/groupe
+├── Ressources
+│   └── KillTrackerResource - Suit les compteurs de kills
+├── Systemes
+│   ├── KillTrackerSystem - Surveille les morts de NPCs
+│   └── SpawnBeaconCheckRemovalSystem - Nettoyage spawn beacons
+└── Actions NPC
+    ├── BuilderActionCompleteTask - Completer tache sur NPC
+    ├── BuilderActionStartObjective - Demarrer objectif depuis NPC
+    └── BuilderSensorHasTask - Verifier si joueur a une tache
+```
+
+## Types de Taches
+
+### Interface KillTask
+
+Toutes les taches basees sur les kills implementent cette interface:
+
+```java
+public interface KillTask {
+    void checkKilledEntity(
+        Store<EntityStore> store,
+        Ref<EntityStore> npcRef,
+        Objective objective,
+        NPCEntity npc,
+        Damage damageInfo
+    );
+}
+```
+
+### Types de Taches Enregistres
+
+| Type | Classe Asset | Description |
+|------|--------------|-------------|
+| `KillSpawnBeacon` | `KillSpawnBeaconObjectiveTaskAsset` | Tuer NPCs de beacons |
+| `KillSpawnMarker` | `KillSpawnMarkerObjectiveTaskAsset` | Tuer NPCs de markers |
+| `Bounty` | `BountyObjectiveTaskAsset` | Chasser une cible specifique |
+| `KillNPC` | `KillObjectiveTaskAsset` | Tuer NPCs par groupe |
+
+### Tache Bounty
+
+Fait apparaitre un NPC specifique et le marque comme cible de prime:
+
+```java
+public class BountyObjectiveTask extends ObjectiveTask implements KillTask {
+    boolean completed;
+    UUID entityUuid;  // UUID du NPC cible
+
+    // Fait apparaitre le NPC a la position et ajoute un marqueur carte
+    protected TransactionRecord[] setup0(Objective objective, World world, Store<EntityStore> store) {
+        // Obtenir la position de spawn depuis la configuration
+        Vector3i spawnPosition = getAsset().getWorldLocationProvider()
+            .runCondition(world, objectivePosition);
+
+        // Faire apparaitre le NPC bounty
+        Pair<Ref<EntityStore>, INonPlayerCharacter> npcPair =
+            NPCPlugin.get().spawnNPC(store, getAsset().getNpcId(), null, spawnPosition, Vector3f.ZERO);
+
+        // Ajouter marqueur sur la carte
+        addMarker(new MapMarker(
+            getBountyMarkerIDFromUUID(npcUuid),
+            "Bounty Target",
+            "Home.png",
+            transform
+        ));
+
+        // Enregistrer le tracker de kills
+        store.getResource(KillTrackerResource.getResourceType()).watch(transaction);
+
+        return transactionRecords;
+    }
+
+    @Override
+    public void checkKilledEntity(Store<EntityStore> store, Ref<EntityStore> npcRef,
+                                   Objective objective, NPCEntity npc, Damage damageInfo) {
+        if (!this.entityUuid.equals(uuid)) return;
+        this.completed = true;
+        this.complete(objective, store);
+        objective.checkTaskSetCompletion(store);
+        this.removeMarker(getBountyMarkerIDFromUUID(uuid));
+    }
+}
+```
+
+### Configuration d'Asset
+
+```yaml
+# Objectives/bounty_quest.json
+{
+  "Id": "bounty_quest",
+  "TaskSets": [
+    {
+      "Tasks": [
+        {
+          "Type": "Bounty",
+          "NpcId": "bandit_leader",
+          "WorldLocationProvider": {
+            "Type": "LocationRadius",
+            "Radius": 50
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Tracker de Kills
+
+### KillTrackerResource
+
+Ressource monde qui suit les kills de NPCs:
+
+```java
+ResourceType<EntityStore, KillTrackerResource> type =
+    NPCObjectivesPlugin.get().getKillTrackerResourceType();
+```
+
+### KillTrackerSystem
+
+Systeme ECS qui surveille les morts de NPCs et notifie les taches:
+
+```java
+// Enregistrer une transaction pour surveiller les kills
+KillTaskTransaction transaction = new KillTaskTransaction(task, objective, store);
+store.getResource(KillTrackerResource.getResourceType()).watch(transaction);
+```
+
+## Actions NPC
+
+Enregistrees comme types de composants core NPC pour l'integration IA:
+
+### Action CompleteTask
+
+```java
+// Complete une tache quand interaction NPC se produit
+NPCPlugin.get().registerCoreComponentType("CompleteTask", BuilderActionCompleteTask::new);
+```
+
+### Action StartObjective
+
+```java
+// Demarre un objectif depuis dialogue/interaction NPC
+NPCPlugin.get().registerCoreComponentType("StartObjective", BuilderActionStartObjective::new);
+```
+
+### Sensor HasTask
+
+```java
+// Sensor qui verifie si le joueur a une tache specifique
+NPCPlugin.get().registerCoreComponentType("HasTask", BuilderSensorHasTask::new);
+```
+
+## Utilisation de l'API
+
+### Verifier si Joueur a une Tache
+
+```java
+boolean hasTask = NPCObjectivesPlugin.hasTask(playerUUID, npcId, "taskId");
+```
+
+### Mettre a Jour Completion de Tache
+
+```java
+String animationId = NPCObjectivesPlugin.updateTaskCompletion(
+    store, ref, playerRef, npcId, "taskId"
+);
+```
+
+### Demarrer Objectif depuis NPC
+
+```java
+NPCObjectivesPlugin.startObjective(playerReference, "quest_id", store);
+```
+
+## Ordre de Chargement des Assets
+
+Le plugin assure un ordre de chargement correct:
+
+```java
+AssetRegistry.getAssetStore(ObjectiveAsset.class).injectLoadsAfter(SpawnMarker.class);
+AssetRegistry.getAssetStore(ObjectiveAsset.class).injectLoadsAfter(BeaconNPCSpawn.class);
+AssetRegistry.getAssetStore(ObjectiveAsset.class).injectLoadsAfter(NPCGroup.class);
+```