mini-arcade-core 0.9.9__py3-none-any.whl → 1.0.0__py3-none-any.whl

mini_arcade_core/scenes/systems/system_pipeline.py

@@ -0,0 +1,57 @@
+"""
+Pipeline for managing and executing systems in order.
+Defines the SystemPipeline dataclass that holds and runs systems.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Generic, Iterable, List
+
+from mini_arcade_core.scenes.systems.base_system import (
+    BaseSystem,
+    TSystemContext,
+)
+
+
+@dataclass
+class SystemPipeline(Generic[TSystemContext]):
+    """
+    Pipeline for managing and executing systems in order.
+
+    :ivar systems (List[BaseSystem[TSystemContext]]): List of systems in the pipeline.
+    """
+
+    systems: List[BaseSystem[TSystemContext]] = field(default_factory=list)
+
+    def add(self, system: BaseSystem[TSystemContext]):
+        """
+        Add a system to the pipeline and sort by order.
+
+        :param system: The system to add.
+        :type system: BaseSystem[TSystemContext]
+        """
+        self.systems.append(system)
+        self.systems.sort(key=lambda s: getattr(s, "order", 0))
+
+    def extend(self, systems: Iterable[BaseSystem[TSystemContext]]):
+        """
+        Extend the pipeline with multiple systems.
+
+        :param systems: An iterable of systems to add.
+        :type systems: Iterable[BaseSystem[TSystemContext]]
+        """
+        for s in systems:
+            self.add(s)
+
+    def step(self, ctx: TSystemContext):
+        """
+        Execute a step for each system in the pipeline.
+
+        :param ctx: The system context.
+        :type ctx: TSystemContext
+        """
+        for system in self.systems:
+            if hasattr(system, "enabled") and not system.enabled(ctx):
+                continue
+            system.step(ctx)

mini_arcade_core/sim/protocols.py

@@ -0,0 +1,41 @@
+"""
+Simulation scene protocol module.
+Defines the SimScene protocol for simulation scenes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.runtime.context import RuntimeContext
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+
+@dataclass
+class SimScene:
+    """
+    Simulation-first scene protocol.
+
+    tick() advances the simulation and returns a RenderPacket for this scene.
+    """
+
+    context: RuntimeContext
+
+    def on_enter(self):
+        """Called when the scene is entered."""
+
+    def on_exit(self):
+        """Called when the scene is exited."""
+
+    def tick(self, input_frame: InputFrame, dt: float) -> RenderPacket:
+        """
+        Advance the simulation by dt seconds, processing input_frame.
+
+        :param input_frame: InputFrame with input events for this frame.
+        :param dt: Time delta in seconds since the last tick.
+
+        :return: RenderPacket for this frame.
+        :rtype: RenderPacket
+        """
+        raise NotImplementedError()

mini_arcade_core/sim/runner.py

@@ -0,0 +1,222 @@
+"""
+Simulation runner module.
+Defines the SimRunner class for running simulation scenes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import perf_counter, sleep
+from typing import Dict, Optional
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.engine.render.pipeline import RenderPipeline
+from mini_arcade_core.runtime.input_frame import InputFrame
+from mini_arcade_core.runtime.scene.scene_port import SceneEntry
+from mini_arcade_core.runtime.services import RuntimeServices
+
+
+def _neutral_input(frame_index: int, dt: float) -> InputFrame:
+    # InputFrame is frozen; create a clean snapshot for non-input scenes.
+    return InputFrame(frame_index=frame_index, dt=dt)
+
+
+def _has_tick(scene: object) -> bool:
+    # Avoid isinstance(..., Protocol). Structural check.
+    return callable(getattr(scene, "tick", None))
+
+
+def _has_draw(scene: object) -> bool:
+    return callable(getattr(scene, "draw", None))
+
+
+def _has_update(scene: object) -> bool:
+    return callable(getattr(scene, "update", None))
+
+
+def _has_handle_event(scene: object) -> bool:
+    return callable(getattr(scene, "handle_event", None))
+
+
+@dataclass(frozen=True)
+class SimRunnerConfig:
+    """
+    Config for sim runner.
+
+    - record: if True, capture a frame each tick using deterministic naming.
+    - run_id: required when record=True.
+    - max_frames: optional safety stop (useful for offline sims/tests).
+    """
+
+    fps: int = 60
+    record: bool = False
+    run_id: str = "run"
+    max_frames: Optional[int] = None
+    # If True, still forward raw events to the input scene's handle_event (legacy UI / text input).
+    forward_events_to_input_scene: bool = True
+
+
+class SimRunner:
+    """
+    Simulation-first runner.
+
+    Uses:
+      - services.scenes.update_entries() for ticking (policy-aware)
+      - services.scenes.visible_entries() for rendering (opaque-aware)
+      - services.scenes.input_entry() for input focus
+    """
+
+    def __init__(
+        self,
+        backend: Backend,
+        services: RuntimeServices,
+        *,
+        render_pipeline: Optional[RenderPipeline] = None,
+    ):
+        if services.scenes is None:
+            raise ValueError("RuntimeServices.scenes must be set")
+        if services.input is None:
+            raise ValueError("RuntimeServices.input must be set")
+        if services.capture is None:
+            # recording is optional, but capture port should exist in v1
+            raise ValueError("RuntimeServices.capture must be set")
+
+        self.backend = backend
+        self.services = services
+        self.pipeline = render_pipeline or RenderPipeline()
+
+        # cache: scene object id -> last RenderPacket
+        self._packets: Dict[int, RenderPacket] = {}
+
+        self._running: bool = False
+
+    def stop(self):
+        """
+        Stop the simulation loop.
+        """
+        self._running = False
+
+    # TODO: Solve too-many-statements, too-many-branches and too-many-locals
+    # warning later
+    # Justification: The run method orchestrates multiple complex steps in the
+    # simulation loop.
+    # pylint: disable=too-many-statements,too-many-branches,too-many-locals
+    def run(
+        self, initial_scene_id: str, *, cfg: Optional[SimRunnerConfig] = None
+    ):
+        """
+        Run the simulation loop starting from the initial scene.
+
+        :param initial_scene_id: ID of the initial scene to load.
+        :type initial_scene_id: str
+
+        :param cfg: Optional SimRunnerConfig instance.
+        :type cfg: Optional[SimRunnerConfig]
+        """
+        cfg = cfg or SimRunnerConfig()
+
+        scenes = self.services.scenes
+        assert scenes is not None
+
+        # start at initial scene
+        scenes.change(initial_scene_id)
+
+        self._running = True
+        target_dt = 1.0 / cfg.fps if cfg.fps > 0 else 0.0
+
+        last_time = perf_counter()
+        frame_index = 0
+
+        while self._running:
+            if cfg.max_frames is not None and frame_index >= cfg.max_frames:
+                break
+
+            now = perf_counter()
+            dt = now - last_time
+            last_time = now
+
+            # 1) poll events -> build InputFrame
+            events = list(self.backend.poll_events())
+            input_frame = self.services.input.build(events, frame_index, dt)
+
+            # 2) OS quit request is a hard stop
+            if input_frame.quit:
+                # use ScenePort.quit so Game.quit can be centralized there
+                scenes.quit()
+                break
+
+            # 3) input focus scene (top of visible stack)
+            input_entry: Optional[SceneEntry] = scenes.input_entry()
+            if input_entry is None:
+                break
+
+            # Optional legacy: forward raw events to focused scene
+            if cfg.forward_events_to_input_scene and _has_handle_event(
+                input_entry.scene
+            ):
+                for ev in events:
+                    input_entry.scene.handle_event(ev)
+
+            # 4) tick/update policy-aware scenes
+            for entry in scenes.update_entries():
+                scene_obj = entry.scene
+                scene_key = id(scene_obj)
+
+                # Only the input-focused scene receives the actual input_frame
+                effective_input = (
+                    input_frame
+                    if entry is input_entry
+                    else _neutral_input(frame_index, dt)
+                )
+
+                if _has_tick(scene_obj):
+                    packet = scene_obj.tick(effective_input, dt)  # SimScene
+                    if not isinstance(packet, RenderPacket):
+                        raise TypeError(
+                            f"{entry.scene_id}.tick() must "
+                            f"return RenderPacket, got {type(packet)!r}"
+                        )
+                    self._packets[scene_key] = packet
+                elif _has_update(scene_obj):
+                    # legacy scene; keep packet cache if any
+                    scene_obj.update(dt)
+
+            # 5) render visible stack (policy-aware)
+            self.backend.begin_frame()
+
+            for entry in scenes.visible_entries():
+                scene_obj = entry.scene
+                scene_key = id(scene_obj)
+
+                if _has_tick(scene_obj):
+                    packet = self._packets.get(scene_key)
+                    # If first frame and no packet exists yet, do a dt=0 tick to bootstrap
+                    if packet is None:
+                        packet = scene_obj.tick(
+                            _neutral_input(frame_index, 0.0), 0.0
+                        )
+                        self._packets[scene_key] = packet
+                    self.pipeline.draw_packet(self.backend, packet)
+
+                elif _has_draw(scene_obj):
+                    # legacy scene draw path
+                    scene_obj.draw(self.backend)
+
+            self.backend.end_frame()
+
+            # 6) deterministic capture (optional)
+            if cfg.record:
+                # label could be "frame" or something semantic later
+                self.services.capture.screenshot_sim(
+                    cfg.run_id, frame_index, label="frame"
+                )
+
+            # 7) frame pacing
+            if target_dt > 0 and dt < target_dt:
+                sleep(target_dt - dt)
+
+            frame_index += 1
+
+        # cleanup scenes
+        scenes.clean()

mini_arcade_core/{two_d → spaces/d2}/collision2d.py

@@ -4,45 +4,35 @@
 
 from __future__ import annotations
 
+from abc import ABC, abstractmethod
 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:
+class Collider2D(ABC):
+    """
+    Abstract base class for 2D colliders.
     """
-    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
+    position: Position2D
+    size: Size2D
 
-    :param pos_b: Top-left position of rectangle B.
-    :type pos_b: Position2D
+    @abstractmethod
+    def intersects(self, other: Collider2D) -> bool:
+        """
+        Check if this collider intersects with another collider.
 
-    :param size_b: Size of rectangle B.
-    :type size_b: Size2D
+        :param other: The other collider to check against.
+        :type other: Collider2D
 
-    :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
-    )
+        :return: True if the colliders intersect.
+        :rtype: bool
+        """
 
 
 @dataclass
-class RectCollider:
+class RectCollider(Collider2D):
     """
     OOP collision helper that wraps a Position2D + Size2D pair.
 
@@ -66,6 +56,13 @@ class RectCollider:
         :return: True if the rectangles intersect.
         :rtype: bool
         """
-        return _rects_intersect(
-            self.position, self.size, other.position, other.size
+        pos_a = self.position
+        size_a = self.size
+        pos_b = other.position
+        size_b = other.size
+        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
         )

mini_arcade_core/{two_d → spaces/d2}/geometry2d.py

@@ -19,6 +19,15 @@ class Position2D:
     x: float
     y: float
 
+    def to_tuple(self) -> tuple[float, float]:
+        """
+        Convert Position2D to a tuple.
+
+        :return: Tuple of (x, y).
+        :rtype: tuple[float, float]
+        """
+        return (self.x, self.y)
+
 
 @dataclass
 class Size2D:
@@ -32,6 +41,15 @@ class Size2D:
     width: int
     height: int
 
+    def to_tuple(self) -> tuple[int, int]:
+        """
+        Convert Size2D to a tuple.
+
+        :return: Tuple of (width, height).
+        :rtype: tuple[int, int]
+        """
+        return (self.width, self.height)
+
 
 @dataclass
 class Bounds2D:

mini_arcade_core/{two_d → spaces/d2}/kinematics2d.py

@@ -7,8 +7,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Optional
 
-from mini_arcade_core.backend import Color
-
+from .collision2d import Collider2D
 from .geometry2d import Position2D, Size2D
 from .physics2d import Velocity2D
 
@@ -27,7 +26,8 @@ class KinematicData:
     position: Position2D
     size: Size2D
     velocity: Velocity2D
-    color: Optional[Color] = None  # future use
+    time_scale: float = 1.0
+    collider: Optional[Collider2D] = None
 
     # Justification: Convenience factory with many params.
     # pylint: disable=too-many-arguments,too-many-positional-arguments
@@ -40,7 +40,7 @@ class KinematicData:
         height: int,
         vx: float = 0.0,
         vy: float = 0.0,
-        color: Optional[Color] = None,
+        time_scale: float = 1.0,
     ) -> "KinematicData":
         """
         Convenience factory for rectangular kinematic data.
@@ -63,9 +63,6 @@ class KinematicData:
         :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
         """
@@ -73,7 +70,7 @@ class KinematicData:
             position=Position2D(float(x), float(y)),
             size=Size2D(int(width), int(height)),
             velocity=Velocity2D(float(vx), float(vy)),
-            color=color,
+            time_scale=time_scale,
         )
 
     # pylint: enable=too-many-arguments,too-many-positional-arguments

mini_arcade_core/{two_d → spaces/d2}/physics2d.py

@@ -19,6 +19,15 @@ class Velocity2D:
     vx: float = 0.0
     vy: float = 0.0
 
+    def to_tuple(self) -> tuple[float, float]:
+        """
+        Convert Velocity2D to a tuple.
+
+        :return: Tuple of (vx, vy).
+        :rtype: tuple[float, float]
+        """
+        return (self.vx, self.vy)
+
     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

mini_arcade_core/ui/__init__.py

@@ -1,14 +0,0 @@
-"""
-UI utilities and components for Mini Arcade Core.
-Includes buttons, labels, and layout management.
-"""
-
-from __future__ import annotations
-
-from .menu import Menu, MenuItem, MenuStyle
-
-__all__ = [
-    "Menu",
-    "MenuItem",
-    "MenuStyle",
-]