Directory and file structure

Repository's root folder

The project repository contains everything needed to develop, document, and release the plugin.
As is standard for Godot addons, the actual code is located in the addons folder. Additional directories in the project root are used for documentation, automation, and a Godot project, which is automatically created in the game folder as soon as the plugin is enabled.

Below is the directory structure of the main Popochiu repository:

<Project Root>
├── .github                                 <-- Holds GitHub-related stuff, such as issue templates
|                                               and workflows actions.
|
├── addons
│   └── popochiu                            <-- The Popochiu Plugin and Engine reside here.
|                                               This is the part distributed in releases.
|
├── builds                                  <-- Used by release automation; should remain empty.
|
├── docs                                    <-- Contains the source for the documentation you are reading.
│   ├── dist                                <------ Used by release automation; you can ignore this.
│   ├── scripts                             <------ Holds scripts related to release automation.
│   └── src                                 <------ The main documentation source folder,
|       |                                           organized into subdirectories for each section.
│       ├── assets                          <---------- A special folder for public assets like
|       |                                                images, CSS files, and other resources.
|       └── < ... content folders ... >
├── game                                    <-- Automatically created when the plugin is enabled;
|                                               contains a functional Popochiu game. Not versioned.
└── release-notes                           <-- Contains text files with release notes, used during
                                                the release process.

In the root directory, you’ll also find the following notable files:

home_banner.png  
icon.svg  
LEEME.md  
LICENSE  
popochiu.ico  
README.md  

These files are related to the project's README (available in Spanish as well) and general branding. Additionally, there’s the project.godot file, which is distributed with the plugin but generally should not be included in PRs unless under very specific circumstances.

You’ll also find the project’s .gitignore file. It’s fairly standard, excluding Godot-generated import files, common editor junk, and some files generated by release automations. It’s a good idea to review it and understand what’s excluded from the project before moving forward.

Popochiu Addon folder

We won’t delve too deeply into the plugin's content here (refer to the Project Overview section for more details), but the addons folder is organized as follows:

/addons/popochiu
|
├── editor                                  <-- Contains `@tool` scripts that extend Godot's editor
|   |                                           functionality, adding Popochiu docks, panels, gizmos, etc.
|   |
│   ├── canvas_editor_menu                  <------ Logic for adding buttons to the scene toolbar.
│   ├── config                              <------ Logic and defaults for project and editor settings.
│   ├── factories                           <------ Factory classes for creating Popochiu objects
|   |                                               (rooms, characters, dialogues, props, etc.).
│   ├── gizmos                              <------ Custom gizmos for Popochiu objects, used in scene
|   |                                               preview to interactively set their properties.
│   ├── helpers                             <------ Classes with commonly used static methods.
│   ├── importers                           <------ Asset importers for various formats.
│   ├── inspector                           <------ Extensions and customizations for the inspectors of
|   |                                               Popochiu objects.
│   ├── main_dock                           <------ Implementation of Popochiu's main dock (entry point
|   |                                               for all game elements).
│   └── popups                              <------ Editor popups for tasks like running migrations,
|                                                   object creation, progress bars, project setup, etc.
|
|
├── engine                                  <-- Contains the game engine — the core that actually runs your game.
|   |                                           Subfolder names are mostly self-explanatory and represent
|   |                                           various engine subsystems (see "Project Overview" section).
│   ├── audio_manager
│   ├── cursor
│   │   └── sprites
│   ├── helpers                             <------ Contains helper functions useful in both game scripts
|   |                                               and core engine code.
|   |
│   ├── interfaces                          <------ Provides code for Singleton accessors (A, C, E, etc.).
|   |
│   ├── objects
│   │   ├── character
│   │   ├── clickable
│   │   ├── dialog
│   │   ├── gui
│   │   ├── hotspot
│   │   ├── inventory_item
│   │   ├── prop
│   │   ├── region
│   │   ├── room
│   │   ├── transition_layer
│   │   └── walkable_area
│   ├── others                              <------ Contains miscellaneous engine logic.
│   └── templates                           <------ Game UI templates (e.g., 9-Verbs, SimpleClick, Icon-Bar).
│       └── gui
├── icons
├── migration                               <------ Handles the logic for upgrading users' projects to new
|   |                                               Popochiu versions as they are released.
│   ├── helpers
│   ├── migration
│   └── migrations
└── palette

If your contribution adds new elements to the engine or plugin, please ensure they are placed in their appropriate locations.