Scene Transitions Internals

Purpose

Explain command-level transition semantics for:

  • ChangeSceneCommand

  • PushSceneCommand

  • PopSceneCommand

  • RemoveSceneCommand

Core files

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

  • packages/mini-arcade-core/src/mini_arcade_core/engine/scenes/scene_manager.py

  • packages/mini-arcade-core/src/mini_arcade_core/engine/scenes/models.py

change: replace current stack

ChangeSceneCommand(scene_id) calls scenes.change(scene_id).

Current SceneAdapter.change(...) implementation:

  1. clean(): pop all scenes and call on_exit()

  2. push(scene_id, as_overlay=False): create new scene instance and call on_enter()

Implication:

  • previous stack is discarded

  • new scene starts with fresh local state

Use for:

  • menu -> gameplay

  • restart gameplay from scratch

  • back to main menu

push: add scene without discarding stack

PushSceneCommand(scene_id, as_overlay=...) appends a new scene entry.

Use with as_overlay=True and explicit ScenePolicy for:

  • pause overlays

  • modal dialogs

  • debug or tool overlays

Pause-overlay policy details:

  • docs/source/concepts/overlay_policies.md

  • docs/source/tutorials/scene/pause_overlay_policy.md

pop / remove: unwind overlays or specific scenes

  • PopSceneCommand() removes top scene

  • RemoveSceneCommand(scene_id) removes first matching scene from top

Use for:

  • close pause overlay

  • dismiss temporary modal scene

Choosing the right transition command

  • need full state reset -> change

  • need temporary layer over current state -> push + policy

  • need to go back from temporary layer -> pop or remove

ScenePolicy interaction

When pushing overlays, ScenePolicy controls whether underlying scenes:

  • update (blocks_update)

  • receive input (blocks_input)

  • remain visible (is_opaque)

For change, policy on old scenes is irrelevant because stack is cleaned first.

Tutorial reference

  • docs/source/tutorials/scene/change_scene.md