mini-arcade-core 1.1.1__py3-none-any.whl → 1.2.1__py3-none-any.whl

mini_arcade_core/engine/scenes/models.py

@@ -0,0 +1,54 @@
+"""
+Models for scene management in the engine.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.scenes.sim_scene import SimScene
+
+
+@dataclass(frozen=True)
+class ScenePolicy:
+    """
+    Controls how a scene behaves in the scene stack.
+
+    blocks_update: if True, scenes below do not tick/update (pause modal)
+    blocks_input:  if True, scenes below do not receive input
+    is_opaque:     if True, scenes below are not rendered
+    receives_input: if True, scene can receive input
+    """
+
+    blocks_update: bool = False
+    blocks_input: bool = False
+    is_opaque: bool = False
+    receives_input: bool = True
+
+
+@dataclass(frozen=True)
+class SceneEntry:
+    """
+    An entry in the scene stack.
+
+    :ivar scene_id (str): Identifier of the scene.
+    :ivar scene (SimScene): The scene instance.
+    :ivar is_overlay (bool): Whether the scene is an overlay.
+    :ivar policy (ScenePolicy): The scene's policy.
+    """
+
+    scene_id: str
+    scene: SimScene
+    is_overlay: bool
+    policy: ScenePolicy
+
+
+@dataclass(frozen=True)
+class StackItem:
+    """
+    An item in the scene stack.
+
+    :ivar entry (SceneEntry): The scene entry.
+    """
+
+    entry: SceneEntry

mini_arcade_core/engine/scenes/scene_manager.py

@@ -0,0 +1,213 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+from mini_arcade_core.engine.scenes.models import (
+    SceneEntry,
+    ScenePolicy,
+    StackItem,
+)
+from mini_arcade_core.runtime.context import RuntimeContext
+from mini_arcade_core.scenes.registry import SceneRegistry
+
+if TYPE_CHECKING:
+    from mini_arcade_core.engine.game import Game
+    from mini_arcade_core.scenes.sim_scene import SimScene
+
+
+class SceneAdapter:
+    """
+    Manages multiple scenes (not implemented).
+    """
+
+    def __init__(self, registry: SceneRegistry, game: Game):
+        self._registry = registry
+        self._stack: List[StackItem] = []
+        self._game = game
+
+    @property
+    def current_scene(self) -> SimScene | None:
+        """
+        Get the currently active scene.
+
+        :return: The active Scene instance, or None if no scene is active.
+        :rtype: SimScene | None
+        """
+        return self._stack[-1].entry.scene if self._stack else None
+
+    @property
+    def visible_stack(self) -> List[SimScene]:
+        """
+        Return the list of scenes that should be drawn (base + overlays).
+        We draw from the top-most non-overlay scene upward.
+
+        :return: List of visible Scene instances.
+        :rtype: List[SimScene]
+        """
+        return [e.scene for e in self.visible_entries()]
+
+    @property
+    def listed_scenes(self) -> List[SimScene]:
+        """
+        Return all scenes in the stack.
+
+        :return: List of all Scene instances in the stack.
+        :rtype: List[SimScene]
+        """
+        return [item.entry.scene for item in self._stack]
+
+    def change(self, scene_id: str):
+        """
+        Change the current scene to the specified scene.
+
+        :param scene_id: Identifier of the scene to switch to.
+        :type scene_id: str
+        """
+        self.clean()
+        self.push(scene_id, as_overlay=False)
+
+    def push(
+        self,
+        scene_id: str,
+        *,
+        as_overlay: bool = False,
+        policy: ScenePolicy | None = None,
+    ):
+        """
+        Push a new scene onto the scene stack.
+
+        :param scene_id: Identifier of the scene to push.
+        :type scene_id: str
+
+        :param as_overlay: Whether to push the scene as an overlay.
+        :type as_overlay: bool
+        """
+        # default policy based on overlay vs base
+        if policy is None:
+            # base scenes: do not block anything by default
+            policy = ScenePolicy()
+        runtime_context = RuntimeContext.from_game(self._game)
+        scene = self._registry.create(
+            scene_id, runtime_context
+        )  # or whatever your factory call is
+        scene.on_enter()
+
+        entry = SceneEntry(
+            scene_id=scene_id,
+            scene=scene,
+            is_overlay=as_overlay,
+            policy=policy,
+        )
+        self._stack.append(StackItem(entry=entry))
+
+    def pop(self) -> SimScene | None:
+        """
+        Pop the current scene from the scene stack.
+
+        :return: The popped Scene instance, or None if the stack was empty.
+        :rtype: SimScene | None
+        """
+        if not self._stack:
+            return
+        item = self._stack.pop()
+        item.entry.scene.on_exit()
+
+    def clean(self):
+        """Clean up all scenes from the scene stack."""
+        while self._stack:
+            self.pop()
+
+    def quit(self):
+        """Quit the game"""
+        self._game.quit()
+
+    def visible_entries(self) -> list[SceneEntry]:
+        """
+        Render from bottom->top unless an opaque entry exists; if so,
+            render only from that entry up.
+
+        :return: List of SceneEntry instances to render.
+        :rtype: list[SceneEntry]
+        """
+        entries = [i.entry for i in self._stack]
+        # find highest opaque from top down; render starting there
+        for idx in range(len(entries) - 1, -1, -1):
+            if entries[idx].policy.is_opaque:
+                return entries[idx:]
+        return entries
+
+    def update_entries(self) -> list[SceneEntry]:
+        """
+        Tick/update scenes considering blocks_update.
+        Typical: pause overlay blocks update below it.
+
+        :return: List of SceneEntry instances to update.
+        :rtype: list[SceneEntry]
+        """
+        vis = self.visible_entries()
+        if not vis:
+            return []
+        out = []
+        for entry in reversed(vis):  # top->down
+            out.append(entry)
+            if entry.policy.blocks_update:
+                break
+        return list(reversed(out))  # bottom->top order
+
+    def input_entry(self) -> SceneEntry | None:
+        """
+        Who gets input this frame. If top blocks_input, only it receives input.
+        If not, top still gets input (v1 simple). Later you can allow fall-through.
+
+        :return: The SceneEntry that receives input, or None if no scenes are active.
+        :rtype: SceneEntry | None
+        """
+        vis = self.visible_entries()
+        if not vis:
+            return None
+
+        # If some scene blocks input, only scenes at/above it can receive.
+        start_idx = 0
+        for idx in range(len(vis) - 1, -1, -1):
+            if vis[idx].policy.blocks_input:
+                start_idx = idx
+                break
+
+        candidates = vis[start_idx:]
+
+        # Pick the top-most candidate that actually receives input.
+        for entry in reversed(candidates):
+            if entry.policy.receives_input:
+                return entry
+
+        return None
+
+    def has_scene(self, scene_id: str) -> bool:
+        """
+        Check if a scene with the given ID exists in the stack.
+
+        :param scene_id: Identifier of the scene to check.
+        :type scene_id: str
+
+        :return: True if the scene exists in the stack, False otherwise.
+        :rtype: bool
+        """
+        return any(item.entry.scene_id == scene_id for item in self._stack)
+
+    def remove_scene(self, scene_id: str):
+        """
+        Remove a scene with the given ID from the stack.
+
+        :param scene_id: Identifier of the scene to remove.
+        :type scene_id: str
+        """
+        # remove first match from top (overlay is usually near top)
+        for i in range(len(self._stack) - 1, -1, -1):
+            if self._stack[i].entry.scene_id == scene_id:
+                item = self._stack.pop(i)
+                item.entry.scene.on_exit()
+                return

mini_arcade_core/runtime/audio/audio_adapter.py

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

mini_arcade_core/runtime/audio/audio_port.py

@@ -4,14 +4,10 @@ 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.

mini_arcade_core/runtime/capture/capture_adapter.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
 
 
@@ -74,15 +79,25 @@ class CapturePathBuilder:
 
 
 class CaptureAdapter(CapturePort):
-    """Adapter for capturing frames."""
+    """
+    Adapter for capturing frames.
+
+    :param backend: Backend instance to use for capturing frames.
+    :type backend: Backend
+    :param path_builder: Optional CapturePathBuilder for building file paths.
+    :type path_builder: CapturePathBuilder | None
+    """
 
     def __init__(
         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)
@@ -91,28 +106,32 @@ 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)
+        logger.critical(f"Capturing screenshot to: {out_path}")
 
-        # If backend only saves BMP, capture to a temp bmp next to output
-        bmp_path = out_path.with_suffix(".bmp")
+        # temp BMP next to output (unique)
+        bmp_path = out_path.with_suffix(f".{uuid4().hex}.bmp")
+        bmp_path.parent.mkdir(parents=True, exist_ok=True)
 
-        self.backend.capture_frame(str(bmp_path))
-        if not bmp_path.exists():
-            raise RuntimeError("Backend capture_frame did not create BMP file")
+        ok_native = self.backend.capture.bmp(str(bmp_path))  # returns bool
+        if not ok_native or not bmp_path.exists():
+            raise RuntimeError("Backend capture.bmp failed to 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
+        job_id = uuid4().hex
+        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")
+            # optional: cleanup temp bmp since we won't process it
+            try:
+                bmp_path.unlink(missing_ok=True)
+            except Exception:  # pylint: disable=broad-exception-caught
+                pass
 
         return str(out_path)
 
     def screenshot_bytes(self) -> bytes:
-        data = self.backend.capture_frame(path=None)
+        data = self.backend.capture.bmp(path=None)
         if data is None:
             raise RuntimeError("Backend returned None for screenshot_bytes()")
         return data
@@ -120,24 +139,27 @@ 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_frame(str(bmp_path))
 
-        if not bmp_path.exists():
-            raise RuntimeError("Backend capture_frame did not create BMP file")
+        bmp_path = out_path.with_suffix(f".{uuid4().hex}.bmp")
+        bmp_path.parent.mkdir(parents=True, exist_ok=True)
 
-        self._bmp_to_image(str(bmp_path), str(out_path))
+        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")
 
-        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
+        job_id = f"{run_id}:{frame_index}"
+        ok = self.worker.enqueue(
+            CaptureJob(job_id=job_id, out_path=out_path, bmp_path=bmp_path)
+        )
+        if not ok:
+            logger.warning("Sim screenshot dropped: capture queue full")
+            try:
+                bmp_path.unlink(missing_ok=True)
+            # Justification: Broad exception catch for cleanup
+            # pylint: disable=broad-exception-caught
+            except Exception:
+                pass
+            # pylint: enable=broad-exception-caught
 
         return str(out_path)

mini_arcade_core/runtime/capture/capture_port.py

@@ -4,14 +4,10 @@ Service interfaces for runtime components.
 
 from __future__ import annotations
 
-from mini_arcade_core.backend import Backend
-
 
 class CapturePort:
     """Interface for frame capture operations."""
 
-    backend: Backend
-
     def screenshot(self, label: str | None = None) -> str:
         """
         Capture the current frame.

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/context.py

@@ -9,12 +9,14 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from mini_arcade_core.engine.cheats import CheatManager
     from mini_arcade_core.engine.commands import CommandQueue
-    from mini_arcade_core.engine.game import Game, GameConfig, GameSettings
-    from mini_arcade_core.managers.cheats import CheatManager
+    from mini_arcade_core.engine.game import Game, GameConfig
+    from mini_arcade_core.engine.gameplay_settings import GamePlaySettings
     from mini_arcade_core.runtime.services import RuntimeServices
 
 
+# TODO: Remove cheats and command_queue from here later if unused.
 @dataclass(frozen=True)
 class RuntimeContext:
     """
@@ -22,14 +24,14 @@ class RuntimeContext:
 
     :ivar services (RuntimeServices): Runtime services.
     :ivar config (GameConfig): Game configuration.
-    :ivar settings (GameSettings): Game settings.
+    :ivar settings (GamePlaySettings): Game settings.
     :ivar command_queue (CommandQueue | None): Optional command queue.
     :ivar cheats (CheatManager | None): Optional cheat manager.
     """
 
     services: RuntimeServices
     config: GameConfig
-    settings: GameSettings
+    settings: GamePlaySettings
     command_queue: CommandQueue | None = None
     cheats: CheatManager | None = None
 
@@ -48,6 +50,6 @@ class RuntimeContext:
             services=game_entity.services,
             config=game_entity.config,
             settings=game_entity.settings,
-            command_queue=game_entity.command_queue,
-            cheats=game_entity.cheat_manager,
+            command_queue=game_entity.managers.command_queue,
+            cheats=game_entity.managers.cheats,
         )