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

mini_arcade_core/__init__.py

@@ -5,31 +5,21 @@ 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
+# TODO: Consider reducing parameters by using a single config object
+# TODO: Delegate responsibilities to Game class where appropriate
 def run_game(
     scene: SceneFactoryLike | None = None,
     config: GameConfig | None = None,
@@ -40,11 +30,14 @@ def run_game(
     Convenience helper to bootstrap and run a game with a single scene.
 
     Supports both:
-      - run_game(SceneClass, cfg)            # legacy
-      - run_game(config=cfg, initial_scene="main", registry=...)  # registry-based
-      - run_game(cfg)                       # config-only
+        - run_game(SceneClass, cfg)            # legacy
+        - run_game(config=cfg, initial_scene="main", registry=...)  # registry-based
+        - run_game(cfg)                       # config-only
+
+    :param scene: Optional SimScene factory/class to register
+    :type scene: SceneFactoryLike | None
 
-    :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,47 +48,35 @@ 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 +104,11 @@ def get_version() -> str:
         return "0.0.0"
 
 
+__all__ = [
+    "Game",
+    "GameConfig",
+    "WindowConfig",
+    "run_game",
+]
+
 __version__ = get_version()

mini_arcade_core/backend/__init__.py

@@ -6,13 +6,9 @@ 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
+from .backend import Backend, WindowSettings
 
 __all__ = [
     "Backend",
-    "Event",
-    "EventType",
-    "Color",
+    "WindowSettings",
 ]

mini_arcade_core/backend/backend.py

@@ -5,12 +5,29 @@ This is the only part of the code that talks to SDL/pygame directly.
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Iterable, Protocol
 
 from .events import Event
 from .types import Color
 
 
+@dataclass
+class WindowSettings:
+    """
+    Settings for the backend window.
+
+    :ivar width (int): Width of the window in pixels.
+    :ivar height (int): Height of the window in pixels.
+    """
+
+    width: int
+    height: int
+
+
+# TODO: Refactor backend interface into smaller protocols?
+# Justification: Many public methods needed for backend interface
+# pylint: disable=too-many-public-methods
 class Backend(Protocol):
     """
     Interface that any rendering/input backend must implement.
@@ -18,20 +35,23 @@ class Backend(Protocol):
     mini-arcade-core only talks to this protocol, never to SDL/pygame directly.
     """
 
-    def init(self, width: int, height: int, title: str):
+    def init(self, window_settings: WindowSettings):
         """
         Initialize the backend and open a window.
         Should be called once before the main loop.
 
-        :param width: Width of the window in pixels.
-        :type width: int
+        :param window_settings: Settings for the backend window.
+        :type window_settings: WindowSettings
+        """
 
-        :param height: Height of the window in pixels.
-        :type height: int
+    def set_window_title(self, title: str):
+        """
+        Set the window title.
 
-        :param title: Title of the window.
+        :param title: The new title for the window.
         :type title: str
         """
+        raise NotImplementedError
 
     def poll_events(self) -> Iterable[Event]:
         """
@@ -96,14 +116,13 @@ class Backend(Protocol):
         :type color: Color
         """
 
-    # pylint: enable=too-many-arguments,too-many-positional-arguments
-
     def draw_text(
         self,
         x: int,
         y: int,
         text: str,
         color: Color = (255, 255, 255),
+        font_size: int | None = None,
     ):
         """
         Draw text at the given position in a default font and color.
@@ -124,6 +143,8 @@ class Backend(Protocol):
         :type color: Color
         """
 
+    # pylint: enable=too-many-arguments,too-many-positional-arguments
+
     def measure_text(self, text: str) -> tuple[int, int]:
         """
         Measure the width and height of the given text string in pixels.
@@ -149,3 +170,122 @@ class Backend(Protocol):
         :rtype: bytes | None
         """
         raise NotImplementedError
+
+    def init_audio(
+        self, frequency: int = 44100, channels: int = 2, chunk_size: int = 2048
+    ):
+        """
+        Initialize SDL_mixer audio.
+
+        :param frequency: Audio frequency in Hz.
+        :type frequency: int
+
+        :param channels: Number of audio channels (1=mono, 2=stereo).
+        :type channels: int
+
+        :param chunk_size: Size of audio chunks.
+        :type chunk_size: int
+        """
+
+    def shutdown_audio(self):
+        """Shutdown SDL_mixer audio and free loaded sounds."""
+
+    def load_sound(self, sound_id: str, path: str):
+        """
+        Load a WAV sound and store it by ID.
+        Example: backend.load_sound("hit", "assets/sfx/hit.wav")
+
+        :param sound_id: Unique identifier for the sound.
+        :type sound_id: str
+
+        :param path: File path to the WAV sound.
+        :type path: str
+        """
+
+    def play_sound(self, sound_id: str, loops: int = 0):
+        """
+        Play a loaded sound.
+        loops=0 => play once
+        loops=-1 => infinite loop
+        loops=1 => play twice (SDL convention)
+
+        :param sound_id: Unique identifier for the sound.
+        :type sound_id: str
+
+        :param loops: Number of times to loop the sound.
+        :type loops: int
+        """
+
+    def set_master_volume(self, volume: int):
+        """
+        Master volume: 0..128
+        """
+
+    def set_sound_volume(self, sound_id: str, volume: int):
+        """
+        Per-sound volume: 0..128
+
+        :param sound_id: Unique identifier for the sound.
+        :type sound_id: str
+
+        :param volume: Volume level (0-128).
+        :type volume: int
+        """
+
+    def stop_all_sounds(self):
+        """Stop all channels."""
+
+    def set_viewport_transform(
+        self, offset_x: int, offset_y: int, scale: float
+    ):
+        """
+        Apply a transform so draw_* receives VIRTUAL coords and backend maps to screen.
+
+        :param offset_x: X offset in pixels.
+        :type offset_x: int
+
+        :param offset_y: Y offset in pixels.
+        :type offset_y: int
+
+        :param scale: Scale factor.
+        :type scale: float
+        """
+        raise NotImplementedError
+
+    def clear_viewport_transform(self):
+        """Reset any viewport transform back to identity."""
+        raise NotImplementedError
+
+    def resize_window(self, width: int, height: int):
+        """
+        Resize the actual OS window (SDL_SetWindowSize in native backend).
+
+        :param width: New width in pixels.
+        :type width: int
+
+        :param height: New height in pixels.
+        :type height: int
+        """
+        raise NotImplementedError
+
+    def set_clip_rect(self, x: int, y: int, w: int, h: int):
+        """
+        Set a clipping rectangle for rendering.
+
+        :param x: X position of the rectangle's top-left corner.
+        :type x: int
+
+        :param y: Y position of the rectangle's top-left corner.
+        :type y: int
+
+        :param w: Width of the rectangle.
+        :type w: int
+
+        :param h: Height of the rectangle.
+        :type h: int
+        """
+        raise NotImplementedError
+
+    def clear_clip_rect(self):
+        """Clear any clipping rectangle."""
+        raise NotImplementedError

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)