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

mini_arcade_core/scenes/registry.py

@@ -1,5 +1,5 @@
 """
-Scene registry for mini arcade core.
+SimScene registry for mini arcade core.
 Allows registering and creating scenes by string IDs.
 """
 
@@ -10,11 +10,13 @@ import pkgutil
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Dict, Protocol
 
+from mini_arcade_core.runtime.context import RuntimeContext
+
 from .autoreg import snapshot
 
 if TYPE_CHECKING:
-    from mini_arcade_core.game import Game
-    from mini_arcade_core.scenes import Scene
+    from mini_arcade_core.engine.commands import CommandQueue
+    from mini_arcade_core.sim import SimScene
 
 
 class SceneFactory(Protocol):
@@ -22,7 +24,7 @@ class SceneFactory(Protocol):
     Protocol for scene factory callables.
     """
 
-    def __call__(self, game: "Game") -> "Scene": ...
+    def __call__(self, context: RuntimeContext) -> "SimScene": ...
 
 
 @dataclass
@@ -40,28 +42,28 @@ class SceneRegistry:
         :param scene_id: The string ID for the scene.
         :type scene_id: str
 
-        :param factory: A callable that creates a Scene instance.
+        :param factory: A callable that creates a SimScene instance.
         :type factory: SceneFactory
         """
         self._factories[scene_id] = factory
 
-    def register_cls(self, scene_id: str, scene_cls: type["Scene"]):
+    def register_cls(self, scene_id: str, scene_cls: type["SimScene"]):
         """
-        Register a Scene class under a given scene ID.
+        Register a SimScene class under a given scene ID.
 
         :param scene_id: The string ID for the scene.
         :type scene_id: str
 
-        :param scene_cls: The Scene class to register.
-        :type scene_cls: type["Scene"]
+        :param scene_cls: The SimScene class to register.
+        :type scene_cls: type["SimScene"]
         """
 
-        def return_factory(game: "Game") -> "Scene":
-            return scene_cls(game)
+        def return_factory(context: RuntimeContext) -> "SimScene":
+            return scene_cls(context)
 
         self.register(scene_id, return_factory)
 
-    def create(self, scene_id: str, game: "Game") -> "Scene":
+    def create(self, scene_id: str, context: RuntimeContext) -> "SimScene":
         """
         Create a scene instance using the registered factory for the given scene ID.
 
@@ -71,22 +73,22 @@ class SceneRegistry:
         :param game: The Game instance to pass to the scene factory.
         :type game: Game
 
-        :return: A new Scene instance.
-        :rtype: Scene
+        :return: A new SimScene instance.
+        :rtype: SimScene
 
         :raises KeyError: If no factory is registered for the given scene ID.
         """
         try:
-            return self._factories[scene_id](game)
+            return self._factories[scene_id](context)
         except KeyError as e:
             raise KeyError(f"Unknown scene_id={scene_id!r}") from e
 
-    def load_catalog(self, catalog: Dict[str, type["Scene"]]):
+    def load_catalog(self, catalog: Dict[str, type["SimScene"]]):
         """
-        Load a catalog of Scene classes into the registry.
+        Load a catalog of SimScene classes into the registry.
 
-        :param catalog: A dictionary mapping scene IDs to Scene classes.
-        :type catalog: Dict[str, type["Scene"]]
+        :param catalog: A dictionary mapping scene IDs to SimScene classes.
+        :type catalog: Dict[str, type["SimScene"]]
         """
         for scene_id, cls in catalog.items():
             self.register_cls(scene_id, cls)

mini_arcade_core/scenes/sim_scene.py

@@ -0,0 +1,41 @@
+"""
+Simulation scene protocol module.
+Defines the SimScene protocol for simulation scenes.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+
+@runtime_checkable
+class SimScene(Protocol):
+    """ "Protocol for a simulation scene in the mini arcade core."""
+
+    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):
+        """
+        Advance the simulation by one tick.
+
+        :param input_frame: Current input frame.
+        :type input_frame: InputFrame
+
+        :param dt: Delta time since last tick.
+        :type dt: float
+        """
+
+    def build_render_packet(self) -> RenderPacket:
+        """
+        Build the render packet for the current scene state.
+
+        :return: RenderPacket instance.
+        :rtype: RenderPacket
+        """

mini_arcade_core/scenes/systems/base_system.py

@@ -0,0 +1,40 @@
+"""
+Protocol for base systems in the mini arcade core.
+Defines the BaseSystem protocol that all systems should implement.
+"""
+
+from __future__ import annotations
+
+from typing import Generic, Protocol, TypeVar, runtime_checkable
+
+# Justification: Type variable name is conventional.
+# pylint: disable=invalid-name
+TSystemContext = TypeVar("TSystemContext")
+# pylint: enable=invalid-name
+
+
+@runtime_checkable
+class BaseSystem(Protocol, Generic[TSystemContext]):
+    """Protocol for a system that operates within a given context."""
+
+    name: str
+    order: int
+
+    def enabled(self, ctx: TSystemContext) -> bool:
+        """
+        Determine if the system is enabled in the given context.
+
+        :param ctx: The system context.
+        :type ctx: TSystemContext
+
+        :return: True if the system is enabled, False otherwise.
+        :rtype: bool
+        """
+
+    def step(self, ctx: TSystemContext):
+        """
+        Perform a single step of the system within the given context.
+
+        :param ctx: The system context.
+        :type ctx: TSystemContext
+        """

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/spaces/__init__.py

@@ -1,12 +0,0 @@
-"""
-Mini Arcade Core Spaces Module
-This module contains different space definitions for the Mini Arcade Core framework.
-"""
-
-from __future__ import annotations
-
-from . import d2
-
-__all__ = [
-    "d2",
-]

mini_arcade_core/spaces/d2/__init__.py

@@ -1,30 +0,0 @@
-"""
-Two-dimensional utilities and components for Mini Arcade Core.
-Includes 2D entities, boundaries, and physics.
-"""
-
-from __future__ import annotations
-
-from .boundaries2d import (
-    RectKinematic,
-    RectSprite,
-    VerticalBounce,
-    VerticalWrap,
-)
-from .collision2d import RectCollider
-from .geometry2d import Bounds2D, Position2D, Size2D
-from .kinematics2d import KinematicData
-from .physics2d import Velocity2D
-
-__all__ = [
-    "Bounds2D",
-    "Position2D",
-    "Size2D",
-    "KinematicData",
-    "Velocity2D",
-    "RectCollider",
-    "RectKinematic",
-    "RectSprite",
-    "VerticalBounce",
-    "VerticalWrap",
-]

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