mini-arcade-core 0.9.2__py3-none-any.whl → 0.9.3__py3-none-any.whl

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/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/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.2.dist-info → mini_arcade_core-0.9.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 0.9.2
+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.2.dist-info → mini_arcade_core-0.9.3.dist-info}/RECORD

@@ -1,19 +1,20 @@
-mini_arcade_core/__init__.py,sha256=7Ioji-MpfSQq4Ok3agVzP4mvcTNiThrY-DTDmVYFKo0,2609
+mini_arcade_core/__init__.py,sha256=l1POPqWz4432MvXlftzB9K0jGWmq9jzDTDe-9bPWvs4,2739
 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=2DaFRdu7ogrwukh2MRnTh0Hy2r1XcaGSHEpLBNxfqIU,7273
+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=F6zw7-FthcZeApLSpPe9sjwAm7ed9ji8pfw1CG24ac4,1699
 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=79krwtWkGXKLSxG37PZsIIeFLayx9OTDN6esJepthlE,11343
-mini_arcade_core-0.9.2.dist-info/METADATA,sha256=6NW5an292zZXvaDVoLUKayukctCRzizdbHqM0a9vZ5g,8188
-mini_arcade_core-0.9.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-mini_arcade_core-0.9.2.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-0.9.2.dist-info/RECORD,,
+mini_arcade_core-0.9.3.dist-info/METADATA,sha256=MzprnzdjBtSbBmvJwXi4EsnDbgOZsu253zBmO7TF0hA,8188
+mini_arcade_core-0.9.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mini_arcade_core-0.9.3.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-0.9.3.dist-info/RECORD,,