mini-arcade-core 1.2.0__tar.gz → 1.2.2__tar.gz

{mini_arcade_core-1.2.0 → mini_arcade_core-1.2.2}/PKG-INFO

@@ -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 → mini_arcade_core-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "1.2.0"
+version = "1.2.2"
 description = "Tiny scene-based game loop core for small arcade games."
 authors = [
     { name = "Santiago Rincon", email = "rincores@gmail.com" },

{mini_arcade_core-1.2.0 → mini_arcade_core-1.2.2}/src/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-1.2.0 → mini_arcade_core-1.2.2}/src/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-1.2.0 → mini_arcade_core-1.2.2}/src/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-1.2.2/src/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-1.2.2/src/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-1.2.2/src/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-1.2.2/src/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()