mini-arcade-core 0.7.1__tar.gz → 0.7.3__tar.gz

{mini_arcade_core-0.7.1 → mini_arcade_core-0.7.3}/PKG-INFO

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

{mini_arcade_core-0.7.1 → mini_arcade_core-0.7.3}/pyproject.toml

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

{mini_arcade_core-0.7.1 → mini_arcade_core-0.7.3}/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.1 → mini_arcade_core-0.7.3}/src/mini_arcade_core/backend.py

@@ -11,7 +11,14 @@ from typing import Iterable, Protocol
 
 
 class EventType(Enum):
-    """High-level event types understood by the core."""
+    """
+    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()
@@ -46,20 +53,39 @@ class Backend(Protocol):
     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:
@@ -84,8 +110,22 @@ class Backend(Protocol):
     ) -> 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
@@ -102,6 +142,18 @@ class Backend(Protocol):
 
         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:
@@ -109,5 +161,11 @@ class Backend(Protocol):
         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.7.1 → mini_arcade_core-0.7.3}/src/mini_arcade_core/game.py

@@ -124,6 +124,15 @@ class Game:
     ) -> 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")

mini_arcade_core-0.7.3/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.7.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."""