Documentation/content/gameplay-systems/objectives.en.md

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