scene/change_scene

Goal

Understand and verify how ChangeSceneCommand works at runtime:

  • how input enqueues a scene-change command

  • how SceneAdapter.change() replaces the active stack

  • why scene-local state resets after each transition

Why this tutorial exists

Scene transitions are a core control flow in games (menu -> gameplay, restart, game over, back to menu). This tutorial isolates transition behavior without menu systems or gameplay systems.

Source map

  • Settings profile: examples/settings/scene/change_scene.yml

  • Example builder: examples/catalog/scene/change_scene/main.py

  • Scene implementations: examples/catalog/scene/change_scene/scenes/scene.py

  • Core command: packages/mini-arcade-core/src/mini_arcade_core/engine/commands.py

  • Core stack manager: packages/mini-arcade-core/src/mini_arcade_core/engine/scenes/scene_manager.py

Runtime flow (actual)

This example reads numeric key presses and enqueues:

  • ChangeSceneCommand("change_scene_hub")

  • ChangeSceneCommand("change_scene_arena")

  • ChangeSceneCommand("change_scene_lab")

ChangeSceneCommand.execute(...) calls:

context.managers.scenes.change(self.scene_id)

Current SceneAdapter.change(...) behavior:

  1. clean() pops all scenes in stack (on_exit() called).

  2. push(scene_id, as_overlay=False) creates and enters new scene instance.

Because of this, scene-local variables reset on every transition.

What this example proves

Each scene displays:

  • scene_id

  • instance_id (global monotonic id across scene creations)

  • instance_frames

  • instance_elapsed

  • visible stack summary

When you press 1, 2, or 3, instance_id changes and counters reset, demonstrating full scene replacement, not scene reuse.

Run

Default:

mini-arcade run --example scene/change_scene

Force pygame:

mini-arcade run --example scene/change_scene --pass-through --backend pygame

Force native:

mini-arcade run --example scene/change_scene --pass-through --backend native

Controls

  • 1 -> change_scene_hub

  • 2 -> change_scene_arena

  • 3 -> change_scene_lab

  • F1 -> toggle built-in debug overlay

  • ESC -> quit

What to verify

  1. 1/2/3 always transitions to the target scene.

  2. stack summary shows a single base scene after each change.

  3. instance_id increases after each transition.

  4. instance_frames restarts from low values after each transition.

  5. overlay toggle (F1) still works independently.

Common mistakes

  • expecting change to preserve scene-local state: it does not; state resets because scene instance is recreated

  • using change where overlay behavior is needed: use push(..., as_overlay=True) for pause/modal overlays

  • forgetting to include scene discovery packages in config

Next step