Skip to content

Quest systém ​

Engine obsahuje server-authoritative, data-driven quest systém. Definice questů, objective a rewards jsou uložené v MySQL katalogu; stav jednotlivých hráčů je uložený v MySQL tabulkách. Lua resources se systémem pracují přes tenké API a nikdy přímo nevlastní quest logiku ani persistenci.

Požadavky ​

Quest systém je ve výchozím stavu vypnutý a vyžaduje funkční MySQL připojení:

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

Volitelné ladění:

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"

Pokud je quests_enabled nastavené na false, subsystém se nikdy nespustí. Pokud MySQL není nastavená nebo není dostupná, subsystém čeká ve stavu WaitingForMySql a po připravení MySQL automaticky přejde do Bootstrapping a potom Ready bez ručního reloadu.

Bootstrap schématu ​

Při startu serveru nebo po reloadcfg / exec engine zajistí existenci těchto tabulek pod nakonfigurovaným quest_table_prefix:

  • {prefix}catalogs — revize namespace/channel katalogů
  • {prefix}definitions — definice questů (quest_key, lokalizační title/description klíče, category, kind, repeatable, cooldown, metadata)
  • {prefix}objectives — definice objective navázané na definitions
  • {prefix}rewards — definice reward navázané na definitions
  • {prefix}player_quests — stav questů hráčů (active/ready_to_claim/completed/abandoned, cooldowny, počty)
  • {prefix}player_tracked_quests — připnuté questy hráče
  • {prefix}player_pending_rewards — trvalá fronta item rewards odmítnutých kvůli plnému inventáři
  • {prefix}reward_audit — append-only log doručení reward a výsledků retry

Po bootstrapu engine načte zapnuté definice pro nakonfigurované quest_catalog_namespace a quest_catalog_channel. Sledujte server log:

  • [Quest] Subsystem čeká na MySQL readiness — čekání na MySQL
  • [Quest] Probíhá bootstrap quest catalogu — vytváření nebo ověřování tabulek
  • [Quest] Bootstrap dokončen. catalog=default/live, definitions=N — subsystém je připraven

definitions=0 znamená, že schéma existuje, ale katalog zatím neobsahuje žádné quest řádky.

Seedování definic questů ​

Questy vložte do {prefix}definitions, například:

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 a rewards jsou navázané přes quest_definition_id.

Vestavěný quest journal ​

Engine obsahuje vestavěné quest journal okno v C# a nevyžaduje Lua resource. Hráči ho ve hře otevírají klávesou J, pokud není aktivní konzole nebo chat input.

Tok:

  1. klient odešle VLua_QuestJournalRequest na server
  2. server načte journal hráče z MySQL a odpoví VLua_QuestJournalSync
  3. okno vykreslí vlevo seznam questů podle kategorií a vpravo detail
  4. akce (Accept, Track / Untrack, Abandon, Complete Quest) se posílají přes VLua_QuestAction, autoritativně se aplikují na serveru a následuje nové synchronizační načtení journalu

Journal lze přesouvat i měnit jeho velikost. Pozice, rozměry, UI scale, filtr dokončených questů a hlasitost audio cue se ukládají lokálně pro každého klienta. Ikony questů používají definitions.metadata_json.iconPrefab; ikony objective používají objectives.metadata_json.iconPrefab nebo fallback na filters_json.itemPrefab. give_item rewards používají ikonu svého itemPrefab.

UI chrome vlastní C# engine, ne Lua resources. ValheimLuaEngine/Assets/QuestJournal/UISheet.png a jeho manifest regionů poskytují výchozí skin pro journal, tracker, UI.OpenWindow a UI.ShowPanel; MSBuild a Thunderstore packager je kopírují do BepInEx/plugins/ValheimLuaEngine/Assets/QuestJournal vedle plugin DLL. Kontrakt atlasu a 9-slice borderů je zdokumentovaný v README v tomto adresáři. Chybějící atlas nebo region fallbackne na vestavěný IMGUI skin.

Pasivní tracker se načte automaticky po připojení lokálního hráče. Zobrazuje až pět tracked questů ve stavu active nebo ready bez zachytávání vstupu. Změny objective chodí přes VLua_QuestProgressDelta; klient tracker okamžitě aktualizuje a vyvolá lokální event quest.progress(questKey, objectiveKey, progress, target).

Barvy řádků: žlutá = active, šedá = available, zelená = ready/completed. Tracked questy mají marker. Pokud je quest systém vypnutý nebo MySQL není ready, okno místo dat zobrazí vrácenou chybu.

Lua API ​

Všechny quest operace běží server-side a asynchronně. Každá přijímá volitelný callback s (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) — načte journal hráče jako JSON payload včetně progressu objective
  • Quest.Assign(peerId, questKey, callback) — aktivuje quest, který hráč ještě nemá
  • Quest.Abandon(peerId, questKey, callback) — označí quest jako abandoned a odebere ho z trackeru
  • Quest.Track(peerId, questKey, tracked, callback) — připne nebo odebere quest v trackeru
  • Quest.Complete(peerId, questKey, callback) — dokončí quest, aplikuje rewards a vyvolá quest.completed
  • Quest.Fail(peerId, questKey, callback) — označí aktivní quest jako failed
  • Quest.ReportSignal(peerId, signalKey, payload, callback) — vloží vlastní objective signal

Objective signals a progress ​

Objective se vážou na signály přes signal_key. Engine automaticky směruje vestavěné gameplay events (player.crafted, player.killed_entity, container.items_looted, player.item_picked_up, trader.item_bought, trader.item_sold, player.died_detail) do odpovídajících objective u questů, které má hráč ve stavu active. filters_json se porovnává s payloadem signálu pomocí case-insensitive string comparison. Progress se navyšuje o payload amount a je omezený target_count.

Jakmile všechny objective aktivního questu dosáhnou cíle, jeho stav se změní na ready_to_claim a klientský journal se živě obnoví. Hráč pak použije Complete Quest. Server stav ověří, přepne ho na completed nebo u repeatable questů na cooldown, zvýší completed_count, odebere quest z trackeru a provede rewards. Lua Quest.Complete zůstává k dispozici pro explicitně skriptované okamžité dokončení.

Podporované reward druhy: notify (notifikace hráči s template tokeny), give_item (přidá item do hráčova inventáře), command (spustí server command s template tokeny). U vzdáleného hráče give_item mění authoritative inventory mirror a okamžitě pošle výsledný snapshot klientovi. Odmítnutý give_item se persistuje v {prefix}player_pending_rewards a znovu se zkouší, když si online hráč synchronizuje journal. Retry nejdřív atomicky rezervuje řádek jako delivering; úspěch ho označí jako delivered, zatímco další plný inventář ho vrátí do pending. Přerušená doručení se obnovují během bootstrapu schématu. Každé první doručení i retry zapisuje výsledek do {prefix}reward_audit.

Správci serveru mohou obnovit item rewards, které před opravou doručení hráč nedostal, příkazem quest-reward-retry <serverId> <questKey>. Cílový hráč musí být online. Příkaz zařadí do fronty jen give_item rewards pro daný quest, neduplikuje existující řádek pending nebo delivering a ihned spustí průchod pending doručení. Vyžaduje oprávnění command.questrewardretry.

Universal UI windows ​

Quest UI stojí na universal window runtime, který je dostupný i ostatním resources. Windows podporují vlastní PNG pozadí načítaná ze souborů resource, ikony itemů, scroll regiony a tlačítka vyvolávající lokální 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 }
  }
})

Kompletní reference typů nodů i UI.CloseWindow / UI.WindowExists je v natives.md.

Okna lze umisťovat volně: anchor = 'center' okno vycentruje, left a right ho dockují ke kraji obrazovky s pixelovým offsetem y, a jakákoli jiná hodnota anchor ho umístí přesně na souřadnice x, y.

Pro draggable okna rememberLayout = true ukládá pozici, rozměry i scale pod namespace/window ID. resizable = true zobrazí resize handle v pravém dolním rohu. Vestavěné skiny jsou classic, parchment a minimal; tokens mohou HTML barvami přepsat panel, titleBar, accent, titleText, headerText, text, mutedText a buttonText.

Pro pasivní overlaye, které neodemknou kurzor ani neblokují herní vstup, nastavte focusable = false, například pro malý tracker v rohu obrazovky:

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 pro Valheim postavené na server-authoritative runtime.