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

mini_arcade_core/__init__.py

@@ -5,31 +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 import backend  # noqa: F401
-from mini_arcade_core import keymaps  # noqa: F401
-from mini_arcade_core import managers  # noqa: F401
-from mini_arcade_core import spaces  # noqa: F401
-from mini_arcade_core import ui  # noqa: F401
-from mini_arcade_core.bus import event_bus
-from mini_arcade_core.commands import (
-    BaseCommand,
-    BaseGameCommand,
-    BaseSceneCommand,
-    QuitGameCommand,
-)
-from mini_arcade_core.entity import Entity, KinematicEntity, SpriteEntity
-from mini_arcade_core.game import Game, GameConfig
-from mini_arcade_core.scenes import Scene, SceneRegistry
+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[Scene], Callable[[Game], Scene]]
-
-logger = logging.getLogger(__name__)
+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,
@@ -44,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.
@@ -55,48 +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",
-    "Entity",
-    "SpriteEntity",
-    "KinematicEntity",
-    "BaseCommand",
-    "BaseGameCommand",
-    "BaseSceneCommand",
-    "QuitGameCommand",
-    "event_bus",
-    "run_game",
-    "backend",
-    "keymaps",
-    "managers",
-    "spaces",
-    "ui",
-]
-
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml
 
 
@@ -123,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/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)