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

mini_arcade_core/__init__.py

@@ -0,0 +1,100 @@
+"""
+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 logging
+from importlib.metadata import PackageNotFoundError, version
+
+from .backend import Backend, Event, EventType
+from .boundaries2d import (
+    RectKinematic,
+    RectSprite,
+    VerticalBounce,
+    VerticalWrap,
+)
+from .collision2d import RectCollider
+from .entity import Entity, KinematicEntity, SpriteEntity
+from .game import Game, GameConfig
+from .geometry2d import Bounds2D, Position2D, Size2D
+from .kinematics2d import KinematicData
+from .physics2d import Velocity2D
+from .scene import Scene
+
+logger = logging.getLogger(__name__)
+
+
+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
+
+    :raises ValueError: If the provided config does not have a valid Backend.
+    """
+    cfg = config or GameConfig()
+    if config.backend is None:
+        raise ValueError(
+            "GameConfig.backend must be set to a Backend instance"
+        )
+    game = Game(cfg)
+    scene = initial_scene_cls(game)
+    game.run(scene)
+
+
+__all__ = [
+    "Game",
+    "GameConfig",
+    "Scene",
+    "Entity",
+    "SpriteEntity",
+    "run_game",
+    "Backend",
+    "Event",
+    "EventType",
+    "Velocity2D",
+    "Position2D",
+    "Size2D",
+    "KinematicEntity",
+    "KinematicData",
+    "RectCollider",
+    "VerticalBounce",
+    "Bounds2D",
+    "VerticalWrap",
+    "RectSprite",
+    "RectKinematic",
+]
+
+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"
+
+
+__version__ = get_version()

mini_arcade_core/backend.py

@@ -0,0 +1,225 @@
+"""
+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, Optional, Protocol, Tuple, Union
+
+Color = Union[Tuple[int, int, int], Tuple[int, int, int, int]]
+
+
+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.
+    :cvar MOUSEMOTION: The mouse was moved.
+    :cvar MOUSEBUTTONDOWN: A mouse button was pressed.
+    :cvar MOUSEBUTTONUP: A mouse button was released.
+    :cvar MOUSEWHEEL: The mouse wheel was scrolled.
+    :cvar WINDOWRESIZED: The window was resized.
+    :cvar TEXTINPUT: Text input event (for IME support).
+    """
+
+    UNKNOWN = auto()
+    QUIT = auto()
+
+    KEYDOWN = auto()
+    KEYUP = auto()
+
+    # Mouse
+    MOUSEMOTION = auto()
+    MOUSEBUTTONDOWN = auto()
+    MOUSEBUTTONUP = auto()
+    MOUSEWHEEL = auto()
+
+    # Window / text
+    WINDOWRESIZED = auto()
+    TEXTINPUT = auto()
+
+
+# Justification: Simple data container for now
+# pylint: disable=too-many-instance-attributes
+@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.
+    :ivar scancode (int | None): The hardware scancode of the key, if any.
+    :ivar mod (int | None): Modifier keys bitmask, if any.
+    :ivar repeat (bool | None): Whether this key event is a repeat, if any.
+    :ivar x (int | None): Mouse X position, if any.
+    :ivar y (int | None): Mouse Y position, if any.
+    :ivar dx (int | None): Mouse delta X, if any.
+    :ivar dy (int | None): Mouse delta Y, if any.
+    :ivar button (int | None): Mouse button number, if any.
+    :ivar wheel (Tuple[int, int] | None): Mouse wheel scroll (x, y), if any.
+    :ivar size (Tuple[int, int] | None): New window size (width, height), if any.
+    :ivar text (str | None): Text input, if any.
+    """
+
+    type: EventType
+    key: Optional[int] = None
+
+    # Keyboard extras (optional)
+    scancode: Optional[int] = None
+    mod: Optional[int] = None
+    repeat: Optional[bool] = None
+
+    # Mouse (optional)
+    x: Optional[int] = None
+    y: Optional[int] = None
+    dx: Optional[int] = None
+    dy: Optional[int] = None
+    button: Optional[int] = None
+    wheel: Optional[Tuple[int, int]] = None  # (wheel_x, wheel_y)
+
+    # Window (optional)
+    size: Optional[Tuple[int, int]] = None  # (width, height)
+
+    # Text input (optional)
+    text: Optional[str] = None
+
+
+# pylint: enable=too-many-instance-attributes
+
+
+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):
+        """
+        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):
+        """
+        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
+        """
+
+    # pylint: enable=too-many-arguments,too-many-positional-arguments
+
+    def draw_text(
+        self,
+        x: int,
+        y: int,
+        text: str,
+        color: Color = (255, 255, 255),
+    ):
+        """
+        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
+        """
+
+    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/boundaries2d.py

@@ -0,0 +1,107 @@
+"""
+Boundary behaviors for 2D rectangular objects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .geometry2d import Bounds2D, Position2D, Size2D
+from .physics2d import Velocity2D
+
+
+class RectKinematic(Protocol):
+    """
+    Minimal contract for something that can bounce:
+    - position: Position2D
+    - size: Size2D
+    - velocity: Velocity2D
+
+    :ivar position (Position2D): Top-left position of the object.
+    :ivar size (Size2D): Size of the object.
+    :ivar velocity (Velocity2D): Velocity of the object.
+    """
+
+    position: Position2D
+    size: Size2D
+    velocity: Velocity2D
+
+
+@dataclass
+class VerticalBounce:
+    """
+    Bounce an object off the top/bottom bounds by inverting vy
+    and clamping its position inside the bounds.
+
+    :ivar bounds (Bounds2D): The boundary rectangle.
+    """
+
+    bounds: Bounds2D
+
+    def apply(self, obj: RectKinematic):
+        """
+        Apply vertical bounce to the given object.
+
+        :param obj: The object to apply the bounce to.
+        :type obj: RectKinematic
+        """
+        top = self.bounds.top
+        bottom = self.bounds.bottom
+
+        # Top collision
+        if obj.position.y <= top:
+            obj.position.y = top
+            obj.velocity.vy *= -1
+
+        # Bottom collision
+        if obj.position.y + obj.size.height >= bottom:
+            obj.position.y = bottom - obj.size.height
+            obj.velocity.vy *= -1
+
+
+class RectSprite(Protocol):
+    """
+    Minimal contract for something that can wrap:
+    - position: Position2D
+    - size: Size2D
+    (no velocity required)
+
+    :ivar position (Position2D): Top-left position of the object.
+    :ivar size (Size2D): Size of the object.
+    """
+
+    position: Position2D
+    size: Size2D
+
+
+@dataclass
+class VerticalWrap:
+    """
+    Wrap an object top <-> bottom.
+
+    If it leaves above the top, it reappears at the bottom.
+    If it leaves below the bottom, it reappears at the top.
+
+    :ivar bounds (Bounds2D): The boundary rectangle.
+    """
+
+    bounds: Bounds2D
+
+    def apply(self, obj: RectSprite):
+        """
+        Apply vertical wrap to the given object.
+
+        :param obj: The object to apply the wrap to.
+        :type obj: RectSprite
+        """
+        top = self.bounds.top
+        bottom = self.bounds.bottom
+
+        # Completely above top → appear at bottom
+        if obj.position.y + obj.size.height < top:
+            obj.position.y = bottom
+
+        # Completely below bottom → appear at top
+        elif obj.position.y > bottom:
+            obj.position.y = top - obj.size.height

mini_arcade_core/collision2d.py

@@ -0,0 +1,71 @@
+"""
+2D collision detection helpers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .geometry2d import Position2D, Size2D
+
+
+def _rects_intersect(
+    pos_a: Position2D,
+    size_a: Size2D,
+    pos_b: Position2D,
+    size_b: Size2D,
+) -> bool:
+    """
+    Low-level AABB check. Internal helper.
+
+    :param pos_a: Top-left position of rectangle A.
+    :type pos_a: Position2D
+
+    :param size_a: Size of rectangle A.
+    :type size_a: Size2D
+
+    :param pos_b: Top-left position of rectangle B.
+    :type pos_b: Position2D
+
+    :param size_b: Size of rectangle B.
+    :type size_b: Size2D
+
+    :return: True if the rectangles intersect.
+    :rtype: bool
+    """
+    return not (
+        pos_a.x + size_a.width < pos_b.x
+        or pos_a.x > pos_b.x + size_b.width
+        or pos_a.y + size_a.height < pos_b.y
+        or pos_a.y > pos_b.y + size_b.height
+    )
+
+
+@dataclass
+class RectCollider:
+    """
+    OOP collision helper that wraps a Position2D + Size2D pair.
+
+    It does NOT own the data – it just points to them. If the
+    entity moves (position changes), the collider “sees” it.
+
+    :ivar position (Position2D): Top-left position of the rectangle.
+    :ivar size (Size2D): Size of the rectangle.
+    """
+
+    position: Position2D
+    size: Size2D
+
+    def intersects(self, other: "RectCollider") -> bool:
+        """
+        High-level OOP method to check collision with another collider.
+
+        ;param other: The other rectangle collider.
+        :type other: RectCollider
+
+        :return: True if the rectangles intersect.
+        :rtype: bool
+        """
+        return _rects_intersect(
+            self.position, self.size, other.position, other.size
+        )

mini_arcade_core/entity.py

@@ -0,0 +1,68 @@
+"""
+Entity base classes for mini_arcade_core.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .collision2d import RectCollider
+from .geometry2d import Position2D, Size2D
+from .kinematics2d import KinematicData
+
+
+class Entity:
+    """Entity base class for game objects."""
+
+    def update(self, dt: float):
+        """
+        Advance the entity state by ``dt`` seconds.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+
+    def draw(self, surface: Any):
+        """
+        Render the entity to the given surface.
+
+        :param surface: The surface to draw on.
+        :type surface: Any
+        """
+
+
+class SpriteEntity(Entity):
+    """Entity with position and size."""
+
+    def __init__(self, position: Position2D, size: Size2D):
+        """
+        :param position: Top-left position of the entity.
+        :type position: Position2D
+
+        :param size: Size of the entity.
+        :type size: Size2D
+        """
+        self.position = Position2D(float(position.x), float(position.y))
+        self.size = Size2D(int(size.width), int(size.height))
+        self.collider = RectCollider(self.position, self.size)
+
+
+class KinematicEntity(SpriteEntity):
+    """SpriteEntity with velocity-based movement."""
+
+    def __init__(self, kinematic_data: KinematicData):
+        """
+        :param kinematic_data: Kinematic data for the entity.
+        :type kinematic_data: KinematicData
+        """
+        super().__init__(
+            position=kinematic_data.position,
+            size=kinematic_data.size,
+        )
+
+        self.velocity = kinematic_data.velocity
+
+    def update(self, dt: float):
+        self.position.x, self.position.y = self.velocity.advance(
+            self.position.x, self.position.y, dt
+        )