Popochiu — Asset Pipeline, Audio, Transitions & Save/Load
Deep dive for ../SKILL.md §4. Covers the parts of the engine that don't fit the core rooms/characters/dialog/inventory narrative.
Aseprite importer
res://addons/popochiu/editor/importers/ ships as its own plugin ("PopochiuImporters"), which the main Popochiu plugin enables automatically. It provides dedicated import docks per object type (aseprite_importer_dock_{character,inventory,room}.gd) that shell out to the aseprite CLI executable to export a sprite sheet + JSON tag/frame data from a .aseprite/.ase file, then build AnimationPlayer animations (in an AnimationLibrary) from the tags that drive the target's Sprite2D/TextureRect frames. This is the recommended way to bring animated characters, props, and room art into a room/character/item's generated scene without manually slicing sprite sheets.
Audio (A)
A (PopochiuIAudio) itself exposes two helpers:
func semitone_to_pitch(pitch: float) -> float
func is_playing_cue(cue_name: String) -> boolActual playback lives on the audio cue resources, reachable as generated A.<cue_name> properties (one per cue registered in the dock, mirroring the R/C/I/D autocomplete pattern):
PopochiuAudioCuebase:fade(duration := 1.0, wait_to_end := false, from := -80.0, to := INF, position_2d := Vector2.ZERO),stop(fade_duration := 0.0),change_stream_pitch(pitch),change_stream_volume(volume),is_playing() -> bool. Exported fields:audio: AudioStream,loop,is_2d,can_play_simultaneous,pitch,volume,rnd_pitch,rnd_volume,max_distance,bus.AudioCueSound:play(wait_to_end := false, position_2d := Vector2.ZERO) -> void.AudioCueMusic:play(fade_duration := 0.0, music_position := 0.0) -> void.
Every cue's play/fade/stop has a queue_* Callable-returning twin for use inside E.queue([...]). Rule of thumb: don't await music (A.mx_theme.play() — let it run in the background), but do await when a cutscene beat depends on a sound finishing (await A.sfx_boing.play(true)).
Room transitions (T)
T (PopochiuITransitionLayer) is the transitions singleton (new in 2.1) and replaced the removed E.play_transition():
func play_transition(anim_name := "", duration := -1.0, mode := -1, color := Color(-1, -1, -1, -1)) -> void # queue_play_transition() twin
func show_curtain(color := Color(-1, -1, -1, -1)) -> void
func hide_curtain() -> void
func get_all_transitions_list() -> PackedStringArray
func get_predefined_transitions_list() -> PackedStringArray
func get_custom_transitions_list() -> PackedStringArrayT.PLAY_MODE re-exports PopochiuTransitionLayer.PLAY_MODE: IN, OUT, IN_OUT. R.goto_room() automatically plays the project's default transition unless called with use_transition := false — you only need T.play_transition() directly for cutscene-driven or non-room-change transitions (e.g. a curtain around a dialog-heavy scripted sequence).
Save/load
Fully covered by E:
func has_save() -> bool
func saves_count() -> int
func get_saves_descriptions() -> Dictionary # {slot_number: description}
func save_game(slot := 1, description := "") -> void # emits game_saved
func load_game(slot := 1) -> void # emits game_load_started, then game_loaded(data)Up to 4 slots by default, written as flat JSON to user://save_N.json.
Persistence model:
- Auto-persisted built-ins: props (only those with
clickableon — a non-clickable prop's state is not saved), hotspots, regions and walkable areas store their script variables of the basic types listed below, minus per-type ignore lists (baseline,clickable,link_to_item, … for props). Characters in a room store position, facing,visible,modulate/self_modulate,light_mask,baseline,walk_to_point/look_at_point/dialog_pos, face/follow settings. Rooms storevisited_times;visitedandvisited_first_timeare read-only values derived from it (never assign them). - Custom state: add fields to the generated
*_state.gd(extendsPopochiuRoomData/PopochiuCharacterData/PopochiuInventoryItemData) — auto-saved only if their type isbool/int/float/String,Array, or a packed string/int/float array — aDictionaryis skipped. - Complex types: override
_on_save() -> Dictionary/_on_load(data: Dictionary) -> voidon the data resource (stubbed in every generated*_state.gd, and in dialog scripts too) to flatten/rebuildVector2,Color, custom inner classes, etc. Globalspersistence: safe-typed properties onGlobalsauto-persist; complex data needs public (no-underscore)on_save()/on_load()methods added manually tores://game/popochiu_globals.gd— these are not stubbed by default, unlike the underscore-prefixed virtuals on data resources.- Two independent mechanisms coexist: cross-room persistence (in-memory, via data resources staying loaded while the game runs) vs. save/load-to-disk (JSON at
user://save_N.json, up to 4 slots). Don't conflate them — a bug in_on_save/_on_loadonly breaks disk saves, not cross-room state during a single play session.