# Objectives

# Objectives

Objectives define what a player must do to complete a quest. Each quest has one or more objectives, and every objective has a **type**, a **target**, and a **count**.

The quest editor of the [admin window](./admin-panel#quest-editor) offers the 20 objective types that Quests counts, each with a matching picker for its target.

## Objective Structure

Every objective in your quest JSON follows this structure:

```json
{
  "id": "obj_1",
  "type": "blocks_mined",
  "target": "Ore_Copper*",
  "count": 20,
  "description": {
    "en": "Mine Copper Ore (0/20)",
    "de": "Baue Kupfererz ab (0/20)"
  }
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique identifier within the quest (e.g. `obj_1`, `obj_2`) |
| `type` | Yes | The objective type (see table below) |
| `target` | Yes | What to target -- item ID, mob name, zone, or `"any"` |
| `count` | Yes | How many times the action must be performed |
| `description` | No | Localized display text shown in the quest book |
| `consumeItems` | No | If `true`, collected items are removed from inventory on turn-in |
| `deliverTo` | No | NPC (citizen ID) a `deliver` objective is handed in at |
| `hidden` | No | If `true`, objective is hidden until revealed |
| `revealCondition` | No | When to reveal a hidden objective: `on_progress`, `on_complete`, or `manual` |
| `conditions` | No | Additional conditions (biome, zone, weather, time of day, tool) |
| `revealOnFail` | No | If `true`, hidden objective is revealed when the quest fails |
| `failMessage` | No | Localized failure message (e.g. `{"en-US": "Failed!", "de-DE": "Fehlgeschlagen!"}`) |

## All Objective Types

### Block Objectives

| Type | Description | Example Targets |
|------|-------------|-----------------|
| `blocks_mined` | Mine stone, ores or other mineable blocks | `Rock_Stone`, `Ore_*`, `any` |
| `blocks_chopped` | Chop trees and wood | `Wood_Oak*`, `any` |
| `blocks_dug` | Dig dirt, sand or gravel | `Sand_*`, `Dirt_*`, `any` |
| `blocks_placed` | Place blocks in the world | `Bench_WorkBench`, `Furniture_Crude_Torch` |
| `blocks_harvested` | Harvest crops (F-key interaction) | `Plant_Crop_Wheat*`, `any` |
| `flowers_picked` | Pick flowers | `Plant_Flower_Common_Red`, `any` |

```json title="Example: Mine ores and place a furnace"
"objectives": [
  { "id": "obj_1", "type": "blocks_mined", "target": "Ore_*", "count": 30 },
  { "id": "obj_2", "type": "blocks_placed", "target": "Bench_Furnace", "count": 1 }
]
```

### Combat Objectives

| Type | Description | Example Targets |
|------|-------------|-----------------|
| `kills` | Kill NPCs or mobs | `Goblin_*`, `Fen_Stalker`, `any_mob` |
| `player_kills` | Kill other players | `player` |
| `damage_dealt` | Deal damage to entities | `Scorpion`, `any` |
| `damage_taken` | Receive damage | `any` |

```json title="Example: Hunt goblins and survive damage"
"objectives": [
  { "id": "obj_1", "type": "kills", "target": "Goblin_*", "count": 10 },
  { "id": "obj_2", "type": "damage_taken", "target": "any", "count": 1000 }
]
```

### Item Objectives

| Type | Description | Example Targets |
|------|-------------|-----------------|
| `items_crafted` | Craft items at a workbench or furnace | `Weapon_Sword_*`, `Potion_*`, `Bench_Furnace` |
| `items_collected` | Collect items (enter inventory) | `Ore_*`, `@consumable`, `Plant_Flower_Common_Red` |
| `deliver` | Hand items over to an NPC | Item ID or pattern, plus `deliverTo` |

```json title="Example: Gather food items (any edible item counts)"
"objectives": [
  { "id": "obj_1", "type": "items_collected", "target": "@consumable", "count": 5 }
]
```

#### Deliver

A `deliver` objective counts items the player hands over to a quest giver. Set the NPC with `deliverTo` (a citizen ID):

```json title="Example: Deliver 20 logs to Old Oak"
"objectives": [
  { "id": "obj_1", "type": "deliver", "target": "Wood_*", "count": 20, "deliverTo": "lumberjack_oak" }
]
```

When the player talks to that NPC, the [delivery confirmation](./quest-book-ui#delivery-confirmation) shows exactly what it takes. Items are only taken after **Hand in**, only what is still missing, and only what really left the inventory counts. Without `deliverTo` the items can be handed in at any NPC (the admin window warns about that).

:::caution items_consumed
`items_consumed` is still read from quest files but is not counted by Quests 2.1. Use `items_collected` or `deliver` instead.
:::

### Exploration Objectives

| Type | Description | Example Targets |
|------|-------------|-----------------|
| `distance_traveled` | Walk a certain number of blocks | **Must be** `"any"` |
| `zone_discovered` | Discover named zones | `marketplace`, `ancient_ruins`, `any` |
| `playtime_minutes` | Play for a duration (minutes) | `"any"` or `"total"` |

```json title="Example: Explore the world"
"objectives": [
  { "id": "obj_1", "type": "distance_traveled", "target": "any", "count": 3000 },
  { "id": "obj_2", "type": "zone_discovered", "target": "ancient_ruins", "count": 1 }
]
```

:::warning zone_discovered vs zones_discovered
Use `zone_discovered` (singular) for quest objectives. The plural form `zones_discovered` is used only in the achievement system for cumulative tracking.
:::

:::warning Important: distance_traveled
The target for `distance_traveled` **must always be `"any"`**. Setting it to anything else (like `"walking"` or `"running"`) will cause the objective to never progress.
:::

### Interaction Objectives

| Type | Description | Example Targets |
|------|-------------|-----------------|
| `interact_npc` | Talk to a specific NPC (alias `talk_to_npc`) | NPC citizen ID, e.g. `guide_finn` |
| `command_executed` | Execute a server command | Command name (lowercase, no `/`) |

`complete_hub_quests` is not counted by Quests 2.1 (see [Hub Quests](./quest-types#hub-quests)).

```json title="Example: Collect ores and deliver to an NPC"
"objectives": [
  { "id": "obj_1", "type": "items_collected", "target": "Ore_*", "count": 20 },
  { "id": "obj_2", "type": "interact_npc", "target": "guide_finn", "count": 1 }
]
```

```json title="Example: Execute a command"
"objectives": [
  { "id": "obj_1", "type": "command_executed", "target": "home", "count": 1 }
]
```

:::info command_executed
The `command_executed` objective tracks when a player types a command in chat. The target is the **command name in lowercase without the `/` prefix**. For example, to track when a player uses `/home`, set `"target": "home"`.
:::

### Progress Objectives

| Type | Description | Target / Count |
|------|-------------|----------------|
| `level_reached` | Reach a player level (needs a leveling plugin) | `target` = the level, e.g. `"10"`. The count is fixed at 1 |
| `wait` | Wait a number of seconds after the quest started | no target, `count` = seconds |

```json title="Example: Reach level 10, then wait one minute"
"objectives": [
  { "id": "obj_1", "type": "level_reached", "target": "10", "count": 1 },
  { "id": "obj_2", "type": "wait", "count": 60 }
]
```

`level_reached` completes right away when the player already has the level, and is checked again after level-ups. Wait timers survive relogs and restarts.

### Guild Objectives

From Quests 2.1.9 (not released yet, not tested in game). They need [KyuubiSoft Guilds](https://wiki.kyuubisoft.com/hytale/guilds/), which reports the progress. The quest editor shows them as a fifth row of objective types. No shipped quest uses them; build your own quests on them.

| Type | Description | Target / Count |
|------|-------------|----------------|
| `guild_join` | Join a guild. Founding counts as joining | no target, `count` 1. Counts once per player, so leaving and joining again does not count twice |
| `guild_create` | Found a guild | no target, `count` 1. Once per player |
| `guild_level` | The player's guild reaches a level | `target` = the level number, e.g. `"5"`. Levels already reached count again on joining and login |
| `guild_lock` | Lock chests or doors for the guild | no target, `count` = locks. Each locked spot counts once per player |
| `guild_donate` | Hand in building material for the guild level | `target` = item id, or `any` for any material; `count` = pieces |

```json title="Example: Join a guild, then hand in 64 planks"
"objectives": [
  { "id": "obj_1", "type": "guild_join", "count": 1 },
  { "id": "obj_2", "type": "guild_donate", "target": "Wood_Softwood_Planks", "count": 64 }
]
```

The check view of the admin window warns when a quest uses guild objectives while KyuubiSoft Guilds is not running, because they would never progress then. A `guild_level` target must be a number.

With KyuubiSoft Guilds installed, every completed quest also gives the player's guild experience, within the guild's daily limit per member.

## Target Syntax

Targets determine *what* counts toward an objective. The system supports several matching patterns:

| Pattern | Syntax | Example | Matches |
|---------|--------|---------|---------|
| Any | `"any"` | `"target": "any"` | Everything of that type |
| Exact | Full ID | `"target": "Rock_Stone"` | Only `Rock_Stone` |
| Wildcard | Ends with `*` | `"target": "Ore_*"` | `Ore_Iron`, `Ore_Copper`, `Ore_Gold`, ... |
| Group | `group:Name` | `"target": "group:Stone"` | All blocks in the `Stone` group |
| Property | `@property` | `"target": "@consumable"` | All items with `isConsumable() = true` |
| Multi-target | `targets` array | `"targets": ["Ore_Iron", "Ore_Copper"]` | Both iron and copper ore |

### @Property Targets

For `items_collected` and `items_consumed` objectives, you can use `@` prefixed property targets that match items based on their game properties rather than their ID:

| Target | Matches | Notes |
|--------|---------|-------|
| `@consumable` | All edible items | Includes `Food_*`, `Plant_Fruit_*`, cooked items, etc. |

:::tip Why @consumable instead of Food_*?
Edible items in Hytale use various ID prefixes (`Food_*`, `Plant_Fruit_*`, etc.). Using `@consumable` matches **all** edible items regardless of their naming pattern, making your quest more robust.
:::

### Multi-Target Example

Use the `targets` array (plural) to match multiple specific targets in a single objective:

```json
{
  "id": "obj_1",
  "type": "blocks_mined",
  "targets": ["Ore_Iron", "Ore_Copper", "Ore_Gold"],
  "count": 30
}
```

## Objective Options

### Sequential Mode

Set `"sequential": true` on the quest to require objectives to be completed in order. Players must finish `obj_1` before `obj_2` starts tracking.

```json
{
  "objectives": [
    { "id": "obj_1", "type": "blocks_chopped", "target": "any", "count": 8 },
    { "id": "obj_2", "type": "items_crafted", "target": "Bench_WorkBench", "count": 1 },
    { "id": "obj_3", "type": "blocks_placed", "target": "Bench_WorkBench", "count": 1 }
  ],
  "sequential": true
}
```

### Consume Items

When `consumeItems` is `true`, the collected items are removed from the player's inventory when the quest is turned in. The items are checked first: while any are missing, nothing is completed or taken. For handing items to an NPC, the `deliver` objective is usually the better choice.

```json
{ "id": "obj_1", "type": "items_collected", "target": "Wood_*", "count": 20, "consumeItems": true }
```

### Hidden Objectives

:::caution
`hidden`, `revealCondition`, `revealOnFail`, `failMessage` and the objective `conditions` below are read from quest files, but Quests 2.1 does not apply them: hidden objectives are shown and conditions do not restrict progress. For conditions on the whole quest, use [prerequisites](./story-quests#prerequisites).
:::

Hidden objectives are meant to stay out of the quest book until a reveal condition is met.

```json
{ "id": "obj_secret", "type": "zone_discovered", "target": "hidden_cave", "count": 1, "hidden": true, "revealCondition": "on_progress" }
```

| Reveal Condition | Behavior |
|-----------------|----------|
| `on_progress` | Revealed as soon as any progress is made |
| `on_complete` | Revealed only when the objective is completed |
| `manual` | Must be revealed via admin command or trigger |

## Objective Conditions

These optional conditions are meant to restrict *where* or *when* an objective can be progressed (not applied in 2.1, see above):

```json
{ "id": "obj_1", "type": "blocks_mined", "target": "Ore_*", "count": 20,
  "conditions": { "biome": "desert", "timeOfDay": "night", "tool": "Tool_Pickaxe_Iron" } }
```

| Condition | Values | Description |
|-----------|--------|-------------|
| `biome` | Biome ID | Only counts in this biome |
| `zone` | Zone name | Only counts in this zone |
| `weather` | `clear`, `rain`, `storm` | Only counts during this weather |
| `timeOfDay` | `day`, `night`, `dawn`, `dusk` | Only counts at this time |
| `tool` | Item ID | Only counts when using this tool |
| `minLevel` | Number | Player must be at least this level |
| `requiredBuff` | Buff ID | Player must have this active buff |