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

mini_arcade_core/engine/render/passes/ui.py

@@ -24,7 +24,7 @@ class UIPass:
         """Run the UI render pass."""
         # UI overlays should be screen-space (no world transform / no clip unless you want it)
         backend.clear_viewport_transform()
-        backend.clear_clip_rect()
+        backend.render.clear_clip_rect()
 
         for fp in packets:
             if not fp.is_overlay:

mini_arcade_core/engine/render/passes/world.py

@@ -41,15 +41,15 @@ class WorldPass:
         backend.set_viewport_transform(
             ctx.viewport.offset_x, ctx.viewport.offset_y, ctx.viewport.scale
         )
-        backend.set_clip_rect(
-            ctx.viewport.offset_x,
-            ctx.viewport.offset_y,
-            ctx.viewport.viewport_w,
-            ctx.viewport.viewport_h,
+        backend.render.set_clip_rect(
+            0,
+            0,
+            ctx.viewport.virtual_w,
+            ctx.viewport.virtual_h,
         )
         try:
             for op in packet.ops:
                 op(backend)
         finally:
-            backend.clear_clip_rect()
+            backend.render.clear_clip_rect()
             backend.clear_viewport_transform()

mini_arcade_core/engine/render/pipeline.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass, field
 
 from mini_arcade_core.backend import Backend
 from mini_arcade_core.engine.render.context import RenderContext
+from mini_arcade_core.engine.render.frame_packet import FramePacket
 from mini_arcade_core.engine.render.packet import RenderPacket
 from mini_arcade_core.engine.render.passes.base import RenderPass
 from mini_arcade_core.engine.render.passes.begin_frame import BeginFramePass
@@ -56,10 +57,10 @@ class RenderPipeline:
     )
 
     def render_frame(
-        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+        self, backend: Backend, ctx: RenderContext, packets: list[FramePacket]
     ):
         """
-        Render a frame using the provided Backend, RenderContext, and list of RenderPackets.
+        Render a frame using the provided Backend, RenderContext, and list of FramePackets.
 
         :param backend: Backend to use for rendering.
         :type backend: Backend
@@ -67,8 +68,8 @@ class RenderPipeline:
         :param ctx: RenderContext containing rendering state.
         :type ctx: RenderContext
 
-        :param packets: List of RenderPackets to render.
-        :type packets: list[RenderPacket]
+        :param packets: List of FramePackets to render.
+        :type packets: list[FramePacket]
         """
         for p in self.passes:
             p.run(backend, ctx, packets)
@@ -98,8 +99,8 @@ class RenderPipeline:
         )
 
         backend.set_clip_rect(
-            viewport_state.offset_x,
-            viewport_state.offset_y,
+            0,
+            0,
             viewport_state.viewport_w,
             viewport_state.viewport_h,
         )

mini_arcade_core/engine/render/viewport.py

@@ -4,6 +4,7 @@ Viewport management for virtual to screen coordinate transformations.
 
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass
 from enum import Enum
 
@@ -130,10 +131,15 @@ class Viewport:
         sy = window_h / self._virtual_h
         scale = min(sx, sy) if self._mode == ViewportMode.FIT else max(sx, sy)
 
-        vw = int(round(self._virtual_w * scale))
-        vh = int(round(self._virtual_h * scale))
-        ox = int(round((window_w - vw) / 2))
-        oy = int(round((window_h - vh) / 2))
+        if self._mode == ViewportMode.FIT:
+            vw = int(math.floor(self._virtual_w * scale))
+            vh = int(math.floor(self._virtual_h * scale))
+        else:  # FILL
+            vw = int(math.ceil(self._virtual_w * scale))
+            vh = int(math.ceil(self._virtual_h * scale))
+
+        ox = (window_w - vw) // 2
+        oy = (window_h - vh) // 2
 
         self._state = ViewportState(
             virtual_w=self._virtual_w,

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