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

mini_arcade_core/game.py

@@ -1,287 +0,0 @@
-"""
-Game core module defining the Game class and configuration.
-"""
-
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-from datetime import datetime
-from pathlib import Path
-from time import perf_counter, sleep
-from typing import TYPE_CHECKING, Literal, Union
-
-from PIL import Image  # type: ignore[import]
-
-from mini_arcade_core.backend import Backend
-from mini_arcade_core.scenes.registry import SceneRegistry
-
-if TYPE_CHECKING:  # avoid runtime circular import
-    from mini_arcade_core.scenes import Scene
-
-SceneOrId = Union["Scene", str]
-
-
-@dataclass
-class GameConfig:
-    """
-    Configuration options for the Game.
-
-    :ivar width: Width of the game window in pixels.
-    :ivar height: Height of the game window in pixels.
-    :ivar title: Title of the game window.
-    :ivar fps: Target frames per second.
-    :ivar background_color: RGB background color.
-    :ivar backend: Optional Backend instance to use for rendering and input.
-    """
-
-    width: int = 800
-    height: int = 600
-    title: str = "Mini Arcade Game"
-    fps: int = 60
-    background_color: tuple[int, int, int] = (0, 0, 0)
-    backend: Backend | None = None
-
-
-Difficulty = Literal["easy", "normal", "hard", "insane"]
-
-
-@dataclass
-class GameSettings:
-    """
-    Game settings that can be modified during gameplay.
-
-    :ivar difficulty: Current game difficulty level.
-    """
-
-    difficulty: Difficulty = "normal"
-
-
-@dataclass
-class _StackEntry:
-    scene: "Scene"
-    as_overlay: bool = False
-
-
-class Game:
-    """Core game object responsible for managing the main loop and active scene."""
-
-    def __init__(
-        self, config: GameConfig, registry: SceneRegistry | None = None
-    ):
-        """
-        :param config: Game configuration options.
-        :type config: GameConfig
-
-        :param registry: Optional SceneRegistry for scene management.
-        :type registry: SceneRegistry | None
-
-        :raises ValueError: If the provided config does not have a valid Backend.
-        """
-        self.config = config
-        self._current_scene: Scene | None = None
-        self._running: bool = False
-
-        if config.backend is None:
-            raise ValueError(
-                "GameConfig.backend must be set to a Backend instance"
-            )
-        self.backend: Backend = config.backend
-        self.registry = registry or SceneRegistry(_factories={})
-        self._scene_stack: list[_StackEntry] = []
-        self.settings = GameSettings()
-
-    def current_scene(self) -> "Scene | None":
-        """
-        Get the currently active scene.
-
-        :return: The active Scene instance, or None if no scene is active.
-        :rtype: Scene | None
-        """
-        return self._scene_stack[-1].scene if self._scene_stack else None
-
-    def change_scene(self, scene: SceneOrId):
-        """
-        Swap the active scene. Concrete implementations should call
-        ``on_exit``/``on_enter`` appropriately.
-
-        :param scene: The new scene to activate.
-        :type scene: SceneOrId
-        """
-        scene = self._resolve_scene(scene)
-
-        while self._scene_stack:
-            entry = self._scene_stack.pop()
-            entry.scene.on_exit()
-
-        self._scene_stack.append(_StackEntry(scene=scene, as_overlay=False))
-        scene.on_enter()
-
-    def push_scene(self, scene: SceneOrId, as_overlay: bool = False):
-        """
-        Push a scene on top of the current one.
-        If as_overlay=True, underlying scene(s) may still be drawn but never updated.
-
-        :param scene: The scene to push onto the stack.
-        :type scene: SceneOrId
-
-        :param as_overlay: Whether to treat the scene as an overlay.
-        :type as_overlay: bool
-        """
-        scene = self._resolve_scene(scene)
-
-        top = self.current_scene()
-        if top is not None:
-            top.on_pause()
-
-        self._scene_stack.append(
-            _StackEntry(scene=scene, as_overlay=as_overlay)
-        )
-        scene.on_enter()
-
-    def pop_scene(self) -> "Scene | None":
-        """
-        Pop the top scene. If stack becomes empty, quit.
-
-        :return: The popped Scene instance, or None if the stack is now empty.
-        :rtype: Scene | None
-        """
-        if not self._scene_stack:
-            return None
-
-        popped = self._scene_stack.pop()
-        popped.scene.on_exit()
-
-        top = self.current_scene()
-        if top is None:
-            self.quit()
-            return popped.scene
-
-        top.on_resume()
-        return popped.scene
-
-    def _visible_stack(self) -> list["Scene"]:
-        """
-        Return the list of scenes that should be drawn (base + overlays).
-        We draw from the top-most non-overlay scene upward.
-        """
-        if not self._scene_stack:
-            return []
-
-        # find top-most base scene (as_overlay=False)
-        base_idx = 0
-        for i in range(len(self._scene_stack) - 1, -1, -1):
-            if not self._scene_stack[i].as_overlay:
-                base_idx = i
-                break
-
-        return [e.scene for e in self._scene_stack[base_idx:]]
-
-    def quit(self):
-        """Request that the main loop stops."""
-        self._running = False
-
-    def run(self, initial_scene: SceneOrId):
-        """
-        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: The scene to start the game with.
-        :type initial_scene: SceneOrId
-        """
-        backend = self.backend
-        backend.init(self.config.width, self.config.height, self.config.title)
-
-        br, bg, bb = self.config.background_color
-        backend.set_clear_color(br, bg, bb)
-
-        self.change_scene(initial_scene)
-
-        self._running = True
-        target_dt = 1.0 / self.config.fps if self.config.fps > 0 else 0.0
-        last_time = perf_counter()
-
-        while self._running:
-            now = perf_counter()
-            dt = now - last_time
-            last_time = now
-
-            top = self.current_scene()
-            if top is None:
-                break
-
-            for ev in backend.poll_events():
-                top.handle_event(ev)
-
-            top.update(dt)
-
-            backend.begin_frame()
-            for scene in self._visible_stack():
-                scene.draw(backend)
-            backend.end_frame()
-
-            if target_dt > 0 and dt < target_dt:
-                sleep(target_dt - dt)
-
-        # exit remaining scenes
-        while self._scene_stack:
-            entry = self._scene_stack.pop()
-            entry.scene.on_exit()
-
-    @staticmethod
-    def _convert_bmp_to_image(bmp_path: str, out_path: str) -> bool:
-        """
-        Convert a BMP file to another image format using Pillow.
-
-        :param bmp_path: Path to the input BMP file.
-        :type bmp_path: str
-
-        :param out_path: Path to the output image file.
-        :type out_path: str
-
-        :return: True if conversion was successful, False otherwise.
-        :rtype: bool
-        """
-        try:
-            img = Image.open(bmp_path)
-            img.save(out_path)  # Pillow chooses format from extension
-            return True
-        # Justification: Pillow can raise various exceptions on failure
-        # pylint: disable=broad-exception-caught
-        except Exception:
-            return False
-        # pylint: enable=broad-exception-caught
-
-    def screenshot(
-        self, label: str | None = None, directory: str = "screenshots"
-    ) -> str | None:
-        """
-        Ask backend to save a screenshot. Returns the file path or None.
-
-        :param label: Optional label to include in the filename.
-        :type label: str | None
-
-        :param directory: Directory to save screenshots in.
-        :type directory: str
-
-        :return: The file path of the saved screenshot, or None on failure.
-        :rtype: str | None
-        """
-        os.makedirs(directory, exist_ok=True)
-        stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        label = label or "shot"
-        filename = f"{stamp}_{label}"
-        bmp_path = os.path.join(directory, f"{filename}.bmp")
-
-        if self.backend.capture_frame(bmp_path):
-            out_path = Path(directory) / f"{filename}.png"
-            self._convert_bmp_to_image(bmp_path, str(out_path))
-            return str(out_path)
-        return None
-
-    def _resolve_scene(self, scene: SceneOrId) -> "Scene":
-        if isinstance(scene, str):
-            return self.registry.create(scene, self)
-        return scene

mini_arcade_core/keymaps/__init__.py

@@ -1,15 +0,0 @@
-"""
-Keymaps for Mini Arcade Core.
-Includes key definitions and default key mappings.
-"""
-
-from __future__ import annotations
-
-from .keys import Key, keymap
-from .sdl import SDL_KEYCODE_TO_KEY
-
-__all__ = [
-    "Key",
-    "keymap",
-    "SDL_KEYCODE_TO_KEY",
-]

mini_arcade_core/managers/base.py

@@ -1,132 +0,0 @@
-"""
-Base manager classes for handling collections of items.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Callable, Generic, Iterable, List, Protocol, TypeVar
-
-from mini_arcade_core.backend.backend import Backend
-
-# ---- shared types ----
-T = TypeVar("T")
-OverlayFunc = Callable[[Backend], None]
-
-
-class Overlay(Protocol):
-    """
-    Defines an overlay function.
-
-    :ivar enabled (bool): Whether the overlay is enabled.
-    """
-
-    enabled: bool
-
-    def update(self, dt: float):
-        """
-        Update the overlay state.
-
-        :param dt: Time delta in seconds.
-        :type dt: float
-        """
-
-    def draw(self, surface: "Backend"):
-        """
-        Draw the overlay on the given surface.
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-
-
-class Drawable(Protocol):
-    """Defines a drawable entity."""
-
-    def draw(self, surface: Backend):
-        """
-        Draw the entity on the given surface.
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-
-
-class Updatable(Protocol):
-    """Defines an updatable entity."""
-
-    def update(self, dt: float):
-        """
-        Update the entity state.
-
-        :param dt: Time delta in seconds.
-        :type dt: float
-        """
-
-
-class EntityLike(Drawable, Updatable, Protocol):
-    """Defines a game entity."""
-
-
-@dataclass
-class ListManager(Generic[T]):
-    """
-    Generic manager for a list of items.
-
-    :ivar items (List[T]): List of managed items.
-    """
-
-    items: List[T] = field(default_factory=list)
-
-    def add(self, *items: T):
-        """
-        Add one or more items to the manager.
-
-        :param items: One or more items to add.
-        :type items: T
-        """
-        self.items.extend(items)
-
-    def add_many(self, items: Iterable[T]):
-        """
-        Add multiple items to the manager.
-
-        :param items: An iterable of items to add.
-        :type items: Iterable[T]
-        """
-        self.items.extend(items)
-
-    def remove(self, item: T):
-        """
-        Remove a single item from the manager, if present.
-
-        :param item: The item to remove.
-        :type item: T
-        """
-        if item in self.items:
-            self.items.remove(item)
-
-    def get(self, item: T) -> T | None:
-        """
-        Get an item from the manager.
-
-        :param item: The item to get.
-        :type item: T
-
-        :return: The item if found, else None.
-        :rtype: T | None
-        """
-        for it in self.items:
-            if it == item:
-                return it
-        return None
-
-    def clear(self):
-        """Clear all items from the manager."""
-        self.items.clear()
-
-    def __iter__(self):
-        return iter(self.items)
-
-    def __len__(self) -> int:
-        return len(self.items)

mini_arcade_core/managers/entities.py

@@ -1,38 +0,0 @@
-"""
-Entity manager for handling a collection of entities.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from mini_arcade_core.backend import Backend
-
-from .base import EntityLike, ListManager
-
-
-@dataclass
-class EntityManager(ListManager[EntityLike]):
-    """
-    Manages a collection of entities within a scene.
-    """
-
-    def update(self, dt: float):
-        """
-        Update all managed entities.
-
-        :param dt: Time delta in seconds.
-        :type dt: float
-        """
-        for ent in list(self.items):
-            ent.update(dt)
-
-    def draw(self, surface: "Backend"):
-        """
-        Draw all managed entities.
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-        for ent in list(self.items):
-            ent.draw(surface)

mini_arcade_core/managers/overlays.py

@@ -1,53 +0,0 @@
-"""
-Overlay manager for handling a collection of overlays.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Union
-
-from mini_arcade_core.backend import Backend
-from mini_arcade_core.managers.base import ListManager, Overlay, OverlayFunc
-
-OverlayType = Union[Overlay, OverlayFunc]
-
-
-@dataclass
-class OverlayManager(ListManager[OverlayType]):
-    """
-    Manages a collection of overlays within a scene.
-    """
-
-    def update(self, dt: float):
-        """
-        Update all managed overlays.
-
-        :param dt: Time delta in seconds.
-        :type dt: float
-        """
-        for ov in list(self.items):
-            # class overlays only
-            if hasattr(ov, "update") and hasattr(ov, "draw"):
-                if getattr(ov, "enabled", True):
-                    ov.update(dt)
-
-    def draw(self, surface: "Backend"):
-        """
-        Call all overlays. Scenes should call this at the end of draw().
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-
-        def prio(o: OverlayType) -> int:
-            """Priority for sorting overlays."""
-            return getattr(o, "priority", 0)
-
-        for ov in sorted(list(self.items), key=prio):
-            if hasattr(ov, "draw"):
-                if getattr(ov, "enabled", True):
-                    ov.draw(surface)
-            else:
-                # function overlay
-                ov(surface)

mini_arcade_core/managers/system.py

@@ -1,26 +0,0 @@
-"""
-Manager for scene systems.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from mini_arcade_core.managers.base import ListManager
-from mini_arcade_core.scenes.system import BaseSceneSystem
-
-
-@dataclass
-class SystemManager(ListManager[BaseSceneSystem]):
-    """
-    Manager for scene systems.
-    """
-
-    def sorted(self) -> list[BaseSceneSystem]:
-        """
-        Get systems sorted by priority.
-
-        :return: List of systems sorted by priority.
-        :rtype: list[BaseSceneSystem]
-        """
-        return sorted(self.items, key=lambda s: getattr(s, "priority", 0))

mini_arcade_core/scenes/model.py

@@ -1,34 +0,0 @@
-"""
-Scene base model module.
-Provides the Scene class and related services.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, fields
-from typing import Any
-
-
-@dataclass
-class SceneModel:
-    """
-    Basic data model for a scene.
-    """
-
-    @staticmethod
-    def _serialize_dataclass(obj) -> dict[str, Any]:
-        out = {}
-        for f in fields(obj):
-            if f.metadata.get("serialize", True) is False:
-                continue
-            out[f.name] = getattr(obj, f.name)
-        return out
-
-    def to_dict(self) -> dict:
-        """
-        Convert the SceneModel to a dictionary.
-
-        :return: Dictionary representation of the SceneModel.
-        :rtype: dict
-        """
-        return self._serialize_dataclass(self)

mini_arcade_core/scenes/runtime.py

@@ -1,29 +0,0 @@
-"""
-Container for scene services like entity and overlay managers.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-from mini_arcade_core.managers.entities import EntityManager
-from mini_arcade_core.managers.inputs import InputManager
-from mini_arcade_core.managers.overlays import OverlayManager
-from mini_arcade_core.managers.system import SystemManager
-
-
-@dataclass
-class SceneRuntime:
-    """
-    Container for scene services like entity and overlay managers.
-
-    :ivar input (InputManager): InputManager for handling input bindings and commands.
-    :ivar entities (EntityManager): EntityManager for managing scene entities.
-    :ivar overlays (OverlayManager): OverlayManager for managing scene overlays.
-    :ivar systems (SystemManager): SystemManager for managing scene systems.
-    """
-
-    input: InputManager = field(default_factory=InputManager)
-    entities: EntityManager = field(default_factory=EntityManager)
-    overlays: OverlayManager = field(default_factory=OverlayManager)
-    systems: SystemManager = field(default_factory=SystemManager)