DOCSEARCHbyAlgolia
Submit Docs

Popochiu

repository·develop·Indexed 43 days ago

https://github.com/carenalgas/popochiu

A Godot engine plugin for creating point-and-click adventure games. It includes a runtime engine for game logic—covering rooms, characters, inventory, and dialogue systems—and a specialized editor suite featuring a dedicated Popochiu Dock, visual creation tools, and Aseprite import capabilities.

Tokens
46.3K
Snippets
87
Records
222
Agent score
54%

What's inside Popochiu

  1. What is Popochiu?

    develop

    Popochiu is a Godot plugin designed for creating point-and-click adventure games. It is inspired by tools like Adventure Game Studio and PowerQuest.

    It functions through two main components:

    • Runtime Engine: Provides the logic for rooms, character management, inventory, dialogue systems, save/load support, and interaction mechanics.
    • Editor Plugin: Provides a dedicated Popochiu Dock, visual creation tools with custom gizmos, dialogue tree management, and Aseprite import capabilities.

  2. Overview of Popochiu for Godot

    develop
    Popochiu is a developer-friendly addon designed for creating point-and-click adventure games within the Godot engine. It provides both a specialized adventure game engine and a dedicated Godot Editor plugin to streamline workflows similar to Adventure Game Studio or PowerQuest. It is suitable for both high-resolution and retro-styled games and supports multiple platforms including PC, mobile, and consoles.

  3. Summary of Popochiu scripting foundations

    develop

    Popochiu scripting relies on three core pillars:

    1. Singletons (E, R, C, I, D, A, G, T, Globals, Cursor): Provide global access to all game systems and objects.
    2. Virtual Functions (_on_click(), _on_room_entered(), etc.): Used to define how a specific object behaves in response to direct player actions.
    3. Signals: Used to react to engine-level events or changes occurring on other objects.

  4. Roadmap for creating a basic game stub

    develop

    The following workflow is used to build a functional game stub from scratch in Popochiu:

    1. Game Setup: Set game resolution and select the game GUI.
    2. Character Management: Create characters, add additional characters, and designate the main character.
    3. Room Creation: Create the first room, add Walkable Areas, add hotspots, script interactions, and add props.
    4. Inventory: Add inventory items and implement logic to use them.
    5. Dialogue: Script dialogues and interactions.
    6. UI Customization: Customize the Game UI to fit your project needs.

  5. Understand the Popochiu repository structure

    develop

    The Popochiu repository is organized into several top-level directories. The actual plugin code is located in the addons/popochiu folder, which is the part distributed in releases. Other directories handle documentation, automation, and a sample game project.

    Key directories:

    • addons/popochiu: The Popochiu Plugin and Engine.
    • docs: Source files for the documentation.
    • game: A functional Popochiu game project created automatically when the plugin is enabled. This folder is not versioned.
    • builds: Used by release automation (should remain empty).
    • release-notes: Text files used during the release process.
    <Project Root>
├── .github                                 <-- GitHub-related stuff
├── addons
│   └── popochiu                            <-- The Popochiu Plugin and Engine
├── builds                                  <-- Release automation (keep empty)
├── docs                                    <-- Documentation source
│   ├── dist                               <-- Release automation output
│   ├── scripts                             <-- Release automation scripts
│   └── src                               <-- Main documentation source
├── game                                    <-- Automatically created game project
└── release-notes                           <-- Release notes text files

  6. Overview of Popochiu components

    develop

    Popochiu is divided into two main components that work together to facilitate point-and-click adventure game development:

    1. The Engine (Runtime)

    Handles the game logic and execution. Key features include:

    • Character Management: Supports various emotions during dialogues.
    • Room Systems: Includes interactive objects, points of interest, local characters, walkable areas, reactive regions, and placeholders.
    • Inventory & Dialogue: Built-in inventory management and script-based dialogue systems for complex interactions.
    • Game State: Support for save/load systems and action history.
    • Audio & UI: Customizable transitions, background music, sound effects, and a command-based GUI framework.

    2. The Editor (Plugin)

    An extension for the Godot editor that provides tools for content creation:

    • Popochiu Panel: Centralized access to all game elements.
    • Visual Creation: Custom gizmos for special properties and visual management of all game elements.
    • Asset Pipeline: Direct import of Rooms, Characters, and Inventory items from Aseprite files, preserving their structure.
    • Dialogue Management: Visual tools for managing dialogue trees.

  7. Use the Main Dock to manage game elements

    develop

    The Main Dock (editor/main_dock) is the central interface for game development. It is organized into tabs, groups, and rows:

    • Tabs: Major categories such as main_tab (Characters, Rooms, Dialogues), room_tab (Props, Hotspots, Markers), and audio_tab (Music, SFX).
    • Groups: Collections of items within a tab that include buttons for creating new child elements.
    • Rows: Individual entries for elements.
      • object_row: Used for general or room-specific objects.
      • audio_row: Used for music and sound effects.

    Rows provide quick access to the scene, script, or specific properties of the represented elements.

  8. Understanding 'await' in Popochiu scripts

    develop

    Because Popochiu uses standard Godot GDScript, the await keyword is critical for sequencing actions.

    When you call an asynchronous function (like walking or talking), using await ensures the script pauses until that action is finished before moving to the next line. If you omit await, the character may attempt to perform multiple actions simultaneously (e.g., walking, talking, and turning all at once), leading to unexpected behavior.

  10. How Popochiu resolves animation names and directions

    develop

    Popochiu uses a specific lookup hierarchy to find the correct animation. This allows for flexible naming and automatic directional handling.

    1. Case Sensitivity and Formatting

    Popochiu prefers snake_case. If the exact name you provided in the Inspector doesn't match, Popochiu will automatically attempt to find a snake_case version of that name. This means you can use camelCase or PascalCase in the Inspector, and it will still resolve to snake_case animations if they exist.

    2. Directional Suffixes

    Popochiu automatically appends directional suffixes based on the character's current facing direction. The suffixes are:

    • _r (right)
    • _dr (down-right)
    • _d (down)
    • _dl (down-left)
    • _l (left)
    • _ul (up-left)
    • _u (up)
    • _ur (up-right)

    Lookup Order:

    1. The name with the directional suffix (e.g., walk_r).
    2. The name with the opposite directional suffix (e.g., walk_l).
    3. The base animation name without a suffix (e.g., walk).
    4. If no match is found, it falls back to the standard Popochiu defaults (idle, walk, or talk).

  11. Data resources: where state lives

    develop

    State in Popochiu is not stored on the scene nodes themselves (as nodes are unloaded when leaving a room), but in data resources (.tres files) that extend specific Popochiu data classes. These resources stay in memory to ensure persistence.

    Object typeData classExample file
    RoomPopochiuRoomDataroom_living_room.tres + room_living_room_state.gd
    CharacterPopochiuCharacterDatacharacter_will.tres + character_will_state.gd
    Inventory itemPopochiuInventoryItemDatainventory_item_key.tres + inventory_item_key_state.gd

    When you create an object via the editor, Popochiu generates both the .tres resource and a corresponding *_state.gd script. You add custom properties to the *_state.gd script. You access this state through the state property on the object (e.g., R.LivingRoom.state or C.Popsy.state).

  12. How character scaling behaves when walking between regions

    develop

    Popochiu supports multiple scaling regions within a single room (e.g., one for a foreground area and another for a distant path).

    Behavior:

    • Entry: A character scales as soon as they step into a scaling region.
    • Exit: When a character exits a region, their scale reverts to their default scale, unless they have entered another overlapping scaling region.

    Handling Complex Perspectives:

    For complex paths that move back and forth, you may need to split the scaling area into multiple polygons. In these cases, you will likely need to overlap the polygons and adjust the scaling factors to achieve the desired visual transition.