PS1Graph Quest Authoring¶
How to author a quest in the PS1Graph dock. Slice D2-1 shipped the
compiler + node palette; slice D2-2 added the Quest.new runtime
helper with full prereq resolution + save/load; slice D2-3 wires
per-objective and per-outcome Lua callbacks (on_activate /
on_complete / on_trigger) so quest progress can drive game-side
behaviour without polling.
TL;DR¶
- Author the graph. PS1 Graph dock →
Kind: Quest→ New → right-click → drop Objective and Outcome nodes. - Wire prereqs. Objective A exec-out → Objective B exec-in means "complete A before B unlocks." Multiple incoming edges into one objective = AND (all must complete). Express OR by wiring separate chains to the same downstream objective via independent intermediate objectives.
- Wire outcomes. Objective(s) exec-out → Outcome exec-in. When all of an outcome's incoming objectives are complete, the outcome fires.
- Name everything. Objective Payload[0] = id (Lua key + Persist
key), Payload[1] = display title. Outcome Payload[0] = outcome id
(the value
Quest.newreturns from:Outcome()). - Save it. Sibling
<basename>.luais auto-written with_G.quest_<basename>. - Ship the .lua. Drop into
PS1Scene.UserScriptsand F5 — runs at scene init, table sits in_Gwaiting.
What it compiles to¶
_G.quest_save_the_village = {
initial_objectives = { "find_npc" },
objectives = {
find_npc = { id = "find_npc", title = "Find the elder", prereqs = {} },
talk_to_npc = { id = "talk_to_npc", title = "Speak with the elder", prereqs = { "find_npc" } },
defeat_orc = { id = "defeat_orc", title = "Defeat the orc", prereqs = { "talk_to_npc" } },
},
outcomes = {
{ id = "victory", prereqs = { "defeat_orc" } },
},
}
Initial objectives are those with no incoming objective edge. They're active when the quest starts.
Prereqs are the ids of all upstream objective nodes wired into this node's exec-in. AND-merged at runtime — every prereq must be complete before the node activates / fires.
Outcomes are terminal. A quest with no outcomes is a checklist (player completes objectives but the quest never "ends").
Driving it from Lua¶
Quest.new is built into the runtime as of slice D2-2 — it lives in
_G.Quest before any scene script runs.
-- Construct an instance from the compiled table. Auto-activates
-- the initial objectives on construction.
local q = Quest.new(_G.quest_save_the_village)
q:IsActive("find_npc") --> true
q:IsActive("talk_to_npc") --> false (prereq not met yet)
-- Player completes "find_npc". Returns the list of newly-unlocked
-- objective ids so you can pop a "New objective: ..." HUD.
local unlocked = q:Complete("find_npc")
-- unlocked == { "talk_to_npc" }
q:IsActive("talk_to_npc") --> true
-- Check for an outcome — returns the first outcome whose prereqs
-- are all complete, or nil.
q:Outcome() --> nil (defeat_orc not done)
q:Complete("talk_to_npc")
q:Complete("defeat_orc")
q:Outcome() --> "victory"
Save / load via Persist¶
-- Snapshot the completed set for persistence.
local snap = q:Save() -- { completed = {"find_npc", ...} }
Persist.SetTable("quest_village", snap)
-- ... later, on game load:
local restored = Quest.new(_G.quest_save_the_village)
restored:Load(Persist.GetTable("quest_village"))
-- Active set recomputes deterministically from completed.
Multiple instances¶
Quest.new produces independent instances — useful when one quest
template backs multiple repeatable variants (escort missions,
delivery contracts).
Full API surface¶
| Method | Returns | Notes |
|---|---|---|
:Activate() |
array of newly-unlocked ids | Idempotent; called once on construction |
:Complete(id) |
array of newly-unlocked ids | No-op if id is already complete or not in objectives |
:IsActive(id) |
bool | |
:IsComplete(id) |
bool | |
:ActiveSet() |
array of ids | Order unspecified |
:Outcome() |
string or nil | First satisfied outcome |
:Save() |
snapshot table | { completed = {ids} } |
:Load(snap) |
array of newly-unlocked ids | Replaces internal state, recomputes active |
Node-kind reference¶
| Editor node | Pins | Payloads | Compiles to |
|---|---|---|---|
| Objective | Exec in + Exec out | [0] id, [1] display title, [2] on_activate, [3] on_complete | entry in objectives[id] + on_activate[id] / on_complete[id] for non-empty snippets |
| Outcome | Exec in only | [0] id, [1] on_trigger | entry in outcomes array + on_trigger[id] for non-empty snippet |
Per-objective / per-outcome Lua snippets¶
Each Objective node has two optional snippet fields below the title:
- on_activate — runs when the objective becomes active (initial
state OR a prereq just completed unlocking it). Signature:
function(self)whereselfis the Quest instance. - on_complete — runs when the author calls
q:Complete(id). Signature:function(self).
Outcome nodes have one snippet field below the id:
- on_trigger — runs once when the outcome's prereqs first
become satisfied.
Quest.newtracks a fired-outcome set so the callback doesn't double-fire on subsequent:Complete()calls or across:Load()cycles.
All snippets are single-line Lua. Chain statements with ;.
Example:
Objective "find_npc":
on_activate: HUD.PopBanner("Find the village elder")
on_complete: Audio.PlaySfx("ding")
Outcome "victory":
on_trigger: Persist.Set("chapter1_done", true); Cutscene.Play("villagers_cheer")
self is the Quest instance — set fields like self._gold_earned
to hold per-quest scratch state.
Limits to know about¶
- Snippets are single-line. Chain with
;for multiple statements. Multi-line text-area authoring is a later polish slice. - Cycle guard is ON for quests — a back-edge would mean "completing A depends on B which depends on A," always a logic bug. Use multiple objectives for genuinely parallel branches.
- OR-of-prereqs needs structural workaround — add an intermediate objective with no prereqs of its own and trigger it explicitly from your game code from either branch.
- Save snapshots are
{ completed, fired_outcomes }. Active set is always recomputed from completed + initial; never persisted directly.fired_outcomesis tracked soon_triggercallbacks don't double-fire after a save/load.
Where the code lives¶
| Concern | File |
|---|---|
| Dock palette + visual body | godot-ps1/addons/ps1godot/ui/PS1GraphEditorDock.cs (objective / outcome cases) |
Compiler (CompileQuest) |
godot-ps1/addons/ps1godot/graph/PS1GraphCompiler.cs |
| Companions | docs/ps1graph-dialogue-authoring.md, docs/ps1graph-fsm-authoring.md |