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

mini_arcade_core/managers/__init__.py

@@ -1,22 +0,0 @@
-"""
-Managers module for Mini Arcade Core.
-Provides various manager classes for handling game entities and resources.
-"""
-
-from __future__ import annotations
-
-from .cheats import BaseCheatCommand, CheatCode, CheatManager
-from .entities import EntityManager
-from .inputs import InputManager
-from .overlays import OverlayManager
-from .system import SystemManager
-
-__all__ = [
-    "EntityManager",
-    "OverlayManager",
-    "CheatCode",
-    "CheatManager",
-    "BaseCheatCommand",
-    "InputManager",
-    "SystemManager",
-]

mini_arcade_core/managers/cheats.py

@@ -5,80 +5,19 @@ Provides cheat codes and related functionality.
 
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
 from collections import deque
-from dataclasses import dataclass
-from enum import Enum
-from typing import (
-    TYPE_CHECKING,
-    Callable,
-    Deque,
-    Dict,
-    Generic,
-    Optional,
-    Protocol,
-    Sequence,
-    TypeVar,
-)
-
-from mini_arcade_core.backend import Event, EventType
-from mini_arcade_core.scenes.system import BaseSceneSystem
-
-if TYPE_CHECKING:
-    from mini_arcade_core.scenes import Scene
+from dataclasses import dataclass, field
+from typing import Callable, Deque, Dict, Optional, Sequence, TypeVar
+
+from mini_arcade_core.engine.commands import Command, CommandQueue
+from mini_arcade_core.runtime.input_frame import InputFrame
 
 # Justification: We want to keep the type variable name simple here.
 # pylint: disable=invalid-name
 TContext = TypeVar("TContext")
-TScene = TypeVar("TScene", bound="Scene")
 # pylint: enable=invalid-name
 
 
-@dataclass
-class BaseCheatCommand(ABC, Generic[TContext]):
-    """
-    Base class for cheat codes.
-
-    :ivar enabled (bool): Whether the cheat code is enabled.
-    """
-
-    enabled: bool = True
-
-    def __call__(self, context: TContext) -> None:
-        """
-        Execute the cheat code with the given context.
-
-        :param context: Context object for cheat execution.
-        :type context: TContext
-        """
-        if not self.enabled:
-            return False
-        self.execute(context)
-        return True
-
-    @abstractmethod
-    def execute(self, context: TContext):
-        """
-        Execute the cheat code with the given context.
-
-        :param context: Context object for cheat execution.
-        :type context: TContext
-        """
-        raise NotImplementedError("CheatCommand.execute must be overridden.")
-
-
-class CheatAction(Protocol[TContext]):
-    """
-    Protocol for cheat code actions.
-
-    :ivar enabled: Whether the cheat action is enabled.
-    """
-
-    enabled: bool
-
-    def __call__(self, ctx: TContext) -> bool: ...
-
-
 @dataclass(frozen=True)
 class CheatCode:
     """
@@ -93,141 +32,130 @@ class CheatCode:
 
     name: str
     sequence: tuple[str, ...]
-    action: CheatAction[TContext]
+    command_factory: Optional[Callable[[TContext], Command]] = None
     clear_buffer_on_match: bool = False
     enabled: bool = True
 
 
+@dataclass
 class CheatManager:
     """
     Reusable cheat code matcher.
     Keeps a rolling buffer of recent keys and triggers callbacks on sequence match.
     """
 
-    def __init__(
-        self,
-        buffer_size: int = 16,
-        *,
-        enabled: bool = True,
-        normalize: Optional[Callable[[str], str]] = None,
-        key_getter: Optional[Callable[[object], Optional[str]]] = None,
-    ):
-        """
-        :param buffer_size: Maximum size of the input buffer.
-        :type buffer_size: int
-
-        :param enabled: Whether the cheat manager is enabled.
-        :type enabled: bool
-
-        :param normalize: Optional function to normalize key strings.
-        :type normalize: Callable[[str], str] | None
-
-        :param key_getter: Optional function to extract key string from event object.
-        :type key_getter: Callable[[object], Optional[str]] | None
-        """
-        self.enabled = enabled
-        self._buffer: Deque[str] = deque(maxlen=buffer_size)
-        self._codes: Dict[str, CheatCode] = {}
+    buffer_size: int = 16
+    enabled: bool = True
+    _buffer: Deque[str] = field(default_factory=lambda: deque(maxlen=16))
+    _codes: Dict[str, CheatCode[TContext]] = field(default_factory=dict)
 
-        self._normalize = normalize or (lambda s: s.strip().upper())
-        # key_getter: how to extract a key from an engine/backend event object
-        self._key_getter = key_getter or self._default_key_getter
+    def __post_init__(self):
+        # ensure deque maxlen matches buffer_size
+        self._buffer = deque(maxlen=self.buffer_size)
 
-    # Justification: We want to keep the number of arguments manageable here.
+    # TODO: ISolve too-many-arguments warning later
+    # Justification: The method needs multiple optional parameters for flexibility.
     # pylint: disable=too-many-arguments
-    def register_command(
+    def register(
         self,
         name: str,
-        sequence: Sequence[str],
-        command: BaseCheatCommand[TContext],
         *,
+        sequence: Sequence[str],
+        command_factory: Callable[[TContext], Command],
         clear_buffer_on_match: bool = False,
         enabled: bool = True,
     ):
         """
-        Register a new cheat code that triggers a BaseCheatCommand.
+        Register a new cheat code.
 
-        :param name: Unique name for the cheat code.
+        :param name: Unique name of the cheat code.
         :type name: str
 
         :param sequence: Sequence of key strings that trigger the cheat.
         :type sequence: Sequence[str]
 
-        :param command: BaseCheatCommand to execute when the cheat is activated.
-        :type command: BaseCheatCommand[TContext]
+        :param command_factory: Factory function to create the Command when the cheat is activated.
+        :type command_factory: Callable[[TContext], Command]
 
         :param clear_buffer_on_match: Whether to clear the input buffer after a match.
         :type clear_buffer_on_match: bool
 
         :param enabled: Whether the cheat code is enabled.
         :type enabled: bool
+
+        :raises ValueError: If name is empty or sequence is empty.
         """
         if not name:
-            raise ValueError("Cheat code name must be non-empty.")
+            raise ValueError("Cheat name must be non-empty.")
         if not sequence:
-            raise ValueError(
-                f"Cheat code '{name}' sequence must be non-empty."
-            )
+            raise ValueError(f"Cheat '{name}' sequence must be non-empty.")
 
-        norm_seq = tuple(self._normalize(k) for k in sequence)
+        norm_seq = tuple(self._norm(s) for s in sequence)
         self._codes[name] = CheatCode(
             name=name,
             sequence=norm_seq,
-            action=command,
+            command_factory=command_factory,
             clear_buffer_on_match=clear_buffer_on_match,
             enabled=enabled,
         )
 
     # pylint: enable=too-many-arguments
 
-    def unregister_code(self, name: str):
-        """
-        Unregister a cheat code by name.
-
-        :param name: Name of the cheat code to unregister.
-        :type name: str
+    def process_frame(
+        self,
+        input_frame: InputFrame,
+        *,
+        context: TContext,
+        queue: CommandQueue,
+    ) -> list[str]:
         """
-        self._codes.pop(name, None)
+        Process an InputFrame for cheat code matches.
 
-    def clear_buffer(self):
-        """Clear the input buffer."""
-        self._buffer.clear()
+        :param input_frame: InputFrame containing current inputs.
+        :type input_frame: InputFrame
 
-    def process_event(self, event: object, context: TContext) -> list[str]:
-        """
-        Call from Scene when a key is pressed.
-        Returns list of cheat names matched (often 0 or 1).
+        :param context: Context to pass to command factories.
+        :type context: TContext
 
-        :param event: The event object from the backend/engine.
-        :type event: object
+        :param queue: CommandQueue to push matched commands into.
+        :type queue: CommandQueue
 
-        :param context: Context object passed to cheat callbacks.
-        :type context: TContext
+        :return: List of names of matched cheat codes.
+        :rtype: list[str]
         """
         if not self.enabled:
             return []
-        key = self._key_getter(event)
-        if not key:
-            return []
-        return self.process_key(key, context)
 
-    def process_key(self, key: str, context: TContext) -> list[str]:
+        matched: list[str] = []
+        for key in input_frame.keys_pressed:
+            key_name = getattr(key, "name", str(key))
+            matched.extend(
+                self.process_key(key_name, context=context, queue=queue)
+            )
+        return matched
+
+    def process_key(
+        self, key: str, *, context: TContext, queue: CommandQueue
+    ) -> list[str]:
         """
-        Pure method for tests: feed a key string directly.
+        Process a single key input.
 
         :param key: The key string to process.
         :type key: str
 
-        :param context: Context object passed to cheat callbacks.
+        :param context: Context to pass to command factories.
         :type context: TContext
 
-        :return: List of cheat names matched.
+        :param queue: CommandQueue to push matched commands into.
+        :type queue: CommandQueue
+
+        :return: List of names of matched cheat codes.
         :rtype: list[str]
         """
         if not self.enabled:
             return []
 
-        k = self._normalize(key)
+        k = self._norm(key)
         if not k:
             return []
 
@@ -235,121 +163,24 @@ class CheatManager:
         buf = tuple(self._buffer)
 
         matched: list[str] = []
-        # Check if buffer ends with any cheat sequence
         for code in self._codes.values():
             if not code.enabled:
                 continue
+
             seq = code.sequence
             if len(seq) > len(buf):
                 continue
+
             if buf[-len(seq) :] == seq:
-                code.action(context)
+                queue.push(code.command_factory(context))
                 matched.append(code.name)
+
                 if code.clear_buffer_on_match:
-                    self.clear_buffer()
-                    break  # buffer changed; stop early
+                    self._buffer.clear()
+                    break
 
         return matched
 
     @staticmethod
-    def _default_key_getter(event: object) -> Optional[str]:
-        """
-        Best-effort extraction:
-        - event.key
-        - event.key_code
-        - event.code
-        - event.scancode
-        - dict-like {"key": "..."}
-        Adjust/override with key_getter in your engine if needed.
-
-        :param event: The event object.
-        :type event: object
-
-        :return: Extracted key string, or None if not found.
-        :rtype: Optional[str]
-        """
-        if event is None:
-            return None
-
-        # dict-like
-        if isinstance(event, dict):
-            v = (
-                event.get("key")
-                or event.get("key_code")
-                or event.get("code")
-                or event.get("scancode")
-            )
-            if isinstance(v, Enum):
-                return v.name
-            return str(v) if v is not None else None
-
-        # object-like
-        for attr in ("key", "key_code", "code", "scancode"):
-            if hasattr(event, attr):
-                v = getattr(event, attr)
-                if v is None:
-                    continue
-                if isinstance(v, Enum):
-                    return v.name  # <-- THIS is the important bit
-                return str(v)
-
-        return None
-
-
-class CheatSystem(BaseSceneSystem, Generic[TScene]):
-    """
-    Scene system for handling cheat codes.
-
-    :ivar priority (int): Priority of the system (lower runs first).
-    :ivar enabled (bool): Whether the system is enabled.
-    """
-
-    priority = 10
-
-    def __init__(self, scene: TScene, buffer_size=16):
-        """
-        :param buffer_size: Size of the cheat input buffer.
-        :type buffer_size: int
-        """
-        super().__init__(scene)
-        self.cheats = CheatManager(buffer_size=buffer_size)
-
-    def register(self, name: str, seq: list[str], cmd: Callable, **kwargs):
-        """
-        Helper to register a cheat command.
-
-        :param name: Unique name for the cheat code.
-        :type name: str
-
-        :param seq: Sequence of key strings that trigger the cheat.
-        :type seq: list[str]
-
-        :param cmd: Callable to execute when the cheat is activated.
-        :type cmd: Callable
-
-        :param kwargs: Additional keyword arguments for cheat registration.
-        """
-        self.cheats.register_command(name, seq, cmd, **kwargs)
-
-    def on_enter(self):
-        """
-        Called when the scene is entered.
-        """
-        # register codes here (or via a builder)
-
-    def handle_event(self, event: Event) -> bool:
-        """
-        Handle an event.
-
-        :param event: The event to handle.
-        :type event: Event
-
-        :param scene: The scene receiving the event.
-        :type scene: TScene
-
-        :return: True if the event was handled, False otherwise.
-        :rtype: bool
-        """
-        if event.type == EventType.KEYDOWN:
-            self.cheats.process_event(event, self.scene)
-        return False  # usually don't consume
+    def _norm(s: str) -> str:
+        return s.strip().upper()

mini_arcade_core/managers/inputs.py

@@ -2,6 +2,10 @@
 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
@@ -9,10 +13,10 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Callable, Dict, Optional
 
 from mini_arcade_core.backend import Event, EventType
-from mini_arcade_core.commands import BaseCommand, BaseSceneCommand
 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__)
@@ -139,8 +143,6 @@ class InputManager:
                 )
                 binding.command.execute(to_inject)
 
-    # --- Convenience API ------------------------------------------------------
-
     def on_quit(self, command: BaseCommand, action: str = "quit"):
         """
         Bind a command to the QUIT event.

mini_arcade_core/runtime/audio/audio_adapter.py

@@ -0,0 +1,20 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.runtime.audio.audio_port import AudioPort
+
+
+class SDLAudioAdapter(AudioPort):
+    """A no-op audio adapter."""
+
+    def __init__(self, backend):
+        self.backend = backend
+
+    def load_sound(self, sound_id: str, file_path: str):
+        self.backend.load_sound(sound_id, file_path)
+
+    def play(self, sound_id: str, loops: int = 0):
+        self.backend.play_sound(sound_id, loops)

mini_arcade_core/runtime/audio/audio_port.py

@@ -0,0 +1,36 @@
+"""
+Service interfaces for runtime components.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.backend.backend import Backend
+
+
+class AudioPort:
+    """Interface for audio playback operations."""
+
+    backend: Backend
+
+    def load_sound(self, sound_id: str, file_path: str):
+        """
+        Load a sound from a file and associate it with an identifier.
+
+        :param sound_id: Identifier to associate with the sound.
+        :type sound_id: str
+
+        :param file_path: Path to the sound file.
+        :type file_path: str
+        """
+
+    def play(self, sound_id: str, loops: int = 0):
+        """
+        Play the specified sound.
+
+        :param sound_id: Identifier of the sound to play.
+        :type sound_id: str
+
+        :param loops: Number of times to loop the sound.
+            0 = play once, -1 = infinite loop, 1 = play twice, etc.
+        :type loops: int
+        """

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)