mini-arcade-core 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

mini_arcade_core/engine/commands.py

@@ -5,9 +5,11 @@ Command protocol for executing commands with a given context.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import TYPE_CHECKING, List, Optional, Protocol, TypeVar
 
 from mini_arcade_core.engine.scenes.models import ScenePolicy
+from mini_arcade_core.runtime.capture.replay_format import ReplayHeader
 
 if TYPE_CHECKING:
     from mini_arcade_core.runtime.services import RuntimeServices
@@ -121,7 +123,7 @@ class ScreenshotCommand(Command):
         self,
         context: CommandContext,
     ):
-        context.services.capture.screenshot(label=self.label, mode="manual")
+        context.services.capture.screenshot(label=self.label)
 
 
 @dataclass(frozen=True)
@@ -216,3 +218,69 @@ class ToggleEffectCommand(Command):
         if stack is None:
             return
         stack.toggle(self.effect_id)
+
+
+@dataclass(frozen=True)
+class StartReplayRecordCommand(Command):
+    """
+    Start recording a replay to the specified file.
+
+    :ivar filename (str): The filename to save the replay to.
+    :ivar game_id (str): Identifier of the game.
+    :ivar initial_scene (str): The initial scene of the replay.
+    :ivar seed (int): The random seed used in the replay.
+    :ivar fps (int): Frames per second for the replay.
+    """
+
+    filename: str
+    game_id: str = "mini-arcade"
+    initial_scene: str = "unknown"
+    seed: int = 0
+    fps: int = 60
+
+    def execute(self, context: CommandContext):
+        header = ReplayHeader(
+            game_id=self.game_id,
+            initial_scene=self.initial_scene,
+            seed=self.seed,
+            fps=self.fps,
+        )
+        context.services.capture.start_replay_record(
+            filename=self.filename,
+            header=header,
+        )
+
+
+@dataclass(frozen=True)
+class StopReplayRecordCommand(Command):
+    """Stop recording the current replay."""
+
+    def execute(self, context: CommandContext):
+        context.services.capture.stop_replay_record()
+
+
+@dataclass(frozen=True)
+class StartReplayPlayCommand(Command):
+    """
+    Start playing back a replay from the specified file.
+
+    :ivar path (str): The path to the replay file.
+    :ivar change_scene (bool): Whether to change to the replay's initial scene.
+    """
+
+    path: str
+    change_scene: bool = True
+
+    def execute(self, context: CommandContext):
+        header = context.services.capture.start_replay_play(Path(self.path))
+        if self.change_scene:
+            # NOTE: **IMPORTANT** align game state with the replay header
+            context.managers.scenes.change(header.initial_scene)
+
+
+@dataclass(frozen=True)
+class StopReplayPlayCommand(Command):
+    """Stop playing back the current replay."""
+
+    def execute(self, context: CommandContext):
+        context.services.capture.stop_replay_play()

mini_arcade_core/engine/game.py

@@ -24,7 +24,7 @@ from mini_arcade_core.engine.render.pipeline import RenderPipeline
 from mini_arcade_core.engine.render.render_service import RenderService
 from mini_arcade_core.engine.scenes.scene_manager import SceneAdapter
 from mini_arcade_core.runtime.audio.audio_adapter import SDLAudioAdapter
-from mini_arcade_core.runtime.capture.capture_adapter import CaptureAdapter
+from mini_arcade_core.runtime.capture.capture_service import CaptureService
 from mini_arcade_core.runtime.file.file_adapter import LocalFilesAdapter
 from mini_arcade_core.runtime.input.input_adapter import InputAdapter
 from mini_arcade_core.runtime.scene.scene_query_adapter import (
@@ -70,10 +70,12 @@ class Game:
             ),
         )
         self.services = RuntimeServices(
-            window=WindowAdapter(self.backend),  # Turn into a manager?
+            window=WindowAdapter(self.backend),
             audio=SDLAudioAdapter(self.backend),
             files=LocalFilesAdapter(),
-            capture=CaptureAdapter(self.backend),
+            capture=CaptureService(
+                self.backend
+            ),  # NOTE: Should actually be a manager?
             input=InputAdapter(),
             render=RenderService(),
             scenes=SceneQueryAdapter(self.managers.scenes),

mini_arcade_core/engine/loop/runner.py

@@ -139,14 +139,37 @@ class EngineRunner:
     def _build_input(
         self, events, *, frame: FrameState, timer: FrameTimer | None
     ):
-        # Build InputFrame from events.
-        input_frame = self.services.input.build(
-            events, frame.frame_index, frame.dt
-        )
+        cap = self.services.capture
+
+        if cap.replay_playing:
+            input_frame = cap.next_replay_input()
+
+            # optional but recommended: keep runner's frame_index/dt authoritative
+            input_frame = InputFrame(
+                frame_index=frame.frame_index,
+                dt=frame.dt,
+                keys_down=input_frame.keys_down,
+                keys_pressed=input_frame.keys_pressed,
+                keys_released=input_frame.keys_released,
+                buttons=input_frame.buttons,
+                axes=input_frame.axes,
+                mouse_pos=input_frame.mouse_pos,
+                mouse_delta=input_frame.mouse_delta,
+                text_input=input_frame.text_input,
+                quit=input_frame.quit,
+            )
+        else:
+            input_frame = self.services.input.build(
+                events, frame.frame_index, frame.dt
+            )
+
         if timer:
             timer.mark("input_built")
+
         if input_frame.quit:
             self.managers.command_queue.push(QuitCommand())
+
+        cap.record_input(input_frame)
         return input_frame
 
     def _should_quit(self, input_frame: InputFrame) -> bool:

mini_arcade_core/runtime/capture/capture_service.py

@@ -0,0 +1,96 @@
+"""
+Capture service managing screenshots and replays.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.runtime.capture.capture_service_protocol import (
+    CaptureServicePort,
+)
+from mini_arcade_core.runtime.capture.capture_settings import CaptureSettings
+from mini_arcade_core.runtime.capture.replay import (
+    ReplayPlayer,
+    ReplayRecorder,
+    ReplayRecorderConfig,
+)
+from mini_arcade_core.runtime.capture.replay_format import ReplayHeader
+from mini_arcade_core.runtime.capture.screenshot_capturer import (
+    ScreenshotCapturer,
+)
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+
+class CaptureService(CaptureServicePort):
+    """
+    Owns:
+        - screenshots (delegated)
+        - replay recording (InputFrame stream)
+        - replay playback (feeds InputFrames)
+        - (later) video recording
+    """
+
+    # pylint: disable=too-many-arguments
+    def __init__(
+        self,
+        backend: Backend,
+        *,
+        screenshots: Optional[ScreenshotCapturer] = None,
+        replay_recorder: Optional[ReplayRecorder] = None,
+        replay_player: Optional[ReplayPlayer] = None,
+        settings: Optional[CaptureSettings] = None,
+    ):
+        self.backend = backend
+        self.settings = settings or CaptureSettings()
+
+        self.screenshots = screenshots or ScreenshotCapturer(backend)
+        self.replay_recorder = replay_recorder or ReplayRecorder()
+        self.replay_player = replay_player or ReplayPlayer()
+
+    # -------- screenshots --------
+    def screenshot(self, label: str | None = None) -> str:
+        return self.screenshots.screenshot(label)
+
+    def screenshot_sim(
+        self, run_id: str, frame_index: int, label: str = "frame"
+    ) -> str:
+        return self.screenshots.screenshot_sim(run_id, frame_index, label)
+
+    # -------- replays --------
+    @property
+    def replay_playing(self) -> bool:
+        return self.replay_player.active
+
+    @property
+    def replay_recording(self) -> bool:
+        return self.replay_recorder.active
+
+    def start_replay_record(
+        self,
+        *,
+        filename: str,
+        header: ReplayHeader,
+    ) -> None:
+        path = Path(self.settings.replays_dir) / filename
+        self.replay_recorder.start(
+            ReplayRecorderConfig(path=path, header=header)
+        )
+
+    def stop_replay_record(self) -> None:
+        self.replay_recorder.stop()
+
+    def record_input(self, frame: InputFrame) -> None:
+        self.replay_recorder.record(frame)
+
+    def start_replay_play(self, filename: str) -> ReplayHeader:
+        path = Path(self.settings.replays_dir) / filename
+        return self.replay_player.start(path)
+
+    def stop_replay_play(self) -> None:
+        self.replay_player.stop()
+
+    def next_replay_input(self) -> InputFrame:
+        return self.replay_player.next()

mini_arcade_core/runtime/capture/capture_service_protocol.py

@@ -0,0 +1,125 @@
+"""
+Capture service protocol
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.runtime.capture.capture_settings import CaptureSettings
+from mini_arcade_core.runtime.capture.replay import (
+    ReplayPlayer,
+    ReplayRecorder,
+)
+from mini_arcade_core.runtime.capture.replay_format import ReplayHeader
+from mini_arcade_core.runtime.capture.screenshot_capturer import (
+    ScreenshotCapturer,
+)
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+
+class CaptureServicePort:
+    """
+    Interface for the Capture Service.
+    """
+
+    backend: Backend
+    settings: CaptureSettings
+    screenshots: ScreenshotCapturer
+    replay_recorder: ReplayRecorder
+    replay_player: ReplayPlayer
+
+    # -------- screenshots --------
+    def screenshot(self, label: str | None = None) -> str:
+        """
+        Take a screenshot with an optional label.
+
+        :param label: Optional label for the screenshot.
+        :type label: str | None
+        :return: Path to the saved screenshot.
+        :rtype: str
+        """
+
+    def screenshot_sim(
+        self, run_id: str, frame_index: int, label: str = "frame"
+    ) -> str:
+        """
+        Take a screenshot for a simulation frame.
+
+        :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 for the screenshot.
+        :type label: str
+
+        :return: Path to the saved screenshot.
+        :rtype: str
+        """
+
+    # -------- replays --------
+    @property
+    def replay_playing(self) -> bool:
+        """
+        Check if a replay is currently being played back.
+
+        :return: True if a replay is active, False otherwise.
+        :rtype: bool
+        """
+
+    @property
+    def replay_recording(self) -> bool:
+        """
+        Check if a replay is currently being recorded.
+
+        :return: True if recording is active, False otherwise.
+        :rtype: bool
+        """
+
+    def start_replay_record(
+        self,
+        *,
+        filename: str,
+        header: ReplayHeader,
+    ) -> None:
+        """
+        Start recording a replay.
+
+        :param filename: The filename to save the replay to.
+        :type filename: str
+        :param header: The header information for the replay.
+        :type header: ReplayHeader
+        """
+
+    def stop_replay_record(self) -> None:
+        """Stop recording the current replay."""
+
+    def record_input(self, frame: InputFrame) -> None:
+        """
+        Record an input frame to the replay.
+
+        :param frame: The input frame to record.
+        :type frame: InputFrame
+        """
+
+    def start_replay_play(self, filename: str) -> ReplayHeader:
+        """
+        Start playing back a replay.
+
+        :param filename: The filename of the replay to play.
+        :type filename: str
+        :return: The header information of the replay.
+        :rtype: ReplayHeader
+        """
+
+    def stop_replay_play(self) -> None:
+        """Stop playing back the current replay."""
+
+    def next_replay_input(self) -> InputFrame:
+        """
+        Get the next input frame from the replay.
+
+        :return: The next input frame.
+        :rtype: InputFrame
+        """

mini_arcade_core/runtime/capture/capture_settings.py

@@ -0,0 +1,22 @@
+"""
+Capture settings dataclass
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CaptureSettings:
+    """
+    Settings for the Capture Service.
+
+    :ivar screenshots_dir: Directory to save screenshots.
+    :ivar screenshots_ext: File extension/format for screenshots.
+    :ivar replays_dir: Directory to save replays.
+    """
+
+    screenshots_dir: str = "screenshots"
+    screenshots_ext: str = "png"
+    replays_dir: str = "replays"

mini_arcade_core/runtime/capture/capture_worker.py

@@ -0,0 +1,174 @@
+"""
+Capture worker thread for saving screenshots.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from queue import Empty, Queue
+from threading import Event, Thread
+from typing import Callable, Optional
+
+from PIL import Image
+
+from mini_arcade_core.utils import logger
+
+
+@dataclass(frozen=True)
+class CaptureJob:
+    """
+    Job representing a screenshot to be saved.
+
+    :ivar job_id (str): Unique identifier for the capture job.
+    :ivar out_path (Path): Destination path for the saved screenshot.
+    :ivar bmp_path (Path): Temporary path of the bitmap image to be saved.
+    """
+
+    job_id: str
+    out_path: Path
+    bmp_path: Path  # <-- file-based now
+
+
+@dataclass(frozen=True)
+class CaptureResult:
+    """
+    Result of a completed capture job.
+
+    :ivar job_id (str): Unique identifier for the capture job.
+    :ivar out_path (Path): Destination path where the screenshot was saved.
+    :ivar ok (bool): Whether the capture was successful.
+    :ivar error (Optional[str]): Error message if the capture failed.
+    """
+
+    job_id: str
+    out_path: Path
+    ok: bool
+    error: str | None = None
+
+
+@dataclass
+class WorkerConfig:
+    """
+    Configuration options for the CaptureWorker.
+
+    :ivar queue_size (int): Maximum number of jobs to queue.
+    :ivar on_done (Optional[Callable[[CaptureResult], None]]):
+        Optional callback invoked when a job is done.
+    :ivar name (str): Name of the worker thread.
+    :ivar daemon (bool): Whether the thread is a daemon thread.
+    :ivar delete_temp (bool): Whether to delete temporary bitmap files after saving.
+    """
+
+    queue_size: int = 64
+    on_done: Optional[Callable[[CaptureResult], None]] = None
+    name: str = "capture-worker"
+    daemon: bool = True
+    delete_temp: bool = True
+
+
+class CaptureWorker:
+    """Capture worker thread for saving screenshots asynchronously."""
+
+    def __init__(
+        self,
+        worker_config: WorkerConfig | None = None,
+    ):
+        """
+        :param queue_size: Maximum number of jobs to queue.
+        :type queue_size: int
+        :param on_done: Optional callback invoked when a job is done.
+        :type on_done: Optional[Callable[[CaptureResult], None]]
+        :param name: Name of the worker thread.
+        :type name: str
+        :param daemon: Whether the thread is a daemon thread.
+        :type daemon: bool
+        :param delete_temp: Whether to delete temporary bitmap files after saving.
+        :type delete_temp: bool
+        """
+        if worker_config is None:
+            worker_config = WorkerConfig()
+        self._q: Queue[CaptureJob] = Queue(maxsize=worker_config.queue_size)
+        self._stop = Event()
+        self._thread = Thread(
+            target=self._run,
+            name=worker_config.name,
+            daemon=worker_config.daemon,
+        )
+        self._on_done = worker_config.on_done
+        self._delete_temp = worker_config.delete_temp
+
+    def start(self):
+        """Start the capture worker thread."""
+        if self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread.start()
+
+    def stop(self):
+        """Stop the capture worker thread."""
+        self._stop.set()
+        if self._thread.is_alive():
+            self._thread.join(timeout=2.0)
+
+    def enqueue(self, job: CaptureJob) -> bool:
+        """
+        Enqueue a capture job.
+
+        :param job: CaptureJob to enqueue.
+        :type job: CaptureJob
+        :return: True if the job was enqueued successfully, False otherwise.
+        :rtype: bool
+        """
+        if self._stop.is_set():
+            return False
+        try:
+            self._q.put_nowait(job)
+            return True
+        # Justification: Queue.put_nowait can raise a broad exception
+        # pylint: disable=broad-exception-caught
+        except Exception:
+            return False
+        # pylint: enable=broad-exception-caught
+
+    def _run(self):
+        while not self._stop.is_set():
+            try:
+                job = self._q.get(timeout=0.1)
+            except Empty:
+                continue
+
+            try:
+                job.out_path.parent.mkdir(parents=True, exist_ok=True)
+
+                img = Image.open(str(job.bmp_path))
+                img.save(str(job.out_path))
+
+                if self._delete_temp:
+                    try:
+                        job.bmp_path.unlink(missing_ok=True)
+                    except Exception:  # pylint: disable=broad-exception-caught
+                        logger.warning(
+                            f"Failed to delete temp bmp: {job.bmp_path}"
+                        )
+
+                res = CaptureResult(
+                    job_id=job.job_id, out_path=job.out_path, ok=True
+                )
+
+            except Exception as exc:  # pylint: disable=broad-exception-caught
+                logger.exception("CaptureWorker failed to save screenshot")
+                res = CaptureResult(
+                    job_id=job.job_id,
+                    out_path=job.out_path,
+                    ok=False,
+                    error=str(exc),
+                )
+
+            if self._on_done:
+                try:
+                    self._on_done(res)
+                except Exception:  # pylint: disable=broad-exception-caught
+                    logger.warning("CaptureWorker on_done callback failed")
+
+            self._q.task_done()

mini_arcade_core/runtime/capture/replay.py

@@ -0,0 +1,132 @@
+"""
+Replay recording and playback functionality.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, Optional
+
+from mini_arcade_core.runtime.capture.replay_format import (
+    ReplayHeader,
+    ReplayReader,
+    ReplayWriter,
+)
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+
+@dataclass
+class ReplayRecorderConfig:
+    """
+    Configuration for replay recording.
+
+    :ivar path (Path): Path to save the replay file.
+    :ivar header (ReplayHeader): Header information for the replay.
+    """
+
+    path: Path
+    header: ReplayHeader
+
+
+class ReplayRecorder:
+    """Recorder for game replays."""
+
+    def __init__(self):
+        self._writer: Optional[ReplayWriter] = None
+
+    @property
+    def active(self) -> bool:
+        """
+        Check if the recorder is currently active.
+
+        :return: True if recording is active, False otherwise.
+        :rtype: bool
+        """
+        return self._writer is not None
+
+    def start(self, cfg: ReplayRecorderConfig) -> None:
+        """
+        Start recording a replay.
+
+        :param cfg: Configuration for the replay recorder.
+        :type cfg: ReplayRecorderConfig
+        """
+        if self._writer:
+            raise RuntimeError("ReplayRecorder already active")
+        self._writer = ReplayWriter(cfg.path, cfg.header)
+        self._writer.open()
+
+    def record(self, frame: InputFrame) -> None:
+        """
+        Record an input frame to the replay.
+
+        :param frame: The input frame to record.
+        :type frame: InputFrame
+        """
+        if self._writer:
+            self._writer.write_frame(frame)
+
+    def stop(self) -> None:
+        """Stop recording the current replay."""
+        if self._writer:
+            self._writer.close()
+            self._writer = None
+
+
+class ReplayPlayer:
+    """Player for game replays."""
+
+    def __init__(self):
+        self._reader: Optional[ReplayReader] = None
+        self._it: Optional[Iterator[InputFrame]] = None
+        self.header: Optional[ReplayHeader] = None
+
+    @property
+    def active(self) -> bool:
+        """
+        Check if the player is currently active.
+
+        :return: True if a replay is being played, False otherwise.
+        :rtype: bool
+        """
+        return self._it is not None
+
+    def start(self, path: Path) -> ReplayHeader:
+        """
+        Start playing back a replay.
+
+        :param path: Path to the replay file.
+        :type path: Path
+        :return: The header information of the replay.
+        :rtype: ReplayHeader
+        """
+        if self._reader:
+            raise RuntimeError("ReplayPlayer already active")
+        self._reader = ReplayReader(path)
+        self.header = self._reader.open()
+        self._it = self._reader.frames()
+        return self.header
+
+    def next(self) -> InputFrame:
+        """
+        Get the next input frame from the replay.
+
+        :return: The next input frame.
+        :rtype: InputFrame
+        """
+        if not self._it:
+            raise RuntimeError("ReplayPlayer not active")
+        try:
+            return next(self._it)
+        except StopIteration as exc:
+            self.stop()
+            raise RuntimeError("Replay finished") from exc
+
+    def stop(self) -> None:
+        """Stop playing back the current replay."""
+        if self._reader:
+            self._reader.close()
+        self._reader = None
+        self._it = None
+        self.header = None

mini_arcade_core/runtime/capture/replay_format.py

@@ -0,0 +1,120 @@
+"""
+Replay file format for mini-arcade.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterator, Optional, TextIO
+
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+REPLAY_MAGIC = "mini-arcade-replay"
+REPLAY_VERSION = 1
+
+
+@dataclass(frozen=True)
+class ReplayHeader:
+    """
+    Header information for a mini-arcade replay file.
+
+    :ivar magic: Magic string to identify the file type.
+    :ivar version: Version of the replay format.
+    :ivar game_id: Identifier for the game.
+    :ivar initial_scene: Name of the initial scene.
+    :ivar seed: Seed used for random number generation.
+    :ivar fps: Frames per second of the replay.
+    """
+
+    magic: str = REPLAY_MAGIC
+    version: int = REPLAY_VERSION
+    game_id: str = "unknown"
+    initial_scene: str = "unknown"
+    seed: int = 0
+    fps: int = 60
+
+
+class ReplayWriter:
+    """Replay file writer."""
+
+    def __init__(self, path: Path, header: ReplayHeader):
+        """
+        :param path: Path to save the replay file.
+        :type path: Path
+        :param header: Header information for the replay.
+        :type header: ReplayHeader
+        """
+        self.path = path
+        self.header = header
+        self._f: Optional[TextIO] = None
+
+    def open(self) -> None:
+        """Open the replay file for writing."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._f = self.path.open("w", encoding="utf-8")
+        self._f.write(json.dumps(asdict(self.header)) + "\n")
+
+    def write_frame(self, frame: InputFrame) -> None:
+        """
+        Write an input frame to the replay file.
+
+        :param frame: Input frame to write.
+        :type frame: InputFrame
+        """
+        if not self._f:
+            raise RuntimeError("ReplayWriter is not open")
+        self._f.write(json.dumps(frame.to_dict()) + "\n")
+
+    def close(self) -> None:
+        """Close the replay file."""
+        if self._f:
+            self._f.close()
+            self._f = None
+
+
+class ReplayReader:
+    """Replay file reader."""
+
+    def __init__(self, path: Path):
+        """
+        :param path: Path to the replay file.
+        :type path: Path"""
+        self.path = path
+        self.header: Optional[ReplayHeader] = None
+        self._f: Optional[TextIO] = None
+
+    def open(self) -> ReplayHeader:
+        """
+        Open the replay file for reading.
+
+        :return: The replay header.
+        :rtype: ReplayHeader
+        """
+        self._f = self.path.open("r", encoding="utf-8")
+        header_line = self._f.readline()
+        self.header = ReplayHeader(**json.loads(header_line))
+        if self.header.magic != REPLAY_MAGIC:
+            raise ValueError("Not a mini-arcade replay file")
+        return self.header
+
+    def frames(self) -> Iterator[InputFrame]:
+        """
+        Iterate over input frames in the replay file.
+
+        :return: Input frames from the replay.
+        :rtype: Iterator[InputFrame]
+        """
+        if not self._f:
+            raise RuntimeError("ReplayReader is not open")
+        for line in self._f:
+            if not line.strip():
+                continue
+            yield InputFrame.from_dict(json.loads(line))
+
+    def close(self) -> None:
+        """Close the replay file."""
+        if self._f:
+            self._f.close()
+            self._f = None

mini_arcade_core/runtime/capture/{capture_adapter.py → screenshot_capturer.py}

@@ -8,11 +8,16 @@ from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import Optional
+from uuid import uuid4
 
 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.runtime.capture.capture_worker import (
+    CaptureJob,
+    CaptureWorker,
+)
 from mini_arcade_core.utils import logger
 
 
@@ -73,7 +78,7 @@ class CapturePathBuilder:
         return Path(self.directory) / run_id / name
 
 
-class CaptureAdapter(CapturePort):
+class ScreenshotCapturer(CapturePort):
     """
     Adapter for capturing frames.
 
@@ -87,9 +92,12 @@ class CaptureAdapter(CapturePort):
         self,
         backend: Backend,
         path_builder: Optional[CapturePathBuilder] = None,
+        worker: Optional[CaptureWorker] = None,
     ):
         self.backend = backend
         self.path_builder = path_builder or CapturePathBuilder()
+        self.worker = worker or CaptureWorker()
+        self.worker.start()
 
     def _bmp_to_image(self, bmp_path: str, out_path: str):
         img = Image.open(bmp_path)
@@ -98,25 +106,7 @@ class CaptureAdapter(CapturePort):
     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.bmp(str(bmp_path))
-        if not bmp_path.exists():
-            raise RuntimeError("Backend capture.bmp 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)
+        return self._capture_to(out_path, job_id=uuid4().hex)
 
     def screenshot_bytes(self) -> bytes:
         data = self.backend.capture.bmp(path=None)
@@ -127,24 +117,28 @@ class CaptureAdapter(CapturePort):
     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.bmp(str(bmp_path))
+        return self._capture_to(out_path, job_id=f"{run_id}:{frame_index}")
 
-        if not bmp_path.exists():
-            raise RuntimeError("Backend capture.bmp did not create BMP file")
+    def _capture_to(self, out_path: Path, job_id: str) -> str:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
 
-        self._bmp_to_image(str(bmp_path), str(out_path))
+        bmp_path = out_path.with_suffix(f".{uuid4().hex}.bmp")
+        bmp_path.parent.mkdir(parents=True, exist_ok=True)
 
-        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
+        ok_native = self.backend.capture.bmp(str(bmp_path))
+        if not ok_native or not bmp_path.exists():
+            raise RuntimeError("Backend capture.bmp failed to create BMP file")
 
+        ok = self.worker.enqueue(
+            CaptureJob(job_id=job_id, out_path=out_path, bmp_path=bmp_path)
+        )
+        if not ok:
+            logger.warning("Screenshot dropped: capture queue full")
+            try:
+                bmp_path.unlink(missing_ok=True)
+            except Exception:  # pylint: disable=broad-exception-caught
+                pass
+
+        # IMPORTANT: async, so it's "queued"
         return str(out_path)

mini_arcade_core/runtime/input_frame.py

@@ -4,7 +4,7 @@ Input frame data structure for capturing input state per frame.
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import asdict, dataclass, field
 from typing import Dict, FrozenSet, Tuple
 
 from mini_arcade_core.backend.keys import Key
@@ -24,6 +24,32 @@ class ButtonState:
     pressed: bool
     released: bool
 
+    def to_dict(self) -> Dict[str, bool]:
+        """
+        Convert the ButtonState to a dictionary.
+
+        :return: Dictionary representation of the ButtonState.
+        :rtype: Dict[str, bool]
+        """
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, bool]) -> ButtonState:
+        """
+        Create a ButtonState from a dictionary.
+
+        :param data: Dictionary containing button state data.
+        :type data: Dict[str, bool]
+
+        :return: ButtonState instance.
+        :rtype: ButtonState
+        """
+        return cls(
+            down=data.get("down", False),
+            pressed=data.get("pressed", False),
+            released=data.get("released", False),
+        )
+
 
 # TODO: Solve too-many-instance-attributes warning later
 # Justification: This data class needs multiple attributes to capture input state.
@@ -67,5 +93,57 @@ class InputFrame:
     # Window/OS quit request
     quit: bool = False
 
+    def to_dict(self) -> Dict[str, object]:
+        """
+        Convert the InputFrame to a dictionary.
+
+        :return: Dictionary representation of the InputFrame.
+        :rtype: Dict[str, object]
+        """
+        data = asdict(self)
+
+        # Convert ButtonState objects to dicts
+        data["buttons"] = {
+            name: state.to_dict() for name, state in self.buttons.items()
+        }
+
+        # Convert FrozenSet to list for serialization
+        data["keys_down"] = [k.value for k in self.keys_down]
+        data["keys_pressed"] = [k.value for k in self.keys_pressed]
+        data["keys_released"] = [k.value for k in self.keys_released]
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, object]) -> InputFrame:
+        """
+        Create an InputFrame from a dictionary.
+
+        :param data: Dictionary containing input frame data.
+        :type data: Dict[str, object]
+
+        :return: InputFrame instance.
+        :rtype: InputFrame
+        """
+        return cls(
+            frame_index=data.get("frame_index", 0),
+            dt=data.get("dt", 0.0),
+            keys_down=frozenset(Key(v) for v in data.get("keys_down", [])),
+            keys_pressed=frozenset(
+                Key(v) for v in data.get("keys_pressed", [])
+            ),
+            keys_released=frozenset(
+                Key(v) for v in data.get("keys_released", [])
+            ),
+            buttons={
+                name: ButtonState.from_dict(state)
+                for name, state in data.get("buttons", {}).items()
+            },
+            axes=data.get("axes", {}),
+            mouse_pos=tuple(data.get("mouse_pos", (0, 0))),
+            mouse_delta=tuple(data.get("mouse_delta", (0, 0))),
+            text_input=data.get("text_input", ""),
+            quit=data.get("quit", False),
+        )
+
 
 # pylint: enable=too-many-instance-attributes

mini_arcade_core/runtime/services.py

@@ -7,7 +7,9 @@ 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.capture.capture_service_protocol import (
+    CaptureServicePort,
+)
 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.render.render_port import RenderServicePort
@@ -24,7 +26,7 @@ class RuntimeServices:
     :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 capture (CaptureServicePort): Capture service port.
     :ivar input (InputPort): Input handling service port.
     :ivar render (RenderServicePort): Rendering service port.
     """
@@ -32,7 +34,7 @@ class RuntimeServices:
     window: WindowPort
     audio: AudioPort
     files: FilePort
-    capture: CapturePort
+    capture: CaptureServicePort
     input: InputPort
     render: RenderServicePort
     scenes: SceneQueryPort

{mini_arcade_core-1.2.0.dist-info → mini_arcade_core-1.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 1.2.0
+Version: 1.2.2
 Summary: Tiny scene-based game loop core for small arcade games.
 License: Copyright (c) 2025 Santiago Rincón
            

{mini_arcade_core-1.2.0.dist-info → mini_arcade_core-1.2.2.dist-info}/RECORD

@@ -8,14 +8,14 @@ mini_arcade_core/backend/types.py,sha256=EW0bW4MvsEZKot0Z1h_5LuFSzoYGiJBphTquBz4
 mini_arcade_core/bus.py,sha256=2Etpoa-UWhk33xJjqDlY5YslPDJEjxNoIEVtF3C73vs,1558
 mini_arcade_core/engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/engine/cheats.py,sha256=jMx2a8YnaNCkCG5MPmIzz4uHuS7-_aYf0J45cv2-3v0,5569
-mini_arcade_core/engine/commands.py,sha256=Cw1tAwVRO5U2--hFX1Jq00LH_84oe1Oqw-Ngc0RnkGI,5383
-mini_arcade_core/engine/game.py,sha256=DDdvlv0cN4sjBKtoIuP19W3YQCF1LwZbC_jYCz-1E4U,5767
+mini_arcade_core/engine/commands.py,sha256=oe5VWpFtIEdxQu2m5_pFXnwY1LJ3uhv8wOP27t01tfI,7400
+mini_arcade_core/engine/game.py,sha256=DikhhLK2byDbMxSZH0TsjZOR_qY3mfR3EhXa0J79FX4,5812
 mini_arcade_core/engine/game_config.py,sha256=4AP8n0Uk1HKEdPLOrV1xsySzBljAh8VhZASNrxPIMMc,1034
 mini_arcade_core/engine/gameplay_settings.py,sha256=W8WBwfAvGZftkL4aMnOTx6SsGxwG-9Ou1Ey0AeWPCxs,549
 mini_arcade_core/engine/loop/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/engine/loop/config.py,sha256=Sj1LrdnD_aACmHUuRQuKB7bDbDZy60WVe8sJHRmzmIU,461
 mini_arcade_core/engine/loop/hooks.py,sha256=nmZi-35iMsZoPedTdZzsIKJP6O_iFUeKjB8xc4-XTHU,2417
-mini_arcade_core/engine/loop/runner.py,sha256=uB4onDMO6lWFt40YNJsovkVHXiyaVdEuEFj8kYqWn6k,8858
+mini_arcade_core/engine/loop/runner.py,sha256=M4M-V0En4MIlUbWXtbCCs24PWDNIWcWEiyI86xhcyeE,9652
 mini_arcade_core/engine/loop/state.py,sha256=fzXQ9GP05PVNXEBTgIwA4qjMujxdUae3CXM6uRQz92Y,858
 mini_arcade_core/engine/managers.py,sha256=eQJYe-xYtRha-FWxzJ3DcpwlcHwiT5sGt4oCD9ZPxEE,664
 mini_arcade_core/engine/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -46,8 +46,14 @@ mini_arcade_core/runtime/audio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5
 mini_arcade_core/runtime/audio/audio_adapter.py,sha256=lnP35txPzSKX1_il0nXcK7RMF5Qp9Qhi9YMh_7LTdPM,588
 mini_arcade_core/runtime/audio/audio_port.py,sha256=jBd9WabN41uK3MHjg_1n4AOw83NivJlGE2m430WZTnk,831
 mini_arcade_core/runtime/capture/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/runtime/capture/capture_adapter.py,sha256=XBtiKw3AS2dzB4QogPm9kjhiQAenS25guX87tg-zK58,4882
 mini_arcade_core/runtime/capture/capture_port.py,sha256=niHi0pAo10mC9p73FxFkYBIGLOLRN0PiOvxE4Zgo5fM,1162
+mini_arcade_core/runtime/capture/capture_service.py,sha256=9ig0Wi0OZisefUDse7-v-_SUR1IPGAQmc15S2PZz-rY,2917
+mini_arcade_core/runtime/capture/capture_service_protocol.py,sha256=f17yKG7vPluITZyjCutsGsYlm-FAKE0zgcRhXD-wtUM,3308
+mini_arcade_core/runtime/capture/capture_settings.py,sha256=vDFdZi1HAF10cwrgM-46oVSu4Q5dk-p2F-4-TDBq0Ko,479
+mini_arcade_core/runtime/capture/capture_worker.py,sha256=XAzL28jD8jnGoG3bvsd9yQW5S4Nv7licNJn94QTIzp4,5393
+mini_arcade_core/runtime/capture/replay.py,sha256=oDKY5oDLJS2PU9F57CinDMkDsLJui9V67t-jsjgVyWE,3471
+mini_arcade_core/runtime/capture/replay_format.py,sha256=VekOS4A-N8zrL_m7ByuqTZqMNxAoN9EFStRpSkSnk_k,3387
+mini_arcade_core/runtime/capture/screenshot_capturer.py,sha256=_pDg1U0587MocyADH2b2IpoN8t3dc2XdjrOOz115c20,4652
 mini_arcade_core/runtime/context.py,sha256=ONKQryO3KEOOqHaByxCUola07kdjrnvr4WfXwgwTobk,1777
 mini_arcade_core/runtime/file/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/file/file_adapter.py,sha256=09q7G9Qijml9d4AAjo6HLC1yuoVTjE_7xaT8apT4mk0,523
@@ -55,13 +61,13 @@ mini_arcade_core/runtime/file/file_port.py,sha256=p1MouCSHXZw--rWNMw3aYBLU-of8mX
 mini_arcade_core/runtime/input/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/input/input_adapter.py,sha256=vExQiwFIWTI3zYD8lmnD9TvoQPZvJfI6IINPJUqAdQ0,1467
 mini_arcade_core/runtime/input/input_port.py,sha256=d4ptftwf92_LJdyaUMFxIsLHXBINzQyJACHn4laNyxQ,746
-mini_arcade_core/runtime/input_frame.py,sha256=34-RAfOD-YScVLyRQrarpm7byFTHjsWM77lIH0JsmT8,2384
+mini_arcade_core/runtime/input_frame.py,sha256=DnikpT7LP-HUETnHG6Kan_j11bBXAQyf8XqW6O2FZhc,4948
 mini_arcade_core/runtime/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/render/render_port.py,sha256=Sqp-JBh-iRzzGtgnO_nU1KiJEqyrTYPRDQbg04HdR0A,507
 mini_arcade_core/runtime/scene/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/scene/scene_query_adapter.py,sha256=FNkqXgwxfugX_xqqFlZl0ELXsrW_gco5Au0tJhMGLgQ,909
 mini_arcade_core/runtime/scene/scene_query_port.py,sha256=qTikQVxOkJCdoMoH_lbe_ctJj7SWeJnnqDo6Ee0N_pQ,1019
-mini_arcade_core/runtime/services.py,sha256=iYcXt2CTapgDzSb54DsPasYZ4jTN7tA_B0lV1Sl5b1g,1243
+mini_arcade_core/runtime/services.py,sha256=GE9e-rYL62NwdV6haMrSLqXYhZrLDsAAlIsIPJncW6E,1285
 mini_arcade_core/runtime/window/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/window/window_adapter.py,sha256=VLZGYBVl7sGMmnk5mVowDleTyciAfE-Tc2woNFvRrgE,2890
 mini_arcade_core/runtime/window/window_port.py,sha256=HBy2OjsZzlxbBDQiTqlKEbIaejpN1zDp5whgvKxZxaY,2322
@@ -86,7 +92,7 @@ mini_arcade_core/utils/__init__.py,sha256=id1C0au8r1oIzGha42xXwnI9ojcU1hxPgto6QS
 mini_arcade_core/utils/deprecated_decorator.py,sha256=yrrW2ZqPskK-4MUTyIrMb465Wc54X2poV53ZQutZWqc,1140
 mini_arcade_core/utils/logging.py,sha256=ygKpey6nikp30PrNDP_yRs8pxPPRbsQ0ivR6LUuEn3Q,6413
 mini_arcade_core/utils/profiler.py,sha256=vLzrxDfAplgKGxpuzk4eFJx4t5DU5M3DQAn6sfS5D_4,8733
-mini_arcade_core-1.2.0.dist-info/METADATA,sha256=PeD3ImQ4FG5bjuYKFdLThR59fOvr-lgOS3OaF1XVRis,8188
-mini_arcade_core-1.2.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
-mini_arcade_core-1.2.0.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-1.2.0.dist-info/RECORD,,
+mini_arcade_core-1.2.2.dist-info/METADATA,sha256=uTEmFUmLixZzpR4AfgIe9dZsT6T09VpahwGipIcWRWU,8188
+mini_arcade_core-1.2.2.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+mini_arcade_core-1.2.2.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-1.2.2.dist-info/RECORD,,