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 | |
| Kill Counting | ||
| kill:entityTypeId:qty | Kill count ≥ qty (* wildcard ok) |
tracking req. |
| killCitizen:name:qty | HyCitizens kill count ≥ qty (* wildcard ok) |
tracking req. |
| playerKill:qty | Player-kill count ≥ qty | tracking req. |
| Block Tracking | ||
| break:blockId:qty | Block break count ≥ qty (* wildcard ok) |
tracking req. |
| place:blockId:qty | Block placement count ≥ qty (* wildcard ok) |
tracking req. |
| travelDistance:qty | Blocks traveled ≥ qty | 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 | |
| Logic | ||
| any:req1|req2|... | OR — true if any sub-requirement passes | |
| not:requirement | Negate any requirement | |
| !requirement | Shorthand negation (e.g. !hastag:tag) | |
| 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 |
| 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 | |
| Crafting, Harvest & Pickup | ||
| craft:itemId:qty | Craft count ≥ qty (* wildcard ok) | tracking req. |
| harvest:itemId:qty | Block/crop harvest count ≥ qty (* wildcard ok) | tracking req. |
| pickup:itemId:qty | Pickup count ≥ qty (* wildcard ok) | tracking req. |
| Fishing | ||
| catchfish:fishItemId:qty | Fish catch count ≥ qty by item ID (* wildcard ok) | HyFishing |
| catchfishbiome:biomeName:qty | Catch count by biome (* wildcard ok) | HyFishing |
| catchfishrarity:rarity:qty | Catch count by rarity (case-insensitive) | HyFishing |
| catchfishzone:zoneName:qty | Catch count by zone (* wildcard ok) | HyFishing |
| releasefish:fishItemId:qty | Release count (* wildcard ok) | HyFishing |
| hasfishinbag:fishItemId:qty | Live bag check; * for any fish; no tracking tag needed | HyFishing |
| OrbisGuard Regions | ||
| inregion:regionId | Player is inside named region | OrbisGuard |
| regionowner:regionId | Player owns named region | OrbisGuard |
| regionmember:regionId | Player is member or owner of named region | OrbisGuard |
| 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) | |
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 | ||
| questStarted:id | Add to started quests + notification | |
| questCompleted:id | Move to completed + notification | |
| questRemoved:id | Remove from both lists | |
| 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) | |
| 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 sound to interacting player | |
| sound:soundName:true | Broadcast sound to all players | |
| MMO Skill Tree | ||
| mmo:xp:skillId:give:amount | Give XP in named skill | MMOSkillTree |
| RPG Leveling | ||
| rpgxp:give:amount | Give global RPG XP | RPGLeveling |
| OrbisGuard Regions | ||
| regionaddmember:regionId | Add player as member of region | OrbisGuard |
| regionremovemember:regionId | Remove player from region member list | 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) | |
| 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) |
|
| {username} | Player's username | |
| {npcname} | Page's Name field (NPC display name) | |
| {questname} | Title of player's first started quest | |
| {track:id} | Current count for the named tracker with that ID | |
| {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 |
| {catchprogress:fishItemId} | Fish caught by item ID (requires catchfish named tracker) | HyFishing |
| {catchrarityprogress:rarity} | Fish caught by rarity (requires catchfishrarity named tracker) | HyFishing |
| {catchbiomeprogress:biomeName} | Fish caught by biome (requires catchfishbiome named tracker) | HyFishing |
| {catchzoneprogress:zoneName} | Fish caught by zone (requires catchfishzone named tracker) | HyFishing |
| {releaseprogress:fishItemId} | Fish released by item ID (requires releasefish named tracker) | HyFishing |
| {fishbagcount:fishItemId} | Live fish bag count; * for total | HyFishing |
| {craftprogress:itemId} | Items crafted by item ID (requires craft named tracker) | tracking req. |
| {harvestprogress:itemId} | Items harvested (block/crop) by item ID (requires harvest named tracker) | tracking req. |
| {pickupprogress:itemId} | Items picked up by item ID (requires pickup named tracker) | tracking req. |
| {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{/} |
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) |
| harvest | Items harvested from blocks/crops by item ID (* wildcard ok) |
| pickup | Item pickups by item ID (* wildcard ok) |
| 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) |
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 |
|---|---|
| assigned_quest:questId:citizenId | Records a random quest pool assignment for this player+NPC pair |
| 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 — use
*as a wildcard in entity IDs and block IDs forkill,killCitizen,break, andplacerequirements. Examples:kill:Goblin*:10,place:*Planks:10,break:*Crystal_Purple*:10,killCitizen:*:10. The tracker target must use the same wildcard pattern. - 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 addnotTag:someflag+addTag:someflagto prevent re-firing every tick.