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

mini_arcade_core/managers/inputs.py

@@ -0,0 +1,286 @@
+"""
+Input manager for handling input bindings and commands.
+"""
+
+# TODO: Implement this manager into the new input system
+# Justification: These module will be used later.
+# pylint: disable=no-name-in-module,import-error,used-before-assignment
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable, Dict, Optional
+
+from mini_arcade_core.backend import Event, EventType
+from mini_arcade_core.keymaps import Key
+
+if TYPE_CHECKING:
+    from mini_arcade_core.engine.commands import BaseCommand, BaseSceneCommand
+    from mini_arcade_core.scenes.scene import Scene
+
+logger = logging.getLogger(__name__)
+
+
+Predicate = Callable[["Event"], bool]
+
+
+@dataclass(frozen=True)
+class InputBinding:
+    """
+    Defines an input binding.
+
+    :ivar action (str): The action name.
+    :ivar command (BaseCommand): The command to execute.
+    :ivar predicate (Predicate): Predicate to match events.
+    """
+
+    action: str
+    command: BaseCommand
+    predicate: Predicate  # decides whether this binding matches an event
+
+
+class InputManager:
+    """
+    Manager for handling input bindings and commands.
+    """
+
+    def __init__(self):
+        # event_type -> key -> action -> command
+        self._bindings: Dict[EventType, Dict[Key, Dict[str, BaseCommand]]] = {}
+
+    # Justification: The method needs multiple optional parameters for flexibility.
+    # pylint: disable=too-many-arguments
+    def bind(
+        self,
+        event_type: EventType,
+        action: str,
+        command: BaseCommand,
+        *,
+        key: Optional[Key] = None,
+        button: Optional[int] = None,
+        predicate: Optional[Predicate] = None,
+    ):
+        """
+        Generic binding.
+
+        You can filter by:
+        - key: for KEYDOWN/KEYUP
+        - button: for MOUSEBUTTONDOWN/MOUSEBUTTONUP (if your Event exposes it)
+        - predicate: custom matcher (for anything)
+
+        :param event_type: The type of event to bind to.
+        :type event_type: EventType
+
+        :param action: The action name for the binding.
+        :type action: str
+
+        :param command: The command to execute when the binding is triggered.
+        :type command: BaseCommand
+
+        :param key: Optional key to filter KEYDOWN/KEYUP events.
+        :type key: Key | None
+
+        :param button: Optional button to filter MOUSEBUTTONDOWN/MOUSEBUTTONUP events.
+        :type button: int | None
+
+        :param predicate: Optional custom predicate to match events.
+        :type predicate: Predicate | None
+        """
+        logger.debug(
+            f"Binding {action} to {event_type} with key={key}, button={button}"
+        )
+
+        def default_predicate(ev: Event) -> bool:
+            if key is not None and getattr(ev, "key", None) != key:
+                return False
+            if button is not None and getattr(ev, "button", None) != button:
+                return False
+            return True
+
+        pred = predicate or default_predicate
+        self._bindings.setdefault(event_type, []).append(
+            InputBinding(action=action, command=command, predicate=pred)
+        )
+
+    # pylint: enable=too-many-arguments
+
+    def unbind(self, event_type: EventType, action: str):
+        """
+        Remove bindings by action for an event type.
+
+        :param event_type: The type of event to unbind from.
+        :type event_type: EventType
+
+        :param action: The action name of the binding to remove.
+        :type action: str
+        """
+        lst = self._bindings.get(event_type, [])
+        self._bindings[event_type] = [b for b in lst if b.action != action]
+
+    def clear(self):
+        """Clear all input bindings."""
+        self._bindings.clear()
+
+    def handle_event(self, event: Event, scene: Scene):
+        """
+        Handle an incoming event, executing any matching commands.
+
+        :param event: The event to handle.
+        :type event: Event
+
+        :param scene: The current scene context.
+        :type scene: Scene
+        """
+        et = event.type
+
+        for binding in self._bindings.get(et, []):
+            if binding.predicate(event):
+                to_inject = (
+                    scene.model
+                    if isinstance(binding.command, BaseSceneCommand)
+                    else scene.game
+                )
+                binding.command.execute(to_inject)
+
+    # --- Convenience API ------------------------------------------------------
+
+    def on_quit(self, command: BaseCommand, action: str = "quit"):
+        """
+        Bind a command to the QUIT event.
+
+        :param command: The command to execute on quit.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.QUIT, action=action, command=command)
+
+    def on_key_down(self, key: Key, command: BaseCommand, action: str):
+        """
+        Bind a command to a key down event.
+
+        :param key: The key to bind to.
+        :type key: Key
+
+        :param command: The command to execute on key down.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.KEYDOWN, key=key, action=action, command=command)
+
+    def on_key_up(self, key: Key, command: BaseCommand, action: str):
+        """
+        Bind a command to a key up event.
+
+        :param key: The key to bind to.
+        :type key: Key
+
+        :param command: The command to execute on key up.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.KEYUP, key=key, action=action, command=command)
+
+    def on_mouse_button_down(
+        self, button: int, command: BaseCommand, action: str
+    ):
+        """
+        Bind a command to a mouse button down event.
+
+        :param button: The mouse button to bind to.
+        :type button: int
+
+        :param command: The command to execute on mouse button down.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(
+            EventType.MOUSEBUTTONDOWN,
+            button=button,
+            action=action,
+            command=command,
+        )
+
+    def on_mouse_button_up(
+        self, button: int, command: BaseCommand, action: str
+    ):
+        """
+        Bind a command to a mouse button up event.
+
+        :param button: The mouse button to bind to.
+        :type button: int
+
+        :param command: The command to execute on mouse button up.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(
+            EventType.MOUSEBUTTONUP,
+            button=button,
+            action=action,
+            command=command,
+        )
+
+    def on_mouse_motion(
+        self, command: BaseCommand, action: str = "mouse_motion"
+    ):
+        """
+        Bind a command to mouse motion events.
+
+        :param command: The command to execute on mouse motion.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.MOUSEMOTION, action=action, command=command)
+
+    def on_mouse_wheel(
+        self, command: BaseCommand, action: str = "mouse_wheel"
+    ):
+        """
+        Bind a command to mouse wheel events.
+
+        :param command: The command to execute on mouse wheel.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.MOUSEWHEEL, action=action, command=command)
+
+    def on_window_resized(
+        self, command: BaseCommand, action: str = "window_resized"
+    ):
+        """
+        Bind a command to window resized events.
+
+        :param command: The command to execute on window resize.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.WINDOWRESIZED, action=action, command=command)
+
+    def on_text_input(self, command: BaseCommand, action: str = "text_input"):
+        """
+        Bind a command to text input events.
+
+        :param command: The command to execute on text input.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.TEXTINPUT, action=action, command=command)

mini_arcade_core/runtime/audio/audio_adapter.py

@@ -0,0 +1,13 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.runtime.audio.audio_port import AudioPort
+
+
+class NullAudioAdapter(AudioPort):
+    """A no-op audio adapter."""
+
+    def play(self, sound_id: str): ...

mini_arcade_core/runtime/audio/audio_port.py

@@ -0,0 +1,17 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+
+class AudioPort:
+    """Interface for audio playback operations."""
+
+    def play(self, sound_id: str):
+        """
+        Play the specified sound.
+
+        :param sound_id: Identifier of the sound to play.
+        :type sound_id: str
+        """

mini_arcade_core/runtime/capture/capture_adapter.py

@@ -0,0 +1,143 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from PIL import Image
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.runtime.capture.capture_port import CapturePort
+from mini_arcade_core.utils import logger
+
+
+@dataclass
+class CapturePathBuilder:
+    """
+    Helper to build file paths for captured screenshots.
+
+    :ivar directory (str): Directory to save screenshots in.
+    :ivar prefix (str): Prefix for screenshot filenames.
+    :ivar ext (str): File extension/format for screenshots.
+    """
+
+    directory: str = "screenshots"
+    prefix: str = ""
+    ext: str = "png"  # final output format
+
+    def build(self, label: str) -> Path:
+        """
+        Build a file path for a screenshot with the given label.
+
+        :param label: Label to include in the filename.
+        :type label: str
+
+        :return: Full path for the screenshot file.
+        :rtype: Path
+        """
+        stamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+        safe_label = "".join(
+            c if c.isalnum() or c in ("-", "_") else "_" for c in label
+        )
+        name = f"{self.prefix}{stamp}_{safe_label}.{self.ext}"
+        return Path(self.directory) / name
+
+    def build_sim(self, run_id: str, frame_index: int, label: str) -> Path:
+        """
+        Build a file path for a simulation frame screenshot.
+
+        :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: Label to include in the filename.
+        :type label: str
+
+        :return: Full path for the screenshot file.
+        :rtype: Path
+        """
+        safe_label = "".join(
+            c if c.isalnum() or c in ("-", "_") else "_" for c in label
+        )
+        # deterministic: run_id + frame index
+        name = (
+            f"{self.prefix}{run_id}_f{frame_index:08d}_{safe_label}.{self.ext}"
+        )
+        return Path(self.directory) / run_id / name
+
+
+class CaptureAdapter(CapturePort):
+    """Adapter for capturing frames."""
+
+    def __init__(
+        self,
+        backend: Backend,
+        path_builder: Optional[CapturePathBuilder] = None,
+    ):
+        self.backend = backend
+        self.path_builder = path_builder or CapturePathBuilder()
+
+    def _bmp_to_image(self, bmp_path: str, out_path: str):
+        img = Image.open(bmp_path)
+        img.save(out_path)
+
+    def screenshot(self, label: str | None = None) -> str:
+        label = label or "shot"
+        out_path = self.path_builder.build(label)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # If backend only saves BMP, capture to a temp bmp next to output
+        bmp_path = out_path.with_suffix(".bmp")
+
+        self.backend.capture_frame(str(bmp_path))
+        if not bmp_path.exists():
+            raise RuntimeError("Backend capture_frame did not create BMP file")
+
+        self._bmp_to_image(str(bmp_path), str(out_path))
+        try:
+            bmp_path.unlink(missing_ok=True)
+        # Justification: Various exceptions can occur on file deletion
+        # pylint: disable=broad-exception-caught
+        except Exception:
+            logger.warning(f"Failed to delete temporary BMP file: {bmp_path}")
+        # pylint: enable=broad-exception-caught
+
+        return str(out_path)
+
+    def screenshot_bytes(self) -> bytes:
+        data = self.backend.capture_frame(path=None)
+        if data is None:
+            raise RuntimeError("Backend returned None for screenshot_bytes()")
+        return data
+
+    def screenshot_sim(
+        self, run_id: str, frame_index: int, label: str = "frame"
+    ) -> str:
+        """Screenshot for simulation frames."""
+        out_path = self.path_builder.build_sim(run_id, frame_index, label)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        bmp_path = out_path.with_suffix(".bmp")
+        self.backend.capture_frame(str(bmp_path))
+
+        if not bmp_path.exists():
+            raise RuntimeError("Backend capture_frame did not create BMP file")
+
+        self._bmp_to_image(str(bmp_path), str(out_path))
+
+        try:
+            bmp_path.unlink(missing_ok=True)
+        # Justification: Various exceptions can occur on file deletion
+        # pylint: disable=broad-exception-caught
+        except Exception:
+            logger.warning(f"Failed to delete temporary BMP file: {bmp_path}")
+        # pylint: enable=broad-exception-caught
+
+        return str(out_path)

mini_arcade_core/runtime/capture/capture_port.py

@@ -0,0 +1,32 @@
+"""
+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
+        """

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