mini-arcade-core 0.10.0__tar.gz → 1.0.1__tar.gz

{mini_arcade_core-0.10.0 → mini_arcade_core-1.0.1}/PKG-INFO

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

{mini_arcade_core-0.10.0 → mini_arcade_core-1.0.1}/pyproject.toml

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

mini_arcade_core-1.0.1/src/mini_arcade_core/__init__.py

@@ -0,0 +1,114 @@
+"""
+Entry point for the mini_arcade_core package.
+Provides access to core classes and a convenience function to run a game.
+"""
+
+from __future__ import annotations
+
+import traceback
+from importlib.metadata import PackageNotFoundError, version
+from typing import Callable, Type, Union
+
+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
+# 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,
+    registry: SceneRegistry | None = None,
+    initial_scene: str = "main",
+):
+    """
+    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
+
+    :param scene: Optional SimScene factory/class to register
+    :type scene: SceneFactoryLike | None
+
+    :param initial_scene: The SimScene ID to start the game with.
+    :type initial_scene: str
+
+    :param config: Optional GameConfig to customize game settings.
+    :type config: GameConfig | None
+
+    :param registry: Optional SceneRegistry for scene management.
+    :type registry: SceneRegistry | None
+
+    :raises ValueError: If the provided config does not have a valid Backend.
+    """
+    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
+
+
+PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml
+
+
+def get_version() -> str:
+    """
+    Return the installed package version.
+
+    This is a thin helper around importlib.metadata.version so games can do:
+
+        from mini_arcade_core import get_version
+        print(get_version())
+
+    :return: The version string of the installed package.
+    :rtype: str
+
+    :raises PackageNotFoundError: If the package is not installed.
+    """
+    try:
+        return version(PACKAGE_NAME)
+    except PackageNotFoundError:  # if running from source / editable
+        logger.warning(
+            f"Package '{PACKAGE_NAME}' not found. Returning default version '0.0.0'."
+        )
+        return "0.0.0"
+
+
+__all__ = [
+    "Game",
+    "GameConfig",
+    "WindowConfig",
+    "run_game",
+]
+
+__version__ = get_version()

{mini_arcade_core-0.10.0 → mini_arcade_core-1.0.1}/src/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-1.0.1/src/mini_arcade_core/backend/backend.py

@@ -0,0 +1,291 @@
+"""
+Backend interface for rendering and input.
+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.
+
+    mini-arcade-core only talks to this protocol, never to SDL/pygame directly.
+    """
+
+    def init(self, window_settings: WindowSettings):
+        """
+        Initialize the backend and open a window.
+        Should be called once before the main loop.
+
+        :param window_settings: Settings for the backend window.
+        :type window_settings: WindowSettings
+        """
+
+    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.
+        Concrete backends will translate their native events into core Event objects.
+
+        :return: An iterable of Event objects.
+        :rtype: Iterable[Event]
+        """
+
+    def set_clear_color(self, r: int, g: int, b: int):
+        """
+        Set the background/clear color used by begin_frame.
+
+        :param r: Red component (0-255).
+        :type r: int
+
+        :param g: Green component (0-255).
+        :type g: int
+
+        :param b: Blue component (0-255).
+        :type b: int
+        """
+
+    def begin_frame(self):
+        """
+        Prepare for drawing a new frame (e.g. clear screen).
+        """
+
+    def end_frame(self):
+        """
+        Present the frame to the user (swap buffers).
+        """
+
+    # Justification: Simple drawing API for now
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def draw_rect(
+        self,
+        x: int,
+        y: int,
+        w: int,
+        h: int,
+        color: Color = (255, 255, 255),
+    ):
+        """
+        Draw a filled rectangle in some default color.
+        We'll keep this minimal for now; later we can extend with colors/sprites.
+
+        :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
+
+        :param color: RGB color tuple.
+        :type color: Color
+        """
+
+    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.
+
+        Backends may ignore advanced styling for now; this is just to render
+        simple labels like menu items, scores, etc.
+
+        :param x: X position of the text's top-left corner.
+        :type x: int
+
+        :param y: Y position of the text's top-left corner.
+        :type y: int
+
+        :param text: The text string to draw.
+        :type text: str
+
+        :param color: RGB color tuple.
+        :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.
+
+        :param text: The text string to measure.
+        :type text: str
+
+        :return: A tuple (width, height) in pixels.
+        :rtype: tuple[int, int]
+        """
+        raise NotImplementedError
+
+    def capture_frame(self, path: str | None = None) -> bytes | None:
+        """
+        Capture the current frame.
+        If `path` is provided, save to that file (e.g. PNG).
+        Returns raw bytes (PNG) or None if unsupported.
+
+        :param path: Optional file path to save the screenshot.
+        :type path: str | None
+
+        :return: Raw image bytes if no path given, else None.
+        :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-0.10.0 → mini_arcade_core-1.0.1}/src/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-0.10.0/src/mini_arcade_core/keymaps/sdl.py → mini_arcade_core-1.0.1/src/mini_arcade_core/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-1.0.1/src/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)