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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 1.2.1
+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.1 → 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.1"
+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.1 → 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.1 → 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.1 → 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/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-1.2.2/src/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