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

mini_arcade_core/runtime/capture/capture_port.py

@@ -0,0 +1,51 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.backend import Backend
+
+
+class CapturePort:
+    """Interface for frame capture operations."""
+
+    backend: Backend
+
+    def screenshot(self, label: str | None = None) -> str:
+        """
+        Capture the current frame.
+
+        :param label: Optional label for the screenshot file.
+        :type label: str | None
+
+        :return: Screenshot file path.
+        :rtype: str
+        """
+
+    def screenshot_bytes(self) -> bytes | None:
+        """
+        Capture the current frame and return it as bytes.
+
+        :return: Screenshot data as bytes.
+        :rtype: bytes | None
+        """
+
+    def screenshot_sim(
+        self, run_id: str, frame_index: int, label: str = "frame"
+    ) -> str:
+        """
+        Capture the current frame in a simulation context.
+
+        :param run_id: Unique identifier for the simulation run.
+        :type run_id: str
+
+        :param frame_index: Index of the frame in the simulation.
+        :type frame_index: int
+
+        :param label: Optional label for the screenshot file.
+        :type label: str
+
+        :return: Screenshot file path.
+        :rtype: str
+        """

mini_arcade_core/runtime/context.py

@@ -0,0 +1,53 @@
+""" 
+Runtime context module.
+Defines the RuntimeContext dataclass for game runtime context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mini_arcade_core.engine.commands import CommandQueue
+    from mini_arcade_core.engine.game import Game, GameConfig, GameSettings
+    from mini_arcade_core.managers.cheats import CheatManager
+    from mini_arcade_core.runtime.services import RuntimeServices
+
+
+@dataclass(frozen=True)
+class RuntimeContext:
+    """
+    Context for the game runtime.
+
+    :ivar services (RuntimeServices): Runtime services.
+    :ivar config (GameConfig): Game configuration.
+    :ivar settings (GameSettings): Game settings.
+    :ivar command_queue (CommandQueue | None): Optional command queue.
+    :ivar cheats (CheatManager | None): Optional cheat manager.
+    """
+
+    services: RuntimeServices
+    config: GameConfig
+    settings: GameSettings
+    command_queue: CommandQueue | None = None
+    cheats: CheatManager | None = None
+
+    @staticmethod
+    def from_game(game_entity: Game) -> "RuntimeContext":
+        """
+        Create a RuntimeContext from a Game entity.
+
+        :param game_entity: Game entity to extract context from.
+        :type game_entity: Game
+
+        :return: RuntimeContext instance.
+        :rtype: RuntimeContext
+        """
+        return RuntimeContext(
+            services=game_entity.services,
+            config=game_entity.config,
+            settings=game_entity.settings,
+            command_queue=game_entity.command_queue,
+            cheats=game_entity.cheat_manager,
+        )

mini_arcade_core/runtime/file/file_adapter.py

@@ -0,0 +1,20 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.runtime.file.file_port import FilePort
+
+
+class LocalFilesAdapter(FilePort):
+    """Adapter for local file operations."""
+
+    def write_text(self, path: str, text: str):
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(text)
+
+    def write_bytes(self, path: str, data: bytes):
+        with open(path, "wb") as f:
+            f.write(data)
+            f.write(data)

mini_arcade_core/runtime/file/file_port.py

@@ -0,0 +1,31 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+
+class FilePort:
+    """Interface for file operations."""
+
+    def write_bytes(self, path: str, data: bytes):
+        """
+        Write bytes to a file.
+
+        :param path: Path to the file.
+        :type path: str
+
+        :param data: Data to write.
+        :type data: bytes
+        """
+
+    def write_text(self, path: str, text: str):
+        """
+        Write text to a file.
+
+        :param path: Path to the file.
+        :type path: str
+
+        :param text: Text to write.
+        :type text: str
+        """

mini_arcade_core/runtime/input/input_adapter.py

@@ -0,0 +1,49 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mini_arcade_core.backend.events import Event, EventType
+from mini_arcade_core.backend.keys import Key
+from mini_arcade_core.runtime.input.input_port import InputPort
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+
+@dataclass
+class InputAdapter(InputPort):
+    """Adapter for processing input events."""
+
+    _down: set[Key] = field(default_factory=set)
+
+    def build(
+        self, events: list[Event], frame_index: int, dt: float
+    ) -> InputFrame:
+        pressed: set[Key] = set()
+        released: set[Key] = set()
+        quit_req = False
+
+        for ev in events:
+            if ev.type == EventType.QUIT:
+                quit_req = True
+
+            elif ev.type == EventType.KEYDOWN and ev.key is not None:
+                if ev.key not in self._down:
+                    pressed.add(ev.key)
+                self._down.add(ev.key)
+
+            elif ev.type == EventType.KEYUP and ev.key is not None:
+                if ev.key in self._down:
+                    self._down.remove(ev.key)
+                released.add(ev.key)
+
+        return InputFrame(
+            frame_index=frame_index,
+            dt=dt,
+            keys_down=frozenset(self._down),
+            keys_pressed=frozenset(pressed),
+            keys_released=frozenset(released),
+            quit=quit_req,
+        )

mini_arcade_core/runtime/input/input_port.py

@@ -0,0 +1,31 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.backend.events import Event
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+
+class InputPort:
+    """Interface for input handling operations."""
+
+    def build(
+        self, events: list[Event], frame_index: int, dt: float
+    ) -> InputFrame:
+        """
+        Build an InputFrame from the given events.
+
+        :param events: List of input events.
+        :type events: list[Event]
+
+        :param frame_index: Current frame index.
+        :type frame_index: int
+
+        :param dt: Delta time since last frame.
+        :type dt: float
+
+        :return: Constructed InputFrame.
+        :rtype: InputFrame
+        """

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,90 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from venv import logger
+
+from mini_arcade_core.engine.render.viewport import (
+    Viewport,
+    ViewportMode,
+    ViewportState,
+)
+from mini_arcade_core.runtime.window.window_port import WindowPort
+
+
+class WindowAdapter(WindowPort):
+    """
+    Manages multiple game windows (not implemented).
+    """
+
+    def __init__(self, backend, window_settings):
+        self.backend = backend
+        self.window_settings = window_settings
+
+        self._initialized = False
+
+        # Default: virtual resolution == initial window resolution.
+        # You can override via set_virtual_resolution().
+        self._viewport = Viewport(
+            window_settings.width,
+            window_settings.height,
+            mode=ViewportMode.FIT,
+        )
+
+        # Cached current window size
+        self.size = (window_settings.width, window_settings.height)
+
+    def set_window_size(self, width, height):
+        width = int(width)
+        height = int(height)
+        self.size = (width, height)
+
+        self.window_settings.width = width
+        self.window_settings.height = height
+
+        if not self._initialized:
+            self.backend.init(self.window_settings)
+            self._initialized = True
+        else:
+            self.backend.resize_window(width, height)
+
+        self._viewport.resize(width, height)
+
+    def set_virtual_resolution(self, width: int, height: int):
+        self._viewport.set_virtual_resolution(int(width), int(height))
+        # re-apply using current window size
+        w, h = self.size
+        self._viewport.resize(w, h)
+
+    def set_viewport_mode(self, mode: ViewportMode):
+        self._viewport.set_mode(mode)
+
+    def get_viewport(self) -> ViewportState:
+        return self._viewport.state
+
+    def screen_to_virtual(self, x: float, y: float) -> tuple[float, float]:
+        return self._viewport.screen_to_virtual(x, y)
+
+    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)
+
+    def on_window_resized(self, width: int, height: int):
+        logger.debug(f"Window resized event: {width}x{height}")
+        width = int(width)
+        height = int(height)
+
+        # Update cached size, but DO NOT call backend.resize_window here.
+        self.size = (width, height)
+        self.window_settings.width = width
+        self.window_settings.height = height
+
+        self._viewport.resize(width, height)
+
+    def get_virtual_size(self) -> tuple[int, int]:
+        s = self.get_viewport()
+        return (s.virtual_w, s.virtual_h)