Index of every page on this site: llms.txt
All skills
jame581 avatar

/popochiu

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

Use when using the Popochiu addon — point-and-click adventure framework with rooms, characters, props/hotspots, inventory, dialog trees, and a command-based GUI

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/popochiu

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈43 tokens for metadata: the name and description. ≈2.9k when used: this file. ≈4.8k more on demand in 4 files.

Description uses 2.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈171 characters, or 2.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 or GitHub 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:

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

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:

# 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; the emotion comes from the character's emotion member:

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:

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 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 awaited, 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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning7d3 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    The skill provides comprehensive instructions for using the Popochiu point-and-click adventure framework for Godot 4.7. It covers project setup, room navigation, interaction systems, dialog trees, and the asset pipeline. No security vulnerabilities or malicious patterns were detected.

  • Socket7d

    No alerts

  • Snyk7d

    Risk: MEDIUM · 1 issue

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last week

README badge

README badge for jame581/godotprompter/popochiu