mini-arcade-core 1.1.1__py3-none-any.whl → 1.2.0__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

@@ -74,7 +74,14 @@ 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,
@@ -96,9 +103,9 @@ class CaptureAdapter(CapturePort):
         # If backend only saves BMP, capture to a temp bmp next to output
         bmp_path = out_path.with_suffix(".bmp")
 
-        self.backend.capture_frame(str(bmp_path))
+        self.backend.capture.bmp(str(bmp_path))
         if not bmp_path.exists():
-            raise RuntimeError("Backend capture_frame did not create BMP file")
+            raise RuntimeError("Backend capture.bmp did not create BMP file")
 
         self._bmp_to_image(str(bmp_path), str(out_path))
         try:
@@ -112,7 +119,7 @@ class CaptureAdapter(CapturePort):
         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
@@ -125,10 +132,10 @@ class CaptureAdapter(CapturePort):
         out_path.parent.mkdir(parents=True, exist_ok=True)
 
         bmp_path = out_path.with_suffix(".bmp")
-        self.backend.capture_frame(str(bmp_path))
+        self.backend.capture.bmp(str(bmp_path))
 
         if not bmp_path.exists():
-            raise RuntimeError("Backend capture_frame did not create BMP file")
+            raise RuntimeError("Backend capture.bmp did not create BMP file")
 
         self._bmp_to_image(str(bmp_path), 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/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,
         )

mini_arcade_core/runtime/scene/scene_query_adapter.py

@@ -0,0 +1,31 @@
+"""
+Scene query adapter implementation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from mini_arcade_core.engine.scenes.models import SceneEntry
+from mini_arcade_core.engine.scenes.scene_manager import SceneAdapter
+from mini_arcade_core.runtime.scene.scene_query_port import SceneQueryPort
+
+
+@dataclass
+class SceneQueryAdapter(SceneQueryPort):
+    """Adapter that exposes a read-only view of the SceneAdapter manager."""
+
+    _scenes: SceneAdapter
+
+    def visible_entries(self) -> Sequence[SceneEntry]:
+        return list(self._scenes.visible_entries())
+
+    def input_entry(self) -> SceneEntry | None:
+        return self._scenes.input_entry()
+
+    def stack_summary(self) -> list[str]:
+        out: list[str] = []
+        for e in self._scenes.visible_entries():
+            out.append(f"{e.scene_id} overlay={e.is_overlay}")
+        return out

mini_arcade_core/runtime/scene/scene_query_port.py

@@ -0,0 +1,38 @@
+"""
+Scene query port protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, Sequence, runtime_checkable
+
+from mini_arcade_core.engine.scenes.models import SceneEntry
+
+
+@runtime_checkable
+class SceneQueryPort(Protocol):
+    """Read-only queries over the engine scene stack."""
+
+    def visible_entries(self) -> Sequence[SceneEntry]:
+        """
+        Scenes that should be rendered (policy-aware).
+
+        :return: Sequence of SceneEntry instances that are visible.
+        :rtype: Sequence[SceneEntry]
+        """
+
+    def input_entry(self) -> SceneEntry | None:
+        """
+        The scene that currently receives input (top-most eligible).
+
+        :return: SceneEntry that receives input, or None if stack is empty.
+        :rtype: SceneEntry | None
+        """
+
+    def stack_summary(self) -> list[str]:
+        """
+        Convenience: human-readable stack lines for debug overlays.
+
+        :return: List of strings summarizing the scene stack.
+        :rtype: list[str]
+        """

mini_arcade_core/runtime/services.py

@@ -11,7 +11,7 @@ from mini_arcade_core.runtime.capture.capture_port import CapturePort
 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
-from mini_arcade_core.runtime.scene.scene_port import ScenePort
+from mini_arcade_core.runtime.scene.scene_query_port import SceneQueryPort
 from mini_arcade_core.runtime.window.window_port import WindowPort
 
 
@@ -26,12 +26,13 @@ class RuntimeServices:
     :ivar files (FilePort): File service port.
     :ivar capture (CapturePort): Capture service port.
     :ivar input (InputPort): Input handling service port.
+    :ivar render (RenderServicePort): Rendering service port.
     """
 
     window: WindowPort
-    scenes: ScenePort
     audio: AudioPort
     files: FilePort
     capture: CapturePort
     input: InputPort
     render: RenderServicePort
+    scenes: SceneQueryPort

mini_arcade_core/runtime/window/window_adapter.py

@@ -4,14 +4,14 @@ Module providing runtime adapters for window and scene management.
 
 from __future__ import annotations
 
-from venv import logger
-
+from mini_arcade_core.backend import Backend
 from mini_arcade_core.engine.render.viewport import (
     Viewport,
     ViewportMode,
     ViewportState,
 )
 from mini_arcade_core.runtime.window.window_port import WindowPort
+from mini_arcade_core.utils import logger
 
 
 class WindowAdapter(WindowPort):
@@ -19,71 +19,73 @@ class WindowAdapter(WindowPort):
     Manages multiple game windows (not implemented).
     """
 
-    def __init__(self, backend, window_settings):
-        self.backend = backend
-        self.window_settings = window_settings
-
-        self._initialized = False
+    _drawable_size: tuple[int, int]
 
-        # Default: virtual resolution == initial window resolution.
-        # You can override via set_virtual_resolution().
-        self._viewport = Viewport(
-            window_settings.width,
-            window_settings.height,
-            mode=ViewportMode.FIT,
-        )
-
-        # Cached current window size
-        self.size = (window_settings.width, window_settings.height)
+    def __init__(self, backend: Backend):
+        self.backend = backend
 
-    def set_window_size(self, width, height):
-        width = int(width)
-        height = int(height)
-        self.size = (width, height)
+        self.backend.init()
 
-        self.window_settings.width = width
-        self.window_settings.height = height
+        w, h = self.backend.window.size()
+        self.size = (w, h)
+        self._initialized = True
 
-        if not self._initialized:
-            self.backend.init(self.window_settings)
-            self._initialized = True
-        else:
-            self.backend.resize_window(width, height)
+        self._viewport = Viewport(w, h, mode=ViewportMode.FIT)
+        self._viewport.resize(w, h)
+        self._apply_viewport_transform()
 
-        self._viewport.resize(width, height)
+    def _apply_viewport_transform(self):
+        s = self._viewport.state
+        # This is the missing link in the new backend design:
+        self.backend.set_viewport_transform(s.offset_x, s.offset_y, s.scale)
 
     def set_virtual_resolution(self, width: int, height: int):
         self._viewport.set_virtual_resolution(int(width), int(height))
-        # re-apply using current window size
-        w, h = self.size
+        w, h = self.backend.window.size()
+        self.size = (w, h)
         self._viewport.resize(w, h)
+        self._apply_viewport_transform()
 
     def set_viewport_mode(self, mode: ViewportMode):
         self._viewport.set_mode(mode)
+        # mode change affects scale/offset
+        if self._viewport.state is not None:
+            self._apply_viewport_transform()
 
     def get_viewport(self) -> ViewportState:
         return self._viewport.state
 
     def screen_to_virtual(self, x: float, y: float) -> tuple[float, float]:
-        return self._viewport.screen_to_virtual(x, y)
+        logical_w, logical_h = self.size
+        drawable_w, drawable_h = self._drawable_size
+
+        sx = drawable_w / logical_w if logical_w else 1.0
+        sy = drawable_h / logical_h if logical_h else 1.0
+
+        return self._viewport.screen_to_virtual(x * sx, y * sy)
 
     def set_title(self, title):
-        self.backend.set_window_title(title)
+        self.backend.window.set_title(title)
 
     def set_clear_color(self, r, g, b):
-        self.backend.set_clear_color(r, g, b)
+        self.backend.render.set_clear_color(r, g, b)
 
     def on_window_resized(self, width: int, height: int):
         logger.debug(f"Window resized event: {width}x{height}")
-        width = int(width)
-        height = int(height)
 
-        # Update cached size, but DO NOT call backend.resize_window here.
-        self.size = (width, height)
-        self.window_settings.width = width
-        self.window_settings.height = height
+        # logical
+        logical_w, logical_h = int(width), int(height)
+
+        # drawable (pixel)
+        drawable_w, drawable_h = self.backend.window.drawable_size()
+
+        # store both if useful
+        self.size = (logical_w, logical_h)
+        self._drawable_size = (drawable_w, drawable_h)
 
-        self._viewport.resize(width, height)
+        # viewport should match what renderer draws to:
+        self._viewport.resize(drawable_w, drawable_h)
+        self._apply_viewport_transform()
 
     def get_virtual_size(self) -> tuple[int, int]:
         s = self.get_viewport()

mini_arcade_core/runtime/window/window_port.py

@@ -4,28 +4,14 @@ Service interfaces for runtime components.
 
 from __future__ import annotations
 
-from mini_arcade_core.backend import Backend, WindowSettings
+from typing import Protocol
+
 from mini_arcade_core.engine.render.viewport import ViewportMode, ViewportState
 
 
-class WindowPort:
+class WindowPort(Protocol):
     """Interface for window-related operations."""
 
-    backend: Backend
-    size: tuple[int, int]
-    window_settings_cls: WindowSettings
-
-    def set_window_size(self, width: int, height: int):
-        """
-        Set the size of the window.
-
-        :param width: Width in pixels.
-        :type width: int
-
-        :param height: Height in pixels.
-        :type height: int
-        """
-
     def set_viewport_mode(self, mode: ViewportMode):
         """
         Set the viewport mode for rendering.