Menu Scenes Internals

Purpose

Explain how BaseMenuScene works internally, what extension points it exposes, and how to apply it for main menus and pause overlays.

Core implementation

Main file:

• packages/mini-arcade-core/src/mini_arcade_core/ui/menu.py

Key types:

• MenuItem: menu entry id, static label, command_factory, optional label_fn

• MenuStyle: style/layout options (background, panel, button style, hint, text colors)

• Menu: render + selection state + layout calculations

• BaseMenuScene: scene base class that wires menu systems

BaseMenuScene contract

Implement in your scene subclass:

• menu_title: title text shown at top (None hides title)

• menu_style(): returns MenuStyle for look and layout

• menu_items(): returns menu entries and command factories

Optional:

• quit_command(): command used when ESC is pressed in menu (default is QuitCommand)

Per-frame system pipeline

BaseMenuScene.on_enter() registers these systems in order:

1. MenuInputSystem

2. MenuNavigationSystem

3. MenuActionSystem

4. MenuRenderSystem

Runtime flow:

1. input keys become MenuIntent

2. selection index updates (with cooldown)

3. selected action enqueues command

4. menu is rendered as UI draw op

Command model in menus

MenuItem.command_factory returns a command instance each selection.

Typical commands:

• ChangeSceneCommand(...) for scene transitions

• RemoveSceneCommand(...) for dismissing pause overlays

• QuitCommand() for full exit

• custom commands mutating gameplay settings (difficulty, toggles, etc.)

Dynamic labels

label_fn(ctx) is evaluated each tick to resolve display label. This supports menu text driven by runtime state:

• difficulty level

• audio on/off state

• control profile name

• backend/debug options

Pattern:

1. command mutates runtime state

2. next frame, label_fn reads updated state

3. menu label updates without scene restart

Main menu vs pause overlay

Main menu pattern:

• usually opaque standalone scene

• sets background_color, panel_color, and button styles

• ESC often maps to QuitCommand

Pause overlay pattern:

• pushed with overlay ScenePolicy (as_overlay=True)

• menu style usually uses overlay_color dimming

• quit_command() typically resumes gameplay, not exit

Policy details for pause overlays:

• docs/source/concepts/overlay_policies.md

See real game implementations:

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

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

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

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

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

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

Common mistakes

• forgetting scene discovery package: menu scene never registers

• returning a command class that needs args without wrapping it in a factory

• mutating menu labels manually instead of using label_fn

• assuming pause overlay should use default quit_command (which exits game)

Related tutorial

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