Overlay Policies Internals

Purpose

Explain how ScenePolicy affects rendering, updates, and input routing for overlay scenes such as pause menus, debug overlays, and modal dialogs.

Core files

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

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

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

ScenePolicy fields

  • blocks_update: stop ticking scenes below this entry

  • blocks_input: stop input routing to scenes below this entry

  • is_opaque: hide rendering of scenes below this entry

  • receives_input: whether this scene can be selected as input owner

Pause overlay baseline policy

Typical pause overlay policy:

ScenePolicy(
    blocks_update=True,
    blocks_input=True,
    is_opaque=False,
    receives_input=True,
)

Result:

  • gameplay remains visible

  • gameplay simulation is frozen

  • gameplay input is blocked

  • pause menu receives input

Built-in debug overlay policy

ToggleDebugOverlayCommand uses:

ScenePolicy(
    blocks_update=False,
    blocks_input=False,
    is_opaque=False,
    receives_input=False,
)

Result:

  • gameplay keeps running

  • gameplay keeps receiving input

  • overlay is view-only telemetry

How manager methods apply policy

SceneAdapter.visible_entries():

  • renders from top-most opaque scene upward, otherwise full visible stack

SceneAdapter.update_entries():

  • ticks from bottom to top, cutting off when a scene blocks update

SceneAdapter.input_entry():

  • computes input candidates respecting blockers

  • returns top-most candidate with receives_input=True

Real game usage

  • games/deja-bounce/src/deja_bounce/scenes/commands.py

  • games/asteroids/src/asteroids/scenes/commands.py

  • games/space-invaders/src/space_invaders/scenes/commands.py

All three push pause overlays with blocking policy and resume by removing overlay scene.

Tutorial reference

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