Requirements

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"
]

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"]

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"
]

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"
]

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 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"]

OrbisGuard Regions (OrbisGuard optional dependency)

Check whether the player is inside, owns, or is a member of an OrbisGuard region. All three requirements return false if OrbisGuard is not installed.

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 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"]

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"]