Requirements

Arena

Arena progress requirements use named trackers. Set up a tracker with type arena_complete (counts full completions) or arena_wave (counts waves cleared), then check with track:id:qty. The arena ID used as the target matches what was passed to startArena:. Supports * wildcards (e.g. shadow_* to count all shadow arenas). Wave arenas are now a Core feature — no optional dependency required.

Example

// Require 3 Shadow Trial completions to unlock the final page
"Actions": ["track:shadow_clears:3:arena_complete:[shadow_trial]"]
"Requirements": ["track:shadow_clears:3"]

Mailbox (Books and Papers optional dependency)

Checks the player's mailbox queue from the Books and Papers plugin. The check is per-world; the result reflects the mailbox in whichever world the player is currently in. Always evaluates false when Books and Papers is not installed.

Example

// Show a "you have mail!" page only when something is waiting
"Requirements": ["hasmail"]

Perfect Parries (Perfect Parries optional dependency)

Counts perfect parries and counterattacks via named trackers. Set up a tracker with track:id:parry:[targets] or track:id:counter:[targets], then check with track:id:qty. Targets match the attacker's NPC type ID (e.g. Zombie), the literal Player for PvP, or * for any. Both tracker types remain at 0 if Perfect Parries is not installed.

Example

// Quest start: count any perfect parry, and counterattacks against zombies
"Actions": [
  "questStarted:duelist_trial",
  "track:duelist_parries:parry:[*]",
  "track:zombie_counters:counter:[Zombie]"
]

// Turn-in page
"Requirements": ["track:duelist_parries:25", "track:zombie_counters:10"]

Perfect Dodges (Perfect Dodges optional dependency)

Counts perfect dodges via a named tracker. Set up a tracker with track:id:dodge:[targets], then check with track:id:qty. Targets match the attacker's NPC type ID (e.g. Trork), the literal Player for PvP, or * for any. The tracker remains at 0 if Perfect Dodges is not installed.

Example

// Quest start: count any perfect dodge, plus dodges against trorks
"Actions": [
  "questStarted:nimble_trial",
  "track:any_dodges:dodge:[*]",
  "track:trork_dodges:dodge:[Trork*]"
]

// Turn-in page
"Requirements": ["track:any_dodges:25", "track:trork_dodges:10"]

Block Breaking

Count block breaks using a named tracker of type block. Set up the tracker with track:id:block:blockId (typically in the quest-accept response), then check with track:id:qty. The * wildcard is supported for partial block ID matching (e.g. track:ore_mined:block:*Ore*).

Example

// Require mining 20 iron ore
"Requirements": [
  "questStarted:miners_task",
  "track:ore_mined:20"
]

Block Placing

Count block placements using a named tracker of type place. Set up with track:id:place:blockId, then check with track:id:qty. The * wildcard is supported for partial block ID matching (e.g. track:planks_placed:place:*Planks counts any plank type).

Example

// Require placing 10 stone bricks
"Requirements": [
  "questStarted:build_the_wall",
  "track:planks_placed:10"
]

Cooldown

Checks whether enough time has elapsed since a timestamp was recorded via setTimestamp:key. If the timestamp has never been set for this player, the requirement returns true.

Example

// Ready page: cooldown has elapsed (or never been set)
"Requirements": ["cooldown:daily_key:86400"]

// Waiting page: cooldown is still active
"Requirements": ["not:cooldown:daily_key:86400"]

Use {cooldown:key:totalSeconds} in dialog text to show the remaining wait time (e.g. "Come back in 4 hours 23 minutes.").

Daily Reset Gate

Checks whether a timestamp was set before the most recent past occurrence of a specific clock time (HH:MM, server local time). If the timestamp has never been set, the requirement returns true. Pair with setTimestamp:key in a load action to gate once-per-day events.

Example

// Daily reward resets at midnight (00:00)
"Requirements": ["timedExact:daily_reward:0:0"]
"LoadActions":  ["setTimestamp:daily_reward"]

Economy & Permissions (VaultUnlocked optional dependency)

These requirements integrate with the optional VaultUnlocked plugin. They return false if VaultUnlocked is not installed or the required provider is not active.

Example

// Gate a response on the player being able to afford the cost
"Requirements": ["economy:canafford:500"]

// Only show VIP dialogue if player has the permission node
"Requirements": ["permission:has:myserver.vip"]

Fishing (HyFishing optional dependency)

Fishing count requirements use named trackers. Set up a tracker with the appropriate fishing type (catchfish, catchfishbiome, catchfishrarity, catchfishzone, or releasefish), then check with track:id:qty. All fishing requirements return false if HyFishing is not installed. The hasfishinbag check is a live bag inventory check that requires no tracker.

Example

// Require catching 10 fish of any type
"Requirements": [
  "questStarted:fishing_quest",
  "track:fish_caught:10"
]

// Gate a turn-in on having a specific fish in the bag right now
"Requirements": [
  "hasfishinbag:golden_trout:1"
]

Achievements

Gate quests on the player’s achievement state. See the Achievements section in the Core overview for how achievements are defined and unlocked. All four checks return false when the AchievementManager is unavailable (e.g. before player data is loaded).

Example

// Gate a master-fisher quest behind unlocking the legendary catch milestone
"Requirements": [
  "achievement:legendary_catch"
]

// Hidden bonus dialog once the player has 50+ achievement points
"Requirements": [
  "achievementpoints:50"
]

Global State (server-wide)

Global requirements check server-wide state stored in GlobalData rather than per-player data. Tags and variables in the global store affect all players equally. Mutate global state using the corresponding global actions.

Example

// Show a world event page only when the server event is active
"Requirements": ["global:hastag:world_event_active"]

// Gate a reward on a server-wide counter reaching a threshold
"Requirements": ["global:variable:boss_kills:greaterOrEqual:100"]

HyCitizen Kill Count

Count kills of HyCitizens NPCs using a named tracker of type killcitizen (e.g. track:bandit_kills:killcitizen:Bandit Guard). The name match is case-sensitive and matches the NPC's exact display name. The * wildcard is supported in the tracker target — e.g. track:bandit_kills:killcitizen:Bandit* matches all citizen names beginning with "Bandit".

Example

// Require killing 3 "Bandit Guard" citizens
"Requirements": [
  "questStarted:bandit_raid",
  "track:bandit_kills:3"
]

Inventory

Checks whether the player currently has a sufficient quantity of an item in their inventory. The optional fourth segment :true marks the item as consumable — if the response passes and is selected, the items are removed before actions execute.

Example

// Check without consuming
"Requirements": ["item:gold_ingot:5"]

// Check AND consume on use (item turn-in)
"Requirements": ["item:ancient_blade:1:true"]

Item Group

Matches when the player holds at least qty of any single item whose id matches one of the target patterns (and does not match any exclude pattern). Patterns use the same * wildcard semantics as the named tracker system. The id is a human-readable label used in objective progress text (e.g. Ores: 15/25).

When used as a response requirement with the trailing :true flag, the dialogue prompts the player to pick which specific item id to turn in (if more than one matching stack is present) and consumes qty of the chosen item on click.

Example

// Bring 25 of any ore (but not the rare purple/green variants)
"Requirements": [
  "questStarted:ore_donation",
  "itemgroup:Ores:[*Ore*,*Crustal*]:exclude:[*Purple*,*Green*]:25"
]

// On the response, prompt and consume 25 of whichever ore the player picks
"Responses": [{
  "Text": "Here are the ores.",
  "Requirements": ["itemgroup:Ores:[*Ore*,*Crustal*]:exclude:[*Purple*,*Green*]:25:true"],
  "Actions": ["completequest:ore_donation"]
}]

Item Harvest

Count block/crop harvests using a named tracker of type harvest. Set up with track:id:harvest:itemId, then check with track:id:qty. Fires on InteractivelyPickupItemEvent (block/crop harvest) — does not fire for picking up dropped item entities from the ground. The * wildcard is supported for matching multiple item IDs.

Example

// Require harvesting 20 of any herb
"Requirements": [
  "questStarted:herb_gathering",
  "track:herb_harvest:20"
]

Item Pickup

Count item pickups using a named tracker of type pickup. Set up with track:id:pickup:itemId, then check with track:id:qty. Fires on the same InteractivelyPickupItemEvent as harvest. The * wildcard is supported for matching multiple item IDs.

Example

// Quest requiring picking up 20 of any herb
"Requirements": [
  "questStarted:herb_gathering",
  "track:herb_pickup:20"
]

Item Use

Count item activations (mouse clicks while holding the item) using a named tracker of type use. Set up with track:id:use:itemId, then check with track:id:qty. Increments once per Pressed click; the * wildcard is supported on the target. Use cases: counting melee sword swings, bow shots, wand/spell-tome casts, potion drinks — anything the client triggers via mouse input on a held item. Hytale has no separate spell-cast event, so spells are tracked here on the spell-source item ID.

Example

// Cast a fire tome 5 times (right-click only)
"Actions": ["questStarted:fire_training", "track:fire_casts:use:Tome_Fire:button:right"]
"Requirements": [
  "questStarted:fire_training",
  "track:fire_casts:5"
]

Icon State (QuestLines Icons optional dependency)

Checks whether a per-player icon-state override is currently active on a specific NPC. The override is set with the matching iconState: action — this requirement only reads it. Use it to gate dialogue on a state previously forced by another quest’s action.

Only registered when the QuestLines Icons companion plugin is active. On installs without Icons the requirement always evaluates to false.

Example

// Page only opens once another quest has flagged the smith as ready
"Requirements": ["iconState:smith_id:objectives_complete"]

Kill Counting

Kill counting uses named trackers. Set up a tracker with track:id:kill:entityTypeId (typically in the quest-accept response), then check with track:id:qty. Kill counting is not automatic — counts only accumulate while a tracker is active. Use untrack:id on quest completion to reset the counter.

Example

// Require 10 goblin kills (any goblin variant)
"Requirements": [
  "questStarted:lost_sword",
  "track:goblin_kills:10"
]

Use the variable {track:id} in dialog text to show the player their current count. See Text Variables.

Logic Operators

Requirements can be composed using any (OR logic), not (negation), and the ! shorthand. By default, listing multiple requirements is AND — all must pass. Use any for OR logic.

Examples

// Page visible if player has EITHER quest started
"Requirements": [
  "any:questStarted:quest_a|questStarted:quest_b"
]

// Negate a cooldown to show a "still waiting" page
"Requirements": [
  "not:cooldown:daily_key:86400"
]

// Multiple combined: started AND (has item OR has tag)
"Requirements": [
  "questStarted:delivery",
  "any:item:package:1|hasTag:already_delivered"
]

MMO Skill Level (MMOSkillTree optional dependency)

Compares the player's current level in a named MMO skill. Requires the MMOSkillTree plugin to be active; returns false silently if it is not installed. Skill IDs are case-insensitive (e.g. MINING and mining are the same).

Example

// Require Mining level 10 to access the deep mine quest
"Requirements": ["mmo:MINING:greaterOrEqual:10"]

// Gate a master trainer page on skill level
"Requirements": [
  "questStarted:apprentice_path",
  "mmo:CRAFTING:greaterOrEqual:25"
]

Moon Phase

Example

// Werewolf quest only during full moon
"Requirements": ["moonPhase:full"]

Named Trackers

A tracker is created with the track:id:type:[targets] action and checked here with track:id:qty. The tracker ID ties the setup action, this requirement, the {track:id} variable, and the objective display together — no need to repeat the type or target anywhere else.

In an Objectives list, use the :: label override as normal:
"track:kills:10::Defeat enemies" renders as Defeat enemies: 3/10.

Named Variables

Named variables are numeric values stored per-player. They are set and mutated via the variable: action and compared here as a requirement. Values default to 0 if never set. Comparisons use standard numeric rules; fractional values are supported.

Example

// Complete page — shown once counter reaches 5
"Requirements": [
  "questStarted:my_quest",
  "variable:counter:greaterOrEqual:5"
]

// Progress page — shown while counter is still below 5
"Requirements": [
  "questStarted:my_quest",
  "variable:counter:less:5"
]

Use {variable:name} in dialog text to display the current value to the player. See Text Variables.

NPC Name

Passes when the NPC that opened the current dialogue has a specific display name. The comparison is case-insensitive. Colons in the name are supported — everything after npcname: is treated as the name. This is useful when multiple NPCs share a quest but you want different pages to show depending on which NPC the player interacted with.

Example

// Show a special page only when talking to "Elder Maren"
"Requirements": [
  "questStarted:main_story",
  "npcname:Elder Maren"
]

NPC Talk Count

Talk counts are tracked automatically on every NPC interaction — no tracking tag is needed. The counter is incremented before the dialogue page is resolved. Use the NPC's display name (the name shown above their head) as the key.

Example

// Unlock dialogue on the 3rd visit to Elder Maren
"Requirements": ["talk:Elder Maren:3"]

// A "returning visitor" page for visits 2+
"Requirements": ["talk:Elder Maren:2"]

Regions (QuestLines Claims or OrbisGuard)

Check whether the player is inside, owns, or is a member of a named region. QuestLines Claims is checked first when installed; OrbisGuard is used as a fallback for any region ID Claims does not recognise. Returns false if neither plugin recognises the region ID.

Example

// Show dialogue only while inside the city region
"Requirements": ["inregion:city_of_auren"]

// Gate a landowner page on region ownership
"Requirements": ["regionowner:player_homestead"]

Player Stats

Player-kill and travel-distance counts use named trackers, like all other count-based requirements. Set up with track:id:playerkill:* or track:id:travel:*, then check with track:id:qty. Travel distance is counted in blocks with no progress notification.

Example

// Unlock a bounty page after 5 player kills
"Requirements": [
  "questStarted:bounty_hunter",
  "track:pkills:5"
]

// Reward the player for exploring 1000 blocks
"Requirements": [
  "questStarted:explorer_quest",
  "track:distance:1000"
]

Player Tags

Tags are arbitrary string labels attached to a player's data. They are managed via addTag and removeTag actions. Use them to track custom state that doesn't map to a full quest.

Example

// Only show dialogue if player has the "vip" tag
"Requirements": ["hasTag:vip"]

// Show a path only if a branching choice has NOT been made
"Requirements": ["notTag:chose_evil_path"]

Position

Example

// Player must be near the quest location to turn in
"Requirements": ["nearPosition:120:64:-340:10"]

// Page only shows underground (below Y=40)
"Requirements": ["depth:less:40"]

// Page shows when player is far from a dangerous area
"Requirements": ["distanceFrom:greater:500:64:-200:100"]

Quest Items

Checks whether the player's virtual quest inventory contains at least the given quantity of an item. Quest items are managed by the givequestitem: and removequestitem: actions and are never placed in the player's real pack.

Example

// Require the medallion to show the turn-in page
"Requirements": [
  "questStarted:artifact_hunt",
  "questitem:Ancient_Medallion:1"
]

Quest State

Example

// Show the turn-in page only when quest is in progress
"Requirements": ["questStarted:lost_sword"]

// Show reward page only after completion
"Requirements": ["questCompleted:lost_sword"]

RPG Level & XP (RPGLeveling optional dependency)

Compares the player's global RPG level or total XP. Requires the RPGLeveling plugin to be active; returns false silently if it is not installed.

Example

// Require RPG level 10 to start a veteran quest
"Requirements": ["rpglevel:greaterOrEqual:10"]

// Show a special page only at max level
"Requirements": ["rpglevel:max"]

Endless Leveling (EndlessLeveling optional dependency)

Compares the player's Endless Leveling level, XP, skill attributes, race, or class. Requires the EndlessLeveling plugin to be active; returns false silently if it is not installed. The level cap is per-player (prestige-aware), so ellevel:max uses getLevelCap(uuid).

Example

// Require level 20 and some strength to start a raid
"Requirements": ["ellevel:greaterOrEqual:20", "elskill:STRENGTH:greater:5"]

// Warrior-only dialogue branch
"Requirements": ["elclass:primary:warrior"]

Timed Quest

Timed requirements check whether an active countdown is still running or has expired. The timer is started via the timedStart:key action. Both requirements return false if the timer was never started.

Example

// Expire page — must come BEFORE active page in Pages list
"Requirements": [
  "questStarted:courier_run",
  "timedExpired:courier_timer:300"
]

// Active page — shown while timer is running
"Requirements": [
  "questStarted:courier_run",
  "timedActive:courier_timer:300"
]

Use {timeleft:key:totalSeconds} in dialog text to show the remaining time (e.g. "You have 2 minutes 45 seconds left.").

World

Example

"Requirements": ["world:overworld"]

World Time

Example

// NPC only talks at night
"Requirements": ["timeOfDay:night"]

Zone & Biome

Check the player's current world zone or biome. Zone names correspond to named map regions (e.g. emerald_grove); biome names correspond to biome identifiers (e.g. temperate_forest). No tracking tag required.

Example

// Show dialogue only in the Emerald Grove zone
"Requirements": ["zone:emerald_grove"]

// Show a page only in the temperate forest biome
"Requirements": ["biome:temperate_forest"]