---
name: popochiu
description: Use when using the Popochiu addon — point-and-click adventure framework with rooms, characters, props/hotspots, inventory, dialog trees, and a command-based GUI
title: popochiu
canonical_url: https://skilld.dev/gh/jame581/godotprompter/popochiu
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/dialogs.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/dialogs.md), [references/gui.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/gui.md), [references/inventory.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/inventory.md), [references/pipeline.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/pipeline.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/popochiu`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/popochiu`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/popochiu) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/popochiu`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/popochiu --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/popochiu --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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.2.1` · Godot 4.7 (use 2.1.x on 4.6) · MIT · source: https://github.com/carenalgas/popochiu · pure GDScript (no C# API — GDScript-only skill).

> **Godot 4.8:** not yet confirmed by the addon. The README says 2.2.1 targets Godot 4.7, and no open issue mentions 4.8 (checked 2026-11-12).

---

## 1. When to use Popochiu

| Approach | Best for |
|---|---|
| Hand-rolled (`dialogue-system` + `inventory-system` + `state-machine`) | Custom genre, tight control over every system, no editor tooling needed |
| **Popochiu** | Full point-and-click adventure (AGS/PowerQuest-style): rooms, walk-to-click, verb-based interaction, dialog trees, inventory, save/load — wired together with dock-generated scaffolding |

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 v2.2.1 targets **Godot 4.7** and is GDScript-only (no C# API).

---

## 2. Install & project setup

1. Get Popochiu from [itch.io](https://carenalgas.itch.io/popochiu) or [GitHub Releases](https://github.com/carenalgas/popochiu/releases); copy `addons/popochiu/` into your project.
2. **Project → Project Settings → Plugins** (**Project Settings → Addons → Plugins** on 4.8) → enable **Popochiu**. Godot prompts a restart — **Project → Reload Current Project**. Upgrading a 2.1.x project: open it in **2.2.0** first so its migrations rewrite your scripts, then move to 2.2.1, which removes the methods old scripts may still call. For touch devices keep **Emulate Mouse From Touch** on (Popochiu reads mouse events only).
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):

| Autoload | Interface | Purpose | Key signature |
|---|---|---|---|
| `E` | `Popochiu` | Core engine: queue/cutscene scripting, save/load, camera, commands | `func queue(instructions: Array, show_gui := true) -> void` |
| `R` | `PopochiuIRoom` | Room registry & navigation | `func goto_room(script_name := "", use_transition := true, store_state := true, ignore_change := false) -> void` |
| `C` | `PopochiuICharacter` | Character registry (`C.player`, `C.Popsy`) | `func walk_to_clicked(offset := Vector2.ZERO) -> void` |
| `I` | `PopochiuIInventory` | Inventory registry & active item | `func set_active_item(item: PopochiuInventoryItem = null) -> void` |
| `D` | `PopochiuIDialog` | Dialog registry & inline dialogs | `func show_inline_dialog(options: Array) -> PopochiuDialogOption` |
| `G` | `PopochiuIGraphicInterface` | GUI control: block/unblock, show/hide, hover/system text | `func show_system_text(msg: String, params: Variant = null) -> void` |
| `A` | `PopochiuIAudio` | Audio cue registry (`A.sfx_boing`) | `func is_playing_cue(cue_name: String) -> bool` |

`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`:

```gdscript
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 `Callable`s (the `queue_*` twin of any action) and plain strings:

```gdscript
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` — `E.play_transition()`/`E.queue_play_transition()` were removed in 2.2.1:

```gdscript
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

| Type | Base | Purpose |
|---|---|---|
| **Prop** | `PopochiuProp` (`Area2D`) | Visible/interactive scenery — sprite, optional `link_to_item`, can be a nav obstacle |
| **Hotspot** | `PopochiuHotspot` (`Area2D`) | Invisible interaction zone (no sprite of its own — e.g. part of the background art) |
| **Region** | `PopochiuRegion` (`Area2D`) | Trigger area that tints/scales a character on enter/exit; does **not** receive clicks. `walkable = false` makes it block walking (`character_blocked` signal; a character opts out with `ignore_blocking_regions`) |

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:

```gdscript
# 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](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/gui.md).

---

## 6. Characters & dialog basics

Create characters from the dock; the first one created becomes the Player Character. Say a line; the emotion comes from the character's `emotion` member:

```gdscript
await C.player.walk_to_clicked()
C.player.emotion = "annoyed"
await C.player.say("What a mess.")
C.player.emotion = ""
```

Emotions map to `voices` and `avatars` export arrays (emotion name → audio cue / GUI portrait); `say()` only reads the current `emotion`; its second argument is format data (`Array` for `%`, `Dictionary` for `String.format()`), not an emotion (2.2 breaking change). Only the queue shorthand `"Player(annoyed): What a mess."` sets the emotion and resets it after the line.

Start a named dialog tree from a click handler:

```gdscript
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](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/dialogs.md).

Deep dives: [references/dialogs.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/dialogs.md), [references/inventory.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/inventory.md), [references/gui.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/gui.md), [references/pipeline.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/popochiu/references/pipeline.md)

---

## Implementation checklist

- [ ] Popochiu enabled in **Project Settings → Plugins** (**Project Settings → Addons → Plugins** on 4.8); 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 `await`ed, or they run concurrently instead of sequentially
- [ ] Room transitions use `T.play_transition()`, not the removed `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
