commands/scene_stack_commands

Goal

Understand the built-in scene-stack commands — Push, Pop, and Change — and see them navigate between three scenes.

Why this tutorial exists

Scene navigation is driven entirely by commands. The engine provides:

  • PushSceneCommand — pushes a new scene onto the stack (previous scene stays underneath)

  • PopSceneCommand — pops the top scene, returning to the one below

  • ChangeSceneCommand — replaces the current scene entirely

This example wires three scenes and lets you trigger each command type with keyboard shortcuts.

Source map

  • Settings profile: examples/settings/commands/scene_stack_commands.yml

  • Example builder: examples/catalog/commands/scene_stack_commands/main.py

  • Scene: examples/catalog/commands/scene_stack_commands/scenes/scene.py

  • Shared runner: examples/_shared/runner.py

What to verify

You should see:

  1. Main scene (blue) — press O to push an overlay, C to change to an alternate scene

  2. Overlay scene (green, semi-transparent) — press Backspace to pop back to the main scene

  3. Alternate scene (red) — press Backspace to change back to main

Behavior checks:

  • pushing the overlay does not destroy the main scene underneath

  • popping returns to the exact state the main scene was in

  • changing to the alternate scene removes the main scene from the stack

  • the stack depth indicator updates correctly

Controls

Key

Action

O

Push overlay

C

Change to alternate

Backspace

Pop / go back

ESC

Quit

Run

mini-arcade run --example commands/scene_stack_commands
mini-arcade run --example commands/scene_stack_commands --pass-through --backend pygame
mini-arcade run --example commands/scene_stack_commands --pass-through --backend native

Common mistakes

  • Popping when only one scene is on the stack — causes the engine to quit or error.

  • Using Change when you mean Push — the previous scene is lost.

  • Registering scenes in a separate package that isn’t in discover_packages.

Next step