PS1Graph Behavior Tree Authoring¶
How to author a Behavior Tree in the PS1Graph dock and tick it from Lua. Fifth graph kind alongside Dialogue / FSM / Quest / Untyped. Fills the "decide what to do this tick" niche that FSM (state + transition) doesn't cover well.
When to use which:
- FSM — entity has a current state (patrol / chase / attack) and explicit events trigger transitions ("see_player" sends patrol → chase). Compact for 3-6 state archetypes.
- BT — entity re-decides what to do each tick by walking a prioritised tree. Better for: "try to attack if I can, else flank if I can, else patrol." Scales better than nested-FSM conditions when an entity has many fallback behaviours.
TL;DR — five steps¶
- Author the tree. PS1 Graph dock →
Kind: Behavior Tree→ New → right-click → drop BT Sequence / BT Selector / BT Leaf nodes. - Wire children. Composites have 6 child exec-out slots. Wire each used slot to a child node. Empty slots compile out.
- Author leaf snippets. Each Leaf's Lua must
return "success","failure", or"running". Receivesself(the BT instance). - Save. Sibling
<basename>.luais auto-written with_G.bt_<basename>. - Tick from Lua. From your scene's per-frame Lua:
What it compiles to¶
_G.bt_my_bot = {
root = "n0",
nodes = {
n0 = { kind = "selector", children = {"n1", "n4"} },
n1 = { kind = "sequence", children = {"n2", "n3"} },
n2 = { kind = "leaf", fn = function(self) return self.actor:CanSeePlayer() and "success" or "failure" end },
n3 = { kind = "leaf", fn = function(self) return self.actor:Attack() end },
n4 = { kind = "leaf", fn = function(self) self.actor:Patrol(); return "running" end },
},
}
The author reads top-to-bottom:
1. Selector tries the attack sequence first (n1).
2. n1 (Sequence) requires can-see-player AND attack to both
succeed.
3. If either fails, the Selector falls back to n4 (patrol),
which returns "running" to indicate "still working on it."
Composite semantics¶
Sequence (bt_sequence): walks children left-to-right.
- First failed child → return "failure" immediately.
- First child returning "running" → return "running"; next
Tick resumes from the same child.
- All succeed → return "success".
Selector (bt_selector, a.k.a. "fallback"): walks
left-to-right.
- First succeeded child → return "success".
- First child returning "running" → return "running"; resume
from the same child next Tick.
- All fail → return "failure".
Leaf API¶
The Lua snippet on a Leaf node MUST return one of the three result
strings. Anything else is treated as "failure". The walker
wraps the snippet as:
So return is implicit — write an expression that evaluates to
the result string:
self is the BT instance. Useful fields:
self.actor— whatever was passed tobt:Tick(actor)this frame.self._scratch— empty table you can write to for per-instance state ("how long have I been chasing this target?").self:Reset()— clears all in-flight"running"state on composites so the next tick restarts each subtree from its first child.
Multiple instances¶
BT.new(def) creates an independent instance. One tree
definition can back many entities — each tracks its own
_running + _scratch:
local def = _G.bt_my_bot
local enemy_a = BT.new(def); enemy_a.id = "a"
local enemy_b = BT.new(def); enemy_b.id = "b"
-- a and b advance independently.
Limits to know about¶
- 6 children per composite. Authors with more chain composites (nest a Sequence inside another Selector slot). Variable-pin GraphNodes are a Godot framework limitation.
- No decorator nodes (yet). Common BT primitives like Inverter
/ Repeater / Cooldown aren't shipped. Workaround: wrap the
condition into the Leaf's snippet (
return not <expr>for inverter; track tick counts inself._scratchfor repeat / cooldown). - Leaf snippets are single-line. Same as the dialogue / FSM /
quest pattern. Multi-statement chains via
;; the right-pane Node Details inspector gives a multi-line TextEdit if you need it. - No tick rate control.
bt:Tick(self)is called once per frame from your Lua. Want a tick every N frames? Wrap the call in your own counter.
Where the code lives¶
| Concern | File |
|---|---|
| Dock palette + visual body | godot-ps1/addons/ps1godot/ui/PS1GraphEditorDock.cs (bt_sequence / bt_selector / bt_leaf cases) |
Compiler (CompileBt) |
godot-ps1/addons/ps1godot/graph/PS1GraphCompiler.cs |
Runtime BT.new |
psxsplash-main/src/lua.cpp (kBtHelperSrc block in Lua::Init) |
| Companion docs | docs/ps1graph-dialogue-authoring.md, docs/ps1graph-fsm-authoring.md, docs/ps1graph-quest-authoring.md |