Skip to content

Quest System ​

The engine ships a server-authoritative, data-driven quest system. Quest definitions, objectives, and rewards live in a MySQL catalog; per-player state is stored in MySQL tables. Lua resources interact with the system through a thin API — they never own quest logic or persistence directly.

Requirements ​

The quest system is disabled by default and requires a working MySQL connection:

ini
sets mysql_connection_string "mysql://user:password@host:3306/database?charset=utf8mb4"
set quests_enabled "true"

Optional tuning:

ini
set quest_require_mysql "true"
set quest_catalog_namespace "default"
set quest_catalog_channel "live"
set quest_ui_catalog_namespace "default"
set quest_ui_catalog_channel "live"
set quest_table_prefix "vle_quest_"
set quest_ui_runtime_enabled "true"

If quests_enabled is false, the subsystem never starts. If MySQL is not configured or not reachable, the subsystem waits in WaitingForMySql and transitions to Bootstrapping and then Ready automatically once MySQL becomes ready — no manual reload is needed.

Schema bootstrap ​

On startup (or after reloadcfg / exec) the engine ensures the following tables exist under the configured quest_table_prefix:

  • {prefix}catalogs — catalog namespace/channel revisions
  • {prefix}definitions — quest definitions (quest_key, title/description localization keys, category, kind, repeatable, cooldown, metadata)
  • {prefix}objectives — objective definitions bound to definitions
  • {prefix}rewards — reward definitions bound to definitions
  • {prefix}player_quests — per-player quest state (active/ready_to_claim/completed/abandoned, cooldowns, counts)
  • {prefix}player_tracked_quests — per-player tracker pins
  • {prefix}player_pending_rewards — durable queue for item rewards rejected by a full inventory
  • {prefix}reward_audit — append-only reward delivery and retry outcomes

After bootstrap the engine loads enabled definitions for the configured quest_catalog_namespace and quest_catalog_channel. Watch the server log:

  • [Quest] Subsystem čeká na MySQL readiness — waiting for MySQL
  • [Quest] Probíhá bootstrap quest catalogu — creating/ensuring tables
  • [Quest] Bootstrap dokončen. catalog=default/live, definitions=N — ready

definitions=0 means the schema exists but the catalog has no quest rows yet.

Seeding quest definitions ​

Insert quests into {prefix}definitions, for example:

sql
INSERT INTO vle_quest_definitions
    (catalog_namespace, channel, quest_key, title_key, description_key, category, kind, repeatable, cooldown_seconds, metadata_json, enabled)
VALUES
    ('default', 'live', 'intro_craft_hammer', 'quest.intro_craft_hammer.title', 'quest.intro_craft_hammer.desc', 'crafting', 'standard', 0, 0, '{"iconPrefab":"Hammer"}', 1);

Objectives and rewards are linked through quest_definition_id.

Built-in quest journal ​

The engine includes a built-in quest journal window in C# — no Lua resource is required. Players open it with the J hotkey while in game (unless the console or chat input is active).

Flow:

  1. The client sends VLua_QuestJournalRequest to the server.
  2. The server loads the player's journal from MySQL and replies with VLua_QuestJournalSync.
  3. The window renders a category-grouped quest list on the left and a detail pane on the right.
  4. Actions (Accept, Track / Untrack, Abandon, Complete Quest) are sent via VLua_QuestAction, applied authoritatively on the server, and followed by a fresh journal sync.

The journal is draggable and resizable. Its position, dimensions, UI scale, completed-quest filter, and audio cue volume are stored locally per client. Quest icons use definitions.metadata_json.iconPrefab; objective icons use objectives.metadata_json.iconPrefab or fall back to filters_json.itemPrefab. give_item rewards use their itemPrefab icon.

UI chrome is owned by the C# engine, not by Lua resources. ValheimLuaEngine/Assets/QuestJournal/UISheet.png and its region manifest provide the default skin for the journal, tracker, UI.OpenWindow, and UI.ShowPanel; MSBuild and the Thunderstore packager copy them to BepInEx/plugins/ValheimLuaEngine/Assets/QuestJournal beside the plugin DLL. The atlas contract and 9-slice borders are documented in that directory's README. A missing atlas or region falls back to the built-in IMGUI skin.

A passive tracker is loaded automatically after the local player joins. It shows up to five tracked active/ready quests without capturing input. Objective changes arrive through VLua_QuestProgressDelta; the client updates the tracker immediately and emits local event quest.progress(questKey, objectiveKey, progress, target).

Row colors: yellow = active, gray = available, green = ready/completed. Tracked quests show a marker. If the quest system is disabled or MySQL is not ready, the window shows the returned error instead of quest data.

Lua API ​

All quest operations are server-side and asynchronous. Each takes an optional callback receiving (success: bool, payload: string, error: string).

lua
Quest.GetJournal(sourcePeer, function(success, payload, error)
  if not success then
    print('journal failed: ' .. error)
    return
  end
  local journal = Json.Decode(payload)
  print('quests: ' .. tostring(#journal.quests))
end)

Quest.Assign(sourcePeer, 'intro_craft_hammer')
Quest.Abandon(sourcePeer, 'intro_craft_hammer')
Quest.Track(sourcePeer, 'intro_craft_hammer', true)
  • Quest.GetJournal(peerId, callback) — loads the player's journal as JSON payload (quests including per-objective progress)
  • Quest.Assign(peerId, questKey, callback) — activates a quest the player does not already have
  • Quest.Abandon(peerId, questKey, callback) — marks the quest abandoned and untracks it
  • Quest.Track(peerId, questKey, tracked, callback) — pins/unpins a quest in the tracker
  • Quest.Complete(peerId, questKey, callback) — completes the quest, applies rewards, fires quest.completed
  • Quest.Fail(peerId, questKey, callback) — marks an active quest as failed
  • Quest.ReportSignal(peerId, signalKey, payload, callback) — injects a custom objective signal

Objective signals and progress ​

Objectives bind to signals through signal_key. The engine automatically routes built-in gameplay events (player.crafted, player.killed_entity, container.items_looted, player.item_picked_up, trader.item_bought, trader.item_sold, player.died_detail) into matching objectives for quests the player has active. filters_json is matched against the signal payload (case-insensitive string comparison). Progress increments by the payload amount and is capped at target_count.

When every objective of an active quest reaches its target, its status becomes ready_to_claim and the client journal refreshes live. The player then uses Complete Quest. The server verifies the state, changes it to completed (or cooldown for repeatable quests), increments completed_count, removes the quest from the tracker, and executes rewards. Lua Quest.Complete remains available for explicitly scripted immediate completion.

Supported reward kinds: notify (player notification with template tokens), give_item (adds an item to the player's inventory), command (runs a server command with template tokens). For a remote player, give_item mutates the authoritative inventory mirror and immediately pushes the resulting snapshot to that client. A rejected give_item is persisted in {prefix}player_pending_rewards and retried when that online player synchronizes the journal. Retry first atomically reserves the row as delivering; success marks it delivered, while another full inventory returns it to pending. Interrupted deliveries are recovered during schema bootstrap. Every initial delivery and retry writes an outcome to {prefix}reward_audit.

Server administrators can recover item rewards missed before delivery was fixed with quest-reward-retry <serverId> <questKey>. The target player must be online. The command queues only give_item rewards for that quest, does not duplicate an existing pending or delivering row, and immediately runs the pending delivery pass. It requires the command.questrewardretry permission.

Universal UI windows ​

Quest UI builds on the universal window runtime, which is also available to any resource. Windows support custom PNG backgrounds loaded from resource files, item icons, scroll regions, and buttons that raise local ui.action events.

lua
UI.OpenWindow('quest.journal', {
  title = 'Quest Journal',
  width = 760,
  height = 540,
  scale = 0.9,
  resizable = true,
  rememberLayout = true,
  skin = 'parchment',
  tokens = { accent = '#d8a83e', text = '#34200d' },
  backgroundResource = 'my_resource',
  backgroundPath = 'assets/journal_bg.png',
  model = { questCount = '11/25' },
  nodes = {
    { type = 'header', text = 'Quests: {questCount}' },
    { type = 'button', text = 'Track', action = 'track', actionValue = 'intro_craft_hammer' },
    { type = 'image', iconPrefab = 'Hammer', width = 64, height = 64 }
  }
})

See natives.md for the full node type reference and UI.CloseWindow / UI.WindowExists.

Windows are freely positionable: anchor = 'center' centers the window, left/right dock it to the screen edge with a pixel y offset, and any other anchor value places it exactly at pixel coordinates x, y.

For draggable windows, rememberLayout = true persists position, dimensions, and scale under namespace/window ID. Set resizable = true to expose a lower-right resize handle. Built-in skins are classic, parchment, and minimal; tokens can override panel, titleBar, accent, titleText, headerText, text, mutedText, and buttonText with HTML colors.

Set focusable = false for passive overlays that do not unlock the cursor or block gameplay input — for example a small tracker in the screen corner:

lua
UI.OpenWindow('quest.tracker', {
  title = 'Tracked',
  anchor = 'right',
  y = 120,
  width = 320,
  height = 220,
  closable = false,
  focusable = false,
  nodes = {
    { type = 'header', text = 'Aktivní questy' }
  }
})

Lua resources for Valheim, built on a server-authoritative runtime.