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 and no dialogue UI is shown.

Typical use cases:

• Auto-start intro quests — trigger a quest start the first time a new player connects.
• Passive milestones — detect when a player reaches a kill count or level and award a bonus quest.
• World-event gates — fire effects when a global:hastag world flag is set.
• Location-based triggers — combine with nearPosition or zone requirements to fire when a player enters an area.

Example — auto-start an intro quest on first login

{
  "Id":           "auto_welcome",
  "AutoTrigger": true,
  "Requirements": ["questNotStarted:intro_quest", "!hastag:intro_fired"],
  "LoadActions":  ["addTag:intro_fired", "questStarted:intro_quest", "chat:Welcome to the server, {username}!"]
}

Example — location-based trigger (fires once when player enters area)

{
  "Id":           "dungeon_entrance_trigger",
  "AutoTrigger": true,
  "Requirements": [
    "questStarted:dungeon_quest",
    "nearPosition:450:64:-210:20",
    "!hastag:dungeon_entered"
  ],
  "LoadActions": [
    "addTag:dungeon_entered",
    "setMarker:dungeon_exit:Exit:460:64:-250:Portal",
    "sound:world.dungeon_ambience"
  ]
}

Achievements

Drive achievement state directly from quests or response actions. See the Achievements section in the Core overview for how achievements unlock automatically when their Criteria pass — these actions are for explicit grant/revoke and for opening the UI.

Example

// Award a milestone tier on quest completion and pop the UI to show it
"Actions": [
  "questCompleted:dragon_slayer",
  "unlockachievement:legendary_hunter:2",
  "openachievements"
]

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"]

Chat

Sends a plain chat message directly to the interacting player. Supports all TextFormatter variables (e.g. {username}, {variable:name}). Everything after chat: is the message — colons in the message text are allowed. message: is an alias and behaves identically.

Example

// Simple confirmation message
"Actions": ["chat:Your quest has been recorded, {username}."]

// Alias form — identical effect
"Actions": ["message:Welcome back, {username}!"]

// Used in an if: branch to inform the player of a condition
"Actions": [
  "if:hasTag:quest_started::chat:You already have this quest!::startquest:my_quest"
]

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": [
  "startquest: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": [
  "completequest: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": [
  "completequest:bounty_hunter",
  "item:gold_coin:50",
  "item:health_potion:3"
]

If Action

Executes actions conditionally based on whether a set of requirements passes. Uses :: as a delimiter between the requirements, the then-branch actions, and an optional else-branch. Each section is a comma-separated list. Brackets [] around lists are accepted but optional.

Example

// Flag the player only if they haven't been flagged before
"Actions": ["if:notTag:visited::addTag:visited"]

// Grant a bonus quest if a prerequisite is complete, otherwise inform the player
"Actions": [
  "if:questCompleted:main_quest::startquest:bonus_quest::chat:Complete the main quest first!"
]

// Multiple requirements and multiple actions in each branch
"Actions": [
  "if:hasTag:vip,questCompleted:tutorial::[startquest:vip_quest,chat:Welcome VIP!]::[chat:You are not eligible yet.]"
]

Quest Items

Quest items live in the player's virtual quest inventory — a separate storage tracked by QuestLines, not the player's real item pack. They cannot be dropped, lost, or consumed by normal item: requirements. Use questitem:itemId:qty in Requirements to check them, and removequestitem: to take them back. Quest items are visible to the player in the Quest Items tab of the journal.

Example

// Give the player a quest item on quest start
"Actions": [
  "startquest:artifact_hunt",
  "givequestitem:Ancient_Medallion:1"
]

// Turn in — require the item in Requirements, then remove it in Actions
"Requirements": ["questitem:Ancient_Medallion:1"]
"Actions": [
  "removequestitem:Ancient_Medallion:1",
  "completequest:artifact_hunt"
]

Journal Page Resolution

The Quest Journal (/journal) resolves the current page for each quest the player has started or completed using live page resolution — the same algorithm the HUD uses. The quest's pages are walked in order and the first page whose requirements pass is the one shown in the journal.

No tags or actions are needed to drive the journal. Older versions of QuestLines maintained a hidden log:questId:pageId tag for this; that mechanic was removed in 1.9.4. Any leftover log: tags in player data are harmless and ignored at runtime.

JournalText on a page overrides the Dialog field for the journal entry only — useful when the in-world dialogue is spoken by an NPC but you want the journal written from the player's perspective.

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": [{ "..." }]
}

Objectives

Page Objectives drive the live HUD and Journal goal display. They are built from requirement strings (same format as the Requirements list) plus a special text: prefix for plain-text lines, and they support a ::label override for friendly labels.

Full reference, including the text: special case, the ::label override, contextual-requirement handling, and a complete JSON example, is on the Objectives page.

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": [
  "completequest: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": [
  "startquest: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": [
  "startquest:ambush",
  "spawnCitizen:Bandit Guard:120:64:-340"
]

// Spawn after a 3-second dramatic pause
"Actions": [
  "startquest: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"]

Teleport

Move the interacting player to a fixed or player-relative location, optionally in a different loaded world. Body and head rotation are preserved. The action is a no-op if the named world is not loaded; coordinates outside the loaded chunks are still accepted (the engine streams the destination on arrival).

Example

// Drop the player into a hidden chamber on quest start
"Actions": [
  "questStarted:hidden_temple",
  "tp:120:64:-340"
]

// Cross-world teleport using a player-relative Y offset
"Actions": [
  "tp:0:~10:0:nether_realm"
]

Regions (QuestLines Claims or OrbisGuard)

Add or remove the interacting player as a member of a named region. QuestLines Claims is checked first when installed; OrbisGuard is used as a fallback for any region ID Claims does not recognise. When adding via QL Claims, the member is granted a standard trusted flag set (build, break, interact, container, door, entry, sit, portal). Silently ignored if neither plugin recognises the region.

Example

// Grant access to the guild hall region on quest complete
"Actions": [
  "completequest: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": [
  "startquest:lost_sword",
  "track:goblin_kills:kill:Goblin*"
]

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

Icon State (QuestLines Icons optional dependency)

Sets a per-player icon-state override on a specific NPC, bypassing the auto-computed quest state for that player only. Useful for narrative beats — e.g. force the unknown icon on a fallen NPC the player just discovered, or hold an NPC at objectives_complete after a scripted scene. Pairs with the matching iconState: requirement (see Requirements » Icon State).

Only registered when the QuestLines Icons companion plugin is active — the action silently no-ops on installs without Icons. See the Icons wiki » Per-Player Overrides for the full state list and resolution priority.

Example

// Force the smith's icon to the "turn in" cue while a follow-up
// scene plays out on a different NPC.
"Actions": ["iconState:smith_id:objectives_complete"]

// On turn-in, only clear if our quest set it -- another quest may have
// switched the icon to its own override since.
"Actions": [
  "completequest:trial",
  "iconState:smith_id:objectives_complete:clear"
]

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": [
  "completequest: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": [
  "completequest:training_quest",
  "rpgxp:give:200"
]

Endless Leveling XP (EndlessLeveling optional dependency)

Grants XP to a player's Endless Leveling level. Requires the EndlessLeveling plugin to be active; silently ignored if not installed. Respects the plugin's own bonuses (Discipline multiplier etc.), world XP blacklists, and the player's level cap.

Example

// Give 1500 EL XP on dungeon completion
"Actions": [
  "completequest:dungeon_raid",
  "elxp:give:1500"
]

Wave Arena

Triggers Core-driven wave arenas from quest actions. Arenas are authored via /ql waveeditor and stored under QuestLines/wavearenas/<id>.json. No optional dependency. Pair with track:id:arena_complete:[arenaId] or track:id:arena_wave:[arenaId] to count arena progress for quests. Rewards are configured per-arena via CompletionActions / FailActions (core action strings; see the Wave Arenas page).

Example

// Start the Shadow Trial arena on quest accept; track 3 clears to complete
"Actions": [
  "track:shadow_clears:3:arena_complete:[shadow_trial]",
  "startArena:shadow_trial"
]

Books and Papers (Books and Papers optional dependency)

Integrates with the Books and Papers plugin for delivering items to player mailboxes and giving custom signed books or letters. Both actions are no-ops when Books and Papers is not installed. Pair with the hasmail requirement to gate dialogue on whether the player has unread mail.

Example

// Mail a stack of gold coins to the player on quest completion
"Actions": [
  "questCompleted:lost_letter",
  "mail:Items_Coin_Gold:100"
]

// Hand the player a signed two-page book
"Actions": [
  "givebook:The Sealed Tome:Master Aldwin:Chapter One...\fChapter Two..."
]

Sound

Plays a sound event. Use /sound in-game to browse all available sound event names. Supports 2D (player-relative) and 3D (world-positioned) playback. Coordinates support ~ prefix for player-relative values.

Example

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

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

Title

Shows a large event title on screen. Supports all TextFormatter variables in both the primary and secondary text.

Example

// Show a dramatic boss-intro title to all players
"Actions": [
  "title:The Lich Awakens:Prepare for battle:server:true"
]

// Personal quest-complete message
"Actions": [
  "completequest:main_quest",
  "title:Quest Complete!:Well done, {username}"
]

World Map Markers

Place and remove markers on a player's world map. Markers persist across sessions until explicitly removed. Sending the same id again replaces the existing marker.

Per-player block visibility

Example

// Hide a wall of blocks until the player completes the quest
"Actions": [
  "questStarted:secret_passage",
  "hideBlock:120:64:-30:120:67:-30"
]

// Reveal the wall again on completion
"Actions": [
  "questCompleted:secret_passage",
  "showBlock:120:64:-30:120:67:-30"
]

Example

// Mark an objective location when a quest starts
"Actions": [
  "questStarted:lost_sword",
  "setMarker:goblin_cave:Goblin Cave:450:64:-210:Coordinate:FF6600"
]

// Remove the marker on quest completion
"Actions": [
  "questCompleted:lost_sword",
  "removeMarker:goblin_cave"
]

Macro

Executes a named macro defined in QuestLines/macros/. Each macro is stored as its own <name>.json file. Action macros reuse common action sequences; requirement macros group reusable conditions. Circular references are detected and logged as a warning.

// macros/give_rewards.json — action macro
{
  "Type": "action",
  "Entries": ["economy:give:500", "item:Gold_Coin:5", "addTag:rewarded"]
}

// macros/is_vip.json — requirement macro with AnyMode (OR)
{
  "Type": "requirement",
  "AnyMode": true,
  "Entries": ["hasTag:vip", "permission:has:server.vip"]
}

Example

// Complete the quest and give rewards using a macro
"Actions": [
  "completequest:main_quest",
  "macro:give_rewards"
]

// Gate a response on a VIP requirement macro (OR logic)
"Requirements": ["macro:is_vip"]

Delay

Pauses execution of the remaining actions for a given number of seconds, then resumes. Player data is re-fetched after the delay so variable checks stay current. Decimal values are supported for sub-second precision.

Example

// Give a reward then show a title 1.5 seconds later
"Actions": [
  "item:Health_Potion:3",
  "delay:1.5",
  "title:Potions received!"
]

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.

Modifiers (exclude:, loc:, world:, button:) can appear in any order after the targets and combine with AND semantics — e.g. a tracker with both loc: and world: only counts events that satisfy both gates.

Example — location-gated kills (clear a bandit camp):

// Setup — only kills within 30 blocks of (1024, 64, -512) count
"track:bandit_camp:kill:[Bandit,Marauder]:loc:1024:64:-512:30"

// Combine gates: bandits in that radius AND only in the overworld
"track:bandit_camp:kill:[Bandit,Marauder]:loc:1024:64:-512:30:world:overworld"

// Requirement
"track:bandit_camp:10"

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"

Open GUI (QuestLines GUI companion plugin)

Opens a custom GUI screen for the player. Requires the QuestLines GUI companion plugin. The screen is defined by a .gui.json file in mods/QuestLinesGUI/. When QuestLines GUI is present, it registers this action with Core automatically at startup.

// In a response — open a shop when the player clicks
"opengui:blacksmith_shop"

// In LoadActions — auto-open a welcome screen once per player
// (requires: notTag:seen_welcome)
"addTag:seen_welcome"
"opengui:welcome_screen"