Actions

Auto-Triggered Pages

Every page has an optional AutoTrigger boolean field (default false). When set to true, QuestLines checks the page's requirements on every HUD tick for all online players. As soon as requirements pass, the page's LoadActions are executed automatically — no NPC interaction required. This is useful for world events, passive rewards, or background state changes.

JSON field

{
  "Id":           "auto_welcome",
  "AutoTrigger": true,
  "Requirements": ["questNotStarted:intro_quest", "notTag:auto_welcome_fired"],
  "LoadActions":  ["addTag:auto_welcome_fired", "questStarted:intro_quest"],
  "Name":         "System",
  "Dialog":      "Welcome, adventurer!"
}

Commands

Runs a server command either from the console or as the interacting player. This allows bridging QuestLines with any other plugin that supports commands.

Example

// Teleport the player via console command
"Actions": ["command:tp Steve 100 64 -200:server"]

// Player runs a command (e.g. to join a minigame)
"Actions": ["command:joinqueue arena:player"]

Cooldown & Timer

Example

// Grant daily reward and reset the cooldown clock
"Actions": [
  "item:daily_chest:1",
  "setTimestamp:daily_reward"
]

// Start a 5-minute countdown timer
"Actions": [
  "questStarted:courier_run",
  "timedStart:courier_timer"
]

Dialogue Navigation

Immediately navigates the player to a different dialogue page without closing the UI. This enables branching conversations, sub-menus, and multi-step dialogue trees that don't require NPC re-interaction.

Example

// Hub page response routes to a lore sub-page
"Responses": [{ "Text": "Tell me about the ancient war.", "Actions": ["page:elder_lore_war"] }]

Economy (VaultUnlocked optional dependency)

Give or take currency from the player's economy account. Requires VaultUnlocked with a compatible economy provider. Actions are silently ignored if VaultUnlocked is not installed.

Example

// Quest reward — deposit gold into the player's account
"Actions": [
  "questCompleted:merchant_errand",
  "economy:give:250"
]

// Purchase response — require funds, then deduct them
"Responses": [{
  "Text":         "I'll buy the map for 100 gold.",
  "Requirements": ["economy:canafford:100"],
  "Actions":      ["economy:take:100", "item:treasure_map:1"]
}]

Global State (server-wide)

Manage server-wide tags and variables stored in GlobalData. Unlike per-player tags and variables, these affect and are visible to all players. Changes are persisted to QuestLines/global.json immediately.

Example

// Start a world event by setting a global tag
"Actions": ["global:addtag:world_event_active"]

// Increment a server-wide boss kill counter
"Actions": ["global:variable:boss_kills:add:1"]

Items

Example

// Reward the player for completing a quest
"Actions": [
  "questCompleted:bounty_hunter",
  "item:gold_coin:50",
  "item:health_potion:3"
]

Journal Log Tag

QuestLines automatically maintains a log:questId:pageId tag for every quest a player has interacted with. It records the last dialogue page the player actually saw for that quest and is the data source that powers the Quest Journal (/journal).

You never write this tag yourself. The engine writes it in two places:

• When a player opens NPC dialogue — the resolved page is logged immediately.
• When a page:pageId response navigates to a new page — the target page is logged before its load actions run.

At most one log:questId:* tag exists per quest per player at any time; the old entry is replaced automatically. The tag persists after quest completion so the Journal can show the final dialogue for completed quests.

Load Actions

In addition to response Actions, every Page has a LoadActions field — a list of action strings that run automatically whenever that page is displayed. This happens both on the initial NPC interaction and whenever a page:pageId response navigates to the page. Load actions fire before the player sees any response buttons and regardless of which button they eventually click.

Use LoadActions for side-effects that should happen once per page view, not once per response click — for example, setting a tag, recording a timestamp, or running a server command that logs the visit.

JSON field

{
  "Id":           "my_quest_hub",
  "Requirements": ["questStarted:my_quest"],
  "LoadActions":  ["setTimestamp:last_visit_hub"],
  "Dialog":      "Welcome back, {username}.",
  "Responses": [{ "..." }]
}

Goal Text

Every Page has an optional GoalText string. When a player is tracking a quest, the Quest Goal HUD finds their current page and displays this text. Supports all TextFormatter variables and inline formatting tags.

Superseded by Objectives — if the page has a non-empty Objectives list, GoalText is ignored in the HUD and journal. Old configs that only use GoalText continue to work without any changes.

JSON field

{
  "Id":        "collect_wood",
  "GoalText": "Collect 10 oak logs from the forest.",
  "Dialog":   "Come back when you have the wood."
}

Objectives

Every Page has an optional Objectives list — an array of requirement strings (same format as Requirements). When non-empty, the Quest Goal HUD and Journal replace the static GoalText display with an auto-generated pass/fail objectives list.

Each objective is evaluated live and rendered as a labelled line with a progress counter where applicable:

// HUD / journal output
✓ Kill zombie: 5/5
· Break oak_log: 2/10
· Have iron_sword x1

The pass indicator is ✓ (green) when the requirement passes and · (grey) when it does not. Requirements that have a tracked progress counter (kills, breaks, places, talk, travel, fish, etc.) show current/required alongside the label. Requirements with no counter (e.g. item:, questCompleted:) show only the label.

JSON field

{
  "Id":           "collect_wood",
  "Requirements": ["questStarted:lumber_run"],
  "Objectives":   [
    "break:oak_log:10",
    "item:iron_axe:1"
  ],
  "Dialog":      "Come back when you have the wood."
}

MMO Skill XP (MMOSkillTree optional dependency)

Gives XP to a player's MMO skill. Requires the MMOSkillTree plugin to be active; silently ignored if not installed. Skill IDs are case-insensitive.

Example

// Give 500 Mining XP as a quest reward
"Actions": [
  "questCompleted:miners_task",
  "mmo:xp:MINING:give:500"
]

Named Variables

Named variables are numeric values stored per-player. They can be used to track arbitrary numeric state — scores, choices, counters, or anything that doesn't fit a kill/break counter. Variables default to 0 if never set. Fractional values are supported.

// Spawn count and delay are taken from named variables
"spawn:Zombie:~0:~0:~0:{variable:delay}:{variable:amount}"

Example

// Quest start — initialise a score variable
"Actions": [
  "questStarted:my_quest",
  "variable:score:set:0"
]

// Response that increments the counter
"Actions": ["variable:score:add:1"]

// Response that doubles it
"Actions": ["variable:score:multiply:2"]

Use {variable:name} in dialog text to show the current value to the player. Use variable:name:comparison:value requirements to gate pages or responses on the variable's value. See Requirements → Named Variables and Text Variables.

NPC Spawning

Spawn NPCs in the world as a result of player actions — useful for scripted events, quest escorts, ambushes, and environmental storytelling. Spawned NPCs are not persisted to disk; they exist only until the server restarts or they are killed.

// Spawn 3 units in front of and 1 unit above the player
"spawnCitizen:Bandit Guard:~3:~1:~0"

Example

// Spawn a bandit immediately at a fixed position
"Actions": [
  "questStarted:ambush",
  "spawnCitizen:Bandit Guard:120:64:-340"
]

// Spawn after a 3-second dramatic pause
"Actions": [
  "questStarted:ambush",
  "track:bandit_kills:killcitizen:Bandit Guard",
  "spawnCitizen:Bandit Guard:120:64:-340:3"
]

// Spawn a standard Hytale NPC by role
"Actions": ["spawn:goblin_warrior:200:70:100"]

OrbisGuard Regions (OrbisGuard optional dependency)

Add or remove the interacting player as a member of an OrbisGuard region. Requires OrbisGuard to be active; silently ignored if not installed.

Example

// Grant access to the guild hall region on quest complete
"Actions": [
  "questCompleted:guild_initiation",
  "regionaddmember:guild_hall"
]

Player Tags

Tags are free-form string labels stored on a player's data. They can represent any custom boolean state — visited locations, made choices, unlocked content, etc. Adding a tag that already exists is a no-op (idempotent).

Example

// Record that the player chose a path in branching dialogue
"Actions": ["addTag:chose_merchant_path"]

// Remove a tag when a condition is no longer relevant
"Actions": ["removeTag:pending_escort"]

Quest State

Example

// Accept the quest and begin tracking kills (Goblin* matches Goblin_Duke, Goblin_Miner, etc.)
"Actions": [
  "questStarted:lost_sword",
  "track:goblin_kills:kill:Goblin*"
]

// Complete the quest and tear down tracking
"Actions": [
  "questCompleted:lost_sword",
  "untrack:goblin_kills"
]

Random

Picks one action at random from a bracket-delimited comma-separated list and executes it. Each option in the list is an action string. Only one option is chosen and run per execution. The selection is uniformly random.

Example

// Give one of three random item rewards
"Actions": [
  "questCompleted:loot_chest",
  "random:[item:gold_coin:10,item:health_potion:3,item:rare_gem:1]"
]

RPG Leveling XP (RPGLeveling optional dependency)

Gives XP to a player's global RPG level. Requires the RPGLeveling plugin to be active; silently ignored if not installed.

Example

// Give 200 RPG XP as a quest reward
"Actions": [
  "questCompleted:training_quest",
  "rpgxp:give:200"
]

Sound

Plays a 2D sound event to the interacting player. Use /sound in-game to browse all available sound event names. The optional :true flag broadcasts the sound to all online players instead of just the interacting player.

Example

// Play a quest-complete fanfare for the player
"Actions": [
  "questCompleted:lost_sword",
  "sound:ui.quest_complete"
]

// Announce a world event to all players
"Actions": ["sound:world.boss_roar:true"]

Named Trackers

Named trackers are the preferred way to set up progress counting. Instead of adding a tag, writing a separate requirement, and using a separate variable, a single ID ties everything together. Old tracking flags continue to work.

Example — kill 10 undead:

// Setup (on quest-start response)
"track:undead:kill:[zombie,skeleton,phantom]"

// Requirement (on completion page)
"track:undead:10"

// Variable in dialogue
"You have slain {track:undead} undead so far."

// Objective entry
"track:undead:10::Kill Undead"

// Reset (on quest-complete response)
"untrack:undead"