Popochiu — Dialog Trees
Deep dive for ../SKILL.md §6. Source:
addons/popochiu/engine/objects/dialog/popochiu_dialog.gd(PopochiuDialog extends Resource),popochiu_dialog_option.gd(PopochiuDialogOption extends Resource),addons/popochiu/engine/interfaces/i_dialog.gd(Dsingleton).
Resource structure
A dialog tree is a .tres PopochiuDialog resource with an options: Array[PopochiuDialogOption] export, created via the dock's "Create dialog" button (res://game/dialogs/<name>/dialog_<name>.gd + .tres). Each PopochiuDialogOption has:
| Field | Type | Default | Meaning |
|---|---|---|---|
id |
String |
— | Option identifier, matched in _option_selected / used to derive _on_option_<snake_case_id> |
text |
String |
— | Line shown in the options list |
visible |
bool |
true |
Shown in the current options list |
disabled |
bool |
false |
Not rendered at all; set by turn_off_forever(), and turn_on() cannot undo it |
always_on |
bool |
false |
Always rendered as not yet used (the menu never greys it out) |
used / used_times |
bool / int |
runtime | Tracks whether/how often the option was picked |
Options are authored either in the Inspector (Add Element on the options array) or from code via create_option(id: String, config: Dictionary = {}) -> PopochiuDialogOption inside the _on_build_options virtual — useful when you want to mix Inspector-authored options with procedurally generated ones.
Dialog virtual lifecycle
func _on_build_options(existing_options: Array[PopochiuDialogOption]) -> Array[PopochiuDialogOption]
# optional — return existing_options plus any code-created options
func _on_start() -> void
# must await something — the engine awaits this before showing options
func _option_selected(opt: PopochiuDialogOption) -> void
# called for every picked option; not awaited, see below
func _on_save() -> Dictionary
func _on_load(data: Dictionary) -> voidInstead of one big match in _option_selected, Popochiu also calls a method named _on_option_<snake_case(option.id)> if it exists — option id BYE2 calls _on_option_bye_2(opt) — and shows the options again after it returns. _option_selected is called first but not awaited, so an _on_option_<id>() method starts as soon as _option_selected() reaches its first await and the two run interleaved. Use one style per tree, not both for the same option.
Branching / condition pattern
Verified tutorial example (docs/src/how-to-develop-a-game/script-your-first-dialogue.md, v2.2.1):
func _option_selected(opt: PopochiuDialogOption) -> void:
match opt.id:
"MessyRoom":
await D.say_selected()
await C.Popsy.say("Errr... sorry, I forgot to tidy up!")
turn_off_options(["MessyRoom"])
turn_on_options(["AskBored"])
"Bye":
await D.say_selected()
stop()
_:
stop() # fallback — always include one so an unhandled option doesn't soft-lock the dialog
_show_options()PopochiuDialog public API used in branching logic — all three take an Array, even for one id:
func turn_on_options(ids: Array) -> void
func turn_off_options(ids: Array) -> void
func turn_off_forever_options(ids: Array) -> void
func get_option(opt_id: String) -> PopochiuDialogOption
func start() -> void # queue_start() twin
func stop() -> void # queue_stop() twinThe addon's tutorial warns against passing a bare string (turn_off_options("MessyRoom")) — always wrap in [...].
PopochiuDialogOption instance methods: turn_on(), turn_off(), turn_off_forever() — equivalent single-option shortcuts to the tree-level calls above.
D (PopochiuIDialog) API
func show_inline_dialog(options: Array) -> PopochiuDialogOption # ad hoc option list outside a named tree
func finish_dialog() -> void
func say_selected() -> void # makes C.player say the selected option's text
func create_gibberish(input_string: String) -> String # bbcode-preserving scrambler (spoiler masking, unknown-language effect)
func get_instance(script_name: String) -> PopochiuDialogState: D.active: bool, D.current_dialog: PopochiuDialog, D.selected_option: PopochiuDialogOption, D.trees: Dictionary (per-dialog state cache), D.prev_dialog: PopochiuDialog.
Signals: dialog_started(dlg), option_selected(opt), dialog_finished(dlg), dialog_options_requested(options), inline_dialog_requested(options).
Starting a dialog
func _on_click() -> void:
await C.player.face_clicked()
D.PopsyHouseChat.start()D.PopsyHouseChat is a dock-generated getter on the D autoload (res://game/autoloads/d.gd) — every dialog tree you create in the dock gets one, giving autocomplete for D.<DialogName>.