mini-arcade-core 0.6.1__tar.gz → 0.7.4__tar.gz

{mini_arcade_core-0.6.1 → mini_arcade_core-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 0.6.1
+Version: 0.7.4
 Summary: Tiny scene-based game loop core for small arcade games.
 License: Copyright (c) 2025 Santiago Rincón
            
@@ -34,6 +34,7 @@ Provides-Extra: dev
 Requires-Dist: black (>=24.10,<25.0) ; extra == "dev"
 Requires-Dist: isort (>=5.13,<6.0) ; extra == "dev"
 Requires-Dist: mypy (>=1.5,<2.0) ; extra == "dev"
+Requires-Dist: pillow (<12)
 Requires-Dist: pylint (>=3.3,<4.0) ; extra == "dev"
 Requires-Dist: pytest (>=8.3,<9.0) ; extra == "dev"
 Requires-Dist: pytest-cov (>=6.0,<7.0) ; extra == "dev"

{mini_arcade_core-0.6.1 → mini_arcade_core-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "0.6.1"
+version = "0.7.4"
 description = "Tiny scene-based game loop core for small arcade games."
 authors = [
     { name = "Santiago Rincon", email = "rincores@gmail.com" },
@@ -12,7 +12,7 @@ authors = [
 readme = "README.md"
 license = { file = "LICENSE" }
 requires-python = ">=3.9,<3.12"
-dependencies = []
+dependencies = ["pillow (<12)"]
 
 [project.optional-dependencies]
 dev = [

{mini_arcade_core-0.6.1 → mini_arcade_core-0.7.4}/src/mini_arcade_core/__init__.py

@@ -21,7 +21,10 @@ def run_game(initial_scene_cls: type[Scene], config: GameConfig | None = None):
     Convenience helper to bootstrap and run a game with a single scene.
 
     :param initial_scene_cls: The Scene subclass to instantiate as the initial scene.
+    :type initial_scene_cls: type[Scene]
+
     :param config: Optional GameConfig to customize game settings.
+    :type config: GameConfig | None
     """
     game = Game(config or GameConfig())
     scene = initial_scene_cls(game)

mini_arcade_core-0.7.4/src/mini_arcade_core/backend.py

@@ -0,0 +1,171 @@
+"""
+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 enum import Enum, auto
+from typing import Iterable, Protocol
+
+
+class EventType(Enum):
+    """
+    High-level event types understood by the core.
+
+    :cvar UNKNOWN: Unknown/unhandled event.
+    :cvar QUIT: User requested to quit the game.
+    :cvar KEYDOWN: A key was pressed.
+    :cvar KEYUP: A key was released.
+    """
+
+    UNKNOWN = auto()
+    QUIT = auto()
+    KEYDOWN = auto()
+    KEYUP = auto()
+
+
+@dataclass(frozen=True)
+class Event:
+    """
+    Core event type.
+
+    For now we only care about:
+    - type: what happened
+    - key: integer key code (e.g. ESC = 27), or None if not applicable
+
+    :ivar type (EventType): The type of event.
+    :ivar key (int | None): The key code associated with the event, if any.
+    """
+
+    type: EventType
+    key: int | None = None
+
+
+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, width: int, height: int, title: str) -> None:
+        """
+        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 height: Height of the window in pixels.
+        :type height: int
+
+        :param title: Title of the window.
+        :type title: str
+        """
+
+    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) -> None:
+        """
+        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) -> None:
+        """
+        Prepare for drawing a new frame (e.g. clear screen).
+        """
+
+    def end_frame(self) -> None:
+        """
+        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: tuple[int, int, int] = (255, 255, 255),
+    ) -> None:
+        """
+        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: tuple[int, int, int]
+        """
+
+    # pylint: enable=too-many-arguments,too-many-positional-arguments
+
+    def draw_text(
+        self,
+        x: int,
+        y: int,
+        text: str,
+        color: tuple[int, int, int] = (255, 255, 255),
+    ) -> 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: tuple[int, int, int]
+        """
+
+    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

{mini_arcade_core-0.6.1 → mini_arcade_core-0.7.4}/src/mini_arcade_core/game.py

@@ -4,10 +4,15 @@ Game core module defining the Game class and configuration.
 
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
 from time import perf_counter, sleep
 from typing import TYPE_CHECKING
 
+from PIL import Image  # type: ignore[import]
+
 from .backend import Backend
 
 if TYPE_CHECKING:  # avoid runtime circular import
@@ -32,7 +37,7 @@ class GameConfig:
     title: str = "Mini Arcade Game"
     fps: int = 60
     background_color: tuple[int, int, int] = (0, 0, 0)
-    backend: type[Backend] | None = None
+    backend: Backend | None = None
 
 
 class Game:
@@ -84,6 +89,9 @@ class Game:
         backend = self.backend
         backend.init(self.config.width, self.config.height, self.config.title)
 
+        br, bg, bb = self.config.background_color
+        backend.set_clear_color(br, bg, bb)
+
         self.change_scene(initial_scene)
 
         self._running = True
@@ -113,3 +121,51 @@ class Game:
 
         if self._current_scene is not None:
             self._current_scene.on_exit()
+
+    @staticmethod
+    def _convert_bmp_to_image(bmp_path: str, out_path: str) -> bool:
+        """
+        Convert a BMP file to another image format using Pillow.
+
+        :param bmp_path: Path to the input BMP file.
+        :type bmp_path: str
+
+        :param out_path: Path to the output image file.
+        :type out_path: str
+
+        :return: True if conversion was successful, False otherwise.
+        :rtype: bool
+        """
+        try:
+            img = Image.open(bmp_path)
+            img.save(out_path)  # Pillow chooses format from extension
+            return True
+        except Exception:
+            return False
+
+    def screenshot(
+        self, label: str | None = None, directory: str = "screenshots"
+    ) -> str | None:
+        """
+        Ask backend to save a screenshot. Returns the file path or None.
+
+        :param label: Optional label to include in the filename.
+        :type label: str | None
+
+        :param directory: Directory to save screenshots in.
+        :type directory: str
+
+        :return: The file path of the saved screenshot, or None on failure.
+        :rtype: str | None
+        """
+        os.makedirs(directory, exist_ok=True)
+        stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        label = label or "shot"
+        filename = f"{stamp}_{label}"
+        bmp_path = os.path.join(directory, f"{filename}.bmp")
+
+        if self.backend.capture_frame(bmp_path):
+            out_path = Path(directory) / f"{filename}.png"
+            self._convert_bmp_to_image(bmp_path, str(out_path))
+            return str(out_path)
+        return None

mini_arcade_core-0.7.4/src/mini_arcade_core/scene.py

@@ -0,0 +1,95 @@
+"""
+Base class for game scenes (states/screens).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Callable, List
+
+from mini_arcade_core.backend import Backend
+
+from .game import Game
+
+OverlayFunc = Callable[[Backend], None]
+
+
+class Scene(ABC):
+    """Base class for game scenes (states/screens)."""
+
+    def __init__(self, game: Game):
+        """
+        :param game: Reference to the main Game object.
+        :type game: Game
+        """
+        self.game = game
+        # overlays drawn on top of the scene
+        self._overlays: List[OverlayFunc] = []
+
+    def add_overlay(self, overlay: OverlayFunc) -> None:
+        """
+        Register an overlay (drawn every frame, after entities).
+
+        :param overlay: A callable that takes a Backend and draws on it.
+        :type overlay: OverlayFunc
+        """
+        self._overlays.append(overlay)
+
+    def remove_overlay(self, overlay: OverlayFunc) -> None:
+        """
+        Unregister a previously added overlay.
+
+        :param overlay: The overlay to remove.
+        :type overlay: OverlayFunc
+        """
+        if overlay in self._overlays:
+            self._overlays.remove(overlay)
+
+    def clear_overlays(self) -> None:
+        """Clear all registered overlays."""
+        self._overlays.clear()
+
+    def draw_overlays(self, surface: Backend) -> None:
+        """
+        Call all overlays. Scenes should call this at the end of draw().
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+        for overlay in self._overlays:
+            overlay(surface)
+
+    @abstractmethod
+    def on_enter(self):
+        """Called when the scene becomes active."""
+
+    @abstractmethod
+    def on_exit(self):
+        """Called when the scene is replaced."""
+
+    @abstractmethod
+    def handle_event(self, event: object):
+        """
+        Handle input / events (e.g. pygame.Event).
+
+        :param event: The event to handle.
+        :type event: object
+        """
+
+    @abstractmethod
+    def update(self, dt: float):
+        """
+        Update game logic. ``dt`` is the delta time in seconds.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+
+    @abstractmethod
+    def draw(self, surface: object):
+        """
+        Render to the main surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: object
+        """

mini_arcade_core-0.6.1/src/mini_arcade_core/backend.py

@@ -1,75 +0,0 @@
-"""
-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 enum import Enum, auto
-from typing import Iterable, Protocol
-
-
-class EventType(Enum):
-    """High-level event types understood by the core."""
-
-    UNKNOWN = auto()
-    QUIT = auto()
-    KEYDOWN = auto()
-    KEYUP = auto()
-
-
-@dataclass(frozen=True)
-class Event:
-    """
-    Core event type.
-
-    For now we only care about:
-    - type: what happened
-    - key: integer key code (e.g. ESC = 27), or None if not applicable
-
-    :ivar type (EventType): The type of event.
-    :ivar key (int | None): The key code associated with the event, if any.
-    """
-
-    type: EventType
-    key: int | None = None
-
-
-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, width: int, height: int, title: str) -> None:
-        """
-        Initialize the backend and open a window.
-
-        Should be called once before the main loop.
-        """
-
-    def poll_events(self) -> Iterable[Event]:
-        """
-        Return all pending events since last call.
-
-        Concrete backends will translate their native events into core Event objects.
-        """
-
-    def begin_frame(self) -> None:
-        """
-        Prepare for drawing a new frame (e.g. clear screen).
-        """
-
-    def end_frame(self) -> None:
-        """
-        Present the frame to the user (swap buffers).
-        """
-
-    def draw_rect(self, x: int, y: int, w: int, h: int) -> None:
-        """
-        Draw a filled rectangle in some default color.
-
-        We'll keep this minimal for now; later we can extend with colors/sprites.
-        """

mini_arcade_core-0.6.1/src/mini_arcade_core/scene.py

@@ -1,40 +0,0 @@
-"""
-Base class for game scenes (states/screens).
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-
-from .game import Game
-
-
-class Scene(ABC):
-    """Base class for game scenes (states/screens)."""
-
-    def __init__(self, game: Game):
-        """
-        :param game: Reference to the main Game object.
-        :type game: Game
-        """
-        self.game = game
-
-    @abstractmethod
-    def on_enter(self):
-        """Called when the scene becomes active."""
-
-    @abstractmethod
-    def on_exit(self):
-        """Called when the scene is replaced."""
-
-    @abstractmethod
-    def handle_event(self, event: object):
-        """Handle input / events (e.g. pygame.Event)."""
-
-    @abstractmethod
-    def update(self, dt: float):
-        """Update game logic. ``dt`` is the delta time in seconds."""
-
-    @abstractmethod
-    def draw(self, surface: object):
-        """Render to the main surface."""