mini-arcade-core 1.0.0__tar.gz → 1.0.2__tar.gz

{mini_arcade_core-1.0.0 → mini_arcade_core-1.0.2}/PKG-INFO

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

{mini_arcade_core-1.0.0 → mini_arcade_core-1.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "1.0.0"
+version = "1.0.2"
 description = "Tiny scene-based game loop core for small arcade games."
 authors = [
     { name = "Santiago Rincon", email = "rincores@gmail.com" },

{mini_arcade_core-1.0.0 → mini_arcade_core-1.0.2}/src/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-1.0.0 → mini_arcade_core-1.0.2}/src/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-1.0.0 → mini_arcade_core-1.0.2}/src/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-1.0.0 → mini_arcade_core-1.0.2}/src/mini_arcade_core/engine/commands.py

@@ -7,6 +7,8 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, List, Optional, Protocol, TypeVar
 
+from mini_arcade_core.runtime.scene.scene_port import ScenePolicy
+
 if TYPE_CHECKING:
     from mini_arcade_core.runtime.services import RuntimeServices
 
@@ -167,3 +169,27 @@ class ChangeSceneCommand(Command):
         context: CommandContext,
     ):
         context.services.scenes.change(self.scene_id)
+
+
+@dataclass(frozen=True)
+class ToggleDebugOverlayCommand(Command):
+    """Toggle the debug overlay scene."""
+
+    DEBUG_OVERLAY_ID = "debug_overlay"
+
+    def execute(self, context: CommandContext) -> None:
+        scenes = context.services.scenes
+        if scenes.has_scene(self.DEBUG_OVERLAY_ID):
+            scenes.remove_scene(self.DEBUG_OVERLAY_ID)
+            return
+
+        scenes.push(
+            self.DEBUG_OVERLAY_ID,
+            as_overlay=True,
+            policy=ScenePolicy(
+                blocks_update=False,
+                blocks_input=False,
+                is_opaque=False,
+                receives_input=False,
+            ),
+        )

{mini_arcade_core-1.0.0 → mini_arcade_core-1.0.2}/src/mini_arcade_core/engine/game.py

@@ -8,18 +8,19 @@ 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.backend.keys import Key
 from mini_arcade_core.engine.commands import (
     CommandContext,
     CommandQueue,
     QuitCommand,
+    ToggleDebugOverlayCommand,
 )
-
-# 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 +92,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 +178,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 +227,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 +244,15 @@ 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)
+                # if F1 pressed, toggle debug overlay
+                if e.type == EventType.KEYDOWN and e.key == Key.F1:
+                    self.command_queue.push(ToggleDebugOverlayCommand())
             timer.mark("events_polled")
 
             input_frame = self.services.input.build(events, frame_index, dt)
@@ -294,6 +308,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 +317,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 +329,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 +357,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-1.0.0 → mini_arcade_core-1.0.2}/src/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-1.0.2/src/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-1.0.0 → mini_arcade_core-1.0.2}/src/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-1.0.2/src/mini_arcade_core/runtime/audio/audio_adapter.py

@@ -0,0 +1,20 @@
+"""
+Module providing runtime adapters for window and scene management.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.runtime.audio.audio_port import AudioPort
+
+
+class SDLAudioAdapter(AudioPort):
+    """A no-op audio adapter."""
+
+    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)