mini-arcade-core 0.7.5__tar.gz → 0.8.1__tar.gz

{mini_arcade_core-0.7.5 → mini_arcade_core-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 0.7.5
+Version: 0.8.1
 Summary: Tiny scene-based game loop core for small arcade games.
 License: Copyright (c) 2025 Santiago Rincón
            
@@ -123,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
 ```
@@ -150,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
 
@@ -182,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(
@@ -191,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
 
@@ -220,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
@@ -228,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
 
@@ -250,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.7.5 → mini_arcade_core-0.8.1}/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.7.5 → mini_arcade_core-0.8.1}/pyproject.toml

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

{mini_arcade_core-0.7.5 → mini_arcade_core-0.8.1}/src/mini_arcade_core/__init__.py

@@ -9,8 +9,18 @@ import logging
 from importlib.metadata import PackageNotFoundError, version
 
 from .backend import Backend, Event, EventType
-from .entity import Entity, SpriteEntity
+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__)
@@ -25,8 +35,15 @@ def run_game(initial_scene_cls: type[Scene], config: GameConfig | None = None):
 
     :param config: Optional GameConfig to customize game settings.
     :type config: GameConfig | None
+
+    :raises ValueError: If the provided config does not have a valid Backend.
     """
-    game = Game(config or GameConfig())
+    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)
 
@@ -41,6 +58,17 @@ __all__ = [
     "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

{mini_arcade_core-0.7.5 → mini_arcade_core-0.8.1}/src/mini_arcade_core/backend.py

@@ -7,7 +7,9 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum, auto
-from typing import Iterable, Protocol
+from typing import Iterable, Protocol, Tuple, Union
+
+Color = Union[Tuple[int, int, int], Tuple[int, int, int, int]]
 
 
 class EventType(Enum):
@@ -50,7 +52,7 @@ class Backend(Protocol):
     mini-arcade-core only talks to this protocol, never to SDL/pygame directly.
     """
 
-    def init(self, width: int, height: int, title: str) -> None:
+    def init(self, width: int, height: int, title: str):
         """
         Initialize the backend and open a window.
         Should be called once before the main loop.
@@ -74,7 +76,7 @@ class Backend(Protocol):
         :rtype: Iterable[Event]
         """
 
-    def set_clear_color(self, r: int, g: int, b: int) -> None:
+    def set_clear_color(self, r: int, g: int, b: int):
         """
         Set the background/clear color used by begin_frame.
 
@@ -88,12 +90,12 @@ class Backend(Protocol):
         :type b: int
         """
 
-    def begin_frame(self) -> None:
+    def begin_frame(self):
         """
         Prepare for drawing a new frame (e.g. clear screen).
         """
 
-    def end_frame(self) -> None:
+    def end_frame(self):
         """
         Present the frame to the user (swap buffers).
         """
@@ -106,8 +108,8 @@ class Backend(Protocol):
         y: int,
         w: int,
         h: int,
-        color: tuple[int, int, int] = (255, 255, 255),
-    ) -> None:
+        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.
@@ -125,7 +127,7 @@ class Backend(Protocol):
         :type h: int
 
         :param color: RGB color tuple.
-        :type color: tuple[int, int, int]
+        :type color: Color
         """
 
     # pylint: enable=too-many-arguments,too-many-positional-arguments
@@ -135,8 +137,8 @@ class Backend(Protocol):
         x: int,
         y: int,
         text: str,
-        color: tuple[int, int, int] = (255, 255, 255),
-    ) -> None:
+        color: Color = (255, 255, 255),
+    ):
         """
         Draw text at the given position in a default font and color.
 
@@ -153,7 +155,7 @@ class Backend(Protocol):
         :type text: str
 
         :param color: RGB color tuple.
-        :type color: tuple[int, int, int]
+        :type color: Color
         """
 
     def capture_frame(self, path: str | None = None) -> bytes | None:

mini_arcade_core-0.8.1/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

mini_arcade_core-0.8.1/src/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-0.8.1/src/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
+        )

{mini_arcade_core-0.7.5 → mini_arcade_core-0.8.1}/src/mini_arcade_core/game.py

@@ -29,7 +29,7 @@ class GameConfig:
     :ivar title: Title of the game window.
     :ivar fps: Target frames per second.
     :ivar background_color: RGB background color.
-    :ivar backend: Optional backend class to use for rendering and input.
+    :ivar backend: Optional Backend instance to use for rendering and input.
     """
 
     width: int = 800
@@ -40,6 +40,12 @@ class GameConfig:
     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."""
 
@@ -47,17 +53,28 @@ class Game:
         """
         :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
-        self.backend: Backend | None = config.backend
 
         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):
         """
@@ -67,10 +84,59 @@ class Game:
         :param scene: The new scene to activate.
         :type scene: Scene
         """
-        if self._current_scene is not None:
-            self._current_scene.on_exit()
-        self._current_scene = scene
-        self._current_scene.on_enter()
+        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."""
@@ -103,24 +169,27 @@ class Game:
             dt = now - last_time
             last_time = now
 
-            scene = self._current_scene
-            if scene is None:
+            top = self.current_scene()
+            if top is None:
                 break
 
             for ev in backend.poll_events():
-                scene.handle_event(ev)
+                top.handle_event(ev)
 
-            scene.update(dt)
+            top.update(dt)
 
             backend.begin_frame()
-            scene.draw(backend)
+            for scene in self._visible_stack():
+                scene.draw(backend)
             backend.end_frame()
 
             if target_dt > 0 and dt < target_dt:
                 sleep(target_dt - dt)
 
-        if self._current_scene is not None:
-            self._current_scene.on_exit()
+        # 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:

mini_arcade_core-0.8.1/src/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-0.8.1/src/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-0.8.1/src/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-0.7.5 → mini_arcade_core-0.8.1}/src/mini_arcade_core/scene.py

@@ -7,9 +7,10 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import Callable, List
 
-from mini_arcade_core.backend import Backend
-
+from .backend import Backend, Event
+from .entity import Entity
 from .game import Game
+from .geometry2d import Size2D
 
 OverlayFunc = Callable[[Backend], None]
 
@@ -23,10 +24,55 @@ class Scene(ABC):
         :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_overlay(self, overlay: OverlayFunc) -> None:
+    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).
 
@@ -35,7 +81,7 @@ class Scene(ABC):
         """
         self._overlays.append(overlay)
 
-    def remove_overlay(self, overlay: OverlayFunc) -> None:
+    def remove_overlay(self, overlay: OverlayFunc):
         """
         Unregister a previously added overlay.
 
@@ -45,11 +91,11 @@ class Scene(ABC):
         if overlay in self._overlays:
             self._overlays.remove(overlay)
 
-    def clear_overlays(self) -> None:
+    def clear_overlays(self):
         """Clear all registered overlays."""
         self._overlays.clear()
 
-    def draw_overlays(self, surface: Backend) -> None:
+    def draw_overlays(self, surface: Backend):
         """
         Call all overlays. Scenes should call this at the end of draw().
 
@@ -68,12 +114,12 @@ class Scene(ABC):
         """Called when the scene is replaced."""
 
     @abstractmethod
-    def handle_event(self, event: object):
+    def handle_event(self, event: Event):
         """
         Handle input / events (e.g. pygame.Event).
 
         :param event: The event to handle.
-        :type event: object
+        :type event: Event
         """
 
     @abstractmethod
@@ -86,10 +132,16 @@ class Scene(ABC):
         """
 
     @abstractmethod
-    def draw(self, surface: object):
+    def draw(self, surface: Backend):
         """
         Render to the main surface.
 
         :param surface: The backend surface to draw on.
-        :type surface: object
+        :type surface: Backend
         """
+
+    def on_pause(self):
+        """Called when the game is paused."""
+
+    def on_resume(self):
+        """Called when the game is resumed."""

mini_arcade_core-0.8.1/src/mini_arcade_core/ui/menu.py

@@ -0,0 +1,135 @@
+"""
+Menu system for mini arcade core.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+from mini_arcade_core.backend import Backend, Color, Event, EventType
+
+MenuAction = Callable[[], None]
+
+
+@dataclass(frozen=True)
+class MenuItem:
+    """
+    Represents a single item in a menu.
+
+    :ivar label (str): The text label of the menu item.
+    :ivar on_select (MenuAction): The action to perform when the item is selected.
+    """
+
+    label: str
+    on_select: MenuAction
+
+
+@dataclass
+class MenuStyle:
+    """
+    Styling options for the Menu.
+
+    :ivar normal (Color): Color for unselected items.
+    :ivar selected (Color): Color for the selected item.
+    :ivar line_height (int): Vertical spacing between items.
+    """
+
+    normal: Color = (220, 220, 220)
+    selected: Color = (255, 255, 0)
+    line_height: int = 28
+
+
+class Menu:
+    """A simple text-based menu system."""
+
+    def __init__(
+        self,
+        items: Sequence[MenuItem],
+        *,
+        x: int = 40,
+        y: int = 40,
+        style: MenuStyle | None = None,
+    ):
+        """
+        :param items: Sequence of MenuItem instances to display.
+        type items: Sequence[MenuItem]
+
+        :param x: X coordinate for the menu's top-left corner.
+        :param y: Y coordinate for the menu's top-left corner.
+
+        :param style: Optional MenuStyle for customizing appearance.
+        :type style: MenuStyle | None
+        """
+        self.items = list(items)
+        self.x = x
+        self.y = y
+        self.style = style or MenuStyle()
+        self.selected_index = 0
+
+    def move_up(self):
+        """Move the selection up by one item, wrapping around if necessary."""
+        if self.items:
+            self.selected_index = (self.selected_index - 1) % len(self.items)
+
+    def move_down(self):
+        """Move the selection down by one item, wrapping around if necessary."""
+        if self.items:
+            self.selected_index = (self.selected_index + 1) % len(self.items)
+
+    def select(self):
+        """Select the currently highlighted item, invoking its action."""
+        if self.items:
+            self.items[self.selected_index].on_select()
+
+    def handle_event(
+        self,
+        event: Event,
+        *,
+        up_key: int,
+        down_key: int,
+        select_key: int,
+    ):
+        """
+        Handle an input event to navigate the menu.
+
+        :param event: The input event to handle.
+        :type event: Event
+
+        :param up_key: Key code for moving selection up.
+        type up_key: int
+
+        :param down_key: Key code for moving selection down.
+        :type down_key: int
+
+        :param select_key: Key code for selecting the current item.
+        :type select_key: int
+        """
+        if event.type != EventType.KEYDOWN or event.key is None:
+            return
+        if event.key == up_key:
+            self.move_up()
+        elif event.key == down_key:
+            self.move_down()
+        elif event.key == select_key:
+            self.select()
+
+    def draw(self, surface: Backend):
+        """
+        Draw the menu onto the given backend surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+        for i, item in enumerate(self.items):
+            color = (
+                self.style.selected
+                if i == self.selected_index
+                else self.style.normal
+            )
+            surface.draw_text(
+                self.x,
+                self.y + i * self.style.line_height,
+                item.label,
+                color=color,
+            )

mini_arcade_core-0.7.5/src/mini_arcade_core/entity.py

@@ -1,51 +0,0 @@
-"""
-Entity base classes for mini_arcade_core.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-
-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, x: float, y: float, width: int, height: int):
-        """
-        :param x: X position.
-        :type x: float
-
-        :param y: Y position.
-        :type y: float
-
-        :param width: Width of the entity.
-        :type width: int
-
-        :param height: Height of the entity.
-        :type height: int
-        """
-        self.x = x
-        self.y = y
-        self.width = width
-        self.height = height
-        # TODO: velocity, color, etc.