Popochiu v2.1.0

The time has finally come! After months of work, we're thrilled to announce the release of
Popochiu v2.1.0, a major update packed with new features, improvements, and bug fixes that take
our beloved adventure game engine to the next level.

This release contains 46 improvements among bugfixes, new features, and quality-of-life enhancements,
plus a significant overhaul of the documentation to make it more comprehensive and user-friendly than
ever before.
We are very proud of this one and we hope you'll find it as exciting to use as it was to build.

As always, make sure to read the Final Notes before upgrading!

Fixes

• The inventory limit defined in Project Settings is now correctly enforced when adding items from the Popochiu panel.
• Godot no longer crashes after scaffolding complex scenes such as characters or rooms.
• Camera not following the player and console errors after migrating a project from beta 3 to 2.0 have been resolved.
• Calling E.goto_room() with an invalid room name now gives a clear, descriptive error instead of a cryptic type mismatch - Thanks to @balloonpopper.
• Cleaned up some small debugger errors - again thanks to @balloonpopper.
• Region-based character scaling now works consistently regardless of movement direction.
• The player character can no longer be hovered or clicked when its clickable flag is enabled.
• Games no longer crash at startup when a room has no walkable areas.
• AudioCue now loops correctly in Godot 4.5+ - thanks to @cidneyhamilton.
• Character removed from a room are now permanently removed instead of reappearing after a scene reload.
• Solved some errors happening when deleting objects from the dock, asking to remove their files too.
• On the same line Godot doesn't crash anymore after creating the first room (was happening since 4.4.1).
• Problem with a corner case in Migration 6 solved - thanks to @idbrii.
• Room node is not selected at creation (as it used to...)
• Small UX improvement to polygon editing experience
• The save/load system is now more type-safe - Thanks to @jmschrack

Improvements

Character system

• Characters can now follow other characters, with configurable trigger distance, stop distance, facing behaviour, and cross-room following — perfect for sidekicks and multi-character games.
• The character-following and character-facing APIs have been expanded with explicit start_following_character(), stop_following_character(), start_facing_character(), and stop_facing_character() helpers, plus migration support for older follow-player projects - thanks to @cidneyhamilton for a first draft implementation that underwent further refinement.
• Character outfits are now supported via an animation prefix: set a string like "pajama" and the engine will automatically look for prefixed animations (PajamaWalk, PajamaTalk, etc.), falling back to the standard set.
• Characters can now make dialog portraits flip automatically based on their facing direction, and the feature was later refined with additional configuration for when flipping should happen - thanks to @edmundito for the initial implementation that has been further expanded.
• Dialog position can now be temporarily overridden or offset, with new dialog_position_offset, dialog_position_override, lock_dialog_position() and unlock_dialog_position() APIs.
• A new face_away() helper lets characters turn to the opposite direction with a single call, no matter where they are facing.
• The base animations for idle, walk, and talk are now configurable via inspector properties, making it easy to support states like limping, sliding, or gliding without custom code.
• Several useful read-only properties have been exposed on characters: target_position, is_talking, is_animating, is_visible_in_room, and current_animation.
• Walking logic has been moved from the Room to the Character, improving separation of responsibilities and unblocking related improvements.
• Characters and props now have an alpha property plus fade_in() and fade_out() methods for smooth transparency effects.
• Characters (and Props as well) can now define an encumbrance collider that forces other characters to walk around them. You make it relevant with an obstacle flag and characters with ignore_obstacles flag active can still walk through it (useful for ghostly/ethereal characters).
• Characters customized to use AnimatedSprite2D internally are now properly supported where frame_changed needs to be detected - thanks to @idbrii for generalizing the logic without introducing any special case.

Clickables and inventory

• enable()/disable() now affect both visibility and interactivity on clickables, with dedicated enable_clickability()/disable_clickability() methods and an is_enabled() getter added.
• Inventory items now have a was_removed property so props linked to items can detect when their item has left the inventory.
• Clickables and inventory items now track command interactions via ever_invoked(command), first_invoked(command), and count_invoked(command), allowing for more complex interaction logic based on player behavior.

GUI and game setup

• High-resolution versions of all three GUI templates (SimpleClick, 9-Verbs, Sierra) are now included and available from the Setup window, making Popochiu a proper choice for non-pixel-art games.
• The game Setup window has been redesigned as a wizard: step through game type, resolution, and GUI selection with clear visual cues. A "Custom" path remains available for those who want full control.
• The SimpleClick GUI has been redesigned: the settings bar has moved to a popup triggered by a dedicated button, leaving a cleaner single bar for the inventory — and more room for future customization.
• The Transition Layer has been fully refactored: it now uses shaders, is copied to the game folder on setup (like GUIs), and is exposed as a T singleton (T.play("fade")). A bunch of new transitions are now available, and documentation has been added on how to create custom transitions effects for your game. Future versions will provide a section in the Main Dock to make creating custom transitions easy for everyone. - Thanks to @drbb for this major improvement that will make transitions more flexible and easier to customize.

Aseprite importer

• The Aseprite importer is now a first-class dock panel rather than living in the inspector, with a cleaner layout that works in both dark and light themes.
• Inventory items now have their own Aseprite importer: organize all item sprites in a single .aseprite file, tag them by name, and import everything at once. Supports animations!
• The importer UX has been significantly polished: animations are clickable (opens the Animation panel), each row has a delete button and an AutoPlay toggle, sensible loop defaults are applied per object type, and the Import button now stands out.
• Completion of the core Aseprite importer epic (it was issue number 8, can you imagine how long it sat there?): rooms, characters, and inventory items all have a consistent, tag-based import workflow. Future release will improve on this base to provide even more automation and convenience.

Editor

• Markers now have a proper gizmo handle, consistent with the walk-to and look-at point gizmos introduced earlier.
• Several Popochiu Dock UX improvements: clicking an object in the dock now selects it in the open scene, and opening a scene from the dock selects its root node (activating gizmos and toolbar).
• Create popups are smoother to use now because the name field gets focus automatically - thanks to @idbrii.

Other

• Godot 4.6 is now supported and it's the target version to use with 2.1.0.
• The migration script counter is now compatible with Godot 4.4+, which creates .uid files alongside scripts.
• The version shown in Godot is now correct again, avoiding confusion when checking which Popochiu release is installed.
• Popochiu's Project Settings entries are now visible without enabling the "Advanced" flag.
• It is now possible to add all (or some) options for a Dialog from code - Thanks to @idbrii.

Documentation

• We revisited the tutorial documentation, rephrasing several passages and adding missing details to make the onboarding path clearer and less error-prone for new users (#468).
• We have added a new section to the documentation covering the Transition Layer refactor and how to create custom transitions (#288).
• The The Engine Handbook section has been reworked entirely: the way we export the code reference makes it incredibly more relevant and readable; every public API is now documented with clear descriptions, parameter explanations, and usage examples; we excluded less relevant public classes and methods but they are still fully available inside Godot by inline docs. In addition, the handbook is not actually a handbook, providing explanations about how the engine works, which parts it's made of and how to write games scripts. More will come, but this is a huge step forward in making the engine more accessible and easier to learn for new users, while also providing a more comprehensive reference for experienced developers.

Toolchain and contributor goodies

The repository has received a round of important non-functional improvements that will make it easier for us (and other contributors) to maintain and progress:

• The docs production build is working again (and dramatically improved in speed, features and final results! See the section on annotations in docs/README.md for details)
• The project's .gitignore has been cleaned up to properly exclude unrelated addons from the main repo (#413): this will help contributors using their favorite Godot addons in their local development environments without accidentally committing their code to Popochiu repository.
• A bunch of modern AI-assisted/agentic coding instructions have been added to the repository for those who use AI-powered editors in their workflow:
  • GitHub Copilot instructions + AGENTS.md provide guardrails and instructions for agents to obey when working on the codebase.
  • A custom skill for writing release notes that automates the data collection and drafting of release notes, making it quicker for us to list everything that changed, crediting the right people and moving on producing more value. For those who wonder, we tested the skill on these very release notes and it's working like a charm!

IMPORTANT NOTE: At the time being, we approve and encourage the use of AI-assisted techniques for code generation, refactoring, and documentation writing in the Popochiu codebase, BUT read the relevant section of the contributions guidelines before sending AI-generated code for review.

Final Notes

We encourage everyone to upgrade to v2.1.0 to take advantage of the new features and improvements, but please read the following notes carefully:

1. !!! BACKUP YOUR PROJECT !!! While we have done our best to ensure a smooth transition, this release is huge and it contains so many changes that it's impossible to guarantee a 100% hassle-free upgrade for every project. Make sure to commit your project to version control or create a backup before upgrading, so you can easily revert if anything unexpected happens.
2. Godot 4.6 required. This version of Popochiu targets Godot 4.6. If your project is on an earlier version (it probably is if you're using 2.0.x), please upgrade Popochiu in the project's folder THEN open the project with Godot 4.6 so that the migrations can run effectively.
3. SimpleClick GUI has been redesigned. If your game uses the SimpleClick template, re-running the Setup wizard (or manually merging the updated components) is recommended to pick up the new structure.
4. Transition Layer has been refactored. The TL is now copied to your game folder at setup time. Existing projects should re-run setup and remove (or migrate) any customisations in the old location.