mini-arcade-core 0.3.1__tar.gz → 0.8.0__tar.gz

{mini_arcade_core-0.3.1 → mini_arcade_core-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 0.3.1
+Version: 0.8.0
 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"
@@ -122,21 +123,21 @@ Represents one state of your game (menu, gameplay, pause, etc.):
 from mini_arcade_core import Scene, Game
 
 class MyScene(Scene):
-    def on_enter(self) -> None:
+    def on_enter(self):
         print("Scene entered")
 
-    def on_exit(self) -> None:
+    def on_exit(self):
         print("Scene exited")
 
-    def handle_event(self, event: object) -> None:
+    def handle_event(self, event: object):
         # Handle input / events from your backend
         pass
 
-    def update(self, dt: float) -> None:
+    def update(self, dt: float):
         # Game logic
         pass
 
-    def draw(self, surface: object) -> None:
+    def draw(self, surface: object):
         # Rendering via your backend
         pass
 ```
@@ -149,17 +150,17 @@ Lightweight game object primitives:
 from mini_arcade_core import Entity, SpriteEntity
 
 class Ball(Entity):
-    def __init__(self) -> None:
+    def __init__(self):
         self.x = 100.0
         self.y = 100.0
         self.vx = 200.0
         self.vy = 150.0
 
-    def update(self, dt: float) -> None:
+    def update(self, dt: float):
         self.x += self.vx * dt
         self.y += self.vy * dt
 
-    def draw(self, surface: object) -> None:
+    def draw(self, surface: object):
         # Use your backend to draw the ball on `surface`
         pass
 
@@ -181,7 +182,7 @@ from mini_arcade_core import Game, GameConfig, Scene
 
 
 class PygameGame(Game):
-    def __init__(self, config: GameConfig) -> None:
+    def __init__(self, config: GameConfig):
         super().__init__(config)
         pygame.init()
         self._screen = pygame.display.set_mode(
@@ -190,13 +191,13 @@ class PygameGame(Game):
         pygame.display.set_caption(config.title)
         self._clock = pygame.time.Clock()
 
-    def change_scene(self, scene: Scene) -> None:
+    def change_scene(self, scene: Scene):
         if self._current_scene is not None:
             self._current_scene.on_exit()
         self._current_scene = scene
         self._current_scene.on_enter()
 
-    def run(self, initial_scene: Scene) -> None:
+    def run(self, initial_scene: Scene):
         self.change_scene(initial_scene)
         self._running = True
 
@@ -219,7 +220,7 @@ class PygameGame(Game):
 
 
 class PongScene(Scene):
-    def __init__(self, game: Game) -> None:
+    def __init__(self, game: Game):
         super().__init__(game)
         self.x = 100.0
         self.y = 100.0
@@ -227,17 +228,17 @@ class PongScene(Scene):
         self.vy = 150.0
         self.radius = 10
 
-    def on_enter(self) -> None:
+    def on_enter(self):
         print("Pong started")
 
-    def on_exit(self) -> None:
+    def on_exit(self):
         print("Pong finished")
 
-    def handle_event(self, event: object) -> None:
+    def handle_event(self, event: object):
         # no input yet
         pass
 
-    def update(self, dt: float) -> None:
+    def update(self, dt: float):
         self.x += self.vx * dt
         self.y += self.vy * dt
 
@@ -249,7 +250,7 @@ class PongScene(Scene):
         if self.y < self.radius or self.y > height - self.radius:
             self.vy *= -1
 
-    def draw(self, surface: pygame.Surface) -> None:  # type: ignore[override]
+    def draw(self, surface: pygame.Surface):  # type: ignore[override]
         pygame.draw.circle(
             surface, (255, 255, 255), (int(self.x), int(self.y)), self.radius
         )

{mini_arcade_core-0.3.1 → mini_arcade_core-0.8.0}/README.md

@@ -81,21 +81,21 @@ Represents one state of your game (menu, gameplay, pause, etc.):
 from mini_arcade_core import Scene, Game
 
 class MyScene(Scene):
-    def on_enter(self) -> None:
+    def on_enter(self):
         print("Scene entered")
 
-    def on_exit(self) -> None:
+    def on_exit(self):
         print("Scene exited")
 
-    def handle_event(self, event: object) -> None:
+    def handle_event(self, event: object):
         # Handle input / events from your backend
         pass
 
-    def update(self, dt: float) -> None:
+    def update(self, dt: float):
         # Game logic
         pass
 
-    def draw(self, surface: object) -> None:
+    def draw(self, surface: object):
         # Rendering via your backend
         pass
 ```
@@ -108,17 +108,17 @@ Lightweight game object primitives:
 from mini_arcade_core import Entity, SpriteEntity
 
 class Ball(Entity):
-    def __init__(self) -> None:
+    def __init__(self):
         self.x = 100.0
         self.y = 100.0
         self.vx = 200.0
         self.vy = 150.0
 
-    def update(self, dt: float) -> None:
+    def update(self, dt: float):
         self.x += self.vx * dt
         self.y += self.vy * dt
 
-    def draw(self, surface: object) -> None:
+    def draw(self, surface: object):
         # Use your backend to draw the ball on `surface`
         pass
 
@@ -140,7 +140,7 @@ from mini_arcade_core import Game, GameConfig, Scene
 
 
 class PygameGame(Game):
-    def __init__(self, config: GameConfig) -> None:
+    def __init__(self, config: GameConfig):
         super().__init__(config)
         pygame.init()
         self._screen = pygame.display.set_mode(
@@ -149,13 +149,13 @@ class PygameGame(Game):
         pygame.display.set_caption(config.title)
         self._clock = pygame.time.Clock()
 
-    def change_scene(self, scene: Scene) -> None:
+    def change_scene(self, scene: Scene):
         if self._current_scene is not None:
             self._current_scene.on_exit()
         self._current_scene = scene
         self._current_scene.on_enter()
 
-    def run(self, initial_scene: Scene) -> None:
+    def run(self, initial_scene: Scene):
         self.change_scene(initial_scene)
         self._running = True
 
@@ -178,7 +178,7 @@ class PygameGame(Game):
 
 
 class PongScene(Scene):
-    def __init__(self, game: Game) -> None:
+    def __init__(self, game: Game):
         super().__init__(game)
         self.x = 100.0
         self.y = 100.0
@@ -186,17 +186,17 @@ class PongScene(Scene):
         self.vy = 150.0
         self.radius = 10
 
-    def on_enter(self) -> None:
+    def on_enter(self):
         print("Pong started")
 
-    def on_exit(self) -> None:
+    def on_exit(self):
         print("Pong finished")
 
-    def handle_event(self, event: object) -> None:
+    def handle_event(self, event: object):
         # no input yet
         pass
 
-    def update(self, dt: float) -> None:
+    def update(self, dt: float):
         self.x += self.vx * dt
         self.y += self.vy * dt
 
@@ -208,7 +208,7 @@ class PongScene(Scene):
         if self.y < self.radius or self.y > height - self.radius:
             self.vy *= -1
 
-    def draw(self, surface: pygame.Surface) -> None:  # type: ignore[override]
+    def draw(self, surface: pygame.Surface):  # type: ignore[override]
         pygame.draw.circle(
             surface, (255, 255, 255), (int(self.x), int(self.y)), self.radius
         )

{mini_arcade_core-0.3.1 → mini_arcade_core-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "0.3.1"
+version = "0.8.0"
 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 = [
@@ -57,6 +57,8 @@ strict = false
 disable = [
     # Justification: Allow classes with few public methods for simplicity.
     "too-few-public-methods",
+    # Justification: f-strings are preferred for logging.
+    "logging-fstring-interpolation",
     # Justification: TODOs are acceptable during development.
     "fixme",
 ]

mini_arcade_core-0.8.0/src/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-0.8.0/src/mini_arcade_core/backend.py

@@ -0,0 +1,173 @@
+"""
+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, 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.
+    """
+
+    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):
+        """
+        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-0.8.0/src/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