mini-arcade-core 0.9.5__py3-none-any.whl → 0.9.7__py3-none-any.whl

mini_arcade_core/__init__.py

@@ -7,52 +7,77 @@ from __future__ import annotations
 
 import logging
 from importlib.metadata import PackageNotFoundError, version
-
-from .autoreg import register_scene
-from .backend import Backend, Event, EventType
-from .boundaries2d import (
+from typing import Callable, Type, Union
+
+from mini_arcade_core.backend import Backend, Event, EventType
+from mini_arcade_core.entity import Entity, KinematicEntity, SpriteEntity
+from mini_arcade_core.game import Game, GameConfig
+from mini_arcade_core.keymaps.keys import Key, keymap
+from mini_arcade_core.scenes import Scene, SceneRegistry, register_scene
+from mini_arcade_core.two_d import (
+    Bounds2D,
+    KinematicData,
+    Position2D,
+    RectCollider,
     RectKinematic,
     RectSprite,
+    Size2D,
+    Velocity2D,
     VerticalBounce,
     VerticalWrap,
 )
-from .collision2d import RectCollider
-from .entity import Entity, KinematicEntity, SpriteEntity
-from .game import Game, GameConfig
-from .geometry2d import Bounds2D, Position2D, Size2D
-from .keys import Key, keymap
-from .kinematics2d import KinematicData
-from .physics2d import Velocity2D
-from .registry import SceneRegistry
-from .scene import Scene
+
+SceneFactoryLike = Union[Type[Scene], Callable[[Game], Scene]]
 
 logger = logging.getLogger(__name__)
 
 
 def run_game(
-    initial_scene_cls: type[Scene],
+    scene: SceneFactoryLike | None = None,
     config: GameConfig | None = None,
     registry: SceneRegistry | None = None,
+    initial_scene: str = "main",
 ):
     """
     Convenience helper to bootstrap and run a game with a single scene.
 
-    :param initial_scene_cls: The Scene subclass to instantiate as the initial scene.
-    :type initial_scene_cls: type[Scene]
+    Supports both:
+      - run_game(SceneClass, cfg)            # legacy
+      - run_game(config=cfg, initial_scene="main", registry=...)  # registry-based
+      - run_game(cfg)                       # config-only
+
+    :param initial_scene: The Scene ID to start the game with.
+    :type initial_scene: str
 
     :param config: Optional GameConfig to customize game settings.
     :type config: GameConfig | None
 
+    :param registry: Optional SceneRegistry for scene management.
+    :type registry: SceneRegistry | None
+
     :raises ValueError: If the provided config does not have a valid Backend.
     """
+    # Handle run_game(cfg) where the first arg is actually a GameConfig
+    if isinstance(scene, GameConfig) and config is None:
+        config = scene
+        scene = None
+
     cfg = config or GameConfig()
-    if config.backend is None:
+    if cfg.backend is None:
         raise ValueError(
             "GameConfig.backend must be set to a Backend instance"
         )
+
+    # If user provided a Scene factory/class, ensure it's registered
+    if scene is not None:
+        if registry is None:
+            registry = SceneRegistry(_factories={})
+        registry.register(
+            initial_scene, scene
+        )  # Scene class is callable(game) -> Scene
+
     game = Game(cfg, registry=registry)
-    scene = initial_scene_cls(game)
-    game.run(scene)
+    game.run(initial_scene)
 
 
 __all__ = [

mini_arcade_core/backend/__init__.py

@@ -0,0 +1,18 @@
+"""
+Backend module for rendering and input abstraction.
+Defines the Backend interface and related types.
+This is the only part of the code that talks to SDL/pygame directly.
+"""
+
+from __future__ import annotations
+
+from .backend import Backend
+from .events import Event, EventType
+from .types import Color
+
+__all__ = [
+    "Backend",
+    "Event",
+    "EventType",
+    "Color",
+]

mini_arcade_core/{backend.py → backend/backend.py}

@@ -5,100 +5,10 @@ This is the only part of the code that talks to SDL/pygame directly.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-from enum import Enum, auto
-from typing import Iterable, Optional, Protocol, Tuple, Union
+from typing import Iterable, Protocol
 
-from .keys import Key
-
-Color = Union[Tuple[int, int, int], Tuple[int, int, int, int]]
-
-
-class EventType(Enum):
-    """
-    High-level event types understood by the core.
-
-    :cvar UNKNOWN: Unknown/unhandled event.
-    :cvar QUIT: User requested to quit the game.
-    :cvar KEYDOWN: A key was pressed.
-    :cvar KEYUP: A key was released.
-    :cvar MOUSEMOTION: The mouse was moved.
-    :cvar MOUSEBUTTONDOWN: A mouse button was pressed.
-    :cvar MOUSEBUTTONUP: A mouse button was released.
-    :cvar MOUSEWHEEL: The mouse wheel was scrolled.
-    :cvar WINDOWRESIZED: The window was resized.
-    :cvar TEXTINPUT: Text input event (for IME support).
-    """
-
-    UNKNOWN = auto()
-    QUIT = auto()
-
-    KEYDOWN = auto()
-    KEYUP = auto()
-
-    # Mouse
-    MOUSEMOTION = auto()
-    MOUSEBUTTONDOWN = auto()
-    MOUSEBUTTONUP = auto()
-    MOUSEWHEEL = auto()
-
-    # Window / text
-    WINDOWRESIZED = auto()
-    TEXTINPUT = auto()
-
-
-# Justification: Simple data container for now
-# pylint: disable=too-many-instance-attributes
-@dataclass(frozen=True)
-class Event:
-    """
-    Core event type.
-
-    For now we only care about:
-    - type: what happened
-    - key: integer key code (e.g. ESC = 27), or None if not applicable
-
-    :ivar type (EventType): The type of event.
-    :ivar key (Key | None): The key associated with the event, if any.
-    :ivar key_code (int | None): The key code associated with the event, if any.
-    :ivar scancode (int | None): The hardware scancode of the key, if any.
-    :ivar mod (int | None): Modifier keys bitmask, if any.
-    :ivar repeat (bool | None): Whether this key event is a repeat, if any.
-    :ivar x (int | None): Mouse X position, if any.
-    :ivar y (int | None): Mouse Y position, if any.
-    :ivar dx (int | None): Mouse delta X, if any.
-    :ivar dy (int | None): Mouse delta Y, if any.
-    :ivar button (int | None): Mouse button number, if any.
-    :ivar wheel (Tuple[int, int] | None): Mouse wheel scroll (x, y), if any.
-    :ivar size (Tuple[int, int] | None): New window size (width, height), if any.
-    :ivar text (str | None): Text input, if any.
-    """
-
-    type: EventType
-    key: Key | None = None  # Use Key enum for better clarity
-    key_code: Optional[int] = None
-
-    # Keyboard extras (optional)
-    scancode: Optional[int] = None
-    mod: Optional[int] = None
-    repeat: Optional[bool] = None
-
-    # Mouse (optional)
-    x: Optional[int] = None
-    y: Optional[int] = None
-    dx: Optional[int] = None
-    dy: Optional[int] = None
-    button: Optional[int] = None
-    wheel: Optional[Tuple[int, int]] = None  # (wheel_x, wheel_y)
-
-    # Window (optional)
-    size: Optional[Tuple[int, int]] = None  # (width, height)
-
-    # Text input (optional)
-    text: Optional[str] = None
-
-
-# pylint: enable=too-many-instance-attributes
+from .events import Event
+from .types import Color
 
 
 class Backend(Protocol):

mini_arcade_core/backend/events.py

@@ -0,0 +1,98 @@
+"""
+Core event types and structures.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Optional, Tuple
+
+from mini_arcade_core.keymaps.keys import Key
+
+
+class EventType(Enum):
+    """
+    High-level event types understood by the core.
+
+    :cvar UNKNOWN: Unknown/unhandled event.
+    :cvar QUIT: User requested to quit the game.
+    :cvar KEYDOWN: A key was pressed.
+    :cvar KEYUP: A key was released.
+    :cvar MOUSEMOTION: The mouse was moved.
+    :cvar MOUSEBUTTONDOWN: A mouse button was pressed.
+    :cvar MOUSEBUTTONUP: A mouse button was released.
+    :cvar MOUSEWHEEL: The mouse wheel was scrolled.
+    :cvar WINDOWRESIZED: The window was resized.
+    :cvar TEXTINPUT: Text input event (for IME support).
+    """
+
+    UNKNOWN = auto()
+    QUIT = auto()
+
+    KEYDOWN = auto()
+    KEYUP = auto()
+
+    # Mouse
+    MOUSEMOTION = auto()
+    MOUSEBUTTONDOWN = auto()
+    MOUSEBUTTONUP = auto()
+    MOUSEWHEEL = auto()
+
+    # Window / text
+    WINDOWRESIZED = auto()
+    TEXTINPUT = auto()
+
+
+# Justification: Simple data container for now
+# pylint: disable=too-many-instance-attributes
+@dataclass(frozen=True)
+class Event:
+    """
+    Core event type.
+
+    For now we only care about:
+    - type: what happened
+    - key: integer key code (e.g. ESC = 27), or None if not applicable
+
+    :ivar type (EventType): The type of event.
+    :ivar key (Key | None): The key associated with the event, if any.
+    :ivar key_code (int | None): The key code associated with the event, if any.
+    :ivar scancode (int | None): The hardware scancode of the key, if any.
+    :ivar mod (int | None): Modifier keys bitmask, if any.
+    :ivar repeat (bool | None): Whether this key event is a repeat, if any.
+    :ivar x (int | None): Mouse X position, if any.
+    :ivar y (int | None): Mouse Y position, if any.
+    :ivar dx (int | None): Mouse delta X, if any.
+    :ivar dy (int | None): Mouse delta Y, if any.
+    :ivar button (int | None): Mouse button number, if any.
+    :ivar wheel (Tuple[int, int] | None): Mouse wheel scroll (x, y), if any.
+    :ivar size (Tuple[int, int] | None): New window size (width, height), if any.
+    :ivar text (str | None): Text input, if any.
+    """
+
+    type: EventType
+    key: Key | None = None  # Use Key enum for better clarity
+    key_code: Optional[int] = None
+
+    # Keyboard extras (optional)
+    scancode: Optional[int] = None
+    mod: Optional[int] = None
+    repeat: Optional[bool] = None
+
+    # Mouse (optional)
+    x: Optional[int] = None
+    y: Optional[int] = None
+    dx: Optional[int] = None
+    dy: Optional[int] = None
+    button: Optional[int] = None
+    wheel: Optional[Tuple[int, int]] = None  # (wheel_x, wheel_y)
+
+    # Window (optional)
+    size: Optional[Tuple[int, int]] = None  # (width, height)
+
+    # Text input (optional)
+    text: Optional[str] = None
+
+
+# pylint: enable=too-many-instance-attributes

mini_arcade_core/backend/types.py

@@ -0,0 +1,9 @@
+"""
+Types used in the backend module.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple, Union
+
+Color = Union[Tuple[int, int, int], Tuple[int, int, int, int]]

mini_arcade_core/entity.py

@@ -6,9 +6,12 @@ from __future__ import annotations
 
 from typing import Any
 
-from .collision2d import RectCollider
-from .geometry2d import Position2D, Size2D
-from .kinematics2d import KinematicData
+from mini_arcade_core.two_d import (
+    KinematicData,
+    Position2D,
+    RectCollider,
+    Size2D,
+)
 
 
 class Entity:

mini_arcade_core/game.py

@@ -9,15 +9,15 @@ from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from time import perf_counter, sleep
-from typing import TYPE_CHECKING, Union
+from typing import TYPE_CHECKING, Literal, Union
 
 from PIL import Image  # type: ignore[import]
 
-from .backend import Backend
-from .registry import SceneRegistry
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.scenes import SceneRegistry
 
 if TYPE_CHECKING:  # avoid runtime circular import
-    from .scene import Scene
+    from mini_arcade_core.scenes import Scene
 
 SceneOrId = Union["Scene", str]
 
@@ -43,6 +43,20 @@ class GameConfig:
     backend: Backend | None = None
 
 
+Difficulty = Literal["easy", "normal", "hard", "insane"]
+
+
+@dataclass
+class GameSettings:
+    """
+    Game settings that can be modified during gameplay.
+
+    :ivar difficulty: Current game difficulty level.
+    """
+
+    difficulty: Difficulty = "normal"
+
+
 @dataclass
 class _StackEntry:
     scene: "Scene"
@@ -59,6 +73,9 @@ class Game:
         :param config: Game configuration options.
         :type config: GameConfig
 
+        :param registry: Optional SceneRegistry for scene management.
+        :type registry: SceneRegistry | None
+
         :raises ValueError: If the provided config does not have a valid Backend.
         """
         self.config = config
@@ -72,6 +89,7 @@ class Game:
         self.backend: Backend = config.backend
         self.registry = registry or SceneRegistry(_factories={})
         self._scene_stack: list[_StackEntry] = []
+        self.settings = GameSettings()
 
     def current_scene(self) -> "Scene | None":
         """
@@ -88,7 +106,7 @@ class Game:
         ``on_exit``/``on_enter`` appropriately.
 
         :param scene: The new scene to activate.
-        :type scene: Scene
+        :type scene: SceneOrId
         """
         scene = self._resolve_scene(scene)
 
@@ -103,6 +121,12 @@ class Game:
         """
         Push a scene on top of the current one.
         If as_overlay=True, underlying scene(s) may still be drawn but never updated.
+
+        :param scene: The scene to push onto the stack.
+        :type scene: SceneOrId
+
+        :param as_overlay: Whether to treat the scene as an overlay.
+        :type as_overlay: bool
         """
         scene = self._resolve_scene(scene)
 
@@ -116,7 +140,12 @@ class Game:
         scene.on_enter()
 
     def pop_scene(self) -> "Scene | None":
-        """Pop the top scene. If stack becomes empty, quit."""
+        """
+        Pop the top scene. If stack becomes empty, quit.
+
+        :return: The popped Scene instance, or None if the stack is now empty.
+        :rtype: Scene | None
+        """
         if not self._scene_stack:
             return None
 
@@ -160,7 +189,7 @@ class Game:
         or another backend.
 
         :param initial_scene: The scene to start the game with.
-        :type initial_scene: Scene
+        :type initial_scene: SceneOrId
         """
         backend = self.backend
         backend.init(self.config.width, self.config.height, self.config.title)

mini_arcade_core/keymaps/__init__.py

@@ -0,0 +1,15 @@
+"""
+Keymaps for Mini Arcade Core.
+Includes key definitions and default key mappings.
+"""
+
+from __future__ import annotations
+
+from .keys import Key, keymap
+from .sdl import SDL_KEYCODE_TO_KEY
+
+__all__ = [
+    "Key",
+    "keymap",
+    "SDL_KEYCODE_TO_KEY",
+]

mini_arcade_core/keymaps/sdl.py

@@ -1,36 +1,39 @@
 """
 SDL keymap for mini arcade core.
 Maps SDL keycodes to mini arcade core Key enums.
+
+:cvar SDL_KEYCODE_TO_KEY: dict[int, Key]
+    Mapping from SDL keycodes to Key enums.
 """
 
 from __future__ import annotations
 
-from mini_arcade_core.keys import Key
+from mini_arcade_core.keymaps.keys import Key
 
 # SDL keycodes you need (minimal set)
-SDLK_ESCAPE = 27
-SDLK_RETURN = 13
-SDLK_SPACE = 32
-SDLK_TAB = 9
-SDLK_BACKSPACE = 8
+_SDLK_ESCAPE = 27
+_SDLK_RETURN = 13
+_SDLK_SPACE = 32
+_SDLK_TAB = 9
+_SDLK_BACKSPACE = 8
 
-SDLK_UP = 1073741906
-SDLK_DOWN = 1073741905
-SDLK_LEFT = 1073741904
-SDLK_RIGHT = 1073741903
+_SDLK_UP = 1073741906
+_SDLK_DOWN = 1073741905
+_SDLK_LEFT = 1073741904
+_SDLK_RIGHT = 1073741903
 
-F1 = 1073741882
-F2 = 1073741883
-F3 = 1073741884
-F4 = 1073741885
-F5 = 1073741886
-F6 = 1073741887
-F7 = 1073741888
-F8 = 1073741889
-F9 = 1073741890
-F10 = 1073741891
-F11 = 1073741892
-F12 = 1073741893
+_F1 = 1073741882
+_F2 = 1073741883
+_F3 = 1073741884
+_F4 = 1073741885
+_F5 = 1073741886
+_F6 = 1073741887
+_F7 = 1073741888
+_F8 = 1073741889
+_F9 = 1073741890
+_F10 = 1073741891
+_F11 = 1073741892
+_F12 = 1073741893
 
 SDL_KEYCODE_TO_KEY: dict[int, Key] = {
     # Letters
@@ -61,16 +64,16 @@ SDL_KEYCODE_TO_KEY: dict[int, Key] = {
     ord("y"): Key.Y,
     ord("z"): Key.Z,
     # Arrows
-    SDLK_UP: Key.UP,
-    SDLK_DOWN: Key.DOWN,
-    SDLK_LEFT: Key.LEFT,
-    SDLK_RIGHT: Key.RIGHT,
+    _SDLK_UP: Key.UP,
+    _SDLK_DOWN: Key.DOWN,
+    _SDLK_LEFT: Key.LEFT,
+    _SDLK_RIGHT: Key.RIGHT,
     # Common
-    SDLK_ESCAPE: Key.ESCAPE,
-    SDLK_SPACE: Key.SPACE,
-    SDLK_RETURN: Key.ENTER,
-    SDLK_TAB: Key.TAB,
-    SDLK_BACKSPACE: Key.BACKSPACE,
+    _SDLK_ESCAPE: Key.ESCAPE,
+    _SDLK_SPACE: Key.SPACE,
+    _SDLK_RETURN: Key.ENTER,
+    _SDLK_TAB: Key.TAB,
+    _SDLK_BACKSPACE: Key.BACKSPACE,
     # Numbers
     ord("0"): Key.NUM_0,
     ord("1"): Key.NUM_1,
@@ -83,16 +86,16 @@ SDL_KEYCODE_TO_KEY: dict[int, Key] = {
     ord("8"): Key.NUM_8,
     ord("9"): Key.NUM_9,
     # Function keys
-    F1: Key.F1,
-    F2: Key.F2,
-    F3: Key.F3,
-    F4: Key.F4,
-    F5: Key.F5,
-    F6: Key.F6,
-    F7: Key.F7,
-    F8: Key.F8,
-    F9: Key.F9,
-    F10: Key.F10,
-    F11: Key.F11,
-    F12: Key.F12,
+    _F1: Key.F1,
+    _F2: Key.F2,
+    _F3: Key.F3,
+    _F4: Key.F4,
+    _F5: Key.F5,
+    _F6: Key.F6,
+    _F7: Key.F7,
+    _F8: Key.F8,
+    _F9: Key.F9,
+    _F10: Key.F10,
+    _F11: Key.F11,
+    _F12: Key.F12,
 }

mini_arcade_core/scenes/__init__.py

@@ -0,0 +1,12 @@
+"""
+Scenes module for Mini Arcade Core.
+Provides the base Scene class and related functionality.
+"""
+
+from __future__ import annotations
+
+from .autoreg import register_scene
+from .registry import SceneRegistry
+from .scene import Scene
+
+__all__ = ["Scene", "register_scene", "SceneRegistry"]

mini_arcade_core/{autoreg.py → scenes/autoreg.py}

@@ -8,13 +8,20 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Dict, Type
 
 if TYPE_CHECKING:
-    from .scene import Scene
+    from . import Scene
 
 _AUTO: Dict[str, Type["Scene"]] = {}
 
 
 def register_scene(scene_id: str):
-    """Decorator to mark and register a Scene class under an id."""
+    """
+    Decorator to mark and register a Scene class under an id.
+
+    :param scene_id: The unique identifier for the Scene class.
+    :type scene_id: str
+
+    :raises ValueError: If the scene_id is already registered.
+    """
 
     def deco(cls: Type["Scene"]):
         _AUTO[scene_id] = cls

mini_arcade_core/{registry.py → scenes/registry.py}

@@ -14,7 +14,7 @@ from .autoreg import snapshot
 
 if TYPE_CHECKING:
     from mini_arcade_core.game import Game
-    from mini_arcade_core.scene import Scene
+    from mini_arcade_core.scenes import Scene
 
 
 class SceneFactory(Protocol):

mini_arcade_core/{scene.py → scenes/scene.py}

@@ -5,12 +5,14 @@ Base class for game scenes (states/screens).
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Callable, List
+from typing import TYPE_CHECKING, Callable, List
 
-from .backend import Backend, Event
-from .entity import Entity
-from .game import Game
-from .geometry2d import Size2D
+from mini_arcade_core.backend import Backend, Event
+from mini_arcade_core.entity import Entity
+from mini_arcade_core.two_d import Size2D
+
+if TYPE_CHECKING:
+    from mini_arcade_core.game import Game
 
 OverlayFunc = Callable[[Backend], None]
 

mini_arcade_core/two_d/__init__.py

@@ -0,0 +1,30 @@
+"""
+Two-dimensional utilities and components for Mini Arcade Core.
+Includes 2D entities, boundaries, and physics.
+"""
+
+from __future__ import annotations
+
+from .boundaries2d import (
+    RectKinematic,
+    RectSprite,
+    VerticalBounce,
+    VerticalWrap,
+)
+from .collision2d import RectCollider
+from .geometry2d import Bounds2D, Position2D, Size2D
+from .kinematics2d import KinematicData
+from .physics2d import Velocity2D
+
+__all__ = [
+    "Bounds2D",
+    "Position2D",
+    "Size2D",
+    "KinematicData",
+    "Velocity2D",
+    "RectCollider",
+    "RectKinematic",
+    "RectSprite",
+    "VerticalBounce",
+    "VerticalWrap",
+]

mini_arcade_core/{collision2d.py → two_d/collision2d.py}

@@ -46,7 +46,7 @@ class RectCollider:
     """
     OOP collision helper that wraps a Position2D + Size2D pair.
 
-    It does NOT own the data – it just points to them. If the
+    It does NOT own the data - it just points to them. If the
     entity moves (position changes), the collider “sees” it.
 
     :ivar position (Position2D): Top-left position of the rectangle.

mini_arcade_core/{kinematics2d.py → two_d/kinematics2d.py}

@@ -7,7 +7,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Optional
 
-from .backend import Color
+from mini_arcade_core.backend import Color
+
 from .geometry2d import Position2D, Size2D
 from .physics2d import Velocity2D
 

mini_arcade_core/ui/__init__.py

@@ -0,0 +1,14 @@
+"""
+UI utilities and components for Mini Arcade Core.
+Includes buttons, labels, and layout management.
+"""
+
+from __future__ import annotations
+
+from .menu import Menu, MenuItem, MenuStyle
+
+__all__ = [
+    "Menu",
+    "MenuItem",
+    "MenuStyle",
+]

mini_arcade_core/ui/menu.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from typing import Callable, Sequence
 
 from mini_arcade_core.backend import Backend, Color, Event, EventType
-from mini_arcade_core.geometry2d import Size2D
+from mini_arcade_core.two_d import Size2D
 
 MenuAction = Callable[[], None]
 
@@ -37,6 +37,28 @@ class MenuStyle:
     :ivar normal (Color): Color for unselected items.
     :ivar selected (Color): Color for the selected item.
     :ivar line_height (int): Vertical spacing between items.
+    :ivar title_color (Color): Color for the title text.
+    :ivar title_spacing (int): Vertical space between title and first item.
+    :ivar title_margin_bottom (int): Additional margin below the title.
+    :ivar background_color (Color | None): Solid background color for the menu.
+    :ivar overlay_color (Color | None): Full-screen overlay color.
+    :ivar panel_color (Color | None): Color for the panel behind content.
+    :ivar panel_padding_x (int): Horizontal padding inside the panel.
+    :ivar panel_padding_y (int): Vertical padding inside the panel.
+    :ivar button_enabled (bool): Whether to render items as buttons.
+    :ivar button_fill (Color): Fill color for buttons.
+    :ivar button_border (Color): Border color for buttons.
+    :ivar button_selected_border (Color): Border color for the selected button.
+    :ivar button_width (int | None): Fixed width for buttons, or None for auto-fit.
+    :ivar button_height (int): Fixed height for buttons.
+    :ivar button_gap (int): Vertical gap between buttons.
+    :ivar button_padding_x (int): Horizontal padding inside buttons.
+    :ivar hint (str | None): Optional hint text to display at the bottom.
+    :ivar hint_color (Color): Color for the hint text.
+    :ivar hint_margin_bottom (int): Additional margin below the hint text.
+    :ivar title_font_size (int): Font size for the title text.
+    :ivar hint_font_size (int): Font size for the hint text.
+    :ivar item_font_size (int): Font size for the menu items.
     """
 
     normal: Color = (220, 220, 220)
@@ -98,10 +120,13 @@ class Menu:
     ):
         """
         :param items: Sequence of MenuItem instances to display.
-        type items: Sequence[MenuItem]
+        :type items: Sequence[MenuItem]
 
-        :param x: X coordinate for the menu's top-left corner.
-        :param y: Y coordinate for the menu's top-left corner.
+        :param viewport: Viewport size for the menu's layout and centering.
+        :type viewport: Size2D | None
+
+        :param title: Optional title text for the menu.
+        :type title: str | None
 
         :param style: Optional MenuStyle for customizing appearance.
         :type style: MenuStyle | None
@@ -160,10 +185,8 @@ class Menu:
             self.select()
 
     def _measure_content(self, surface: Backend) -> tuple[int, int, int]:
-        """
-        Returns (content_width, content_height, title_height)
-        where content is items-only (no padding).
-        """
+        # Returns (content_width, content_height, title_height)
+        # where content is items-only (no padding)
         if not self.items and not self.title:
             return 0, 0, 0
 

{mini_arcade_core-0.9.5.dist-info → mini_arcade_core-0.9.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 0.9.5
+Version: 0.9.7
 Summary: Tiny scene-based game loop core for small arcade games.
 License: Copyright (c) 2025 Santiago Rincón
            

mini_arcade_core-0.9.7.dist-info/RECORD

@@ -0,0 +1,26 @@
+mini_arcade_core/__init__.py,sha256=Q6N1eJe5W8r3i_G88-WZ90B71P6eFuH-Zk5xw3p7SBs,3650
+mini_arcade_core/backend/__init__.py,sha256=w-6QTUngdIYZuvEU3B8zL-vXyKbyLDVucbt7yKZdLlc,379
+mini_arcade_core/backend/backend.py,sha256=dLXTtLn5qURftWOWOVQd2ouuZmJpbiOl11KMIDRk2us,4026
+mini_arcade_core/backend/events.py,sha256=usn2HTk5-5ZiaU2IjbrNRpEj_4uoaiqfY3qufQLYy0w,2929
+mini_arcade_core/backend/types.py,sha256=SuiwXGNmXCZxfPsww6zj3V_NK7k4jpoCuzMn19afS-g,175
+mini_arcade_core/entity.py,sha256=vDe2v7GajyGaqckBYeD3cjs--pOTFrDNhMIdf7PZsJQ,1759
+mini_arcade_core/game.py,sha256=C8flMXn_DMHWDmr5FVrTey_nUHabwja8wSaialNMcLg,8526
+mini_arcade_core/keymaps/__init__.py,sha256=_5Y5_61XT5TsOhbb6p2EPzvjCNN9hCPoxTgj_TAfBvA,258
+mini_arcade_core/keymaps/keys.py,sha256=LTg20SwLBI3kpPIiTNpq2yBft_QUGj-iNFSNm9M-Fus,3010
+mini_arcade_core/keymaps/sdl.py,sha256=Tb0amkbmYjYkEkYnMZ6i9QWjwXBkEHIm13-gEMUYENM,2060
+mini_arcade_core/scenes/__init__.py,sha256=0zzGFejPZ4CkWHJSkhjRAWA7GbenyZbTGrKOrA5gON4,291
+mini_arcade_core/scenes/autoreg.py,sha256=b4V0jaA65I2hnT2f___rg_pT556OjrtoNjIRdZrXBaI,1009
+mini_arcade_core/scenes/registry.py,sha256=0B3iSvepydwMpELQz8cRaQeAU0pR1Fz9O1YtWshLjQw,3226
+mini_arcade_core/scenes/scene.py,sha256=nAYr-T1RW-7s0a8JrxesJY36iAtpZsA2cqeIZgZWIeU,3962
+mini_arcade_core/two_d/__init__.py,sha256=iWjm39RYDEshxSmiIWyGWa6Qr9O2gnHfOpzrl63FUro,626
+mini_arcade_core/two_d/boundaries2d.py,sha256=H1HkCR1422MkQIEve2DFKvnav4RpvtLx-qTMxzmdDMQ,2610
+mini_arcade_core/two_d/collision2d.py,sha256=jR5bOmqUaedxRzwFoKBgn7k-ozwklB4RP9pUTVk6aUw,1716
+mini_arcade_core/two_d/geometry2d.py,sha256=js791mMpsE_YbEoqtTOsOxNSflvKgSk6VeVKhj9N318,1282
+mini_arcade_core/two_d/kinematics2d.py,sha256=NFMiIzDYqDquyg_EhD7EQBJ_Sz4RncmkEjfls9NwkPs,2102
+mini_arcade_core/two_d/physics2d.py,sha256=qIq86qWVuvcnLIMEPH6xx7XQO4tQhfiMZY6FseuVOR8,1636
+mini_arcade_core/ui/__init__.py,sha256=RmcZXfBFFmL09j_Bo1LHagRjiKYajuySPilIUNjc3KQ,248
+mini_arcade_core/ui/menu.py,sha256=J3hYY46xOHLN65WSet4-cnQU7L5pu48scjLJUW9IkEM,13681
+mini_arcade_core-0.9.7.dist-info/METADATA,sha256=ghW7JHVtzj3xDdaQHOvhHmo0JjtLM5Rqpk0K-05RqOI,8188
+mini_arcade_core-0.9.7.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mini_arcade_core-0.9.7.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-0.9.7.dist-info/RECORD,,

mini_arcade_core-0.9.5.dist-info/RECORD

@@ -1,21 +0,0 @@
-mini_arcade_core/__init__.py,sha256=FC98P5APhgI8NVQcq24uPFMpg0fg4ei_bphZyg6NhLA,2797
-mini_arcade_core/autoreg.py,sha256=hN16LulpKcekP3XV_UniQ6qpRT_RrNj14CAMeCnfa2s,851
-mini_arcade_core/backend.py,sha256=kB666RiMSpFaxVEi0KIOPGjh4cdCPWDs5vz8MdY37G4,6854
-mini_arcade_core/boundaries2d.py,sha256=H1HkCR1422MkQIEve2DFKvnav4RpvtLx-qTMxzmdDMQ,2610
-mini_arcade_core/collision2d.py,sha256=iq800wsoYQNft3SA-W4jeY1wXhbpz2E7IkIorZBI238,1718
-mini_arcade_core/entity.py,sha256=1AuE-_iMJYHxSyG783fsyByKK8Gx4vWWKMCEPjtgHXw,1776
-mini_arcade_core/game.py,sha256=YJD10IePBcZ8qyt1FCIWX9hnm8HhK85QK7J6hDEH1H4,7734
-mini_arcade_core/geometry2d.py,sha256=js791mMpsE_YbEoqtTOsOxNSflvKgSk6VeVKhj9N318,1282
-mini_arcade_core/keymaps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/keymaps/sdl.py,sha256=lRBvgTfdT7enN0qV7S2ZoLsPAWpaiSHzsyVGDlyTzQA,1924
-mini_arcade_core/keys.py,sha256=LTg20SwLBI3kpPIiTNpq2yBft_QUGj-iNFSNm9M-Fus,3010
-mini_arcade_core/kinematics2d.py,sha256=twBx-1jEwdknIJEyYBUg4VZyAvw1d7pGHaGFd36TPbo,2085
-mini_arcade_core/physics2d.py,sha256=qIq86qWVuvcnLIMEPH6xx7XQO4tQhfiMZY6FseuVOR8,1636
-mini_arcade_core/registry.py,sha256=go3wAu406ZhwocBxmfcgI0Tprg2LXnwcT65_MCMMDX4,3225
-mini_arcade_core/scene.py,sha256=e0E81aHt6saYiGfA-1V2II1yWwcZfvqGTRAv8pZnQtY,3865
-mini_arcade_core/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/ui/menu.py,sha256=LiN1T8YCrigPB4Z6OxNlD0ErL5yAV5skpcAY_bgedKw,12144
-mini_arcade_core-0.9.5.dist-info/METADATA,sha256=pne74vBWZlG2YYVJevZequ1T-MnTC_VZal9tRuYaKnM,8188
-mini_arcade_core-0.9.5.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-mini_arcade_core-0.9.5.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-0.9.5.dist-info/RECORD,,