Requirements

Block Placing

Counts block placements. Requires an active named tracker of type place (e.g. track:planks_placed:place:*Planks). The * wildcard is supported for partial block ID matching (e.g. place:*Planks:10 counts any plank type). Use track:id:qty to check a named tracker instead.

Example

// Require placing 10 stone bricks
"Requirements": [
  "questStarted:build_the_wall",
  "place:Rock_Stone_Brick: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 requirements integrate with the optional HyFishing plugin. They return false if HyFishing is not installed. Tracking tags must be added before counts accumulate, except for hasfishinbag which is a live inventory check requiring no tracking tag.

Example

// Require catching 10 fish of any type
"Requirements": [
  "questStarted:fishing_quest",
  "catchfish:*: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

For killing named HyCitizens NPCs (rather than mob entity types). Requires an active 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 — use killCitizen:*:qty to count kills of any HyCitizens NPC, or a pattern like killCitizen:Bandit*:qty to match all citizen names beginning with "Bandit".

Example

// Require killing 3 "Bandit Guard" citizens
"Requirements": [
  "questStarted:bandit_raid",
  "killCitizen:Bandit Guard: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 Harvest

Tracks how many items a player has harvested from blocks or crops. Requires an active named tracker of type harvest (e.g. track:herb_harvest:harvest:*Herb*). The * wildcard is supported for matching multiple item IDs. Fires on InteractivelyPickupItemEvent (block/crop harvest) — does not fire for picking up dropped item entities from the ground.

Item Pickup

Tracks how many items a player has picked up (via InteractivelyPickupItemEvent, the same event as harvest). Requires an active named tracker of type pickup (e.g. track:herb_pickup:pickup:*Herb*). The * wildcard is supported for matching multiple item IDs.

Example

// Quest requiring picking up 20 of any herb
"Requirements": [
  "questStarted:herb_gathering",
  "pickup:*Herb*:20"
]

Kill Counting

Kill counting requires an active named tracker of type kill (e.g. track:goblin_kills:kill:Goblin*). The counter automatically increments whenever the player kills an entity matching the tracker's target.

Example

// Require 10 goblin kills (any goblin variant)
"Requirements": [
  "questStarted:lost_sword",
  "kill:Goblin*: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 requirements track global player actions. The relevant tracking tag must be added before the counter starts accumulating.

Example

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

// Reward the player for exploring 1000 blocks
"Requirements": [
  "questStarted:explorer_quest",
  "travelDistance: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"]