mini-arcade-core 0.9.0__py3-none-any.whl

mini_arcade_core/game.py

@@ -0,0 +1,243 @@
+"""
+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
+    from .scene import Scene
+
+
+@dataclass
+class GameConfig:
+    """
+    Configuration options for the Game.
+
+    :ivar width: Width of the game window in pixels.
+    :ivar height: Height of the game window in pixels.
+    :ivar title: Title of the game window.
+    :ivar fps: Target frames per second.
+    :ivar background_color: RGB background color.
+    :ivar backend: Optional Backend instance to use for rendering and input.
+    """
+
+    width: int = 800
+    height: int = 600
+    title: str = "Mini Arcade Game"
+    fps: int = 60
+    background_color: tuple[int, int, int] = (0, 0, 0)
+    backend: Backend | None = None
+
+
+@dataclass
+class _StackEntry:
+    scene: "Scene"
+    as_overlay: bool = False
+
+
+class Game:
+    """Core game object responsible for managing the main loop and active scene."""
+
+    def __init__(self, config: GameConfig):
+        """
+        :param config: Game configuration options.
+        :type config: GameConfig
+
+        :raises ValueError: If the provided config does not have a valid Backend.
+        """
+        self.config = config
+        self._current_scene: Scene | None = None
+        self._running: bool = False
+
+        if config.backend is None:
+            raise ValueError(
+                "GameConfig.backend must be set to a Backend instance"
+            )
+        self.backend: Backend = config.backend
+        self._scene_stack: list[_StackEntry] = []
+
+    def current_scene(self) -> "Scene | None":
+        """
+        Get the currently active scene.
+
+        :return: The active Scene instance, or None if no scene is active.
+        :rtype: Scene | None
+        """
+        return self._scene_stack[-1].scene if self._scene_stack else None
+
+    def change_scene(self, scene: Scene):
+        """
+        Swap the active scene. Concrete implementations should call
+        ``on_exit``/``on_enter`` appropriately.
+
+        :param scene: The new scene to activate.
+        :type scene: Scene
+        """
+        while self._scene_stack:
+            entry = self._scene_stack.pop()
+            entry.scene.on_exit()
+
+        self._scene_stack.append(_StackEntry(scene=scene, as_overlay=False))
+        scene.on_enter()
+
+    def push_scene(self, scene: "Scene", as_overlay: bool = False):
+        """
+        Push a scene on top of the current one.
+        If as_overlay=True, underlying scene(s) may still be drawn but never updated.
+        """
+        top = self.current_scene()
+        if top is not None:
+            top.on_pause()
+
+        self._scene_stack.append(
+            _StackEntry(scene=scene, as_overlay=as_overlay)
+        )
+        scene.on_enter()
+
+    def pop_scene(self) -> "Scene | None":
+        """Pop the top scene. If stack becomes empty, quit."""
+        if not self._scene_stack:
+            return None
+
+        popped = self._scene_stack.pop()
+        popped.scene.on_exit()
+
+        top = self.current_scene()
+        if top is None:
+            self.quit()
+            return popped.scene
+
+        top.on_resume()
+        return popped.scene
+
+    def _visible_stack(self) -> list["Scene"]:
+        """
+        Return the list of scenes that should be drawn (base + overlays).
+        We draw from the top-most non-overlay scene upward.
+        """
+        if not self._scene_stack:
+            return []
+
+        # find top-most base scene (as_overlay=False)
+        base_idx = 0
+        for i in range(len(self._scene_stack) - 1, -1, -1):
+            if not self._scene_stack[i].as_overlay:
+                base_idx = i
+                break
+
+        return [e.scene for e in self._scene_stack[base_idx:]]
+
+    def quit(self):
+        """Request that the main loop stops."""
+        self._running = False
+
+    def run(self, initial_scene: Scene):
+        """
+        Run the main loop starting with the given scene.
+
+        This is intentionally left abstract so you can plug pygame, pyglet,
+        or another backend.
+
+        :param initial_scene: The scene to start the game with.
+        :type initial_scene: Scene
+        """
+        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
+        target_dt = 1.0 / self.config.fps if self.config.fps > 0 else 0.0
+        last_time = perf_counter()
+
+        while self._running:
+            now = perf_counter()
+            dt = now - last_time
+            last_time = now
+
+            top = self.current_scene()
+            if top is None:
+                break
+
+            for ev in backend.poll_events():
+                top.handle_event(ev)
+
+            top.update(dt)
+
+            backend.begin_frame()
+            for scene in self._visible_stack():
+                scene.draw(backend)
+            backend.end_frame()
+
+            if target_dt > 0 and dt < target_dt:
+                sleep(target_dt - dt)
+
+        # exit remaining scenes
+        while self._scene_stack:
+            entry = self._scene_stack.pop()
+            entry.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
+        # Justification: Pillow can raise various exceptions on failure
+        # pylint: disable=broad-exception-caught
+        except Exception:
+            return False
+        # pylint: enable=broad-exception-caught
+
+    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/geometry2d.py

@@ -0,0 +1,69 @@
+"""
+2D geometry data structures.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Position2D:
+    """
+    Simple 2D position.
+
+    :ivar x (float): X coordinate.
+    :ivar y (float): Y coordinate.
+    """
+
+    x: float
+    y: float
+
+
+@dataclass
+class Size2D:
+    """
+    Simple 2D size.
+
+    :ivar width (int): Width.
+    :ivar height (int): Height.
+    """
+
+    width: int
+    height: int
+
+
+@dataclass
+class Bounds2D:
+    """
+    Axis-aligned rectangular bounds in world space.
+    (left, top) .. (right, bottom)
+
+    :ivar left (float): Left boundary.
+    :ivar top (float): Top boundary.
+    :ivar right (float): Right boundary.
+    :ivar bottom (float): Bottom boundary.
+    """
+
+    left: float
+    top: float
+    right: float
+    bottom: float
+
+    @classmethod
+    def from_size(cls, size: "Size2D") -> "Bounds2D":
+        """
+        Convenience factory for screen/world bounds starting at (0, 0).
+
+        :param size: Size2D defining the bounds.
+        :type size: Size2D
+
+        :return: Bounds2D from (0,0) to (size.width, size.height).
+        :rtype: Bounds2D
+        """
+        return cls(
+            left=0.0,
+            top=0.0,
+            right=float(size.width),
+            bottom=float(size.height),
+        )

mini_arcade_core/kinematics2d.py

@@ -0,0 +1,78 @@
+"""
+Kinematic helpers for mini_arcade_core (position + size + velocity).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .backend import Color
+from .geometry2d import Position2D, Size2D
+from .physics2d import Velocity2D
+
+
+@dataclass
+class KinematicData:
+    """
+    Simple data structure to hold position, size, and velocity.
+
+    :ivar position (Position2D): Top-left position of the object.
+    :ivar size (Size2D): Size of the object.
+    :ivar velocity (Velocity2D): Velocity of the object.
+    :ivar color (Optional[Color]): Optional color for rendering.
+    """
+
+    position: Position2D
+    size: Size2D
+    velocity: Velocity2D
+    color: Optional[Color] = None  # future use
+
+    # Justification: Convenience factory with many params.
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    @classmethod
+    def rect(
+        cls,
+        x: float,
+        y: float,
+        width: int,
+        height: int,
+        vx: float = 0.0,
+        vy: float = 0.0,
+        color: Optional[Color] = None,
+    ) -> "KinematicData":
+        """
+        Convenience factory for rectangular kinematic data.
+
+        :param x: Top-left X position.
+        :type x: float
+
+        :param y: Top-left Y position.
+        :type y: float
+
+        :param width: Width of the object.
+        :type width: int
+
+        :param height: Height of the object.
+        :type height: int
+
+        :param vx: Velocity in the X direction.
+        :type vx: float
+
+        :param vy: Velocity in the Y direction.
+        :type vy: float
+
+        :param color: Optional color for rendering.
+        :type color: Optional[Color]
+
+        :return: KinematicData instance with the specified parameters.
+        :rtype: KinematicData
+        """
+        return cls(
+            position=Position2D(float(x), float(y)),
+            size=Size2D(int(width), int(height)),
+            velocity=Velocity2D(float(vx), float(vy)),
+            color=color,
+        )
+
+    # pylint: enable=too-many-arguments,too-many-positional-arguments

mini_arcade_core/physics2d.py

@@ -0,0 +1,73 @@
+"""
+Simple 2D physics utilities.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Velocity2D:
+    """
+    Simple 2D velocity vector.
+
+    :ivar vx (float): Velocity in the X direction.
+    :ivar vy (float): Velocity in the Y direction.
+    """
+
+    vx: float = 0.0
+    vy: float = 0.0
+
+    def advance(self, x: float, y: float, dt: float) -> tuple[float, float]:
+        """Return new (x, y) after dt seconds."""
+        return x + self.vx * dt, y + self.vy * dt
+
+    def stop(self):
+        """Stop movement in both axes."""
+        self.vx = 0.0
+        self.vy = 0.0
+
+    def stop_x(self):
+        """Stop horizontal movement."""
+        self.vx = 0.0
+
+    def stop_y(self):
+        """Stop vertical movement."""
+        self.vy = 0.0
+
+    def move_up(self, speed: float):
+        """
+        Set vertical velocity upwards (negative Y).
+
+        :param speed: Speed to set.
+        :type speed: float
+        """
+        self.vy = -abs(speed)
+
+    def move_down(self, speed: float):
+        """
+        Set vertical velocity downwards (positive Y).
+
+        :param speed: Speed to set.
+        :type speed: float
+        """
+        self.vy = abs(speed)
+
+    def move_left(self, speed: float):
+        """
+        Set horizontal velocity to the left (negative X)."
+
+        :param speed: Speed to set.
+        :type speed: float
+        """
+        self.vx = -abs(speed)
+
+    def move_right(self, speed: float):
+        """
+        Set horizontal velocity to the right (positive X).
+
+        :param speed: Speed to set.
+        :type speed: float
+        """
+        self.vx = abs(speed)

mini_arcade_core/scene.py

@@ -0,0 +1,147 @@
+"""
+Base class for game scenes (states/screens).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Callable, List
+
+from .backend import Backend, Event
+from .entity import Entity
+from .game import Game
+from .geometry2d import Size2D
+
+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
+        self.entities: List[Entity] = []
+        self.size: Size2D = Size2D(game.config.width, game.config.height)
+        # overlays drawn on top of the scene
+        self._overlays: List[OverlayFunc] = []
+
+    def add_entity(self, *entities: Entity):
+        """
+        Register one or more entities in this scene.
+
+        :param entities: One or more Entity instances to add.
+        :type entities: Entity
+        """
+        self.entities.extend(entities)
+
+    def remove_entity(self, entity: Entity):
+        """
+        Unregister a single entity, if present.
+
+        :param entity: The Entity instance to remove.
+        :type entity: Entity
+        """
+        if entity in self.entities:
+            self.entities.remove(entity)
+
+    def clear_entities(self):
+        """Remove all entities from the scene."""
+        self.entities.clear()
+
+    def update_entities(self, dt: float):
+        """
+        Default update loop for all entities.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+        for ent in self.entities:
+            ent.update(dt)
+
+    def draw_entities(self, surface: Backend):
+        """
+        Default draw loop for all entities.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+        for ent in self.entities:
+            ent.draw(surface)
+
+    def add_overlay(self, overlay: OverlayFunc):
+        """
+        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):
+        """
+        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):
+        """Clear all registered overlays."""
+        self._overlays.clear()
+
+    def draw_overlays(self, surface: Backend):
+        """
+        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: Event):
+        """
+        Handle input / events (e.g. pygame.Event).
+
+        :param event: The event to handle.
+        :type event: Event
+        """
+
+    @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: Backend):
+        """
+        Render to the main surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+
+    def on_pause(self):
+        """Called when the game is paused."""
+
+    def on_resume(self):
+        """Called when the game is resumed."""