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 offers the 20 objective types that Quests counts, each with a matching picker for its target.
Objective Structure
Section titled “Objective Structure”Every objective in your quest JSON follows this structure:
{ "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
Section titled “All Objective Types”Block Objectives
Section titled “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 |
"objectives": [ { "id": "obj_1", "type": "blocks_mined", "target": "Ore_*", "count": 30 }, { "id": "obj_2", "type": "blocks_placed", "target": "Bench_Furnace", "count": 1 }]Combat Objectives
Section titled “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 |
"objectives": [ { "id": "obj_1", "type": "kills", "target": "Goblin_*", "count": 10 }, { "id": "obj_2", "type": "damage_taken", "target": "any", "count": 1000 }]Item Objectives
Section titled “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 |
"objectives": [ { "id": "obj_1", "type": "items_collected", "target": "@consumable", "count": 5 }]Deliver
Section titled “Deliver”A deliver objective counts items the player hands over to a quest giver. Set the NPC with deliverTo (a citizen ID):
"objectives": [ { "id": "obj_1", "type": "deliver", "target": "Wood_*", "count": 20, "deliverTo": "lumberjack_oak" }]When the player talks to that NPC, the 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
Section titled “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" |
"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
Section titled “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).
"objectives": [ { "id": "obj_1", "type": "items_collected", "target": "Ore_*", "count": 20 }, { "id": "obj_2", "type": "interact_npc", "target": "guide_finn", "count": 1 }]"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
Section titled “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 |
"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
Section titled “Guild Objectives”From Quests 2.1.9 (not released yet, not tested in game). They need KyuubiSoft 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 |
"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
Section titled “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
Section titled “@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
Section titled “Multi-Target Example”Use the targets array (plural) to match multiple specific targets in a single objective:
{ "id": "obj_1", "type": "blocks_mined", "targets": ["Ore_Iron", "Ore_Copper", "Ore_Gold"], "count": 30}Objective Options
Section titled “Objective Options”Sequential Mode
Section titled “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.
{ "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
Section titled “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.
{ "id": "obj_1", "type": "items_collected", "target": "Wood_*", "count": 20, "consumeItems": true }Hidden Objectives
Section titled “Hidden Objectives”Hidden objectives are meant to stay out of the quest book until a reveal condition is met.
{ "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
Section titled “Objective Conditions”These optional conditions are meant to restrict where or when an objective can be progressed (not applied in 2.1, see above):
{ "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 |