mini-arcade-core 1.1.1__tar.gz → 1.2.1__tar.gz

{mini_arcade_core-1.1.1 → mini_arcade_core-1.2.1}/PKG-INFO

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

{mini_arcade_core-1.1.1 → mini_arcade_core-1.2.1}/pyproject.toml

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

mini_arcade_core-1.2.1/src/mini_arcade_core/__init__.py

@@ -0,0 +1,86 @@
+"""
+Entry point for the mini_arcade_core package.
+Provides access to core classes and a convenience function to run a game.
+"""
+
+from __future__ import annotations
+
+import traceback
+from importlib.metadata import PackageNotFoundError, version
+from typing import Callable, Type, Union
+
+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
+
+SceneFactoryLike = Union[Type[SimScene], Callable[[Game], SimScene]]
+
+
+# TODO: Improve exception handliers by usingng and logging in run_game
+def run_game(
+    game_config: GameConfig | None = None,
+    scene_registry: SceneRegistry | None = None,
+):
+    """
+    Convenience helper to bootstrap and run a game with a single scene.
+
+    :param game_config: Optional GameConfig to customize game settings.
+    :type game_config: GameConfig | None
+
+    :param scene_registry: Optional SceneRegistry for scene management.
+    :type scene_registry: SceneRegistry | None
+
+    :raises ValueError: If the provided game_config does not have a valid Backend.
+    """
+    try:
+        cfg = game_config or GameConfig()
+        if cfg.backend is None:
+            raise ValueError(
+                "GameConfig.backend must be set to a Backend instance"
+            )
+
+        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:
+        logger.exception(f"Unhandled exception in game loop: {e}")
+        logger.debug(traceback.format_exc())
+    # pylint: enable=broad-exception-caught
+
+
+PACKAGE_NAME = "mini-arcade-core"
+
+
+def get_version() -> str:
+    """
+    Return the installed package version.
+
+    This is a thin helper around importlib.metadata.version so games can do:
+
+        from mini_arcade_core import get_version
+        print(get_version())
+
+    :return: The version string of the installed package.
+    :rtype: str
+
+    :raises PackageNotFoundError: If the package is not installed.
+    """
+    try:
+        return version(PACKAGE_NAME)
+    except PackageNotFoundError:  # if running from source / editable
+        logger.warning(
+            f"Package '{PACKAGE_NAME}' not found. Returning default version '0.0.0'."
+        )
+        return "0.0.0"
+
+
+__all__ = [
+    "Game",
+    "GameConfig",
+    "run_game",
+]
+
+__version__ = get_version()

{mini_arcade_core-1.1.1 → mini_arcade_core-1.2.1}/src/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-1.2.1/src/mini_arcade_core/backend/backend.py

@@ -0,0 +1,322 @@
+"""
+Backend interface for rendering and input.
+This is the only part of the code that talks to SDL/pygame directly.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Protocol
+
+from .events import Event
+
+# Justification: Many positional and keyword arguments needed for some backend methods.
+# Might be refactored later.
+# pylint: disable=too-many-positional-arguments,too-many-arguments
+
+
+class WindowProtocol(Protocol):
+    """
+    Represents a game window.
+    """
+
+    width: int
+    height: int
+
+    def set_title(self, title: str):
+        """
+        Set the window title.
+
+        :param title: New window title.
+        :type title: str
+        """
+
+    def resize(self, width: int, height: int):
+        """
+        Resize the window.
+
+        :param width: New width in pixels.
+        :type width: int
+        :param height: New height in pixels.
+        :type height: int
+        """
+
+    def size(self) -> tuple[int, int]:
+        """
+        Get the window size.
+
+        :return: Tuple of (width, height) in pixels.
+        :rtype: tuple[int, int]
+        """
+
+    def drawable_size(self) -> tuple[int, int]:
+        """
+        Get the drawable size of the window.
+
+        :return: Tuple of (width, height) in pixels.
+        :rtype: tuple[int, int]
+        """
+
+
+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 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):
+        """Begin a new rendering frame."""
+
+    def end_frame(self):
+        """End the current rendering frame."""
+
+    def draw_rect(self, x: int, y: int, w: int, h: int, color=(255, 255, 255)):
+        """
+        Draw a filled rectangle.
+
+        :param x: The x-coordinate of the rectangle.
+        :type x: int
+        :param y: The y-coordinate of the rectangle.
+        :type y: int
+        :param w: The width of the rectangle.
+        :type w: int
+        :param h: The height of the rectangle.
+        :type h: int
+        :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_line(
+        self, x1: int, y1: int, x2: int, y2: int, color=(255, 255, 255)
+    ):
+        """
+        Draw a line between two points.
+
+        :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]
+        """
+
+    def set_clip_rect(self, x: int, y: int, w: int, h: int):
+        """
+        Set the clipping rectangle.
+
+        :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
+        """
+
+    def clear_clip_rect(self):
+        """Clear the clipping rectangle."""
+
+
+class TextProtocol(Protocol):
+    """
+    Interface for text rendering operations.
+    """
+
+    def measure(
+        self, text: str, font_size: int | None = None
+    ) -> tuple[int, int]:
+        """
+        Measure the width and height of the given text.
+
+        :param text: The text to measure.
+        :type text: str
+        :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]
+        """
+
+    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
+        """
+
+
+class AudioProtocol(Protocol):
+    """
+    Interface for audio operations.
+    """
+
+    def init(
+        self, frequency: int = 44100, channels: int = 2, chunk_size: int = 2048
+    ):
+        """
+        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(self):
+        """
+        Shutdown the audio subsystem.
+        """
+
+    def load_sound(self, sound_id: str, path: str):
+        """
+        Load a sound file.
+
+        :param sound_id: Unique identifier for the sound.
+        :type sound_id: str
+        :param path: File path to the sound.
+        :type path: str
+        """
+
+    def play_sound(self, sound_id: str, loops: int = 0):
+        """
+        Play a loaded sound.
+
+        :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):
+        """
+        Set the master volume.
+
+        :param volume: Volume level (0-128).
+        :type volume: int
+        """
+
+    def set_sound_volume(self, sound_id: str, volume: int):
+        """
+        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(self):
+        """
+        Stop all currently playing sounds.
+        """
+
+
+class CaptureProtocol(Protocol):
+    """
+    Interface for frame capture operations.
+    """
+
+    def bmp(self, path: str | None = None) -> bool:
+        """
+        Capture the current frame as a BMP file.
+
+        :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
+        """
+
+
+# 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.
+
+    :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.
+    """
+
+    window: WindowProtocol
+    audio: AudioProtocol
+    input: InputProtocol
+    render: RenderProtocol
+    text: TextProtocol
+    capture: CaptureProtocol
+
+    def init(self):
+        """
+        Initialize the backend and open a window.
+        Should be called once before the main loop.
+        """
+
+    def set_viewport_transform(
+        self, offset_x: int, offset_y: int, scale: float
+    ):
+        """
+        Set the viewport transformation.
+
+        :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
+        """
+
+    def clear_viewport_transform(self):
+        """
+        Clear the viewport transformation (reset to defaults).
+        """

mini_arcade_core-1.2.1/src/mini_arcade_core/backend/types.py

@@ -0,0 +1,13 @@
+"""
+Types used in the backend module.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple, Union
+
+ColorRGB = Tuple[int, int, int]
+ColorRGBA = Tuple[int, int, int, int]
+
+Color = Union[ColorRGB, ColorRGBA]
+Alpha = Union[float, int]

{mini_arcade_core-1.1.1 → mini_arcade_core-1.2.1}/src/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
@@ -209,7 +209,7 @@ class ToggleEffectCommand(Command):
 
     effect_id: str
 
-    def execute(self, context: CommandContext) -> None:
+    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)

mini_arcade_core-1.2.1/src/mini_arcade_core/engine/game.py

@@ -0,0 +1,154 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.engine.cheats import CheatManager
+from mini_arcade_core.engine.commands import CommandQueue
+from mini_arcade_core.engine.game_config import GameConfig
+from mini_arcade_core.engine.gameplay_settings import GamePlaySettings
+from mini_arcade_core.engine.loop.config import RunnerConfig
+from mini_arcade_core.engine.loop.hooks import DefaultGameHooks
+from mini_arcade_core.engine.loop.runner import EngineRunner
+from mini_arcade_core.engine.managers import EngineManagers
+from mini_arcade_core.engine.render.effects.base import (
+    EffectParams,
+    EffectStack,
+)
+from mini_arcade_core.engine.render.effects.crt import CRTEffect
+from mini_arcade_core.engine.render.effects.registry import EffectRegistry
+from mini_arcade_core.engine.render.effects.vignette import VignetteNoiseEffect
+from mini_arcade_core.engine.render.pipeline import RenderPipeline
+from mini_arcade_core.engine.render.render_service import RenderService
+from mini_arcade_core.engine.scenes.scene_manager import SceneAdapter
+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
+from mini_arcade_core.runtime.scene.scene_query_adapter import (
+    SceneQueryAdapter,
+)
+from mini_arcade_core.runtime.services import RuntimeServices
+from mini_arcade_core.runtime.window.window_adapter import WindowAdapter
+from mini_arcade_core.scenes.registry import SceneRegistry
+from mini_arcade_core.utils import FrameTimer
+from mini_arcade_core.utils.profiler import FrameTimerConfig
+
+
+class Game:
+    """Core game object responsible for managing the main loop and active scene."""
+
+    def __init__(
+        self, config: GameConfig, scene_registry: SceneRegistry | None = None
+    ):
+        """
+        :param config: Game configuration options.
+        :type config: GameConfig
+
+        :param scene_registry: Optional SceneRegistry for scene management.
+        :type scene_registry: SceneRegistry | None
+
+        :raises ValueError: If the provided config does not have a valid Backend.
+        """
+        self.config = config
+        self._running: bool = False
+
+        if self.config.backend is None:
+            raise ValueError(
+                "GameConfig.backend must be set to a Backend instance"
+            )
+
+        self.backend: Backend = self.config.backend
+        self.settings = GamePlaySettings()
+        self.managers = EngineManagers(
+            cheats=CheatManager(),
+            command_queue=CommandQueue(),
+            scenes=SceneAdapter(
+                scene_registry or SceneRegistry(_factories={}), self
+            ),
+        )
+        self.services = RuntimeServices(
+            window=WindowAdapter(self.backend),  # Turn into a manager?
+            audio=SDLAudioAdapter(self.backend),
+            files=LocalFilesAdapter(),
+            capture=CaptureAdapter(self.backend),
+            input=InputAdapter(),
+            render=RenderService(),
+            scenes=SceneQueryAdapter(self.managers.scenes),
+        )
+
+    @property
+    def running(self) -> bool:
+        """Check if the game is currently running."""
+        return self._running
+
+    def quit(self):
+        """Request that the main loop stops."""
+        self._running = False
+
+    def run(self):
+        """
+        Run the main loop starting with the given scene.
+
+        This is intentionally left abstract so you can plug pygame, pyglet,
+        or another backend.
+
+        :param initial_scene_id: The scene id to start the game with (must be registered).
+        :type initial_scene_id: str
+        """
+        self.managers.scenes.change(self.config.initial_scene)
+
+        pipeline = RenderPipeline()
+        effects_registry = EffectRegistry()
+        effects_registry.register(CRTEffect())
+        effects_registry.register(VignetteNoiseEffect())
+
+        effects_stack = EffectStack(
+            enabled=self.config.postfx.enabled,
+            active=list(self.config.postfx.active),
+            params={
+                "crt": EffectParams(intensity=0.35, wobble_speed=1.0),
+                "vignette_noise": EffectParams(
+                    intensity=0.25, wobble_speed=1.0
+                ),
+            },
+        )
+        self.settings.effects_stack = effects_stack
+
+        for p in pipeline.passes:
+            if getattr(p, "name", "") == "PostFXPass":
+                p.registry = effects_registry
+
+        self._running = True
+
+        timer = FrameTimer(
+            config=FrameTimerConfig(enabled=self.config.enable_profiler)
+        )
+        hooks = DefaultGameHooks(self, effects_stack)
+
+        self.services.window.set_virtual_resolution(800, 600)
+        runner = EngineRunner(
+            self,
+            pipeline=pipeline,
+            effects_stack=effects_stack,
+            hooks=hooks,
+        )
+        runner.run(cfg=RunnerConfig(fps=self.config.fps), timer=timer)
+
+    def resolve_world(self) -> object | None:
+        """
+        Resolve and return the current gameplay world.
+
+        :return: The current gameplay world, or None if not found.
+        :rtype: object | None
+        """
+        # Prefer gameplay world underneath overlays:
+        # scan from top to bottom and pick the first scene that has .world
+        for entry in reversed(self.managers.scenes.visible_entries()):
+            scene = entry.scene
+            world = getattr(scene, "world", None)
+            if world is not None:
+                return world
+        return None