Reference
Cheat Sheet
Every requirement, action, tracking flag, text variable, and formatting tag in one place.
tracking req. needs a tracking tag first
VaultUnlocked optional dependency
OrbisGuard optional dependency
HyFishing optional dependency
Requirements
| Format | Description | Notes |
|---|---|---|
| Named Trackers | ||
| track:id:qty | Named tracker count ≥ qty (use with track: action) |
|
| Quest State | ||
| questCompleted:id | Quest is completed | |
| questNotCompleted:id | Quest is not completed | |
| questStarted:id | Quest is in progress | |
| questNotStarted:id | Quest has not been started | |
| Tags | ||
| hasTag:tagName | Player has this tag | |
| notTag:tagName | Player does not have this tag — deprecated, use !hastag:tagName |
|
| Named Trackers | ||
| track:id:qty | Named tracker count ≥ qty (kill, break, place, killcitizen, playerkill, travel, craft, harvest, pickup, fishing; * wildcard ok on target) |
tracking req. |
| Inventory | ||
| item:itemId:qty | Has ≥ qty of item (not consumed) | |
| item:itemId:qty:true | Has ≥ qty of item (consumed on click) | |
| NPC Talk & Name | ||
| talk:citizenName:qty | Talked to this NPC ≥ qty times | auto-tracked |
| npcname:displayName | NPC that opened dialogue has this name (case-insensitive) | |
| Timer & Cooldown | ||
| cooldown:key:seconds | ≥ seconds since setTimestamp, or never set | |
| timedActive:key | Timer running (reads stored duration) | |
| timedActive:key:seconds | Timer running (explicit duration) | |
| timedExpired:key | Timer expired (reads stored duration) | |
| timedExpired:key:seconds | Timer expired (explicit duration) | |
| Position & Depth | ||
| nearPosition:x:y:z:radius | Within radius blocks of point | |
| depth:less|greater|equal:value | Player Y-position comparison | |
| distanceFrom:less|greater|equal:x:y:z:dist | Distance from fixed point | |
| World | ||
| timeOfDay:morning|afternoon|evening|night | Morning 6–11, afternoon 12–16, evening 17–20, night 21–5 | |
| moonPhase:full|waning|new|waxing|<int> | Moon phase (0=full, 4=new, 1–3=waning, 5–7=waxing) | |
| world:worldName | Player is in named world | |
| Named Variables | ||
| variable:name:equal:value | Variable = value | |
| variable:name:greater:value | Variable > value | |
| variable:name:less:value | Variable < value | |
| variable:name:greaterOrEqual:value | Variable ≥ value | |
| variable:name:lessOrEqual:value | Variable ≤ value | |
| Position | ||
| inArea:x1:y1:z1:x2:y2:z2 | Inside axis-aligned box (AABB) defined by two corners | |
| areaCheck:[entityA,entityB]:x:y:z:radius | Any listed entity exists within radius of point; * wildcards ok; Player matches any player |
|
| Logic | ||
| any:req1|req2|... | OR — true if any sub-requirement passes | |
| not:requirement | Negate any requirement | |
| !requirement | Shorthand negation (e.g. !hastag:tag) | |
| macro:name | All requirements in named requirement macro must pass (AND); if AnyMode:true, at least one must pass (OR). Defined in macros/<name>.json. | |
| Economy & Permissions | ||
| economy:canafford:amount | Balance ≥ amount | VaultUnlocked |
| permission:has:perm.node | Player has permission node | VaultUnlocked |
| MMO Skill Tree | ||
| mmo:skillId:equal:value | Skill level = value | MMOSkillTree |
| mmo:skillId:greater:value | Skill level > value | MMOSkillTree |
| mmo:skillId:less:value | Skill level < value | MMOSkillTree |
| mmo:skillId:greaterOrEqual:value | Skill level ≥ value | MMOSkillTree |
| mmo:skillId:lessOrEqual:value | Skill level ≤ value | MMOSkillTree |
| RPG Leveling | ||
| rpglevel:max | Player is at max RPG level | RPGLeveling |
| rpglevel:equal:value | RPG level = value | RPGLeveling |
| rpglevel:greater:value | RPG level > value | RPGLeveling |
| rpglevel:less:value | RPG level < value | RPGLeveling |
| rpglevel:greaterOrEqual:value | RPG level ≥ value | RPGLeveling |
| rpglevel:lessOrEqual:value | RPG level ≤ value | RPGLeveling |
| rpgxp:greater|less|equal|greaterOrEqual|lessOrEqual:value | Total RPG XP comparison | RPGLeveling |
| Endless Leveling | ||
| ellevel:max | Player is at their EL level cap | EndlessLeveling |
| ellevel:equal|greater|less|greaterOrEqual|lessOrEqual:value | EL level comparison | EndlessLeveling |
| elxp:equal|greater|less|greaterOrEqual|lessOrEqual:value | EL XP comparison | EndlessLeveling |
| elskill:SKILL:equal|greater|less|greaterOrEqual|lessOrEqual:value | Skill attribute level (STRENGTH, HASTE, DEFENSE, LIFE_FORCE, STAMINA, FLOW, SORCERY, DISCIPLINE, PRECISION, FEROCITY) | EndlessLeveling |
| elrace:raceId | Player's race matches (case-insensitive) | EndlessLeveling |
| elclass:classId | Primary OR secondary class matches | EndlessLeveling |
| elclass:primary|secondary:classId | Specific class slot matches | EndlessLeveling |
| Timer (daily reset) | ||
| timedExact:key:hour:minute | Daily reset gate; true if timestamp unset or before last HH:MM | |
| Zone & Biome | ||
| zone:regionName | Player is in named world zone | |
| biome:biomeName | Player is in named biome | |
| Fishing | ||
| hasfishinbag:fishItemId:qty | Live bag check; * for any fish; no tracker needed | HyFishing |
| Mailbox | ||
| hasmail | Player has at least one queued item in their Books-and-Papers mailbox | Books and Papers |
| Regions | ||
| inregion:regionId | Player is inside named region | QL Claims / OrbisGuard |
| regionowner:regionId | Player owns named region (rent tenant or buy owner for QL Claims) | QL Claims / OrbisGuard |
| regionmember:regionId | Player is member or owner of named region | QL Claims / OrbisGuard |
| Achievements | ||
| achievement:id[:minStage] | Player has unlocked any stage (or at least minStage) of the named achievement | |
| achievementstages:id:n | Player has unlocked at least n stages of a specific achievement | |
| achievementcount:n | Player has unlocked at least n distinct achievements | |
| achievementpoints:n | Total earned achievement points across all unlocked stages ≥ n | |
| Global State | ||
| global:hastag:tagName | Server-wide tag list contains the tag | |
| global:nottag:tagName | Server-wide tag list does not contain the tag | |
| global:variable:name:op:value | Server-wide variable comparison (ops: greater, less, equal, greaterOrEqual, lessOrEqual) | |
| Icon State | ||
| iconState:npcId:state | Player’s per-NPC icon-state override is currently set to state (available, inprogress, objectives_complete, completed, locked, waiting, repeatable_ready, story, custom, unknown) | QuestLines Icons |
Actions
| Format | Description | Notes |
|---|---|---|
| Named Trackers | ||
| track:id:type:[targets] | Create/reset a named tracker | |
| track:id:type:[targets]:exclude:[excl] | Tracker with exclusion filter | |
| untrack:id | Remove tracker and reset count | |
| Quest State | ||
| startquest:id | Add to started quests + notification | |
| completequest:id | Move to completed + notification | |
| removequest:id | Remove from both lists | |
| Achievements | ||
| unlockachievement:id | Force-unlock the next stage; fires that stage’s UnlockActions | |
| unlockachievement:id:tier | Force-unlock a specific 1-based stage (cascades through earlier locked stages) | |
| revokeachievement:id | Remove every stage of the named achievement (destructive) | |
| openachievements | Open the player-facing Achievements UI | |
| Tags | ||
| addTag:tagName | Add tag (no-op if already present) | |
| removeTag:tagName | Remove tag; resets counter if tracking flag | |
| Timer & Cooldown | ||
| setTimestamp:key | Record current time (for cooldown requirement) | |
| clearTimestamp:key | Remove a stored timestamp (resets cooldown / timed gates) | |
| timedStart:key | Record current time (for timed requirements) | |
| timedStart:key:durationSeconds | Record time + store duration (omit seconds in requirements) | |
| Items | ||
| item:itemId:qty | Give qty of item to player + notification | |
| Commands | ||
| command:commandText:server | Run as server console (op-level) | no colons in cmd |
| command:commandText:player | Run as interacting player | no colons in cmd |
| command:commandText:player:elevated | Run as player with temp wildcard perm | VaultUnlocked |
| Navigation | ||
| page:pageId | Navigate to another dialogue page (place last) | |
| NPC Spawning | ||
| spawnCitizen:name:x:y:z | Clone HyCitizens NPC at position | ~ coords ok |
| spawnCitizen:name:x:y:z:delay | Clone with delay in seconds | |
| spawnCitizen:name:x:y:z:delay:qty | Clone multiple NPCs with delay | |
| spawn:roleId:x:y:z | Spawn Hytale NPC by role ID | ~ coords ok |
| spawn:roleId:x:y:z:delay | Spawn with delay in seconds | |
| spawn:roleId:x:y:z:delay:qty | Spawn multiple with delay | |
| Named Variables | ||
| variable:name:set:value | Set variable to value | |
| variable:name:add:value | Add value to variable | |
| variable:name:subtract:value | Subtract value from variable | |
| variable:name:multiply:value | Multiply variable by value | |
| variable:name:divide:value | Divide variable by value | |
| Economy | ||
| economy:give:amount | Deposit amount into player's account | VaultUnlocked |
| economy:take:amount | Withdraw amount from player's account | VaultUnlocked |
| Sound | ||
| sound:soundName | Play 2D sound to interacting player | |
| sound:soundName:true | Broadcast 2D sound to all players | |
| sound:soundName:x:y:z | Play 3D positional sound at coordinates (broadcasts to nearby players; ~ coords ok) | |
| sound:soundName:x:y:z:player | Same but only to triggering player (distance-checked) | |
| Title & Delay | ||
| title:primary[:secondary[:server|player[:isMajor]]] | Show event title; server=broadcast world, player=self only; isMajor=true for large format | |
| delay:N | Pause N seconds (decimals ok) then continue remaining actions | |
| World Map Markers | ||
| setMarker:id:label:x:y:z[:image[:RRGGBB]] | Place a marker on the player's world map. Repeating the same id updates it. Built-in images: Home, Spawn, Portal, Warp, Death, Campfire, Coordinate, Temple_Gateway, PortalInvasion, UserA-UserF. | |
| removeMarker:id | Remove the map marker with the given id (clears on reconnect) | |
| Per-Player Block Visibility | ||
| hideBlock:x:y:z[:world] hideBlock:x1:y1:z1:x2:y2:z2[:world] |
Hide a block (3 coords) or 3D box (6 coords) from this player only — they see Air; everyone else sees the real block. Persists across reconnect; resync runs on login and on a periodic tick (default 5s). Volume capped via block_override_max_region_volume (default 32768). |
|
| showBlock:x:y:z[:world] showBlock:x1:y1:z1:x2:y2:z2[:world] |
Clear a hideBlock override and re-send the real block(s). Coords must match the hidden region (any order); partial overlaps are not removed. | |
| Macro | ||
| macro:name | Execute named macro from macros/<name>.json. Action macros run entries in order; requirement macros AND all entries (or OR if AnyMode:true). Manage macros in the editor Macros tab. | |
| MMO Skill Tree | ||
| mmo:xp:skillId:give:amount | Give XP in named skill | MMOSkillTree |
| RPG Leveling | ||
| rpgxp:give:amount | Give global RPG XP | RPGLeveling |
| Endless Leveling | ||
| elxp:give:amount | Grant EL XP (respects bonuses, cap, world blacklists) | EndlessLeveling |
| Wave Arena | ||
| startArena:arenaId[:x:y:z] | Start wave arena at player pos (or coords; ~ relative) |
Core |
| failArena | Abort the player's current arena session (runs FailActions) | Core |
| Books and Papers | ||
| mail:itemId:qty | Push an item stack to the player's mailbox in their current world | Books and Papers |
| givebook:title:author:body | Give a signed book; \f = page break, \n = line break |
Books and Papers |
| Regions | ||
| regionaddmember:regionId | Add player as member of region | QL Claims / OrbisGuard |
| regionremovemember:regionId | Remove player from region member list | QL Claims / OrbisGuard |
| Global State | ||
| global:addtag:tagName | Add tag to server-wide global tag list | |
| global:removetag:tagName | Remove tag from server-wide global tag list | |
| global:variable:name:op:value | Mutate server-wide variable (ops: add, subtract, multiply, divide, set) | |
| Icon State | ||
| iconState:npcId:state | Set per-player icon-state override on the named NPC; states: available, inprogress, objectives_complete, completed, locked, waiting, repeatable_ready, story, custom, unknown | QuestLines Icons |
| iconState:npcId:state:clear | Guarded clear — removes the override only if it currently equals state | QuestLines Icons |
| Random | ||
| random:[action1,action2,...] | Pick and execute one action at random (page: not allowed inside) | |
Text Variables
Used in Dialog and response Text fields. Substituted at display time.
| Variable | Value | Notes |
|---|---|---|
| {track:id} | Named tracker count (use with track: action) |
|
| {random:[opt1,opt2,...]} | One randomly selected entry from the bracket list | |
| {item:itemId} | How many of the given item the player currently has in their inventory | |
| {icon:itemId} | Renders an item icon inline (dialogue only; silently removed elsewhere) | |
| {username} | Player's username | |
| {npcname} | Page's Name field (NPC display name) | |
| {npcuuid} | Entity UUID of the NPC the player is currently interacting with | |
| {questname} | Title of player's first started quest | |
| {balance} | Economy balance | VaultUnlocked |
| {distancefrom:x:y:z} | Distance to (x,y,z), 1 decimal place | |
| {cooldown:key:totalSeconds} | Remaining cooldown (e.g. "3h 22m 15s") or "ready" | |
| {timeleft:key:totalSeconds} | Remaining timer time, or "expired" | |
| {variable:name} | Named variable value (no decimal for whole numbers) | |
| {mmo:skillId} | Player's current level in named MMO skill (0 if inactive) | MMOSkillTree |
| {rpglevel} | Player's current RPG level (0 if inactive) | RPGLeveling |
| {rpgxp} | Player's current total RPG XP (0 if inactive) | RPGLeveling |
| {rpgxpneeded} | XP needed for next RPG level (0 if inactive or at max) | RPGLeveling |
| {ellevel} | Player's current EL level (0 if inactive) | EndlessLeveling |
| {elxp} | Player's current EL XP (0 if inactive) | EndlessLeveling |
| {elxpneeded} | XP needed for next EL level (0 if inactive or at cap) | EndlessLeveling |
| {elprestige} | Player's EL prestige level (0 if inactive) | EndlessLeveling |
| {elskill:SKILL} | Skill attribute level (STRENGTH, HASTE, DEFENSE, LIFE_FORCE, STAMINA, FLOW, SORCERY, DISCIPLINE, PRECISION, FEROCITY) | EndlessLeveling |
| {elrace} | Player's race ID (empty if inactive) | EndlessLeveling |
| {elclass} / {elclass:primary} | Primary class ID (empty if inactive) | EndlessLeveling |
| {elclass:secondary} | Secondary class ID (empty if inactive) | EndlessLeveling |
| {fishbagcount:fishItemId} | Live fish bag count; * for total | HyFishing |
| {fishmissprogress:fishItemId} | Fish lost in the AA minigame, current vs target | Anglers’ Almanac |
| {catchlegendaryprogress} | Legendary catches counter (AA isLegendary) |
Anglers’ Almanac |
| {catchnewprogress} | New-discovery catches counter (AA isNewDiscovery) |
Anglers’ Almanac |
| {catchperfprogress:rating} | Catches at AA rating (perfect, great, good, fail, nil) | Anglers’ Almanac |
| {global:variable:name} | Server-wide global variable value (defaults to 0) | |
| {regioncount} | Number of OrbisGuard regions currently inside (0 if not active) | OrbisGuard |
| {regionnames} | Comma-separated OrbisGuard region IDs inside ("" if none) | OrbisGuard |
Inline Formatting
Tags are closed with {/}. Can be nested.
| Tag | Effect | Example |
|---|---|---|
| {b}...{/} | Bold | {b}word{/} |
| {i}...{/} | Italic | {i}word{/} |
| {m}...{/} | Monospace | {m}word{/} |
| {#RRGGBB}...{/} | Colored text (6-digit hex) | {#FF4444}text{/} |
| {#RGB}...{/} | Colored text (3-digit hex) | {#F00}text{/} |
| {rainbow}...{/} | Per-character rainbow colors across the span | {rainbow}Colorful!{/} |
| {gradient:#c1:#c2}...{/} | Linear color gradient (2 or more stops, colon-separated) | {gradient:#FF0000:#0000FF}Fade{/} |
Named Trackers
Use track:id:type:[targets] to start counting. Use untrack:id to stop and reset the counter to zero.
The same id ties the setup action, the track:id:qty requirement, the {track:id} variable, and the HUD objective together.
Tracker Types
| Type | Tracks |
|---|---|
| kill | Entity kills by entity type ID (* wildcard ok) |
| killcitizen | HyCitizens NPC kills by exact display name (* wildcard ok) |
| playerkill | Player-vs-player kills (use target *) |
| block | Block breaks by block ID (* wildcard ok) |
| place | Block placements by block ID (* wildcard ok) |
| travel | Blocks traveled (use target *; no notification sent) |
| craft | Items crafted by item ID (* wildcard ok) |
| harvest | Items harvested from blocks/crops by item ID (* wildcard ok) |
| pickup | Item pickups by item ID (* wildcard ok) |
| launch | Times stepped onto a launchpad block; target is the block ID (e.g. Launchpad or *) |
| portal | Times stepped onto a portal block; target is the block ID (Portal_Device, Hub_Portal_*, *Portal*, etc.) |
| catchfish | Fish caught by item ID (* wildcard ok; requires HyFishing) |
| catchfishbiome | Fish caught by biome (requires HyFishing) |
| catchfishrarity | Fish caught by rarity, stored lowercase (requires HyFishing) |
| catchfishzone | Fish caught by zone (* wildcard ok; requires HyFishing) |
| releasefish | Fish released by item ID (* wildcard ok; requires HyFishing) |
| fishmiss | Failed catches in the AA minigame by item ID (* wildcard ok; requires Anglers' Almanac) |
| catchfishlegendary | Legendary catches (AA isLegendary flag; requires Anglers' Almanac; target unused) |
| catchfishnew | New-discovery catches (AA isNewDiscovery flag; requires Anglers' Almanac; target unused) |
| catchfishperf | Catches by AA performance rating: perfect / great / good / fail / nil (requires Anglers' Almanac) |
| arena_complete | Wave arena completions by arena ID (* wildcard ok) |
| arena_wave | Wave arena waves cleared by arena ID (* wildcard ok) |
| dodge | Perfect dodges; targets match the attacker NPC type or Player (requires Perfect Dodges) |
Optional Modifiers
| Modifier | Effect |
|---|---|
| :loc:x:y:z:radius | Only counts events within radius of (x,y,z) |
| :world:worldName | Only counts events in the named world (* wildcard ok) |
| :exclude:[a,b] | Ignores events matching any exclude pattern |
Examples
| Action | Notes |
|---|---|
| track:goblin_kills:kill:Goblin* | Counts all Goblin variants |
| track:ore_mined:block:[*Ore*]:exclude:[*Ruby*] | Any ore except ruby |
| track:distance:travel:* | Blocks traveled anywhere |
| track:kills:kill:Zombie:loc:-71:122:186:15 | Location-gated |
| track:kills:kill:Zombie:world:cave | World-gated |
| untrack:goblin_kills | Remove tracker + reset count |
| untrack:[id1,id2] | Remove multiple at once |
System Tags (auto-managed)
| Tag | Meaning |
|---|---|
| log:questId:pageId | Last dialogue page the player saw for this quest — powers the Quest Journal. Written automatically; do not set manually. |
Key Rules
- Page order matters. The first page whose requirements all pass is shown. Put more-specific pages (quest complete, objective done) before less-specific ones (quest not started).
- All requirements and actions are case-insensitive at parse time — the parser lowercases input before matching. Write them lowercase in JSON for clarity.
cooldownreturns true if the timestamp was never set. Place the "ready" page before the "waiting" page so new players always see the reward first.timedActiveandtimedExpiredreturn false if never started. This prevents expiry pages from showing before the quest begins.- Always call
untrack:idon quest completion. Failing to do so lets the counter accumulate indefinitely and can break future quests. - Items are consumed before actions execute when
item:...:trueis used as a requirement. page:pageIdshould be the last action in a list — it navigates immediately.- Commands cannot contain colons — the parser splits on
:. Use an alias or wrapper command instead. - Coordinates in
spawnCitizen/spawnsupport~prefix for player-relative positioning (e.g.~5= player coord + 5). LoadActionson a page fire automatically every time that page is shown, before any button is clicked.- Partial name matching in tracker targets — use
*as a wildcard when setting up a named tracker. Examples:track:goblin_kills:kill:Goblin*(all Goblin variants),track:planks_placed:place:*Planks(any plank type),track:ore_mined:block:*Ore*. The same wildcard used in setup is automatically applied when the tracker increments. - Variables in action strings —
{variable:name}substitution works inside action strings (not just dialog text). Example:"spawn:Zombie:~0:~0:~0:{variable:delay}:{variable:amount}". - Auto-trigger pages — set
"AutoTrigger": trueon a page's JSON and itsLoadActionsfire automatically on every HUD tick as soon as requirements pass. Always add!hastag:someflagas a requirement andaddTag:someflagas a load action to prevent re-firing every tick.