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

title, type, weight

title	type	weight
Objectives	docs	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/:

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:

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:

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

# 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

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

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

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

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

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

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

# Objectives/config.yaml
ObjectiveGameplayConfig:
  DefaultObjectives:
    - tutorial_quest
    - welcome_message