mini-arcade-core 0.9.9__py3-none-any.whl → 1.0.0__py3-none-any.whl

mini_arcade_core/__init__.py

@@ -5,39 +5,19 @@ Provides access to core classes and a convenience function to run a game.
 
 from __future__ import annotations
 
-import logging
+import traceback
 from importlib.metadata import PackageNotFoundError, version
 from typing import Callable, Type, Union
 
-from mini_arcade_core.backend import Backend, Event, EventType
-from mini_arcade_core.cheats import CheatCode, CheatManager
-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,
-    SceneServices,
-    register_scene,
-)
-from mini_arcade_core.two_d import (
-    Bounds2D,
-    KinematicData,
-    Position2D,
-    RectCollider,
-    RectKinematic,
-    RectSprite,
-    Size2D,
-    Velocity2D,
-    VerticalBounce,
-    VerticalWrap,
-)
-
-SceneFactoryLike = Union[Type[Scene], Callable[[Game], Scene]]
-
-logger = logging.getLogger(__name__)
+from mini_arcade_core.engine.game import Game, GameConfig, WindowConfig
+from mini_arcade_core.scenes.registry import SceneRegistry
+from mini_arcade_core.scenes.sim_scene import SimScene
+from mini_arcade_core.utils import logger
 
+SceneFactoryLike = Union[Type[SimScene], Callable[[Game], SimScene]]
 
+
+# TODO: Improve exception handling and logging in run_game
 def run_game(
     scene: SceneFactoryLike | None = None,
     config: GameConfig | None = None,
@@ -52,7 +32,7 @@ def run_game(
       - 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.
+    :param initial_scene: The SimScene ID to start the game with.
     :type initial_scene: str
 
     :param config: Optional GameConfig to customize game settings.
@@ -63,59 +43,36 @@ def run_game(
 
     :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 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)
-    game.run(initial_scene)
+    try:
+        # 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 cfg.backend is None:
+            raise ValueError(
+                "GameConfig.backend must be set to a Backend instance"
+            )
+
+        # If user provided a SimScene factory/class, ensure it's registered
+        if scene is not None:
+            if registry is None:
+                registry = SceneRegistry(_factories={})
+            registry.register(
+                initial_scene, scene
+            )  # SimScene class is callable(game) -> SimScene
+
+        game = Game(cfg, registry=registry)
+        game.run(initial_scene)
+    # Justification: We need to catch all exceptions while we improve error handling.
+    # pylint: disable=broad-exception-caught
+    except Exception as e:
+        logger.exception(f"Unhandled exception in game loop: {e}")
+        logger.debug(traceback.format_exc())
+    # pylint: enable=broad-exception-caught
 
 
-__all__ = [
-    "Game",
-    "GameConfig",
-    "Scene",
-    "Entity",
-    "SpriteEntity",
-    "run_game",
-    "Backend",
-    "Event",
-    "EventType",
-    "Velocity2D",
-    "Position2D",
-    "Size2D",
-    "KinematicEntity",
-    "KinematicData",
-    "RectCollider",
-    "VerticalBounce",
-    "Bounds2D",
-    "VerticalWrap",
-    "RectSprite",
-    "RectKinematic",
-    "Key",
-    "keymap",
-    "SceneRegistry",
-    "register_scene",
-    "CheatManager",
-    "CheatCode",
-    "SceneServices",
-]
-
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml
 
 
@@ -142,4 +99,11 @@ def get_version() -> str:
         return "0.0.0"
 
 
+__all__ = [
+    "Game",
+    "GameConfig",
+    "WindowConfig",
+    "run_game",
+]
+
 __version__ = get_version()

mini_arcade_core/backend/__init__.py

@@ -7,12 +7,7 @@ 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/backend.py

@@ -33,6 +33,15 @@ class Backend(Protocol):
         :type title: str
         """
 
+    def set_window_title(self, title: str):
+        """
+        Set the window title.
+
+        :param title: The new title for the window.
+        :type title: str
+        """
+        raise NotImplementedError
+
     def poll_events(self) -> Iterable[Event]:
         """
         Return all pending events since last call.

mini_arcade_core/backend/events.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from enum import Enum, auto
 from typing import Optional, Tuple
 
-from mini_arcade_core.keymaps.keys import Key
+from mini_arcade_core.backend.keys import Key
 
 
 class EventType(Enum):

mini_arcade_core/{keymaps/sdl.py → backend/sdl_map.py}

@@ -8,7 +8,7 @@ Maps SDL keycodes to mini arcade core Key enums.
 
 from __future__ import annotations
 
-from mini_arcade_core.keymaps.keys import Key
+from mini_arcade_core.backend.keys import Key
 
 # SDL keycodes you need (minimal set)
 _SDLK_ESCAPE = 27

mini_arcade_core/bus.py

@@ -0,0 +1,57 @@
+"""
+Event bus module.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, ClassVar, Dict, List, Optional
+
+
+class EventBus:
+    """
+    Simple event bus for managing event subscriptions and emissions.
+    """
+
+    _instance: ClassVar[Optional["EventBus"]] = None
+    _subscribers: Dict[str, List[Callable]]
+
+    def __new__(cls):
+        if cls._instance is None:
+            inst = super().__new__(cls)
+            inst._subscribers = {}
+            cls._instance = inst
+        return cls._instance
+
+    def on(self, event_type: str, handler: Callable):
+        """
+        Subscribe a handler to an event type.
+
+        :param event_type: The type of event to subscribe to.
+        :type event_type: str
+
+        :param handler: The handler function to call when the event is emitted.
+        :type handler: Callable
+        """
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+        self._subscribers[event_type].append(handler)
+
+    def emit(self, event_type: str, **kwargs):
+        """
+        Emit an event of a given type, calling all subscribed handlers.
+
+        :param event_type: The type of event to emit.
+        :type event_type: str
+
+        :param kwargs: Additional keyword arguments to pass to handlers.
+        """
+        handlers = self._subscribers.get(event_type, [])
+        for handler in handlers:
+            handler(**kwargs)
+
+    def clear(self):
+        """Clear all subscribers from the event bus."""
+        self._subscribers.clear()
+
+
+event_bus = EventBus()

mini_arcade_core/engine/commands.py

@@ -0,0 +1,169 @@
+"""
+Command protocol for executing commands with a given context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, List, Optional, Protocol, TypeVar
+
+if TYPE_CHECKING:
+    from mini_arcade_core.runtime.services import RuntimeServices
+
+# Justification: Generic type for context
+# pylint: disable=invalid-name
+TContext = TypeVar("TContext")
+# pylint: enable=invalid-name
+
+
+@dataclass
+class CommandContext:
+    """
+    Context for command execution.
+
+    :ivar services (RuntimeServices): The runtime services.
+    :ivar commands (CommandQueue | None): Optional command queue.
+    :ivar settings (object | None): Optional settings object.
+    :ivar world (object | None): The world object (can be any type).
+    """
+
+    services: RuntimeServices
+    commands: Optional["CommandQueue"] = None
+    settings: Optional[object] = None
+    world: Optional[object] = None
+
+
+class Command(Protocol):
+    """
+    A command is the only allowed "write path" from input/systems into:
+    - scene operations (push/pop/change/quit)
+    - capture
+    - global game lifecycle
+    - later: world mutations (if you pass a world reference)
+
+    For now we keep it simple: commands only need RuntimeServices.
+    """
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        """
+        Execute the command with the given world and runtime services.
+
+        :param services: Runtime services for command execution.
+        :type services: RuntimeServices
+
+        :param commands: Optional command queue for command execution.
+        :type commands: object | None
+
+        :param settings: Optional settings object for command execution.
+        :type settings: object | None
+
+        :param world: The world object (can be any type).
+        :type world: object | None
+        """
+
+
+@dataclass
+class CommandQueue:
+    """
+    Queue for storing and executing commands.
+    """
+
+    _items: List[Command] = field(default_factory=list)
+
+    def push(self, cmd: Command):
+        """
+        Push a command onto the queue.
+
+        :param cmd: Command to be added to the queue.
+        :type cmd: Command
+        """
+        self._items.append(cmd)
+
+    def drain(self) -> List[Command]:
+        """
+        Drain and return all commands from the queue.
+
+        :return: List of commands that were in the queue.
+        :rtype: list[Command]
+        """
+        items = self._items
+        self._items = []
+        return items
+
+
+@dataclass(frozen=True)
+class QuitCommand(Command):
+    """Quit the game."""
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.quit()
+
+
+@dataclass(frozen=True)
+class ScreenshotCommand(Command):
+    """
+    Take a screenshot.
+
+    :ivar label (str | None): Optional label for the screenshot file.
+    """
+
+    label: str | None = None
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.capture.screenshot(label=self.label, mode="manual")
+
+
+@dataclass(frozen=True)
+class PushSceneCommand(Command):
+    """
+    Push a new scene onto the scene stack.
+
+    :ivar scene_id (str): Identifier of the scene to push.
+    :ivar as_overlay (bool): Whether to push the scene as an overlay.
+    """
+
+    scene_id: str
+    as_overlay: bool = False
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.push(self.scene_id, as_overlay=self.as_overlay)
+
+
+@dataclass(frozen=True)
+class PopSceneCommand(Command):
+    """Pop the current scene from the scene stack."""
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.pop()
+
+
+@dataclass(frozen=True)
+class ChangeSceneCommand(Command):
+    """
+    Change the current scene to the specified scene.
+
+    :ivar scene_id (str): Identifier of the scene to switch to.
+    """
+
+    scene_id: str
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.change(self.scene_id)