Popochiu

Related skills: dialogue-system for hand-rolled dialogue data, inventory-system for generic inventory patterns, save-load for core-engine persistence.

Addon: Popochiu · version v2.1.1 · Godot 4.6 · MIT · source: https://github.com/carenalgas/popochiu · pure GDScript (no C# API — GDScript-only skill).

1. When to use Popochiu

Choose Popochiu when you're building a classic point-and-click adventure and want the room/character/prop/dialog/inventory pipeline pre-built, with a dock that scaffolds new objects and autoload registries that give autocomplete (R.House, C.Popsy, I.Key, D.PopsyHouseChat). Hand-roll with dialogue-system + inventory-system + state-machine when your genre isn't point-and-click, or you need full control over the interaction model. Popochiu requires Godot 4.6 and is GDScript-only (no C# API).

2. Install & project setup

1. Get Popochiu from itch.io or GitHub Releases; copy addons/popochiu/ into your project.
2. Project → Project Settings → Plugins → enable Popochiu. Godot prompts a restart — Project → Reload Current Project.
3. On first run, PopochiuResources.init_file_structure() scaffolds res://game/ (layout below) plus popochiu_data.cfg (a ConfigFile registry of every room/character/item/dialog) and popochiu_globals.gd (an empty Globals autoload — add your own state here).
4. The setup wizard pops up automatically (re-open via the dock's "Setup" button): pick a game type (Retro / Pixel Art or Modern / Hi-Res — sets the stretch aspect and pixel-art texture filtering; the custom-settings form offers Custom / Pixel Art / High Resolution), a Resolution, and a GUI Template (9 Verb, the Sierra-style "Action Bar", Simple Click, or Custom).
5. Two companion plugins, PopochiuImporters (Aseprite import docks) and PopochiuGizmo, are enabled automatically along with Popochiu.

Dock-generated layout:

res://game/
  popochiu_globals.gd        # Globals autoload — add vars/on_save/on_load
  popochiu_data.cfg          # registry of rooms/characters/items/dialogs/GUI/setup
  autoloads/{r,c,i,d,a}.gd   # generated — never hand-edit; rewritten per new object
  rooms/<name>/room_<name>.gd (+ .tscn, state script)
  characters/<name>/character_<name>.gd (+ .tscn, state script)
  inventory_items/<name>/inventory_item_<name>.gd (+ .tscn, state script)
  dialogs/<name>/dialog_<name>.gd (+ .tres)
  gui/gui.tscn, gui/gui_commands.gd
  transition_layer/transition_layer.tscn (+ .gd)

3. Core concepts & the one-letter autoloads

Game scripts talk to Popochiu almost entirely through short autoload singletons (not PopochiuUtils or class names, which are for engine-internal code):

R/C/I/D back onto generated files (res://game/autoloads/*.gd) rewritten every time you create an object in the dock — never hand-edit them; put custom logic in the object's own script instead. Two more singletons round out the surface: T (PopochiuITransitionLayer, screen transitions — §4) and Cursor (mouse cursor rendering).

4. Rooms & navigation

Create rooms from the dock's "Create room" button — it scaffolds room_<name>.gd/.tscn under res://game/rooms/<name>/ with child nodes $Props, $Characters, $Hotspots, $Regions, $WalkableAreas, $Markers. A room needs at least one enabled Walkable Area or characters won't path on click.

R.goto_room() changes rooms — there is no E.goto_room(); room navigation lives on R:

func _on_click() -> void:
    await C.player.walk_to_clicked()
    R.goto_room("Garden")

E.queue() scripts a cutscene from an ordered instruction list — mix Callables (the queue_* twin of any action) and plain strings:

func _on_room_transition_finished() -> void:
    E.queue([
        "Popsy: Finally, some fresh air.",
        C.Popsy.queue_walk_to(Vector2(400, 300)),
        "...",  # 1s pause
        C.Popsy.queue_say("Now, where did I put that key?"),
    ])

String shorthand accepted by queue()/cutscene(): "Name: text" (says a line), "Name(emotion): text", "Name[N]: text" (auto-continues after N seconds), "."/".."/"..." (0.25s/0.5s/1s pauses, doubling per dot), any other string shown via G.show_system_text(). E.cutscene() is additionally skippable via the popochiu-skip input action (default Esc).

Room transitions go through T (new in 2.1) — not the deprecated E.play_transition()/E.queue_play_transition() (still present in 2.1.1 but print a runtime warning):

await T.play_transition("fade", 0.5, T.PLAY_MODE.IN_OUT)

R.goto_room() plays the project's default transition automatically unless called with use_transition := false.

5. Interactions

Props, Hotspots, and Characters all extend PopochiuClickable and share one virtual lifecycle. Override these underscore-prefixed methods in generated scripts — the engine calls public wrappers (on_click(), etc.) that call these internally, so never override the public wrapper itself:

# prop_key.gd
extends PopochiuProp

func _on_click() -> void:
    await C.player.walk_to_clicked()
    I.Key.add_as_active()

func _on_item_used(item: PopochiuInventoryItem) -> void:
    if item == I.Oil:
        await C.player.say("That should stop it squeaking.")

Full callback set: _on_room_set, _on_click, _on_double_click, _on_right_click, _on_middle_click, _on_item_used(item), _on_position_changed, _on_movement_started, _on_movement_ended.

Command-based GUI, at a glance: each shipped GUI template (9 Verb / Sierra / SimpleClick) registers verbs via E.register_command(id, "Display Name", fallback). On click, Popochiu snake_cases the active command and looks for on_<command>() on the clicked object (e.g. on_look_at()) before falling back to _on_click(). Full mechanics — including E.current_command, registering custom commands, and the deprecated E.active_command snippet you may see in older tutorials — are in references/gui.md.

6. Characters & dialog basics

Create characters from the dock; the first one created becomes the Player Character. Say a line with an optional emotion:

await C.player.walk_to_clicked()
await C.player.say("What a mess.", "annoyed")

Emotions map to voices and avatars export arrays (emotion name → audio cue / GUI portrait); say() sets emotion for the duration of the line, then resets it to "".

Start a named dialog tree from a click handler:

func _on_click() -> void:
    await C.player.face_clicked()
    D.PopsyHouseChat.start()

Dialog trees are PopochiuDialog resources with branching options, per-option conditions, and handler methods — full authoring pattern (including the Array-only turn_on_options()/turn_off_options() gotcha) is in references/dialogs.md.

Deep dives: references/dialogs.md, references/inventory.md, references/gui.md, references/pipeline.md

Implementation checklist

• Popochiu enabled in Project Settings → Plugins; project reloaded after enabling
• Setup wizard run once (Game Type, Resolution, GUI Template) before authoring rooms
• Every room has at least one enabled Walkable Area, or characters won't path on click
• Room navigation uses R.goto_room() — not a nonexistent E.goto_room()
• Cutscene scripting uses E.queue([...])/E.cutscene([...]), not bare queue_*() calls (those are silent no-ops outside a queue)
• Non-queue_ action calls (say(), walk_to(), …) are awaited, or they run concurrently instead of sequentially
• Room transitions use T.play_transition(), not the deprecated E.play_transition()
• res://game/autoloads/{r,c,i,d,a}.gd are never hand-edited — they're dock-regenerated
• Custom persisted fields live on the generated *_state.gd resource (JSON-safe types, or _on_save/_on_load overrides for complex ones)
• turn_on_options()/turn_off_options()/turn_off_forever_options() are called with an Array, even for one id
• Command handlers use on_<command>() (verb-specific) or the _on_click() fallback — never override the public on_click() wrapper itself
• GUI template chosen once and treated as a starting point — switching templates later replaces the whole res://game/gui/ tree