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 | |
| 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 |
| 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 |
| 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 | ||
| startquest:id | Add to started quests + notification | |
| completequest:id | Move to completed + notification | |
| removequest: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 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) | |
| 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 |
| 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) |
|
| {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) | |
| {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 |
| {fishbagcount:fishItemId} | Live fish bag count; * for total | HyFishing |
| {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) |
| 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 |
|---|---|
| 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.