mini-arcade-core 0.9.2__tar.gz → 0.9.4__tar.gz

{mini_arcade_core-0.9.2 → mini_arcade_core-0.9.4}/PKG-INFO

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

{mini_arcade_core-0.9.2 → mini_arcade_core-0.9.4}/pyproject.toml

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

{mini_arcade_core-0.9.2 → mini_arcade_core-0.9.4}/src/mini_arcade_core/__init__.py

@@ -8,6 +8,7 @@ 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 (
     RectKinematic,
@@ -22,12 +23,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 +50,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 +78,8 @@ __all__ = [
     "RectKinematic",
     "Key",
     "keymap",
+    "SceneRegistry",
+    "register_scene",
 ]
 
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml

mini_arcade_core-0.9.4/src/mini_arcade_core/autoreg.py

@@ -0,0 +1,39 @@
+"""
+Autoregistration utilities for mini arcade core.
+Allows automatic registration of Scene classes via decorators.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, Type
+
+if TYPE_CHECKING:
+    from .scene import Scene
+
+_AUTO: Dict[str, Type["Scene"]] = {}
+
+
+def register_scene(scene_id: str):
+    """Decorator to mark and register a Scene class under an id."""
+
+    def deco(cls: Type["Scene"]):
+        _AUTO[scene_id] = cls
+        setattr(cls, "__scene_id__", scene_id)
+        return cls
+
+    return deco
+
+
+def snapshot() -> Dict[str, Type["Scene"]]:
+    """
+    Copy of current catalog (useful for tests).
+
+    :return: A copy of the current scene catalog.
+    :rtype: Dict[str, Type["Scene"]]
+    """
+    return dict(_AUTO)
+
+
+def clear():
+    """Clear the current catalog (useful for tests)."""
+    _AUTO.clear()

{mini_arcade_core-0.9.2 → mini_arcade_core-0.9.4}/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.4/src/mini_arcade_core/registry.py

@@ -0,0 +1,112 @@
+"""
+Scene registry for mini arcade core.
+Allows registering and creating scenes by string IDs.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Dict, Protocol
+
+from .autoreg import snapshot
+
+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):
+        """
+        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 register_cls(self, scene_id: str, scene_cls: type["Scene"]):
+        """
+        Register a Scene class under a given scene ID.
+
+        :param scene_id: The string ID for the scene.
+        :type scene_id: str
+
+        :param scene_cls: The Scene class to register.
+        :type scene_cls: type["Scene"]
+        """
+
+        def return_factory(game: "Game") -> "Scene":
+            return scene_cls(game)
+
+        self.register(scene_id, return_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
+
+    def load_catalog(self, catalog: Dict[str, type["Scene"]]):
+        """
+        Load a catalog of Scene classes into the registry.
+
+        :param catalog: A dictionary mapping scene IDs to Scene classes.
+        :type catalog: Dict[str, type["Scene"]]
+        """
+        for scene_id, cls in catalog.items():
+            self.register_cls(scene_id, cls)
+
+    def discover(self, package: str) -> "SceneRegistry":
+        """
+        Import all modules in a package so @scene decorators run.
+
+        :param package: The package name to scan for scene modules.
+        :type package: str
+
+        :return: The SceneRegistry instance (for chaining).
+        :rtype: SceneRegistry
+        """
+        pkg = importlib.import_module(package)
+        if not hasattr(pkg, "__path__"):
+            return self  # not a package
+
+        for mod in pkgutil.walk_packages(pkg.__path__, pkg.__name__ + "."):
+            importlib.import_module(mod.name)
+
+        self.load_catalog(snapshot())
+        return self

{mini_arcade_core-0.9.2 → mini_arcade_core-0.9.4}/src/mini_arcade_core/ui/menu.py

@@ -253,9 +253,7 @@ class Menu:
                 color=self.style.hint_color,
             )
 
-    def _draw_text_items(
-        self, surface: Backend, x_center: int, cursor_y: int
-    ) -> None:
+    def _draw_text_items(self, surface: Backend, x_center: int, cursor_y: int):
         for i, item in enumerate(self.items):
             color = (
                 self.style.selected
@@ -272,9 +270,7 @@ class Menu:
 
     # Justification: Local variables for layout calculations
     # pylint: disable=too-many-locals
-    def _draw_buttons(
-        self, surface: Backend, x_center: int, cursor_y: int
-    ) -> None:
+    def _draw_buttons(self, surface: Backend, x_center: int, cursor_y: int):
         # Determine button width: fixed or auto-fit
         if self.style.button_width is not None:
             bw = self.style.button_width
@@ -366,6 +362,6 @@ class Menu:
         text: str,
         *,
         color: Color,
-    ) -> None:
+    ):
         w, _ = surface.measure_text(text)
         surface.draw_text(x_center - (w // 2), y, text, color=color)