Init

content/gameplay-systems/objectives.fr.md

@@ -0,0 +1,204 @@
+---
+title: Objectifs
+type: docs
+weight: 1
+---
+
+Le systeme d'objectifs fournit des mecaniques de quetes avec des taches, des completions et un suivi de progression.
+
+**Package:** `com.hypixel.hytale.builtin.adventure.objectives`
+
+## Concepts Cles
+
+### ObjectiveAsset
+
+Les objectifs sont definis comme des assets JSON charges depuis `Objectives/`:
+
+```java
+public class ObjectiveAsset {
+    protected String id;                              // Identifiant unique
+    protected String category;                        // Categorie de quete
+    protected TaskSet[] taskSets;                     // Groupes de taches sequentiels
+    protected ObjectiveCompletionAsset[] completionHandlers;  // Recompenses
+    protected String objectiveTitleKey;               // Cle de localisation du titre
+    protected String objectiveDescriptionKey;         // Cle de localisation de description
+    protected boolean removeOnItemDrop;               // Retirer items objectif au drop
+}
+```
+
+### TaskSet
+
+Chaque objectif contient un ou plusieurs TaskSets a completer sequentiellement:
+
+```java
+public class TaskSet {
+    protected String descriptionId;      // Cle de description optionnelle
+    protected ObjectiveTaskAsset[] tasks; // Taches a completer en parallele
+}
+```
+
+### Instance d'Objectif
+
+Quand demarre, une instance `Objective` suit l'etat:
+
+```java
+public class Objective {
+    private final UUID uuid;                    // ID unique de l'instance
+    private final String objectiveId;           // Reference ID de l'asset
+    private final Set<UUID> playerUUIDs;        // Joueurs participants
+    private ObjectiveTask[] currentTasks;       // Taches actives
+    private int taskSetIndex;                   // Index du TaskSet courant
+}
+```
+
+## Types de Taches
+
+Le systeme fournit des types de taches integres enregistres par `ObjectivePlugin`:
+
+| Type | Classe | Description |
+|------|--------|-------------|
+| `Craft` | `CraftObjectiveTask` | Fabriquer des items specifiques |
+| `Gather` | `GatherObjectiveTask` | Collecter des items dans l'inventaire |
+| `UseBlock` | `UseBlockObjectiveTask` | Interagir avec des blocs |
+| `UseEntity` | `UseEntityObjectiveTask` | Interagir avec des entites |
+| `TreasureMap` | `TreasureMapObjectiveTask` | Trouver des emplacements de tresor |
+| `ReachLocation` | `ReachLocationTask` | Atteindre des coordonnees specifiques |
+
+### Exemple d'Asset de Tache
+
+```yaml
+# Objectives/collect_wood.json
+{
+  "Id": "collect_wood",
+  "Category": "tutorial",
+  "TaskSets": [
+    {
+      "Tasks": [
+        {
+          "Type": "Gather",
+          "Item": "oak_log",
+          "Amount": 10
+        }
+      ]
+    }
+  ],
+  "Completions": [
+    {
+      "Type": "GiveItems",
+      "Items": [
+        { "Item": "gold_coin", "Amount": 5 }
+      ]
+    }
+  ]
+}
+```
+
+## Gestionnaires de Completion
+
+Quand tous les TaskSets sont completes, les gestionnaires de completion s'executent:
+
+| Type | Classe | Description |
+|------|--------|-------------|
+| `GiveItems` | `GiveItemsCompletion` | Donner des items au joueur |
+| `ClearObjectiveItems` | `ClearObjectiveItemsCompletion` | Retirer les items lies a l'objectif |
+
+## Utilisation de l'API
+
+### Demarrer des Objectifs
+
+```java
+ObjectivePlugin plugin = ObjectivePlugin.get();
+
+// Demarrer un objectif pour un joueur
+plugin.startObjective(player, "collect_wood");
+
+// Avec des donnees personnalisees
+Objective objective = plugin.startObjective(player, "collect_wood", customData);
+```
+
+### Suivre la Progression
+
+```java
+// Obtenir les objectifs actifs du joueur
+ObjectiveHistoryComponent history = store.getComponent(
+    playerRef,
+    ObjectiveHistoryComponent.getComponentType()
+);
+
+// Verifier le statut de l'objectif
+ObjectiveHistoryData data = history.getObjectiveData("collect_wood");
+if (data != null && data.isCompleted()) {
+    // Deja complete
+}
+```
+
+### Completer des Objectifs
+
+```java
+// Marquer l'objectif comme complete (declenche les completions)
+objective.complete(objectivePlugin);
+
+// Annuler l'objectif sans recompenses
+objective.cancel(objectivePlugin);
+```
+
+## Conditions de Declenchement
+
+Les objectifs peuvent avoir des conditions de declenchement pour l'activation:
+
+```java
+// Declencheur base sur la meteo
+public class WeatherTriggerCondition { /* ... */ }
+
+// Declencheur base sur la position
+public class ObjectiveLocationTriggerCondition { /* ... */ }
+
+// Declencheur base sur l'heure
+public class HourRangeTriggerCondition { /* ... */ }
+```
+
+## Marqueurs de Position
+
+Utilisez les marqueurs pour creer des objectifs spatiaux:
+
+```java
+// Definir une zone de marqueur
+public interface ObjectiveLocationMarkerArea {
+    boolean isInArea(Vector3d position);
+}
+
+// Types de zones integres
+public class ObjectiveLocationAreaRadius { /* Zone spherique */ }
+public class ObjectiveLocationAreaBox { /* Zone boite */ }
+```
+
+## Commandes
+
+| Commande | Description |
+|----------|-------------|
+| `/objective start <id> [joueur]` | Demarrer un objectif |
+| `/objective complete <id> [joueur]` | Forcer la completion |
+| `/objective history [joueur]` | Voir l'historique |
+| `/objective panel` | Ouvrir le panneau admin |
+
+## Evenements
+
+```java
+// Coffre au tresor ouvert pendant l'objectif
+public class TreasureChestOpeningEvent implements IEvent<UUID> {
+    public TreasureChestState getChestState();
+    public Player getPlayer();
+}
+```
+
+## Configuration
+
+Les assets sont charges depuis le repertoire `Objectives/` avec support d'heritage:
+
+```yaml
+# Objectives/config.yaml
+ObjectiveGameplayConfig:
+  DefaultObjectives:
+    - tutorial_quest
+    - welcome_message
+```