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

mini_arcade_core/__init__.py

@@ -9,7 +9,8 @@ import traceback
 from importlib.metadata import PackageNotFoundError, version
 from typing import Callable, Type, Union
 
-from mini_arcade_core.engine.game import Game, GameConfig, WindowConfig
+from mini_arcade_core.engine.game import Game
+from mini_arcade_core.engine.game_config import GameConfig
 from mini_arcade_core.scenes.registry import SceneRegistry
 from mini_arcade_core.scenes.sim_scene import SimScene
 from mini_arcade_core.utils import logger
@@ -17,59 +18,31 @@ from mini_arcade_core.utils import logger
 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
+# TODO: Improve exception handliers by usingng and logging in run_game
 def run_game(
-    scene: SceneFactoryLike | None = None,
-    config: GameConfig | None = None,
-    registry: SceneRegistry | None = None,
-    initial_scene: str = "main",
+    game_config: GameConfig | None = None,
+    scene_registry: SceneRegistry | None = None,
 ):
     """
     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
+    :param game_config: Optional GameConfig to customize game settings.
+    :type game_config: GameConfig | None
 
-    :param scene: Optional SimScene factory/class to register
-    :type scene: SceneFactoryLike | None
+    :param scene_registry: Optional SceneRegistry for scene management.
+    :type scene_registry: SceneRegistry | None
 
-    :param initial_scene: The SimScene ID to start the game with.
-    :type initial_scene: str
-
-    :param config: Optional GameConfig to customize game settings.
-    :type config: GameConfig | None
-
-    :param registry: Optional SceneRegistry for scene management.
-    :type registry: SceneRegistry | None
-
-    :raises ValueError: If the provided config does not have a valid Backend.
+    :raises ValueError: If the provided game_config does not have a valid Backend.
     """
     try:
-        # Handle run_game(cfg) where the first arg is actually a GameConfig
-        if isinstance(scene, GameConfig) and config is None:
-            config = scene
-            scene = None
-
-        cfg = config or GameConfig()
+        cfg = game_config or GameConfig()
         if cfg.backend is None:
             raise ValueError(
                 "GameConfig.backend must be set to a Backend instance"
             )
 
-        # If user provided a SimScene factory/class, ensure it's registered
-        if scene is not None:
-            if registry is None:
-                registry = SceneRegistry(_factories={})
-            registry.register(
-                initial_scene, scene
-            )  # SimScene class is callable(game) -> SimScene
-
-        game = Game(cfg, registry=registry)
-        game.run(initial_scene)
+        game = Game(cfg, scene_registry=scene_registry)
+        game.run()
     # Justification: We need to catch all exceptions while we improve error handling.
     # pylint: disable=broad-exception-caught
     except Exception as e:
@@ -78,7 +51,7 @@ def run_game(
     # pylint: enable=broad-exception-caught
 
 
-PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml
+PACKAGE_NAME = "mini-arcade-core"
 
 
 def get_version() -> str:
@@ -107,7 +80,6 @@ def get_version() -> str:
 __all__ = [
     "Game",
     "GameConfig",
-    "WindowConfig",
     "run_game",
 ]
 

mini_arcade_core/backend/__init__.py

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

mini_arcade_core/backend/backend.py

@@ -5,287 +5,318 @@ 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
 
+# Justification: Many positional and keyword arguments needed for some backend methods.
+# Might be refactored later.
+# pylint: disable=too-many-positional-arguments,too-many-arguments
 
-@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.
+class WindowProtocol(Protocol):
+    """
+    Represents a game window.
     """
 
     width: int
     height: int
 
+    def set_title(self, title: str):
+        """
+        Set the window title.
 
-# 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.
+        :param title: New window title.
+        :type title: str
+        """
 
-    mini-arcade-core only talks to this protocol, never to SDL/pygame directly.
-    """
+    def resize(self, width: int, height: int):
+        """
+        Resize the window.
 
-    def init(self, window_settings: WindowSettings):
+        :param width: New width in pixels.
+        :type width: int
+        :param height: New height in pixels.
+        :type height: int
         """
-        Initialize the backend and open a window.
-        Should be called once before the main loop.
 
-        :param window_settings: Settings for the backend window.
-        :type window_settings: WindowSettings
+    def size(self) -> tuple[int, int]:
         """
+        Get the window size.
 
-    def set_window_title(self, title: str):
+        :return: Tuple of (width, height) in pixels.
+        :rtype: tuple[int, int]
         """
-        Set the window title.
 
-        :param title: The new title for the window.
-        :type title: str
+    def drawable_size(self) -> tuple[int, int]:
         """
-        raise NotImplementedError
+        Get the drawable size of the window.
 
-    def poll_events(self) -> Iterable[Event]:
+        :return: Tuple of (width, height) in pixels.
+        :rtype: tuple[int, int]
         """
-        Return all pending events since last call.
-        Concrete backends will translate their native events into core Event objects.
 
-        :return: An iterable of Event objects.
+
+class InputProtocol(Protocol):
+    """
+    Interface for input operations.
+    """
+
+    def poll(self) -> Iterable[Event]:
+        """
+        Get the list of input events since the last call.
+
+        :return: Iterable of Event instances.
         :rtype: Iterable[Event]
         """
 
+
+class RenderProtocol(Protocol):
+    """
+    Interface for rendering operations.
+    """
+
     def set_clear_color(self, r: int, g: int, b: int):
         """
-        Set the background/clear color used by begin_frame.
+        Set the clear color for the renderer.
 
         :param r: Red component (0-255).
         :type r: int
-
         :param g: Green component (0-255).
         :type g: int
-
         :param b: Blue component (0-255).
         :type b: int
         """
 
     def begin_frame(self):
-        """
-        Prepare for drawing a new frame (e.g. clear screen).
-        """
+        """Begin a new rendering frame."""
 
     def end_frame(self):
-        """
-        Present the frame to the user (swap buffers).
-        """
+        """End the current rendering frame."""
 
-    # Justification: Simple drawing API for now
-    # pylint: disable=too-many-arguments,too-many-positional-arguments
-    def draw_rect(
-        self,
-        x: int,
-        y: int,
-        w: int,
-        h: int,
-        color: Color = (255, 255, 255),
-    ):
+    def draw_rect(self, x: int, y: int, w: int, h: int, color=(255, 255, 255)):
         """
-        Draw a filled rectangle in some default color.
-        We'll keep this minimal for now; later we can extend with colors/sprites.
+        Draw a filled rectangle.
 
-        :param x: X position of the rectangle's top-left corner.
+        :param x: The x-coordinate of the rectangle.
         :type x: int
-
-        :param y: Y position of the rectangle's top-left corner.
+        :param y: The y-coordinate of the rectangle.
         :type y: int
-
-        :param w: Width of the rectangle.
+        :param w: The width of the rectangle.
         :type w: int
-
-        :param h: Height of the rectangle.
+        :param h: The height of the rectangle.
         :type h: int
-
-        :param color: RGB color tuple.
-        :type color: Color
+        :param color: The color of the rectangle as an (R, G, B) or (R, G, B, A) tuple.
+        :type color: tuple[int, int, int] | tuple[int, int, int, int]
         """
 
-    def draw_text(
-        self,
-        x: int,
-        y: int,
-        text: str,
-        color: Color = (255, 255, 255),
-        font_size: int | None = None,
+    def draw_line(
+        self, x1: int, y1: int, x2: int, y2: int, color=(255, 255, 255)
     ):
         """
-        Draw text at the given position in a default font and color.
+        Draw a line between two points.
 
-        Backends may ignore advanced styling for now; this is just to render
-        simple labels like menu items, scores, etc.
+        :param x1: The x-coordinate of the start point.
+        :type x1: int
+        :param y1: The y-coordinate of the start point.
+        :type y1: int
+        :param x2: The x-coordinate of the end point.
+        :type x2: int
+        :param y2: The y-coordinate of the end point.
+        :type y2: int
+        :param color: The color of the line as an (R, G, B) or (R, G, B, A) tuple.
+        :type color: tuple[int, int, int] | tuple[int, int, int, int]
+        """
 
-        :param x: X position of the text's top-left corner.
-        :type x: int
+    def set_clip_rect(self, x: int, y: int, w: int, h: int):
+        """
+        Set the clipping rectangle.
 
-        :param y: Y position of the text's top-left corner.
+        :param x: The x-coordinate of the clipping rectangle.
+        :type x: int
+        :param y: The y-coordinate of the clipping rectangle.
         :type y: int
+        :param w: The width of the clipping rectangle.
+        :type w: int
+        :param h: The height of the clipping rectangle.
+        :type h: int
+        """
 
-        :param text: The text string to draw.
-        :type text: str
+    def clear_clip_rect(self):
+        """Clear the clipping rectangle."""
 
-        :param color: RGB color tuple.
-        :type color: Color
-        """
 
-    # pylint: enable=too-many-arguments,too-many-positional-arguments
+class TextProtocol(Protocol):
+    """
+    Interface for text rendering operations.
+    """
 
-    def measure_text(self, text: str) -> tuple[int, int]:
+    def measure(
+        self, text: str, font_size: int | None = None
+    ) -> tuple[int, int]:
         """
-        Measure the width and height of the given text string in pixels.
+        Measure the width and height of the given text.
 
-        :param text: The text string to measure.
+        :param text: The text to measure.
         :type text: str
-
-        :return: A tuple (width, height) in pixels.
+        :param font_size: The font size to use for measurement.
+        :type font_size: int | None
+        :return: A tuple containing the width and height of the text.
         :rtype: tuple[int, int]
         """
-        raise NotImplementedError
 
-    def capture_frame(self, path: str | None = None) -> bytes | None:
+    def draw(
+        self,
+        x: int,
+        y: int,
+        text: str,
+        color=(255, 255, 255),
+        font_size: int | None = None,
+    ):
+        """
+        Draw the given text at the specified position.
+
+        :param x: The x-coordinate to draw the text.
+        :type x: int
+        :param y: The y-coordinate to draw the text.
+        :type y: int
+        :param text: The text to draw.
+        :type text: str
+        :param color: The color of the text as an (R, G, B) or (R, G, B, A) tuple.
+        :type color: tuple[int, int, int] | tuple[int, int, int, int]
+        :param font_size: The font size to use for drawing.
+        :type font_size: int | None
         """
-        Capture the current frame.
-        If `path` is provided, save to that file (e.g. PNG).
-        Returns raw bytes (PNG) or None if unsupported.
 
-        :param path: Optional file path to save the screenshot.
-        :type path: str | None
 
-        :return: Raw image bytes if no path given, else None.
-        :rtype: bytes | None
-        """
-        raise NotImplementedError
+class AudioProtocol(Protocol):
+    """
+    Interface for audio operations.
+    """
 
-    def init_audio(
+    def init(
         self, frequency: int = 44100, channels: int = 2, chunk_size: int = 2048
     ):
         """
-        Initialize SDL_mixer audio.
+        Initialize audio subsystem.
 
         :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 shutdown(self):
+        """
+        Shutdown the audio subsystem.
+        """
 
     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")
+        Load a sound file.
 
         :param sound_id: Unique identifier for the sound.
         :type sound_id: str
-
-        :param path: File path to the WAV sound.
+        :param path: File path to the 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
+        Set the master volume.
+
+        :param volume: Volume level (0-128).
+        :type volume: int
         """
 
     def set_sound_volume(self, sound_id: str, volume: int):
         """
-        Per-sound volume: 0..128
+        Set volume for a specific sound.
 
         :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
-    ):
+    def stop_all(self):
+        """
+        Stop all currently playing sounds.
         """
-        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
+class CaptureProtocol(Protocol):
+    """
+    Interface for frame capture operations.
+    """
 
-        :param scale: Scale factor.
-        :type scale: float
+    def bmp(self, path: str | None = None) -> bool:
         """
-        raise NotImplementedError
-
-    def clear_viewport_transform(self):
-        """Reset any viewport transform back to identity."""
-        raise NotImplementedError
+        Capture the current frame as a BMP file.
 
-    def resize_window(self, width: int, height: int):
+        :param path: Optional file path to save the BMP. If None, returns bytes.
+        :type path: str | None
+        :return: Whether the capture was successful.
+        :rtype: bool
         """
-        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
+# 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.
+    mini-arcade-core only talks to this protocol, never to SDL/pygame directly.
 
-    def set_clip_rect(self, x: int, y: int, w: int, h: int):
-        """
-        Set a clipping rectangle for rendering.
+    :ivar window (WindowProtocol): Window management interface.
+    :ivar audio (AudioProtocol): Audio management interface.
+    :ivar input (InputProtocol): Input management interface.
+    :ivar render (RenderProtocol): Rendering interface.
+    :ivar text (TextProtocol): Text rendering interface.
+    :ivar capture (CaptureProtocol): Frame capture interface.
+    """
 
-        :param x: X position of the rectangle's top-left corner.
-        :type x: int
+    window: WindowProtocol
+    audio: AudioProtocol
+    input: InputProtocol
+    render: RenderProtocol
+    text: TextProtocol
+    capture: CaptureProtocol
 
-        :param y: Y position of the rectangle's top-left corner.
-        :type y: int
+    def init(self):
+        """
+        Initialize the backend and open a window.
+        Should be called once before the main loop.
+        """
 
-        :param w: Width of the rectangle.
-        :type w: int
+    def set_viewport_transform(
+        self, offset_x: int, offset_y: int, scale: float
+    ):
+        """
+        Set the viewport transformation.
 
-        :param h: Height of the rectangle.
-        :type h: int
+        :param offset_x: Horizontal offset.
+        :type offset_x: int
+        :param offset_y: Vertical offset.
+        :type offset_y: int
+        :param scale: Scaling factor.
+        :type scale: float
         """
-        raise NotImplementedError
 
-    def clear_clip_rect(self):
-        """Clear any clipping rectangle."""
-        raise NotImplementedError
+    def clear_viewport_transform(self):
+        """
+        Clear the viewport transformation (reset to defaults).
+        """

mini_arcade_core/backend/types.py

@@ -6,4 +6,8 @@ from __future__ import annotations
 
 from typing import Tuple, Union
 
-Color = Union[Tuple[int, int, int], Tuple[int, int, int, int]]
+ColorRGB = Tuple[int, int, int]
+ColorRGBA = Tuple[int, int, int, int]
+
+Color = Union[ColorRGB, ColorRGBA]
+Alpha = Union[float, int]

mini_arcade_core/engine/commands.py

@@ -7,7 +7,7 @@ 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
+from mini_arcade_core.engine.scenes.models import ScenePolicy
 
 if TYPE_CHECKING:
     from mini_arcade_core.runtime.services import RuntimeServices
@@ -30,7 +30,7 @@ class CommandContext:
     """
 
     services: RuntimeServices
-    commands: Optional["CommandQueue"] = None
+    managers: object
     settings: Optional[object] = None
     world: Optional[object] = None
 
@@ -104,7 +104,7 @@ class QuitCommand(Command):
         self,
         context: CommandContext,
     ):
-        context.services.scenes.quit()
+        context.managers.scenes.quit()
 
 
 @dataclass(frozen=True)
@@ -140,7 +140,7 @@ class PushSceneCommand(Command):
         self,
         context: CommandContext,
     ):
-        context.services.scenes.push(self.scene_id, as_overlay=self.as_overlay)
+        context.managers.scenes.push(self.scene_id, as_overlay=self.as_overlay)
 
 
 @dataclass(frozen=True)
@@ -151,7 +151,7 @@ class PopSceneCommand(Command):
         self,
         context: CommandContext,
     ):
-        context.services.scenes.pop()
+        context.managers.scenes.pop()
 
 
 @dataclass(frozen=True)
@@ -168,7 +168,7 @@ class ChangeSceneCommand(Command):
         self,
         context: CommandContext,
     ):
-        context.services.scenes.change(self.scene_id)
+        context.managers.scenes.change(self.scene_id)
 
 
 @dataclass(frozen=True)
@@ -182,7 +182,7 @@ class ToggleDebugOverlayCommand(Command):
     DEBUG_OVERLAY_ID = "debug_overlay"
 
     def execute(self, context: CommandContext):
-        scenes = context.services.scenes
+        scenes = context.managers.scenes
         if scenes.has_scene(self.DEBUG_OVERLAY_ID):
             scenes.remove_scene(self.DEBUG_OVERLAY_ID)
             return
@@ -197,3 +197,22 @@ class ToggleDebugOverlayCommand(Command):
                 receives_input=False,
             ),
         )
+
+
+@dataclass(frozen=True)
+class ToggleEffectCommand(Command):
+    """
+    Toggle a post-processing effect on or off.
+
+    :ivar effect_id (str): Identifier of the effect to toggle.
+    """
+
+    effect_id: str
+
+    def execute(self, context: CommandContext):
+        # effects live in context.meta OR in a dedicated service/settings.
+        # v1 simplest: stash stack into context.settings or context.services.render
+        stack = getattr(context.settings, "effects_stack", None)
+        if stack is None:
+            return
+        stack.toggle(self.effect_id)