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

mini_arcade_core/runtime/input_frame.py

@@ -0,0 +1,71 @@
+"""
+Input frame data structure for capturing input state per frame.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, FrozenSet, Tuple
+
+from mini_arcade_core.backend.keys import Key
+
+
+@dataclass(frozen=True)
+class ButtonState:
+    """
+    State of a single action button.
+
+    :ivar down (bool): Whether the button is currently held down.
+    :ivar pressed (bool): Whether the button was pressed this frame.
+    :ivar released (bool): Whether the button was released this frame.
+    """
+
+    down: bool
+    pressed: bool
+    released: bool
+
+
+# TODO: Solve too-many-instance-attributes warning later
+# Justification: This data class needs multiple attributes to capture input state.
+# pylint: disable=too-many-instance-attributes
+@dataclass(frozen=True)
+class InputFrame:
+    """
+    Snapshot of input state for a single frame.
+
+    :ivar frame_index (int): Sequential index of the frame.
+    :ivar dt (float): Delta time since the last frame in seconds.
+    :ivar keys_down (FrozenSet[Key]): Set of currently held down keys.
+    :ivar keys_pressed (FrozenSet[Key]): Set of keys pressed this frame.
+    :ivar keys_released (FrozenSet[Key]): Set of keys released this frame.
+    :ivar buttons (Dict[str, ButtonState]): Mapping of action button names to their states.
+    :ivar axes (Dict[str, float]): Mapping of axis names to their float values.
+    :ivar mouse_pos (Tuple[int, int]): Current mouse position (x, y).
+    :ivar mouse_delta (Tuple[int, int]): Mouse movement delta (dx, dy)
+    :ivar text_input (str): Text input entered this frame.
+    :ivar quit (bool): Whether a quit request was made this frame.
+    """
+
+    frame_index: int
+    dt: float
+
+    # Physical keys (device-level snapshot) – supports cheats & replay
+    keys_down: FrozenSet[Key] = frozenset()
+    keys_pressed: FrozenSet[Key] = frozenset()
+    keys_released: FrozenSet[Key] = frozenset()
+
+    # action buttons (jump, confirm, pause, etc.)
+    buttons: Dict[str, ButtonState] = field(default_factory=dict)
+    # axes (move_y, aim_x, etc.)
+    axes: Dict[str, float] = field(default_factory=dict)
+
+    # optional: pass through for UI needs
+    mouse_pos: Tuple[int, int] = (0, 0)
+    mouse_delta: Tuple[int, int] = (0, 0)
+    text_input: str = ""
+
+    # Window/OS quit request
+    quit: bool = False
+
+
+# pylint: enable=too-many-instance-attributes

mini_arcade_core/runtime/scene/scene_adapter.py

@@ -0,0 +1,97 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.runtime.context import RuntimeContext
+from mini_arcade_core.runtime.scene.scene_port import (
+    SceneEntry,
+    ScenePolicy,
+    ScenePort,
+    StackItem,
+)
+
+
+class SceneAdapter(ScenePort):
+    """
+    Manages multiple scenes (not implemented).
+    """
+
+    def __init__(self, registry, game):
+        self._registry = registry
+        self._stack = []
+        self._game = game
+
+    @property
+    def current_scene(self):
+        return self._stack[-1].entry.scene if self._stack else None
+
+    @property
+    def visible_stack(self):
+        return [e.scene for e in self.visible_entries()]
+
+    def change(self, scene_id):
+        self.clean()
+        self.push(scene_id, as_overlay=False)
+
+    def push(
+        self,
+        scene_id,
+        *,
+        as_overlay=False,
+        policy=None,
+    ):
+        # default policy based on overlay vs base
+        if policy is None:
+            # base scenes: do not block anything by default
+            policy = ScenePolicy()
+        runtime_context = RuntimeContext.from_game(self._game)
+        scene = self._registry.create(
+            scene_id, runtime_context
+        )  # or whatever your factory call is
+        scene.on_enter()
+
+        entry = SceneEntry(
+            scene_id=scene_id,
+            scene=scene,
+            is_overlay=as_overlay,
+            policy=policy,
+        )
+        self._stack.append(StackItem(entry=entry))
+
+    def pop(self):
+        if not self._stack:
+            return
+        item = self._stack.pop()
+        item.entry.scene.on_exit()
+
+    def clean(self):
+        while self._stack:
+            self.pop()
+
+    def quit(self):
+        self._game.quit()
+
+    def visible_entries(self):
+        entries = [i.entry for i in self._stack]
+        # find highest opaque from top down; render starting there
+        for idx in range(len(entries) - 1, -1, -1):
+            if entries[idx].policy.is_opaque:
+                return entries[idx:]
+        return entries
+
+    def update_entries(self):
+        vis = self.visible_entries()
+        if not vis:
+            return []
+        out = []
+        for entry in reversed(vis):  # top->down
+            out.append(entry)
+            if entry.policy.blocks_update:
+                break
+        return list(reversed(out))  # bottom->top order
+
+    def input_entry(self):
+        vis = self.visible_entries()
+        return vis[-1] if vis else None

mini_arcade_core/runtime/scene/scene_port.py

@@ -0,0 +1,149 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List
+
+from mini_arcade_core.scenes.registry import SceneRegistry
+
+if TYPE_CHECKING:
+    from mini_arcade_core.engine.game import Game
+    from mini_arcade_core.scenes.scene import Scene
+    from mini_arcade_core.sim.protocols import SimScene
+
+
+@dataclass(frozen=True)
+class ScenePolicy:
+    """
+    Controls how a scene behaves in the scene stack.
+
+    blocks_update: if True, scenes below do not tick/update (pause modal)
+    blocks_input:  if True, scenes below do not receive input
+    is_opaque:     if True, scenes below are not rendered
+    """
+
+    blocks_update: bool = False
+    blocks_input: bool = False
+    is_opaque: bool = False
+
+
+@dataclass(frozen=True)
+class SceneEntry:
+    """
+    An entry in the scene stack.
+
+    :ivar scene_id (str): Identifier of the scene.
+    :ivar scene (Scene): The scene instance.
+    :ivar is_overlay (bool): Whether the scene is an overlay.
+    :ivar policy (ScenePolicy): The scene's policy.
+    """
+
+    scene_id: str
+    scene: SimScene
+    is_overlay: bool
+    policy: ScenePolicy
+
+
+@dataclass
+class StackItem:
+    """
+    An item in the scene stack.
+
+    :ivar entry (SceneEntry): The scene entry.
+    """
+
+    entry: SceneEntry
+
+
+class ScenePort:
+    """Interface for scene management operations."""
+
+    _registry: SceneRegistry
+    _stack: List[StackItem]
+    _game: Game
+
+    @property
+    def current_scene(self) -> "SimScene | None":
+        """
+        Get the currently active scene.
+
+        :return: The active Scene instance, or None if no scene is active.
+        :rtype: SimScene | None
+        """
+
+    @property
+    def visible_stack(self) -> List["SimScene"]:
+        """
+        Return the list of scenes that should be drawn (base + overlays).
+        We draw from the top-most non-overlay scene upward.
+
+        :return: List of visible Scene instances.
+        :rtype: List[SimScene]
+        """
+
+    def change(self, scene_id: str):
+        """
+        Change the current scene to the specified scene.
+
+        :param scene_id: Identifier of the scene to switch to.
+        :type scene_id: str
+        """
+
+    def push(self, scene_id: str, *, as_overlay: bool = False):
+        """
+        Push a new scene onto the scene stack.
+
+        :param scene_id: Identifier of the scene to push.
+        :type scene_id: str
+
+        :param as_overlay: Whether to push the scene as an overlay.
+        :type as_overlay: bool
+        """
+
+    def pop(self) -> "Scene | None":
+        """
+        Pop the current scene from the scene stack.
+
+        :return: The popped Scene instance, or None if the stack was empty.
+        :rtype: Scene | None
+        """
+
+    def clean(self):
+        """
+        Clean up all scenes from the scene stack.
+        """
+
+    def quit(self):
+        """
+        Quit the game
+        """
+
+    def visible_entries(self) -> list[SceneEntry]:
+        """
+        Render from bottom->top unless an opaque entry exists; if so,
+            render only from that entry up.
+
+        :return: List of SceneEntry instances to render.
+        :rtype: list[SceneEntry]
+        """
+
+    def update_entries(self) -> list[SceneEntry]:
+        """
+        Tick/update scenes considering blocks_update.
+        Typical: pause overlay blocks update below it.
+
+        :return: List of SceneEntry instances to update.
+        :rtype: list[SceneEntry]
+        """
+
+    def input_entry(self) -> SceneEntry | None:
+        """
+        Who gets input this frame. If top blocks_input, only it receives input.
+        If not, top still gets input (v1 simple). Later you can allow fall-through.
+
+        :return: The SceneEntry that receives input, or None if no scenes are active.
+        :rtype: SceneEntry | None
+        """

mini_arcade_core/runtime/services.py

@@ -0,0 +1,35 @@
+"""
+Service container for runtime components.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.runtime.audio.audio_port import AudioPort
+from mini_arcade_core.runtime.capture.capture_port import CapturePort
+from mini_arcade_core.runtime.file.file_port import FilePort
+from mini_arcade_core.runtime.input.input_port import InputPort
+from mini_arcade_core.runtime.scene.scene_port import ScenePort
+from mini_arcade_core.runtime.window.window_port import WindowPort
+
+
+@dataclass
+class RuntimeServices:
+    """
+    Container for runtime service ports.
+
+    :ivar window (WindowPort): Window service port.
+    :ivar scenes (ScenePort): Scene management service port.
+    :ivar audio (AudioPort): Audio service port.
+    :ivar files (FilePort): File service port.
+    :ivar capture (CapturePort): Capture service port.
+    :ivar input (InputPort): Input handling service port.
+    """
+
+    window: WindowPort
+    scenes: ScenePort
+    audio: AudioPort
+    files: FilePort
+    capture: CapturePort
+    input: InputPort

mini_arcade_core/runtime/window/window_adapter.py

@@ -0,0 +1,26 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.runtime.window.window_port import WindowPort
+
+
+class WindowAdapter(WindowPort):
+    """
+    Manages multiple game windows (not implemented).
+    """
+
+    def __init__(self, backend):
+        self.backend = backend
+
+    def set_window_size(self, width, height):
+        self.size = (width, height)
+        self.backend.init(width, height)
+
+    def set_title(self, title):
+        self.backend.set_window_title(title)
+
+    def set_clear_color(self, r, g, b):
+        self.backend.set_clear_color(r, g, b)

mini_arcade_core/runtime/window/window_port.py

@@ -0,0 +1,47 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.backend import Backend
+
+
+class WindowPort:
+    """Interface for window-related operations."""
+
+    backend: Backend
+    size: tuple[int, int]
+
+    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_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
+        """

mini_arcade_core/scenes/__init__.py

@@ -1,12 +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 .registry import SceneRegistry
-from .scene import Scene, SceneServices
-
-__all__ = ["Scene", "register_scene", "SceneRegistry", "SceneServices"]

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
+        """