mini-arcade-core 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

mini_arcade_core/__init__.py

@@ -18,6 +18,8 @@ SceneFactoryLike = Union[Type[SimScene], Callable[[Game], SimScene]]
 
 
 # TODO: Improve exception handling and logging in run_game
+# TODO: Consider reducing parameters by using a single config object
+# TODO: Delegate responsibilities to Game class where appropriate
 def run_game(
     scene: SceneFactoryLike | None = None,
     config: GameConfig | None = None,
@@ -28,9 +30,12 @@ def run_game(
     Convenience helper to bootstrap and run a game with a single scene.
 
     Supports both:
-      - run_game(SceneClass, cfg)            # legacy
-      - run_game(config=cfg, initial_scene="main", registry=...)  # registry-based
-      - run_game(cfg)                       # config-only
+        - run_game(SceneClass, cfg)            # legacy
+        - run_game(config=cfg, initial_scene="main", registry=...)  # registry-based
+        - run_game(cfg)                       # config-only
+
+    :param scene: Optional SimScene factory/class to register
+    :type scene: SceneFactoryLike | None
 
     :param initial_scene: The SimScene ID to start the game with.
     :type initial_scene: str

mini_arcade_core/backend/__init__.py

@@ -6,8 +6,9 @@ This is the only part of the code that talks to SDL/pygame directly.
 
 from __future__ import annotations
 
-from .backend import Backend
+from .backend import Backend, WindowSettings
 
 __all__ = [
     "Backend",
+    "WindowSettings",
 ]

mini_arcade_core/backend/backend.py

@@ -5,12 +5,29 @@ This is the only part of the code that talks to SDL/pygame directly.
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Iterable, Protocol
 
 from .events import Event
 from .types import Color
 
 
+@dataclass
+class WindowSettings:
+    """
+    Settings for the backend window.
+
+    :ivar width (int): Width of the window in pixels.
+    :ivar height (int): Height of the window in pixels.
+    """
+
+    width: int
+    height: int
+
+
+# TODO: Refactor backend interface into smaller protocols?
+# Justification: Many public methods needed for backend interface
+# pylint: disable=too-many-public-methods
 class Backend(Protocol):
     """
     Interface that any rendering/input backend must implement.
@@ -18,19 +35,13 @@ class Backend(Protocol):
     mini-arcade-core only talks to this protocol, never to SDL/pygame directly.
     """
 
-    def init(self, width: int, height: int, title: str):
+    def init(self, window_settings: WindowSettings):
         """
         Initialize the backend and open a window.
         Should be called once before the main loop.
 
-        :param width: Width of the window in pixels.
-        :type width: int
-
-        :param height: Height of the window in pixels.
-        :type height: int
-
-        :param title: Title of the window.
-        :type title: str
+        :param window_settings: Settings for the backend window.
+        :type window_settings: WindowSettings
         """
 
     def set_window_title(self, title: str):
@@ -105,14 +116,13 @@ class Backend(Protocol):
         :type color: Color
         """
 
-    # pylint: enable=too-many-arguments,too-many-positional-arguments
-
     def draw_text(
         self,
         x: int,
         y: int,
         text: str,
         color: Color = (255, 255, 255),
+        font_size: int | None = None,
     ):
         """
         Draw text at the given position in a default font and color.
@@ -133,6 +143,8 @@ class Backend(Protocol):
         :type color: Color
         """
 
+    # pylint: enable=too-many-arguments,too-many-positional-arguments
+
     def measure_text(self, text: str) -> tuple[int, int]:
         """
         Measure the width and height of the given text string in pixels.
@@ -158,3 +170,122 @@ class Backend(Protocol):
         :rtype: bytes | None
         """
         raise NotImplementedError
+
+    def init_audio(
+        self, frequency: int = 44100, channels: int = 2, chunk_size: int = 2048
+    ):
+        """
+        Initialize SDL_mixer audio.
+
+        :param frequency: Audio frequency in Hz.
+        :type frequency: int
+
+        :param channels: Number of audio channels (1=mono, 2=stereo).
+        :type channels: int
+
+        :param chunk_size: Size of audio chunks.
+        :type chunk_size: int
+        """
+
+    def shutdown_audio(self):
+        """Shutdown SDL_mixer audio and free loaded sounds."""
+
+    def load_sound(self, sound_id: str, path: str):
+        """
+        Load a WAV sound and store it by ID.
+        Example: backend.load_sound("hit", "assets/sfx/hit.wav")
+
+        :param sound_id: Unique identifier for the sound.
+        :type sound_id: str
+
+        :param path: File path to the WAV sound.
+        :type path: str
+        """
+
+    def play_sound(self, sound_id: str, loops: int = 0):
+        """
+        Play a loaded sound.
+        loops=0 => play once
+        loops=-1 => infinite loop
+        loops=1 => play twice (SDL convention)
+
+        :param sound_id: Unique identifier for the sound.
+        :type sound_id: str
+
+        :param loops: Number of times to loop the sound.
+        :type loops: int
+        """
+
+    def set_master_volume(self, volume: int):
+        """
+        Master volume: 0..128
+        """
+
+    def set_sound_volume(self, sound_id: str, volume: int):
+        """
+        Per-sound volume: 0..128
+
+        :param sound_id: Unique identifier for the sound.
+        :type sound_id: str
+
+        :param volume: Volume level (0-128).
+        :type volume: int
+        """
+
+    def stop_all_sounds(self):
+        """Stop all channels."""
+
+    def set_viewport_transform(
+        self, offset_x: int, offset_y: int, scale: float
+    ):
+        """
+        Apply a transform so draw_* receives VIRTUAL coords and backend maps to screen.
+
+        :param offset_x: X offset in pixels.
+        :type offset_x: int
+
+        :param offset_y: Y offset in pixels.
+        :type offset_y: int
+
+        :param scale: Scale factor.
+        :type scale: float
+        """
+        raise NotImplementedError
+
+    def clear_viewport_transform(self):
+        """Reset any viewport transform back to identity."""
+        raise NotImplementedError
+
+    def resize_window(self, width: int, height: int):
+        """
+        Resize the actual OS window (SDL_SetWindowSize in native backend).
+
+        :param width: New width in pixels.
+        :type width: int
+
+        :param height: New height in pixels.
+        :type height: int
+        """
+        raise NotImplementedError
+
+    def set_clip_rect(self, x: int, y: int, w: int, h: int):
+        """
+        Set a clipping rectangle for rendering.
+
+        :param x: X position of the rectangle's top-left corner.
+        :type x: int
+
+        :param y: Y position of the rectangle's top-left corner.
+        :type y: int
+
+        :param w: Width of the rectangle.
+        :type w: int
+
+        :param h: Height of the rectangle.
+        :type h: int
+        """
+        raise NotImplementedError
+
+    def clear_clip_rect(self):
+        """Clear any clipping rectangle."""
+        raise NotImplementedError

mini_arcade_core/engine/game.py

@@ -8,18 +8,17 @@ from dataclasses import dataclass, field
 from time import perf_counter, sleep
 from typing import Dict, Literal
 
-from mini_arcade_core.backend import Backend
+from mini_arcade_core.backend import Backend, WindowSettings
+from mini_arcade_core.backend.events import EventType
 from mini_arcade_core.engine.commands import (
     CommandContext,
     CommandQueue,
     QuitCommand,
 )
-
-# from mini_arcade_core.sim.runner import SimRunner, SimRunnerConfig
 from mini_arcade_core.engine.render.packet import RenderPacket
 from mini_arcade_core.engine.render.pipeline import RenderPipeline
 from mini_arcade_core.managers.cheats import CheatManager
-from mini_arcade_core.runtime.audio.audio_adapter import NullAudioAdapter
+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.file.file_adapter import LocalFilesAdapter
 from mini_arcade_core.runtime.input.input_adapter import InputAdapter
@@ -91,7 +90,7 @@ class FrameTimer:
     :ivar marks (Dict[str, float]): Recorded time marks.
     """
 
-    enabled: bool = True
+    enabled: bool = False
     marks: Dict[str, float] = field(default_factory=dict)
 
     def mark(self, name: str):
@@ -177,9 +176,13 @@ class Game:
         self.services = RuntimeServices(
             window=WindowAdapter(
                 self.backend,
+                WindowSettings(
+                    width=self.config.window.width,
+                    height=self.config.window.height,
+                ),
             ),
             scenes=SceneAdapter(self.registry, self),
-            audio=NullAudioAdapter(),
+            audio=SDLAudioAdapter(self.backend),
             files=LocalFilesAdapter(),
             capture=CaptureAdapter(self.backend),
             input=InputAdapter(),
@@ -222,7 +225,7 @@ class Game:
         packet_cache: dict[int, RenderPacket] = {}
 
         timer = FrameTimer(enabled=True)
-        report_every = 60  # print once per second at 60fps
+        # report_every = 60  # print once per second at 60fps
 
         # TODO: Integrate SimRunner for simulation stepping
         # TODO: Fix assignment-from-no-return warning in self.services.input.build
@@ -239,6 +242,12 @@ class Game:
             last_time = now
 
             events = list(backend.poll_events())
+
+            for e in events:
+                if e.type == EventType.WINDOWRESIZED and e.size:
+                    w, h = e.size
+                    logger.debug(f"Window resized event: {w}x{h}")
+                    self.services.window.on_window_resized(w, h)
             timer.mark("events_polled")
 
             input_frame = self.services.input.build(events, frame_index, dt)
@@ -294,6 +303,7 @@ class Game:
             backend.begin_frame()
             timer.mark("begin_frame_done")
 
+            vp = self.services.window.get_viewport()
             for entry in self.services.scenes.visible_entries():
                 scene = entry.scene
                 packet = packet_cache.get(id(scene))
@@ -302,7 +312,7 @@ class Game:
                     packet = scene.tick(_neutral_input(frame_index, 0.0), 0.0)
                     packet_cache[id(scene)] = packet
 
-                pipeline.draw_packet(backend, packet)
+                pipeline.draw_packet(backend, packet, vp)
 
             timer.mark("draw_done")
             backend.end_frame()
@@ -314,12 +324,14 @@ class Game:
             timer.mark("sleep_end")
 
             # --- report ---
-            if frame_index % report_every == 0 and frame_index > 0:
-                ms = timer.report_ms()
-                total = (perf_counter() - timer.marks["frame_start"]) * 1000.0
-                logger.debug(
-                    f"[Frame {frame_index}] total={total:.2f}ms | {ms}"
-                )
+            # if timer.enabled and (
+            #     frame_index % report_every == 0 and frame_index > 0
+            # ):
+            #     ms = timer.report_ms()
+            #     total = (perf_counter() - timer.marks["frame_start"]) * 1000.0
+            #     logger.debug(
+            #         f"[Frame {frame_index}] total={total:.2f}ms | {ms}"
+            #     )
 
             frame_index += 1
 
@@ -340,6 +352,9 @@ class Game:
         br, bg, bb = self.config.window.background_color
         self.services.window.set_clear_color(br, bg, bb)
 
+        # the “authoring resolution”
+        self.services.window.set_virtual_resolution(800, 600)
+
     def _resolve_world(self) -> object | None:
         # Prefer gameplay world underneath overlays:
         # scan from top to bottom and pick the first scene that has .world

mini_arcade_core/engine/render/pipeline.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass
 
 from mini_arcade_core.backend import Backend
 from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.engine.render.viewport import ViewportState
 
 
 @dataclass
@@ -23,7 +24,12 @@ class RenderPipeline:
       - backend draw pass
     """
 
-    def draw_packet(self, backend: Backend, packet: RenderPacket):
+    def draw_packet(
+        self,
+        backend: Backend,
+        packet: RenderPacket,
+        viewport_state: ViewportState,
+    ):
         """
         Draw the given RenderPacket using the provided Backend.
 
@@ -35,5 +41,23 @@ class RenderPipeline:
         """
         if not packet:
             return
-        for op in packet.ops:
-            op(backend)
+
+        backend.set_viewport_transform(
+            viewport_state.offset_x,
+            viewport_state.offset_y,
+            viewport_state.scale,
+        )
+
+        # backend.set_clip_rect(
+        #     viewport_state.offset_x,
+        #     viewport_state.offset_y,
+        #     viewport_state.viewport_w,
+        #     viewport_state.viewport_h,
+        # )
+
+        try:
+            for op in packet.ops:
+                op(backend)
+        finally:
+            backend.clear_clip_rect()
+            backend.clear_viewport_transform()

mini_arcade_core/engine/render/viewport.py

@@ -0,0 +1,203 @@
+"""
+Viewport management for virtual to screen coordinate transformations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from mini_arcade_core.utils import logger
+
+
+class ViewportMode(str, Enum):
+    """
+    Viewport scaling modes.
+
+    :cvar FIT: Scale to fit within window, preserving aspect ratio (letterbox).
+    :cvar FILL: Scale to fill entire window, preserving aspect ratio (crop).
+    """
+
+    FIT = "fit"  # letterbox
+    FILL = "fill"  # crop
+
+
+# Justification: Many attributes needed to describe viewport state
+# pylint: disable=too-many-instance-attributes
+@dataclass(frozen=True)
+class ViewportState:
+    """
+    Current state of the viewport.
+
+    :ivar virtual_w (int): Virtual canvas width.
+    :ivar virtual_h (int): Virtual canvas height.
+    :ivar window_w (int): Current window width.
+    :ivar window_h (int): Current window height.
+    :ivar mode (ViewportMode): Current viewport mode.
+    :ivar scale (float): Current scale factor.
+    :ivar viewport_w (int): Width of the viewport rectangle on screen.
+    :ivar viewport_h (int): Height of the viewport rectangle on screen.
+    :ivar offset_x (int): X offset of the viewport rectangle on screen.
+    :ivar offset_y (int): Y offset of the viewport rectangle on screen.
+    """
+
+    virtual_w: int
+    virtual_h: int
+
+    window_w: int
+    window_h: int
+
+    mode: ViewportMode
+    scale: float
+
+    # viewport rect in screen pixels where the virtual canvas lands
+    # (can be larger than window in FILL mode -> offsets can be negative)
+    viewport_w: int
+    viewport_h: int
+    offset_x: int
+    offset_y: int
+
+
+# pylint: enable=too-many-instance-attributes
+
+
+class Viewport:
+    """
+    Manages viewport transformations between virtual and screen coordinates.
+    """
+
+    def __init__(
+        self,
+        virtual_w: int,
+        virtual_h: int,
+        mode: ViewportMode = ViewportMode.FIT,
+    ):
+        """
+        :param virtual_w: Virtual canvas width.
+        :type virtual_w: int
+
+        :param virtual_h: Virtual canvas height.
+        :type virtual_h: int
+
+        :param mode: Viewport scaling mode.
+        :type mode: ViewportMode
+        """
+        self._virtual_w = int(virtual_w)
+        self._virtual_h = int(virtual_h)
+        self._mode = mode
+        self._state: ViewportState | None = None
+
+    def set_virtual_resolution(self, w: int, h: int):
+        """
+        Set a new virtual resolution.
+
+        :param w: New virtual width.
+        :type w: int
+
+        :param h: New virtual height.
+        :type h: int
+        """
+        self._virtual_w = int(w)
+        self._virtual_h = int(h)
+        if self._state:
+            self.resize(self._state.window_w, self._state.window_h)
+
+    def set_mode(self, mode: ViewportMode):
+        """
+        Set a new viewport mode.
+
+        :param mode: New viewport mode.
+        :type mode: ViewportMode
+        """
+        self._mode = mode
+        if self._state:
+            self.resize(self._state.window_w, self._state.window_h)
+
+    def resize(self, window_w: int, window_h: int):
+        """
+        Resize the viewport based on the current window size.
+
+        :param window_w: Current window width.
+        :type window_w: int
+
+        :param window_h: Current window height.
+        :type window_h: int
+        """
+        window_w = int(window_w)
+        window_h = int(window_h)
+
+        sx = window_w / self._virtual_w
+        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))
+
+        self._state = ViewportState(
+            virtual_w=self._virtual_w,
+            virtual_h=self._virtual_h,
+            window_w=window_w,
+            window_h=window_h,
+            mode=self._mode,
+            scale=float(scale),
+            viewport_w=vw,
+            viewport_h=vh,
+            offset_x=ox,
+            offset_y=oy,
+        )
+        logger.debug(
+            f"Viewport resized: window=({window_w}x{window_h}), "
+            f"virtual=({self._virtual_w}x{self._virtual_h}), "
+            f"mode={self._mode}, scale={scale:.3f}, "
+            f"viewport=({vw}x{vh})@({ox},{oy})"
+        )
+
+    @property
+    def state(self) -> ViewportState:
+        """
+        Get the current viewport state.
+
+        :return: Current ViewportState.
+        :rtype: ViewportState
+
+        :raises RuntimeError: If the viewport has not been initialized.
+        """
+        if self._state is None:
+            raise RuntimeError(
+                "Viewport not initialized. Call resize(window_w, window_h)."
+            )
+        return self._state
+
+    def screen_to_virtual(self, x: float, y: float) -> tuple[float, float]:
+        """
+        Convert screen coordinates to virtual coordinates.
+
+        :param x: X coordinate on the screen.
+        :type x: float
+
+        :param y: Y coordinate on the screen.
+        :type y: float
+
+        :return: Corresponding virtual coordinates (x, y).
+        :rtype: tuple[float, float]
+        """
+        s = self.state
+        return ((x - s.offset_x) / s.scale, (y - s.offset_y) / s.scale)
+
+    def virtual_to_screen(self, x: float, y: float) -> tuple[float, float]:
+        """
+        Convert virtual coordinates to screen coordinates.
+
+        :param x: X coordinate in virtual space.
+        :type x: float
+
+        :param y: Y coordinate in virtual space.
+        :type y: float
+
+        :return: Corresponding screen coordinates (x, y).
+        :rtype: tuple[float, float]
+        """
+        s = self.state
+        return (s.offset_x + x * s.scale, s.offset_y + y * s.scale)

mini_arcade_core/managers/inputs.py

@@ -143,8 +143,6 @@ class InputManager:
                 )
                 binding.command.execute(to_inject)
 
-    # --- Convenience API ------------------------------------------------------
-
     def on_quit(self, command: BaseCommand, action: str = "quit"):
         """
         Bind a command to the QUIT event.

mini_arcade_core/runtime/audio/audio_adapter.py

@@ -7,7 +7,14 @@ from __future__ import annotations
 from mini_arcade_core.runtime.audio.audio_port import AudioPort
 
 
-class NullAudioAdapter(AudioPort):
+class SDLAudioAdapter(AudioPort):
     """A no-op audio adapter."""
 
-    def play(self, sound_id: str): ...
+    def __init__(self, backend):
+        self.backend = backend
+
+    def load_sound(self, sound_id: str, file_path: str):
+        self.backend.load_sound(sound_id, file_path)
+
+    def play(self, sound_id: str, loops: int = 0):
+        self.backend.play_sound(sound_id, loops)

mini_arcade_core/runtime/audio/audio_port.py

@@ -4,14 +4,33 @@ Service interfaces for runtime components.
 
 from __future__ import annotations
 
+from mini_arcade_core.backend.backend import Backend
+
 
 class AudioPort:
     """Interface for audio playback operations."""
 
-    def play(self, sound_id: str):
+    backend: Backend
+
+    def load_sound(self, sound_id: str, file_path: str):
+        """
+        Load a sound from a file and associate it with an identifier.
+
+        :param sound_id: Identifier to associate with the sound.
+        :type sound_id: str
+
+        :param file_path: Path to the sound file.
+        :type file_path: str
+        """
+
+    def play(self, sound_id: str, loops: int = 0):
         """
         Play the specified sound.
 
         :param sound_id: Identifier of the sound to play.
         :type sound_id: str
+
+        :param loops: Number of times to loop the sound.
+            0 = play once, -1 = infinite loop, 1 = play twice, etc.
+        :type loops: int
         """

mini_arcade_core/runtime/capture/capture_port.py

@@ -30,3 +30,22 @@ class CapturePort:
         :return: Screenshot data as bytes.
         :rtype: bytes | None
         """
+
+    def screenshot_sim(
+        self, run_id: str, frame_index: int, label: str = "frame"
+    ) -> str:
+        """
+        Capture the current frame in a simulation context.
+
+        :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: Optional label for the screenshot file.
+        :type label: str
+
+        :return: Screenshot file path.
+        :rtype: str
+        """

mini_arcade_core/runtime/window/window_adapter.py

@@ -4,6 +4,13 @@ Module providing runtime adapters for window and scene management.
 
 from __future__ import annotations
 
+from venv import logger
+
+from mini_arcade_core.engine.render.viewport import (
+    Viewport,
+    ViewportMode,
+    ViewportState,
+)
 from mini_arcade_core.runtime.window.window_port import WindowPort
 
 
@@ -12,15 +19,72 @@ class WindowAdapter(WindowPort):
     Manages multiple game windows (not implemented).
     """
 
-    def __init__(self, backend):
+    def __init__(self, backend, window_settings):
         self.backend = backend
+        self.window_settings = window_settings
+
+        self._initialized = False
+
+        # 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 set_window_size(self, width, height):
+        width = int(width)
+        height = int(height)
         self.size = (width, height)
-        self.backend.init(width, height)
+
+        self.window_settings.width = width
+        self.window_settings.height = height
+
+        if not self._initialized:
+            self.backend.init(self.window_settings)
+            self._initialized = True
+        else:
+            self.backend.resize_window(width, height)
+
+        self._viewport.resize(width, height)
+
+    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
+        self._viewport.resize(w, h)
+
+    def set_viewport_mode(self, mode: ViewportMode):
+        self._viewport.set_mode(mode)
+
+    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)
 
     def set_title(self, title):
         self.backend.set_window_title(title)
 
     def set_clear_color(self, r, g, b):
         self.backend.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
+
+        self._viewport.resize(width, height)
+
+    def get_virtual_size(self) -> tuple[int, int]:
+        s = self.get_viewport()
+        return (s.virtual_w, s.virtual_h)

mini_arcade_core/runtime/window/window_port.py

@@ -4,7 +4,8 @@ Service interfaces for runtime components.
 
 from __future__ import annotations
 
-from mini_arcade_core.backend import Backend
+from mini_arcade_core.backend import Backend, WindowSettings
+from mini_arcade_core.engine.render.viewport import ViewportMode, ViewportState
 
 
 class WindowPort:
@@ -12,6 +13,7 @@ class WindowPort:
 
     backend: Backend
     size: tuple[int, int]
+    window_settings_cls: WindowSettings
 
     def set_window_size(self, width: int, height: int):
         """
@@ -24,6 +26,47 @@ class WindowPort:
         :type height: int
         """
 
+    def set_viewport_mode(self, mode: ViewportMode):
+        """
+        Set the viewport mode for rendering.
+
+        :param mode: The viewport mode to set.
+        :type mode: ViewportMode
+        """
+
+    def get_viewport(self) -> ViewportState:
+        """
+        Get the current viewport state.
+
+        :return: The current ViewportState.
+        :rtype: ViewportState
+        """
+
+    def screen_to_virtual(self, x: float, y: float) -> tuple[float, float]:
+        """
+        Convert screen coordinates to virtual coordinates.
+
+        :param x: X coordinate on the screen.
+        :type x: float
+
+        :param y: Y coordinate on the screen.
+        :type y: float
+
+        :return: Corresponding virtual coordinates (x, y).
+        :rtype: tuple[float, float]
+        """
+
+    def set_virtual_resolution(self, width: int, height: int):
+        """
+        Set the virtual resolution for rendering.
+
+        :param width: Virtual width in pixels.
+        :type width: int
+
+        :param height: Virtual height in pixels.
+        :type height: int
+        """
+
     def set_title(self, title: str):
         """
         Set the window title.
@@ -45,3 +88,22 @@ class WindowPort:
         :param b: Blue component (0-255).
         :type b: int
         """
+
+    def on_window_resized(self, width: int, height: int):
+        """
+        Handle window resized event.
+
+        :param width: New width of the window.
+        :type width: int
+
+        :param height: New height of the window.
+        :type height: int
+        """
+
+    def get_virtual_size(self) -> tuple[int, int]:
+        """
+        Get the current virtual resolution size.
+
+        :return: Tuple of (virtual_width, virtual_height).
+        :rtype: tuple[int, int]
+        """

mini_arcade_core/spaces/d2/boundaries2d.py

@@ -39,25 +39,34 @@ class VerticalBounce:
 
     bounds: Bounds2D
 
-    def apply(self, obj: RectKinematic):
+    def apply(self, obj: RectKinematic) -> bool:
         """
         Apply vertical bounce to the given object.
 
         :param obj: The object to apply the bounce to.
         :type obj: RectKinematic
+
+        :return: True if a bounce occurred, False otherwise.
+        :rtype: bool
         """
         top = self.bounds.top
         bottom = self.bounds.bottom
 
+        bounced = False
+
         # Top collision
         if obj.position.y <= top:
             obj.position.y = top
             obj.velocity.vy *= -1
+            bounced = True
 
         # Bottom collision
         if obj.position.y + obj.size.height >= bottom:
             obj.position.y = bottom - obj.size.height
             obj.velocity.vy *= -1
+            bounced = True
+
+        return bounced
 
 
 class RectSprite(Protocol):

mini_arcade_core/ui/menu.py

@@ -128,6 +128,7 @@ class MenuStyle:
 class Menu:
     """A simple text-based menu system."""
 
+    # TODO: Solve too-many-arguments warning later
     # Justification: Multiple attributes for menu state
     # pylint: disable=too-many-arguments
     def __init__(
@@ -151,6 +152,9 @@ class Menu:
 
         :param style: Optional MenuStyle for customizing appearance.
         :type style: MenuStyle | None
+
+        :param on_select: Optional callback when an item is selected.
+        :type on_select: Optional[Callable[[MenuItem], None]]
         """
         self.items = list(items)
         self.viewport = viewport
@@ -250,6 +254,7 @@ class Menu:
 
         return False
 
+    # TODO: Delegate drawing to a renderer class later
     def draw(self, surface: Backend):
         """
         Draw the menu onto the given backend surface.
@@ -342,6 +347,7 @@ class Menu:
                 font_size=self.style.item_font_size,
             )
 
+    # TODO: Solve too-many-locals warning later
     # Justification: Local variables for layout calculations
     # pylint: disable=too-many-locals
     def _draw_buttons(self, surface: Backend, x_center: int, cursor_y: int):
@@ -454,13 +460,14 @@ class Menu:
                 + self.style.title_margin_bottom
             )
 
-        # ✅ Sticky width (never shrink)
+        # Sticky width (never shrink)
         if self.stable_width:
             self._max_content_w_seen = max(self._max_content_w_seen, max_w)
             max_w = self._max_content_w_seen
 
         return max_w, content_h, title_h
 
+    # TODO: Solve too-many-arguments warning later
     # Justification: Many arguments for text drawing utility
     # pylint: disable=too-many-arguments
     @staticmethod
@@ -674,8 +681,6 @@ class BaseMenuScene(SimScene):
         super().__init__(ctx)
         self.model = MenuModel()
 
-    # ---- hooks (same spirit as before) ----
-
     @property
     def menu_title(self) -> str | None:
         """
@@ -717,7 +722,7 @@ class BaseMenuScene(SimScene):
     def on_enter(self):
         self.menu = Menu(
             self._build_display_items(),
-            viewport=self.context.services.window.size,
+            viewport=self.context.services.window.get_virtual_size(),
             title=self.menu_title,
             style=self.menu_style(),
         )

mini_arcade_core/utils/logging.py

@@ -1,5 +1,6 @@
 """
 Logging utilities for Mini Arcade Core.
+Provides a console logger with colored output and class/function context.
 """
 
 from __future__ import annotations
@@ -11,6 +12,7 @@ from typing import Optional
 
 
 def _classname_from_locals(locals_: dict) -> Optional[str]:
+    """Retrieve the class name from locals dict, if available."""
     self_obj = locals_.get("self")
     if self_obj is not None:
         return type(self_obj).__name__
@@ -73,10 +75,6 @@ class ConsoleColorFormatter(logging.Formatter):
         return f"{color}{msg}{self.COLORS['RESET']}"
 
 
-# --------------------------------------------------------------------------------------
-# Global logging setup (single source of truth)
-# --------------------------------------------------------------------------------------
-
 LOGGER_FORMAT = (
     "%(asctime)s [%(levelname)-8.8s] [%(name)s] "
     "%(module)s.%(classname)s.%(funcName)s: "
@@ -166,9 +164,5 @@ def configure_logging(level: int = logging.DEBUG):
     root.addHandler(console)
 
 
-# --------------------------------------------------------------------------------------
-# Public logger for DejaBounce
-# --------------------------------------------------------------------------------------
-
 configure_logging()
 logger = logging.getLogger("mini-arcade-core")

{mini_arcade_core-1.0.0.dist-info → mini_arcade_core-1.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 1.0.0
+Version: 1.0.1
 Summary: Tiny scene-based game loop core for small arcade games.
 License: Copyright (c) 2025 Santiago Rincón
            

{mini_arcade_core-1.0.0.dist-info → mini_arcade_core-1.0.1.dist-info}/RECORD

@@ -1,6 +1,6 @@
-mini_arcade_core/__init__.py,sha256=Cyp7bCkNW018_AlhUGXRH29iPytyW03dE5cvetezxLg,3441
-mini_arcade_core/backend/__init__.py,sha256=J1wZBHX-aqmBP3zh_ey9PK2b_gnWp72zxMfKcs3iwSw,274
-mini_arcade_core/backend/backend.py,sha256=9CYcI7llbUhyO1p3Rjl-jmsw2c3KsQUtPAx0ys-WnW4,4237
+mini_arcade_core/__init__.py,sha256=axwl7fiQ2Zu2vPOTMUxwnvR746gI9RhpBWpBCId_yqo,3686
+mini_arcade_core/backend/__init__.py,sha256=E9uOCttCkXwdN_5MlcFHUmG3Bj6RYMatNNOno4C_6aI,312
+mini_arcade_core/backend/backend.py,sha256=RpFclQFDOLSaqCACWR0sT_OQYjDIfYzQaFvnHzURLvI,7788
 mini_arcade_core/backend/events.py,sha256=5Ohve3CQ6n2CztiOhbCoz6yFDY4z0j4v4R9FBKRDRjc,2929
 mini_arcade_core/backend/keys.py,sha256=LTg20SwLBI3kpPIiTNpq2yBft_QUGj-iNFSNm9M-Fus,3010
 mini_arcade_core/backend/sdl_map.py,sha256=_yBRtvaFUcQKy1kcoIf-SPhbbKEW7dzvzBcI6TLmKjc,2060
@@ -8,20 +8,21 @@ mini_arcade_core/backend/types.py,sha256=SuiwXGNmXCZxfPsww6zj3V_NK7k4jpoCuzMn19a
 mini_arcade_core/bus.py,sha256=2Etpoa-UWhk33xJjqDlY5YslPDJEjxNoIEVtF3C73vs,1558
 mini_arcade_core/engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/engine/commands.py,sha256=1g7XBWmiVYxe2IUggPpUs5uaZP9PHZKfr6cQuhez8eg,4044
-mini_arcade_core/engine/game.py,sha256=ovfSCNczMN8Tu-rj83reHKl32OKEa649PwMbshlLpac,11479
+mini_arcade_core/engine/game.py,sha256=hq7cYdiQrPFNagc1BbARhzXYMBtFzCaTcTKQnNBDqy0,12137
 mini_arcade_core/engine/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/engine/render/packet.py,sha256=OiAPwGoVHo04OcUWMAoA_N1AFPUMyf8yxNgJthGj4-c,1440
-mini_arcade_core/engine/render/pipeline.py,sha256=4Pdwwt-fo4dK3uqPb3M_IiRIDxymilAK8fOaiojsl10,891
+mini_arcade_core/engine/render/pipeline.py,sha256=XdnzAXNle8_CJOPzYJaEy9Dp_UgoCgJwIh-GpW9-n5E,1516
+mini_arcade_core/engine/render/viewport.py,sha256=fbzH3_rc27IGUtDalmxz5cukwHnpt1kopIeVqmTab20,5784
 mini_arcade_core/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/managers/cheats.py,sha256=jMx2a8YnaNCkCG5MPmIzz4uHuS7-_aYf0J45cv2-3v0,5569
-mini_arcade_core/managers/inputs.py,sha256=LL0Q_QYUF3K1orpLIrmYXOadBUascyJVpd2KYvpTNDU,8605
+mini_arcade_core/managers/inputs.py,sha256=9HZ0BnJyUX-elfGETPhhPZnTkz2bK83pEKj7GHPbPFU,8523
 mini_arcade_core/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/audio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/runtime/audio/audio_adapter.py,sha256=CEMYbAhCT1MoIsH6PTqu2kE6iOCcB7SwnFjBqk3hLlc,286
-mini_arcade_core/runtime/audio/audio_port.py,sha256=idUxRIr_qga46gL31_GMwQ3j-zfNyuyYC-Ygkl_tIO4,338
+mini_arcade_core/runtime/audio/audio_adapter.py,sha256=9ithbInYUB72ErwvlNrbIlI55uw0DT2QD33geYNXT3c,522
+mini_arcade_core/runtime/audio/audio_port.py,sha256=3Mqv7TchEVkmd-RVjUpCD-EqA-yiL0Jf2Sj3rQwP678,907
 mini_arcade_core/runtime/capture/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/capture/capture_adapter.py,sha256=qJ2JiOLJHbP00IesbAyyPGPBxSaxwPJRTMaMjMU4bXs,4660
-mini_arcade_core/runtime/capture/capture_port.py,sha256=lZme02Cs9aeb_qpZnAz3sClZieG-lFc05wbFPCyB4_I,704
+mini_arcade_core/runtime/capture/capture_port.py,sha256=NVxMJrQJELiSYuUJ29tvsdIcCBq4f1dTT2rDLZs6gnI,1230
 mini_arcade_core/runtime/context.py,sha256=IQpAhtbN0ZqJVXG6KXFq3FPk0sIGyPmyNgBYviqZl7A,1632
 mini_arcade_core/runtime/file/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/file/file_adapter.py,sha256=09q7G9Qijml9d4AAjo6HLC1yuoVTjE_7xaT8apT4mk0,523
@@ -35,8 +36,8 @@ mini_arcade_core/runtime/scene/scene_adapter.py,sha256=dYkqFWN3FcRmf9tsZ5wz1QZX6
 mini_arcade_core/runtime/scene/scene_port.py,sha256=uDFrN7fudIldNkivEkagQd9-b1HVI71BpTpSv5Oh6JI,3854
 mini_arcade_core/runtime/services.py,sha256=9LX7O-AYFTxKgBDewzu0B_D01EJ41WVAdl8U1ZcvEYg,1061
 mini_arcade_core/runtime/window/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/runtime/window/window_adapter.py,sha256=EMSWE72aWWzCN0uRuVJvry3g2PQTBmEa_zEfgK6weKY,637
-mini_arcade_core/runtime/window/window_port.py,sha256=HwY8ilhZLLK5cZbEA93R5crjOA4i8Gn2MB8y4BbI4o4,988
+mini_arcade_core/runtime/window/window_adapter.py,sha256=_yCcJwvHN0gEPh0rkgLEKtPZ50qRbONsUTbgtV1m7Y8,2689
+mini_arcade_core/runtime/window/window_port.py,sha256=JbSH549De7fa4ifQ0EH5QQoq03Got1n9C4qViLgciUU,2682
 mini_arcade_core/scenes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/scenes/autoreg.py,sha256=wsuY7YUSZFmDyToKHFriAG78OU48-7J4BfL_X6T5GBg,1037
 mini_arcade_core/scenes/registry.py,sha256=EF5qaAgoLwJa3IV_3wclvjHpE3jZt-KHB3GOJS9lQy8,3390
@@ -49,17 +50,17 @@ mini_arcade_core/sim/protocols.py,sha256=b7d2WAKRokTNbteNhUaWdGx9vc9Fnccxb-5rPwo
 mini_arcade_core/sim/runner.py,sha256=ZF-BZJw-NcaFrg4zsUu1zOUUBZwZbRYflqcdF1jDcmM,7446
 mini_arcade_core/spaces/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/spaces/d2/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/spaces/d2/boundaries2d.py,sha256=H1HkCR1422MkQIEve2DFKvnav4RpvtLx-qTMxzmdDMQ,2610
+mini_arcade_core/spaces/d2/boundaries2d.py,sha256=xeTnd0pW5DKfqaKsfSBXnufeb45aXNIspgHRyLXWejo,2804
 mini_arcade_core/spaces/d2/collision2d.py,sha256=5IvgLnyVb8i0uzzZuum1noWsNhoxcvHOLaHkmrTMTxQ,1710
 mini_arcade_core/spaces/d2/geometry2d.py,sha256=FuYzef-XdOyb1aeGLJbxINxr0WJHnqFFBgtbPi1WonY,1716
 mini_arcade_core/spaces/d2/kinematics2d.py,sha256=AJ3DhPXNgm6wZYwCljMIE4_2BYx3E2rPcwhXTgQALkU,2030
 mini_arcade_core/spaces/d2/physics2d.py,sha256=OQT7r-zMtmoKD2aWCSNmRAdI0OGIpxGX-pLR8LcAMbQ,1854
 mini_arcade_core/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/ui/menu.py,sha256=94W9lFI0qVB-v-f0b5U05p-MTmzaa5H1RGxy-1S01go,24345
+mini_arcade_core/ui/menu.py,sha256=pUC6qfG3lNXa1Ga2Kz_cSgjiAfAWVMRevum61G_RE8k,24646
 mini_arcade_core/utils/__init__.py,sha256=3Q9r6bTyqImYix8BnOGwWjAz25nbTQezGcRq3m5KEYE,189
 mini_arcade_core/utils/deprecated_decorator.py,sha256=yrrW2ZqPskK-4MUTyIrMb465Wc54X2poV53ZQutZWqc,1140
-mini_arcade_core/utils/logging.py,sha256=IqkM1C5yezb3qnmqlftROlHO6mBCW0iWQmyIR9mwd-4,5576
-mini_arcade_core-1.0.0.dist-info/METADATA,sha256=hMAIBh7Kk29GpAzrP4LziqDT3fzHc0SoiNmhz8A70YY,8188
-mini_arcade_core-1.0.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-mini_arcade_core-1.0.0.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-1.0.0.dist-info/RECORD,,
+mini_arcade_core/utils/logging.py,sha256=YyirsGRSpGtxegUl3HWz37mGNngK3QkYm2_aZjXJC84,5279
+mini_arcade_core-1.0.1.dist-info/METADATA,sha256=zon5lZWKZ3_tLUoLgjItQRCTWBxLEzHSOp1IyhNGH14,8188
+mini_arcade_core-1.0.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+mini_arcade_core-1.0.1.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-1.0.1.dist-info/RECORD,,