mini-arcade-core 0.9.1__tar.gz → 0.9.3__tar.gz

{mini_arcade_core-0.9.1 → mini_arcade_core-0.9.3}/PKG-INFO

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

{mini_arcade_core-0.9.1 → mini_arcade_core-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "0.9.1"
+version = "0.9.3"
 description = "Tiny scene-based game loop core for small arcade games."
 authors = [
     { name = "Santiago Rincon", email = "rincores@gmail.com" },

{mini_arcade_core-0.9.1 → mini_arcade_core-0.9.3}/src/mini_arcade_core/__init__.py

@@ -22,12 +22,17 @@ 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
 
 logger = logging.getLogger(__name__)
 
 
-def run_game(initial_scene_cls: type[Scene], config: GameConfig | None = None):
+def run_game(
+    initial_scene_cls: type[Scene],
+    config: GameConfig | None = None,
+    registry: SceneRegistry | None = None,
+):
     """
     Convenience helper to bootstrap and run a game with a single scene.
 
@@ -44,7 +49,7 @@ def run_game(initial_scene_cls: type[Scene], config: GameConfig | None = None):
         raise ValueError(
             "GameConfig.backend must be set to a Backend instance"
         )
-    game = Game(cfg)
+    game = Game(cfg, registry=registry)
     scene = initial_scene_cls(game)
     game.run(scene)
 
@@ -72,6 +77,7 @@ __all__ = [
     "RectKinematic",
     "Key",
     "keymap",
+    "SceneRegistry",
 ]
 
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml

{mini_arcade_core-0.9.1 → mini_arcade_core-0.9.3}/src/mini_arcade_core/backend.py

@@ -214,6 +214,18 @@ class Backend(Protocol):
         :type color: Color
         """
 
+    def measure_text(self, text: str) -> tuple[int, int]:
+        """
+        Measure the width and height of the given text string in pixels.
+
+        :param text: The text string to measure.
+        :type text: str
+
+        :return: A tuple (width, height) in pixels.
+        :rtype: tuple[int, int]
+        """
+        raise NotImplementedError
+
     def capture_frame(self, path: str | None = None) -> bytes | None:
         """
         Capture the current frame.

{mini_arcade_core-0.9.1 → mini_arcade_core-0.9.3}/src/mini_arcade_core/game.py

@@ -9,15 +9,18 @@ from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from time import perf_counter, sleep
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Union
 
 from PIL import Image  # type: ignore[import]
 
 from .backend import Backend
+from .registry import SceneRegistry
 
 if TYPE_CHECKING:  # avoid runtime circular import
     from .scene import Scene
 
+SceneOrId = Union["Scene", str]
+
 
 @dataclass
 class GameConfig:
@@ -49,7 +52,9 @@ class _StackEntry:
 class Game:
     """Core game object responsible for managing the main loop and active scene."""
 
-    def __init__(self, config: GameConfig):
+    def __init__(
+        self, config: GameConfig, registry: SceneRegistry | None = None
+    ):
         """
         :param config: Game configuration options.
         :type config: GameConfig
@@ -65,6 +70,7 @@ class Game:
                 "GameConfig.backend must be set to a Backend instance"
             )
         self.backend: Backend = config.backend
+        self.registry = registry or SceneRegistry(_factories={})
         self._scene_stack: list[_StackEntry] = []
 
     def current_scene(self) -> "Scene | None":
@@ -76,7 +82,7 @@ class Game:
         """
         return self._scene_stack[-1].scene if self._scene_stack else None
 
-    def change_scene(self, scene: Scene):
+    def change_scene(self, scene: SceneOrId):
         """
         Swap the active scene. Concrete implementations should call
         ``on_exit``/``on_enter`` appropriately.
@@ -84,6 +90,8 @@ class Game:
         :param scene: The new scene to activate.
         :type scene: Scene
         """
+        scene = self._resolve_scene(scene)
+
         while self._scene_stack:
             entry = self._scene_stack.pop()
             entry.scene.on_exit()
@@ -91,11 +99,13 @@ class Game:
         self._scene_stack.append(_StackEntry(scene=scene, as_overlay=False))
         scene.on_enter()
 
-    def push_scene(self, scene: "Scene", as_overlay: bool = False):
+    def push_scene(self, scene: SceneOrId, as_overlay: bool = False):
         """
         Push a scene on top of the current one.
         If as_overlay=True, underlying scene(s) may still be drawn but never updated.
         """
+        scene = self._resolve_scene(scene)
+
         top = self.current_scene()
         if top is not None:
             top.on_pause()
@@ -142,7 +152,7 @@ class Game:
         """Request that the main loop stops."""
         self._running = False
 
-    def run(self, initial_scene: Scene):
+    def run(self, initial_scene: SceneOrId):
         """
         Run the main loop starting with the given scene.
 
@@ -241,3 +251,8 @@ class Game:
             self._convert_bmp_to_image(bmp_path, str(out_path))
             return str(out_path)
         return None
+
+    def _resolve_scene(self, scene: SceneOrId) -> "Scene":
+        if isinstance(scene, str):
+            return self.registry.create(scene, self)
+        return scene

mini_arcade_core-0.9.3/src/mini_arcade_core/registry.py

@@ -0,0 +1,62 @@
+"""
+Scene registry for mini arcade core.
+Allows registering and creating scenes by string IDs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Dict, Protocol
+
+if TYPE_CHECKING:
+    from mini_arcade_core.game import Game
+    from mini_arcade_core.scene import Scene
+
+
+class SceneFactory(Protocol):
+    """
+    Protocol for scene factory callables.
+    """
+
+    def __call__(self, game: "Game") -> "Scene": ...
+
+
+@dataclass
+class SceneRegistry:
+    """
+    Registry for scene factories, allowing registration and creation of scenes by string IDs.
+    """
+
+    _factories: Dict[str, SceneFactory]
+
+    def register(self, scene_id: str, factory: SceneFactory) -> None:
+        """
+        Register a scene factory under a given scene ID.
+
+        :param scene_id: The string ID for the scene.
+        :type scene_id: str
+
+        :param factory: A callable that creates a Scene instance.
+        :type factory: SceneFactory
+        """
+        self._factories[scene_id] = factory
+
+    def create(self, scene_id: str, game: "Game") -> "Scene":
+        """
+        Create a scene instance using the registered factory for the given scene ID.
+
+        :param scene_id: The string ID of the scene to create.
+        :type scene_id: str
+
+        :param game: The Game instance to pass to the scene factory.
+        :type game: Game
+
+        :return: A new Scene instance.
+        :rtype: Scene
+
+        :raises KeyError: If no factory is registered for the given scene ID.
+        """
+        try:
+            return self._factories[scene_id](game)
+        except KeyError as e:
+            raise KeyError(f"Unknown scene_id={scene_id!r}") from e

mini_arcade_core-0.9.3/src/mini_arcade_core/ui/menu.py

@@ -0,0 +1,371 @@
+"""
+Menu system for mini arcade core.
+"""
+
+from __future__ import annotations
+
+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
+
+MenuAction = Callable[[], None]
+
+
+@dataclass(frozen=True)
+class MenuItem:
+    """
+    Represents a single item in a menu.
+
+    :ivar label (str): The text label of the menu item.
+    :ivar on_select (MenuAction): The action to perform when the item is selected.
+    """
+
+    label: str
+    on_select: MenuAction
+
+
+# Justification: Data container for styling options needs
+# some attributes.
+# pylint: disable=too-many-instance-attributes
+@dataclass
+class MenuStyle:
+    """
+    Styling options for the Menu.
+
+    :ivar normal (Color): Color for unselected items.
+    :ivar selected (Color): Color for the selected item.
+    :ivar line_height (int): Vertical spacing between items.
+    """
+
+    normal: Color = (220, 220, 220)
+    selected: Color = (255, 255, 0)
+
+    # Layout
+    line_height: int = 28
+    title_color: Color = (255, 255, 255)
+    title_spacing: int = 18
+
+    # Scene background (solid)
+    background_color: Color | None = None  # e.g. BACKGROUND
+
+    # Optional full-screen overlay (dim)
+    overlay_color: Color | None = None  # e.g. (0,0,0,0.5) for pause
+
+    # Panel behind content (optional)
+    panel_color: Color | None = None
+    panel_padding_x: int = 24
+    panel_padding_y: int = 18
+
+    # Button rendering (optional)
+    button_enabled: bool = False
+    button_fill: Color = (30, 30, 30, 1.0)
+    button_border: Color = (120, 120, 120, 1.0)
+    button_selected_border: Color = (255, 255, 0, 1.0)
+    button_width: int | None = (
+        None  # if None -> auto-fit to longest label + padding
+    )
+    button_height: int = 40
+    button_gap: int = 20
+    button_padding_x: int = 20  # used for auto-fit + text centering
+
+    # Hint footer (optional)
+    hint: str | None = None
+    hint_color: Color = (200, 200, 200)
+    hint_margin_bottom: int = 50
+
+
+# pylint: enable=too-many-instance-attributes
+
+
+class Menu:
+    """A simple text-based menu system."""
+
+    def __init__(
+        self,
+        items: Sequence[MenuItem],
+        *,
+        viewport: Size2D | None = None,
+        title: str | None = None,
+        style: MenuStyle | None = None,
+    ):
+        """
+        :param items: Sequence of MenuItem instances to display.
+        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 style: Optional MenuStyle for customizing appearance.
+        :type style: MenuStyle | None
+        """
+        self.items = list(items)
+        self.viewport = viewport
+        self.title = title
+        self.style = style or MenuStyle()
+        self.selected_index = 0
+
+    def move_up(self):
+        """Move the selection up by one item, wrapping around if necessary."""
+        if self.items:
+            self.selected_index = (self.selected_index - 1) % len(self.items)
+
+    def move_down(self):
+        """Move the selection down by one item, wrapping around if necessary."""
+        if self.items:
+            self.selected_index = (self.selected_index + 1) % len(self.items)
+
+    def select(self):
+        """Select the currently highlighted item, invoking its action."""
+        if self.items:
+            self.items[self.selected_index].on_select()
+
+    def handle_event(
+        self,
+        event: Event,
+        *,
+        up_key: int,
+        down_key: int,
+        select_key: int,
+    ):
+        """
+        Handle an input event to navigate the menu.
+
+        :param event: The input event to handle.
+        :type event: Event
+
+        :param up_key: Key code for moving selection up.
+        type up_key: int
+
+        :param down_key: Key code for moving selection down.
+        :type down_key: int
+
+        :param select_key: Key code for selecting the current item.
+        :type select_key: int
+        """
+        if event.type != EventType.KEYDOWN or event.key is None:
+            return
+        if event.key == up_key:
+            self.move_up()
+        elif event.key == down_key:
+            self.move_down()
+        elif event.key == select_key:
+            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).
+        """
+        if not self.items and not self.title:
+            return 0, 0, 0
+
+        max_w = 0
+        title_h = 0
+
+        if self.title:
+            tw, th = surface.measure_text(self.title)
+            max_w = max(max_w, tw)
+            title_h = th
+
+        # Items
+        for it in self.items:
+            w, _ = surface.measure_text(it.label)
+            max_w = max(max_w, w)
+
+        items_h = len(self.items) * self.style.line_height
+
+        # Total content height includes title block if present
+        content_h = items_h
+        if self.title:
+            content_h += title_h + self.style.title_spacing
+
+        return max_w, content_h, title_h
+
+    def draw(self, surface: Backend):
+        """
+        Draw the menu onto the given backend surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+        if self.viewport is None:
+            raise ValueError(
+                "Menu requires viewport=Size2D for centering/layout"
+            )
+
+        vw, vh = self.viewport.width, self.viewport.height
+
+        # 0) Solid background (for main menus)
+        if self.style.background_color is not None:
+            surface.draw_rect(0, 0, vw, vh, color=self.style.background_color)
+
+        # 1) Overlay (for pause, etc.)
+        if self.style.overlay_color is not None:
+            surface.draw_rect(0, 0, vw, vh, color=self.style.overlay_color)
+
+        # 2) Compute menu content bounds (panel area)
+        content_w, content_h, title_h = self._measure_content(surface)
+
+        pad_x, pad_y = self.style.panel_padding_x, self.style.panel_padding_y
+        panel_w = content_w + pad_x * 2
+        panel_h = content_h + pad_y * 2
+
+        x0 = (vw - panel_w) // 2
+        y0 = (vh - panel_h) // 2
+
+        # Optional vertical offset if you add it later:
+        # y0 += self.style.center_offset_y
+
+        # 3) Panel (optional)
+        if self.style.panel_color is not None:
+            surface.draw_rect(
+                x0, y0, panel_w, panel_h, color=self.style.panel_color
+            )
+
+        # 4) Draw title + items
+        cursor_y = y0 + pad_y
+        x_center = x0 + (panel_w // 2)
+
+        if self.title:
+            self._draw_text_center_x(
+                surface,
+                x_center,
+                cursor_y,
+                self.title,
+                color=self.style.title_color,
+            )
+            cursor_y += title_h + self.style.title_spacing
+
+        if self.style.button_enabled:
+            self._draw_buttons(surface, x_center, cursor_y)
+        else:
+            self._draw_text_items(surface, x_center, cursor_y)
+
+        # 5) Hint footer (optional)
+        if self.style.hint:
+            self._draw_text_center_x(
+                surface,
+                vw // 2,
+                vh - self.style.hint_margin_bottom,
+                self.style.hint,
+                color=self.style.hint_color,
+            )
+
+    def _draw_text_items(
+        self, surface: Backend, x_center: int, cursor_y: int
+    ) -> None:
+        for i, item in enumerate(self.items):
+            color = (
+                self.style.selected
+                if i == self.selected_index
+                else self.style.normal
+            )
+            self._draw_text_center_x(
+                surface,
+                x_center,
+                cursor_y + i * self.style.line_height,
+                item.label,
+                color=color,
+            )
+
+    # Justification: Local variables for layout calculations
+    # pylint: disable=too-many-locals
+    def _draw_buttons(
+        self, surface: Backend, x_center: int, cursor_y: int
+    ) -> None:
+        # Determine button width: fixed or auto-fit
+        if self.style.button_width is not None:
+            bw = self.style.button_width
+        else:
+            max_label_w = 0
+            for it in self.items:
+                w, _ = surface.measure_text(it.label)
+                max_label_w = max(max_label_w, w)
+            bw = max_label_w + self.style.button_padding_x * 2
+
+        bh = self.style.button_height
+        gap = self.style.button_gap
+
+        # We treat cursor_y as “top of first button”
+        for i, item in enumerate(self.items):
+            y = cursor_y + i * (bh + gap)
+            x = x_center - bw // 2
+
+            selected = i == self.selected_index
+            border = (
+                self.style.button_selected_border
+                if selected
+                else self.style.button_border
+            )
+
+            # Border rect
+            surface.draw_rect(x - 4, y - 4, bw + 8, bh + 8, color=border)
+            # Fill rect
+            surface.draw_rect(x, y, bw, bh, color=self.style.button_fill)
+
+            # Label color
+            text_color = self.style.selected if selected else self.style.normal
+            tw, th = surface.measure_text(item.label)
+            tx = x + (bw - tw) // 2
+            ty = y + (bh - th) // 2
+            surface.draw_text(tx, ty, item.label, color=text_color)
+
+    # pylint: enable=too-many-locals
+
+    def _measure_content(self, surface: Backend) -> tuple[int, int, int]:
+        # If button mode: content height differs (button_height + gaps)
+        max_w = 0
+        title_h = 0
+
+        if self.title:
+            tw, th = surface.measure_text(self.title)
+            max_w = max(max_w, tw)
+            title_h = th
+
+        if not self.items:
+            content_h = 0
+            if self.title:
+                content_h = title_h
+            return max_w, content_h, title_h
+
+        if self.style.button_enabled:
+            # width: either fixed or auto-fit
+            if self.style.button_width is not None:
+                items_w = self.style.button_width
+            else:
+                max_label_w = 0
+                for it in self.items:
+                    w, _ = surface.measure_text(it.label)
+                    max_label_w = max(max_label_w, w)
+                items_w = max_label_w + self.style.button_padding_x * 2
+
+            max_w = max(max_w, items_w)
+
+            bh = self.style.button_height
+            gap = self.style.button_gap
+            items_h = len(self.items) * bh + (len(self.items) - 1) * gap
+        else:
+            for it in self.items:
+                w, _ = surface.measure_text(it.label)
+                max_w = max(max_w, w)
+            items_h = len(self.items) * self.style.line_height
+
+        content_h = items_h
+        if self.title:
+            content_h += title_h + self.style.title_spacing
+
+        return max_w, content_h, title_h
+
+    @staticmethod
+    def _draw_text_center_x(
+        surface: Backend,
+        x_center: int,
+        y: int,
+        text: str,
+        *,
+        color: Color,
+    ) -> None:
+        w, _ = surface.measure_text(text)
+        surface.draw_text(x_center - (w // 2), y, text, color=color)

mini_arcade_core-0.9.1/src/mini_arcade_core/ui/menu.py

@@ -1,135 +0,0 @@
-"""
-Menu system for mini arcade core.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Callable, Sequence
-
-from mini_arcade_core.backend import Backend, Color, Event, EventType
-
-MenuAction = Callable[[], None]
-
-
-@dataclass(frozen=True)
-class MenuItem:
-    """
-    Represents a single item in a menu.
-
-    :ivar label (str): The text label of the menu item.
-    :ivar on_select (MenuAction): The action to perform when the item is selected.
-    """
-
-    label: str
-    on_select: MenuAction
-
-
-@dataclass
-class MenuStyle:
-    """
-    Styling options for the Menu.
-
-    :ivar normal (Color): Color for unselected items.
-    :ivar selected (Color): Color for the selected item.
-    :ivar line_height (int): Vertical spacing between items.
-    """
-
-    normal: Color = (220, 220, 220)
-    selected: Color = (255, 255, 0)
-    line_height: int = 28
-
-
-class Menu:
-    """A simple text-based menu system."""
-
-    def __init__(
-        self,
-        items: Sequence[MenuItem],
-        *,
-        x: int = 40,
-        y: int = 40,
-        style: MenuStyle | None = None,
-    ):
-        """
-        :param items: Sequence of MenuItem instances to display.
-        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 style: Optional MenuStyle for customizing appearance.
-        :type style: MenuStyle | None
-        """
-        self.items = list(items)
-        self.x = x
-        self.y = y
-        self.style = style or MenuStyle()
-        self.selected_index = 0
-
-    def move_up(self):
-        """Move the selection up by one item, wrapping around if necessary."""
-        if self.items:
-            self.selected_index = (self.selected_index - 1) % len(self.items)
-
-    def move_down(self):
-        """Move the selection down by one item, wrapping around if necessary."""
-        if self.items:
-            self.selected_index = (self.selected_index + 1) % len(self.items)
-
-    def select(self):
-        """Select the currently highlighted item, invoking its action."""
-        if self.items:
-            self.items[self.selected_index].on_select()
-
-    def handle_event(
-        self,
-        event: Event,
-        *,
-        up_key: int,
-        down_key: int,
-        select_key: int,
-    ):
-        """
-        Handle an input event to navigate the menu.
-
-        :param event: The input event to handle.
-        :type event: Event
-
-        :param up_key: Key code for moving selection up.
-        type up_key: int
-
-        :param down_key: Key code for moving selection down.
-        :type down_key: int
-
-        :param select_key: Key code for selecting the current item.
-        :type select_key: int
-        """
-        if event.type != EventType.KEYDOWN or event.key is None:
-            return
-        if event.key == up_key:
-            self.move_up()
-        elif event.key == down_key:
-            self.move_down()
-        elif event.key == select_key:
-            self.select()
-
-    def draw(self, surface: Backend):
-        """
-        Draw the menu onto the given backend surface.
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-        for i, item in enumerate(self.items):
-            color = (
-                self.style.selected
-                if i == self.selected_index
-                else self.style.normal
-            )
-            surface.draw_text(
-                self.x,
-                self.y + i * self.style.line_height,
-                item.label,
-                color=color,
-            )