PS1Graph Dialogue Authoring¶
How to author a PS1Graph dialogue graph and get it running on PSX.
Covers the full path from clicking New in the dock to seeing
on-screen dialogue when you F5. Companion to ROADMAP.md Graph
authoring framework (PS1Graph) / D1 — this doc is the practical
walkthrough.
TL;DR — the five steps¶
- Author the graph. PS1 Graph dock → set
Kind: Dialogue→ New → right-click → drop Line / Choice / Set Flag / Condition / Play Sound / Start Cutscene / Comment nodes. Wire exec pins. - Save it. Save As… → e.g.
res://graphs/intro.tres. A siblingintro.luais written automatically. - Ship the .lua. Select your
PS1Scene→ Inspector → Scripting → addres://graphs/intro.luato UserScripts. - Author the dialogue_box canvas. Add a
PS1UICanvasnamed exactlydialogue_boxto your scene with the elements listed below. (Skip this on first pass — without a canvas the walker prints to the debug console, which is fine for verifying the graph runs.) - Trigger the dialogue. In your scene Lua, call
Dialog.RunGraph(_G.dialogue_<basename>).
How the pieces wire up¶
┌──────────────────┐ sibling .lua ┌─────────────────────┐
│ PS1Graph dock │ ────────────────▶│ PS1Scene │
│ Save → .tres │ │ .UserScripts │
│ + .lua │ │ ↑ ships at export │
└──────────────────┘ └─────────┬───────────┘
│
▼
┌──────────────────────────────────┐ LoadLuaFile runs the chunk
│ PSX runtime (psxsplash) │ once at scene init, which
│ _G.dialogue_<basename> = {...} │ installs the dialogue table
│ │ on _G but does nothing else.
│ Author Lua somewhere: │
│ Dialog.RunGraph( │
│ _G.dialogue_<basename>) │
│ → walker starts │
└──────────────────────────────────┘
The compiled .lua is just a global-assignment of the dialogue table.
Nothing happens until Dialog.RunGraph is called — the table sits
in _G waiting for a trigger. That's why step 5 above is necessary.
The basename → global name mapping¶
The compiler derives a Lua-safe identifier from the .tres filename:
| Saved path | Global name |
|---|---|
res://graphs/intro.tres |
_G.dialogue_intro |
res://dlg/mom-yells.tres |
_G.dialogue_mom_yells |
(unsaved) |
_G.dialogue_unnamed |
Algorithm: filename without extension, lowercased, non-alphanumeric
characters replaced with _, leading digit prefixed with _.
Visible in the first line of the compiled .lua.
The dialogue_box canvas¶
The walker findCanvas("dialogue_box") on Dialog.RunGraph. If the
canvas exists, the walker drives it. If it doesn't, the walker
prints to the PCSX-Redux debug console instead — useful for
verifying the graph logic before you've built any UI.
Required canvas name: exactly dialogue_box.
Expected element names (all optional — missing elements are skipped silently, so you can ship a minimal canvas first and grow it):
| Element name | Type | Purpose |
|---|---|---|
speaker |
PS1UIText |
Current line's speaker name |
text |
PS1UIText |
Current line body / choice prompt |
option_1 |
PS1UIText |
Choice option 1 text |
option_2 |
PS1UIText |
Choice option 2 text |
option_3 |
PS1UIText |
Choice option 3 text |
cursor_1 |
any | Visibility-toggled cursor next to option 1 |
cursor_2 |
any | Visibility-toggled cursor next to option 2 |
cursor_3 |
any | Visibility-toggled cursor next to option 3 |
The cursor elements can be PS1UIImage, PS1UIBox, or even another
PS1UIText displaying >. The walker toggles their visible
property to match the currently-selected option; only one is visible
at a time.
Any other element on the dialogue_box (a background Box, a
frame, a portrait, decorative graphics) is auto-shown when the
dialogue starts and auto-hidden when it stops. You don't need to
flip VisibleOnLoad on those — the walker manages the whole canvas
as a unit. Only the named slots above get per-node lifecycle
management.
If you don't add cursor elements, the walker re-renders each
option's text with a > (selected) / (unselected) prefix every
frame, so you still get a visible selection indicator without
authoring three cursor elements. Add real cursor elements when you
want fancier styling.
Themes don't auto-apply¶
PS1UICanvas.Theme only paints elements whose ThemeSlot is
non-Custom. If your dialogue text comes out the wrong color, open
each PS1UIElement and set Appearance → ThemeSlot to Text
(or Accent for the speaker, etc.). With Custom (the default),
the element uses its raw Color field and ignores the canvas theme.
A reasonable starting layout:
dialogue_boxcanvas,sortOrderhigh enough to draw over gameplay.- A
PS1UIBoxbackground spanning the lower third of the 320×240 screen. speaker(left-aligned, top of the box).text(left-aligned, below speaker).option_1,option_2,option_3(stacked, indented slightly).cursor_1..3as small arrow images aligned with each option row.
You can start with just speaker + text to get line dialogue
working, then add option_* and cursor_* when you add a Choice
node.
Triggering the dialogue from Lua¶
Once the .lua is in UserScripts and (optionally) the canvas exists,
trigger the dialogue from any Lua context:
-- From a scene script's onSceneCreationEnd:
function onSceneCreationEnd()
Dialog.RunGraph(_G.dialogue_intro)
end
-- From a trigger volume's onTriggerEnter:
function onTriggerEnter(self, other)
if not Persist.Get("met_bob") then
Dialog.RunGraph(_G.dialogue_first_meeting)
end
end
-- From an interactable's onInteract (NPC dialogue):
function onInteract(self)
Dialog.RunGraph(_G.dialogue_shopkeeper)
end
Dialog.RunGraph returns immediately — the walker continues across
frames. While it's running, Dialog.IsActive() returns true.
Dialog.Stop() aborts in-progress dialogue (useful for cutscene
interrupts).
Node-kind cheat sheet¶
| Editor node | Compiles to | What it does |
|---|---|---|
| Line | kind="line" + speaker, text, next |
Display one line, wait for X |
| Choice | kind="choice" + 3 options |
D-pad to select, X to confirm |
| Set Flag | kind="action" + Persist.Set(name, bool) |
Auto-advance |
| Condition (flag) | kind="condition" + Persist.Get(name) == true |
Branch on flag, two exec outs |
| Play Sound | kind="action" + Audio.PlaySfx(clip) |
Auto-advance |
| Start Cutscene | kind="action" + Cutscene.Play(id) |
Auto-advance |
| Lua Snippet | kind="action" + author-supplied Lua |
Power-user action — runs arbitrary Lua, auto-advance |
| Lua Condition | kind="condition" + return (<expr>) |
Power-user branch — arbitrary Lua expression, two exec outs |
| Sub-Dialogue | kind="sub_dialogue" + target basename |
Call into another dialogue table; return on the sub's nil-next |
| Comment | — | Decoration; compiles to nothing |
Action and Condition nodes chain at one node per frame (~16ms each) which is imperceptible — a Set-Flag → Play-Sound → Line sequence looks instant.
Per-line audio + skip control (D1h)¶
Line nodes have two extra fields beneath the text:
- audio clip name — references a clip in
PS1Scene.AudioClips. Plays viaAudio.PlaySfxon line entry so XA / SPU / CDDA routing stays in one place. Empty = no audio. - skippable CheckBox — when off, the X-button advance is blocked. If the line has audio: locked for the clip's duration. No audio: locked for 2 seconds (120 frames @ 60Hz). The lock is per-line; subsequent lines reset it.
Use non-skippable lines for cutscene-style narration where the player shouldn't dismiss the line before the voiceover finishes.
Anim Notify markers (D1i)¶
Lines have a notifies field below the skippable checkbox.
Pipe-separated entries of the form frame:lua:
When the line is active, the runner ticks a per-line frame counter
and pcalls each entry's Lua snippet on the frame matching its :
prefix. Use these to punctuate a line with timed SFX, set-flag
pulses, or camera moves without splitting the line across many
graph nodes.
Up to 8 notifies per line (runtime cap). Malformed entries
(missing colon, non-integer frame) compile to a --[[…]] comment
in the .lua so you can see them in the generated output.
Sub-Dialogue node (D1j)¶
A Sub-Dialogue node runs another dialogue table inline, then
returns to the parent at the node's exec-out. Use to factor shared
sequences (shopkeeper greeting, death sting, "are you sure?"
confirmation) into reusable .tres files.
The Payload is the target's basename — for res://dlg/shopkeeper.tres
that's shopkeeper. At runtime the walker resolves it as
_G.dialogue_shopkeeper, so the target's .lua must be loaded
(usually via the same PS1Scene.UserScripts list).
Stack depth is capped at 4 — sub-dialogue chains beyond that print a debug warning and end the dialogue cleanly rather than blowing the stack.
Power-user nodes (Lua Snippet / Lua Condition)¶
Lua Snippet runs whatever Lua you type, single line (chain with ;
for multiple statements). Reach for it when the structured nodes
above don't cover what you need — calling a custom Lua function,
mutating a global table, sequencing several APIs in one step. The
walker pcalls the snippet so a syntax error prints + doesn't fire
rather than crashing the scene.
Lua Condition is the same idea for branches. The expression is
wrapped in return (<expr>) at compile time, so you can write any
boolean expression (or anything Lua treats as truthy — only nil
and false are false). Empty expression compiles to return false,
so leaving the field blank is debuggable, not a crash.
Both are intentional escape hatches. Prefer the structured nodes when they cover the case (better introspection, easier to lint later) and reach for the Lua versions when the structured set falls short.
Player controls during dialogue¶
- X (Cross): Advance line / confirm choice
- D-pad Up: Move cursor up in a choice
- D-pad Down: Move cursor down in a choice
One-frame input deferral on the entry frame of each node — the X press that advanced into a node won't immediately advance back out. This means choices are stable from the moment they appear.
Troubleshooting¶
| Symptom | Likely cause |
|---|---|
Nothing happens after Dialog.RunGraph call |
Wrong global name. Compare your _G.dialogue_<basename> against the first line of the compiled .lua. |
| Walker logs in debug console but no on-screen text | No dialogue_box canvas in the scene — the walker falls back to printf. |
| Some lines appear but speaker is blank | The speaker element isn't named exactly speaker, or doesn't exist on the canvas. Walker silently skips missing elements. |
| Choices don't navigate | Fewer than 2 active options on the node, or D-pad Up/Down not reaching the runner. Cursor element is not required — the walker prefixes the selected option with > automatically if cursors aren't authored. |
| Dialogue text comes out wrong color | Each element's ThemeSlot defaults to Custom and uses its raw Color field, ignoring the canvas theme. Set ThemeSlot = Text (or another slot) per element. |
| Branch always takes the false arm | The flag isn't set yet. Persist.Set("name", true) somewhere upstream, or check the flag name matches between Set Flag and Condition nodes. |
| Compiled .lua exists but isn't running on PSX | Not in PS1Scene.UserScripts, or the export didn't include it. Look for [PS1Godot] Lua on 'PS1Scene.UserScripts[N]': res://… in the editor Output after export. |
| Editor crashes on graph operations | Restart Godot — C# DLLs don't hot-reload, stale plugin code persists across project builds. |
Limits to know about¶
- 3 choice options max. Variable-pin GraphNode support isn't in yet; chain Choice nodes for wider fanout.
Conditionreads flags only. Arbitrary Lua expressions need a future "Lua Snippet" node kind (not shipped).- No
GiveItemnode. Blocked on a missingInventoryLua API in the runtime; lands when inventory ships. - D-pad Up/Down is edge-triggered, no auto-repeat. Long option lists need one press per move.
- Canvas isn't authored for you. First-run experience is the
printf fallback until you build the
dialogue_box.
Where the code lives¶
| Concern | File |
|---|---|
| Editor dock | godot-ps1/addons/ps1godot/ui/PS1GraphEditorDock.cs |
| Resource types | godot-ps1/addons/ps1godot/graph/PS1Graph{Resource,Node,Connection}.cs |
| Compiler | godot-ps1/addons/ps1godot/graph/PS1GraphCompiler.cs |
| Runtime walker | psxsplash-main/src/dialogue.{hh,cpp} |
| Lua API binding | psxsplash-main/src/luaapi.cpp (search Dialog_) |
| Sibling .lua write | PS1GraphEditorDock.WriteCompiledLuaSibling |
UserScripts plumbing |
godot-ps1/addons/ps1godot/exporter/SceneCollector.cs (search UserScripts) |
ROADMAP.md "Graph authoring framework (PS1Graph)" tracks the
slice-by-slice changelog.