Init

content/gameplay-systems/objectives.en.md

@@ -0,0 +1,204 @@
+---
+title: Objectives
+type: docs
+weight: 1
+---
+
+The objectives system provides quest mechanics with tasks, completions, and progress tracking.
+
+**Package:** `com.hypixel.hytale.builtin.adventure.objectives`
+
+## Core Concepts
+
+### ObjectiveAsset
+
+Objectives are defined as JSON assets loaded from `Objectives/`:
+
+```java
+public class ObjectiveAsset {
+    protected String id;                              // Unique identifier
+    protected String category;                        // Quest category
+    protected TaskSet[] taskSets;                     // Sequential task groups
+    protected ObjectiveCompletionAsset[] completionHandlers;  // Rewards
+    protected String objectiveTitleKey;               // Localization key for title
+    protected String objectiveDescriptionKey;         // Localization key for description
+    protected boolean removeOnItemDrop;               // Remove objective items on drop
+}
+```
+
+### TaskSet
+
+Each objective contains one or more TaskSets that must be completed sequentially:
+
+```java
+public class TaskSet {
+    protected String descriptionId;      // Optional description key
+    protected ObjectiveTaskAsset[] tasks; // Tasks to complete in parallel
+}
+```
+
+### Objective Instance
+
+When started, an `Objective` instance tracks state:
+
+```java
+public class Objective {
+    private final UUID uuid;                    // Unique instance ID
+    private final String objectiveId;           // Asset ID reference
+    private final Set<UUID> playerUUIDs;        // Participating players
+    private ObjectiveTask[] currentTasks;       // Active tasks
+    private int taskSetIndex;                   // Current TaskSet index
+}
+```
+
+## Task Types
+
+The system provides built-in task types registered by `ObjectivePlugin`:
+
+| Type | Class | Description |
+|------|-------|-------------|
+| `Craft` | `CraftObjectiveTask` | Craft specific items |
+| `Gather` | `GatherObjectiveTask` | Collect items in inventory |
+| `UseBlock` | `UseBlockObjectiveTask` | Interact with blocks |
+| `UseEntity` | `UseEntityObjectiveTask` | Interact with entities |
+| `TreasureMap` | `TreasureMapObjectiveTask` | Find treasure locations |
+| `ReachLocation` | `ReachLocationTask` | Reach specific coordinates |
+
+### Task Asset Example
+
+```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 }
+      ]
+    }
+  ]
+}
+```
+
+## Completion Handlers
+
+When all TaskSets complete, completion handlers execute:
+
+| Type | Class | Description |
+|------|-------|-------------|
+| `GiveItems` | `GiveItemsCompletion` | Give items to player |
+| `ClearObjectiveItems` | `ClearObjectiveItemsCompletion` | Remove objective-related items |
+
+## API Usage
+
+### Starting Objectives
+
+```java
+ObjectivePlugin plugin = ObjectivePlugin.get();
+
+// Start objective for player
+plugin.startObjective(player, "collect_wood");
+
+// With custom data
+Objective objective = plugin.startObjective(player, "collect_wood", customData);
+```
+
+### Tracking Progress
+
+```java
+// Get player's active objectives
+ObjectiveHistoryComponent history = store.getComponent(
+    playerRef,
+    ObjectiveHistoryComponent.getComponentType()
+);
+
+// Check objective status
+ObjectiveHistoryData data = history.getObjectiveData("collect_wood");
+if (data != null && data.isCompleted()) {
+    // Already completed
+}
+```
+
+### Completing Objectives
+
+```java
+// Mark objective as complete (triggers completions)
+objective.complete(objectivePlugin);
+
+// Cancel objective without rewards
+objective.cancel(objectivePlugin);
+```
+
+## Trigger Conditions
+
+Objectives can have trigger conditions for activation:
+
+```java
+// Weather-based trigger
+public class WeatherTriggerCondition { /* ... */ }
+
+// Location-based trigger
+public class ObjectiveLocationTriggerCondition { /* ... */ }
+
+// Time-based trigger
+public class HourRangeTriggerCondition { /* ... */ }
+```
+
+## Location Markers
+
+Use markers to create spatial objectives:
+
+```java
+// Define marker area
+public interface ObjectiveLocationMarkerArea {
+    boolean isInArea(Vector3d position);
+}
+
+// Built-in area types
+public class ObjectiveLocationAreaRadius { /* Spherical area */ }
+public class ObjectiveLocationAreaBox { /* Box area */ }
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/objective start <id> [player]` | Start an objective |
+| `/objective complete <id> [player]` | Force complete |
+| `/objective history [player]` | View history |
+| `/objective panel` | Open admin panel |
+
+## Events
+
+```java
+// Treasure chest opened during objective
+public class TreasureChestOpeningEvent implements IEvent<UUID> {
+    public TreasureChestState getChestState();
+    public Player getPlayer();
+}
+```
+
+## Configuration
+
+Assets are loaded from `Objectives/` directory with inheritance support:
+
+```yaml
+# Objectives/config.yaml
+ObjectiveGameplayConfig:
+  DefaultObjectives:
+    - tutorial_quest
+    - welcome_message
+```