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

mini_arcade_core/runtime/window/window_port.py

@@ -0,0 +1,109 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.backend import Backend, WindowSettings
+from mini_arcade_core.engine.render.viewport import ViewportMode, ViewportState
+
+
+class WindowPort:
+    """Interface for window-related operations."""
+
+    backend: Backend
+    size: tuple[int, int]
+    window_settings_cls: WindowSettings
+
+    def set_window_size(self, width: int, height: int):
+        """
+        Set the size of the window.
+
+        :param width: Width in pixels.
+        :type width: int
+
+        :param height: Height in pixels.
+        :type height: int
+        """
+
+    def set_viewport_mode(self, mode: ViewportMode):
+        """
+        Set the viewport mode for rendering.
+
+        :param mode: The viewport mode to set.
+        :type mode: ViewportMode
+        """
+
+    def get_viewport(self) -> ViewportState:
+        """
+        Get the current viewport state.
+
+        :return: The current ViewportState.
+        :rtype: ViewportState
+        """
+
+    def screen_to_virtual(self, x: float, y: float) -> tuple[float, float]:
+        """
+        Convert screen coordinates to virtual coordinates.
+
+        :param x: X coordinate on the screen.
+        :type x: float
+
+        :param y: Y coordinate on the screen.
+        :type y: float
+
+        :return: Corresponding virtual coordinates (x, y).
+        :rtype: tuple[float, float]
+        """
+
+    def set_virtual_resolution(self, width: int, height: int):
+        """
+        Set the virtual resolution for rendering.
+
+        :param width: Virtual width in pixels.
+        :type width: int
+
+        :param height: Virtual height in pixels.
+        :type height: int
+        """
+
+    def set_title(self, title: str):
+        """
+        Set the window title.
+
+        :param title: The new title for the window.
+        :type title: str
+        """
+
+    def set_clear_color(self, r: int, g: int, b: int):
+        """
+        Set the clear color for the window.
+
+        :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 on_window_resized(self, width: int, height: int):
+        """
+        Handle window resized event.
+
+        :param width: New width of the window.
+        :type width: int
+
+        :param height: New height of the window.
+        :type height: int
+        """
+
+    def get_virtual_size(self) -> tuple[int, int]:
+        """
+        Get the current virtual resolution size.
+
+        :return: Tuple of (virtual_width, virtual_height).
+        :rtype: tuple[int, int]
+        """

mini_arcade_core/scenes/__init__.py

@@ -1,22 +0,0 @@
-"""
-Scenes module for Mini Arcade Core.
-Provides the base Scene class and related functionality.
-"""
-
-from __future__ import annotations
-
-from .autoreg import register_scene
-from .model import SceneModel
-from .registry import SceneRegistry
-from .runtime import SceneRuntime
-from .scene import Scene
-from .system import BaseSceneSystem
-
-__all__ = [
-    "Scene",
-    "register_scene",
-    "SceneRegistry",
-    "SceneRuntime",
-    "SceneModel",
-    "BaseSceneSystem",
-]

mini_arcade_core/scenes/autoreg.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Dict, Type
 
 if TYPE_CHECKING:
-    from . import Scene
+    from mini_arcade_core.scenes.scene import Scene
 
 _AUTO: Dict[str, Type["Scene"]] = {}
 

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",
-]