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

mini_arcade_core/engine/game.py

@@ -0,0 +1,354 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+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.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.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.input_frame import InputFrame
+from mini_arcade_core.runtime.scene.scene_adapter import SceneAdapter
+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 logger
+
+
+@dataclass
+class WindowConfig:
+    """
+    Configuration for a game window (not implemented).
+
+    :ivar width (int): Width of the window in pixels.
+    :ivar height (int): Height of the window in pixels.
+    :ivar background_color (tuple[int, int, int]): RGB background color.
+    :ivar title (str): Title of the window.
+    """
+
+    width: int
+    height: int
+    background_color: tuple[int, int, int]
+    title: str
+
+
+@dataclass
+class GameConfig:
+    """
+    Configuration options for the Game.
+
+    :ivar window (WindowConfig | None): Optional window configuration.
+    :ivar fps (int): Target frames per second.
+    :ivar backend (Backend | None): Optional Backend instance to use for rendering and input.
+    """
+
+    window: WindowConfig | None = None
+    fps: int = 60
+    backend: Backend | None = None
+
+
+Difficulty = Literal["easy", "normal", "hard", "insane"]
+
+
+@dataclass
+class GameSettings:
+    """
+    Game settings that can be modified during gameplay.
+
+    :ivar difficulty (Difficulty): Current game difficulty level.
+    """
+
+    difficulty: Difficulty = "normal"
+
+
+def _neutral_input(frame_index: int, dt: float) -> InputFrame:
+    """Create a neutral InputFrame with no input events."""
+    return InputFrame(frame_index=frame_index, dt=dt)
+
+
+@dataclass
+class FrameTimer:
+    """
+    Simple frame timer for marking and reporting time intervals.
+
+    :ivar enabled (bool): Whether timing is enabled.
+    :ivar marks (Dict[str, float]): Recorded time marks.
+    """
+
+    enabled: bool = True
+    marks: Dict[str, float] = field(default_factory=dict)
+
+    def mark(self, name: str):
+        """
+        Record a time mark with the given name.
+
+        :param name: Name of the mark.
+        :type name: str
+        """
+        if not self.enabled:
+            return
+        self.marks[name] = perf_counter()
+
+    def diff_ms(self, start: str, end: str) -> float:
+        """
+        Get the time difference in milliseconds between two marks.
+
+        :param start: Name of the start mark.
+        :type start: str
+
+        :param end: Name of the end mark.
+        :type end: str
+
+        :return: Time difference in milliseconds.
+        :rtype: float
+        """
+        return (self.marks[end] - self.marks[start]) * 1000.0
+
+    def report_ms(self) -> Dict[str, float]:
+        """
+        Returns diffs between consecutive marks in insertion order.
+
+        :return: Dictionary mapping "start->end" to time difference in milliseconds.
+        :rtype: Dict[str, float]
+        """
+        if not self.enabled:
+            return {}
+
+        keys = list(self.marks.keys())
+        out: Dict[str, float] = {}
+        for a, b in zip(keys, keys[1:]):
+            out[f"{a}->{b}"] = self.diff_ms(a, b)
+        return out
+
+    def clear(self):
+        """Clear all recorded marks."""
+        if not self.enabled:
+            return
+        self.marks.clear()
+
+
+# TODO: Fix too-many-instance-attributes warning
+# Justification: Core game class with many dependencies.
+# pylint: disable=too-many-instance-attributes
+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._running: bool = False
+
+        if config.backend is None:
+            raise ValueError(
+                "GameConfig.backend must be set to a Backend instance"
+            )
+        if config.window is None:
+            raise ValueError("GameConfig.window must be set")
+
+        self.backend: Backend = config.backend
+        self.registry = registry or SceneRegistry(_factories={})
+        self.settings = GameSettings()
+        self.services = RuntimeServices(
+            window=WindowAdapter(
+                self.backend,
+            ),
+            scenes=SceneAdapter(self.registry, self),
+            audio=NullAudioAdapter(),
+            files=LocalFilesAdapter(),
+            capture=CaptureAdapter(self.backend),
+            input=InputAdapter(),
+        )
+
+        self.command_queue = CommandQueue()
+        self.cheat_manager = CheatManager()
+
+    def quit(self):
+        """Request that the main loop stops."""
+        self._running = False
+
+    # TODO: Fix too-many-statements and too-many-locals warnings
+    # Justification: Main game loop with multiple responsibilities.
+    # pylint: disable=too-many-statements,too-many-locals
+    def run(self, initial_scene_id: str):
+        """
+        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
+        """
+        backend = self.backend
+
+        self._initialize_window()
+
+        self.services.scenes.change(initial_scene_id)
+
+        pipeline = RenderPipeline()
+
+        self._running = True
+        target_dt = 1.0 / self.config.fps if self.config.fps > 0 else 0.0
+        last_time = perf_counter()
+        frame_index = 0
+
+        # cache packets so blocked-update scenes still render their last frame
+        packet_cache: dict[int, RenderPacket] = {}
+
+        timer = FrameTimer(enabled=True)
+        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
+        # & self.services.scenes.input_entry
+        # Justification: These methods are expected to return values.
+        # pylint: disable=assignment-from-no-return
+
+        while self._running:
+            timer.clear()
+            timer.mark("frame_start")
+
+            now = perf_counter()
+            dt = now - last_time
+            last_time = now
+
+            events = list(backend.poll_events())
+            timer.mark("events_polled")
+
+            input_frame = self.services.input.build(events, frame_index, dt)
+            timer.mark("input_built")
+
+            # Window/OS quit (close button)
+            if input_frame.quit:
+                self.command_queue.push(QuitCommand())
+
+            # who gets input?
+            input_entry = self.services.scenes.input_entry()
+            if input_entry is None:
+                break
+
+            # tick policy-aware scenes
+            timer.mark("tick_start")
+            for entry in self.services.scenes.update_entries():
+                scene = entry.scene
+                effective_input = (
+                    input_frame
+                    if entry is input_entry
+                    else _neutral_input(frame_index, dt)
+                )
+
+                packet = scene.tick(effective_input, dt)
+                packet_cache[id(scene)] = packet
+            timer.mark("tick_end")
+
+            timer.mark("command_ctx_start")
+            command_context = CommandContext(
+                services=self.services,
+                commands=self.command_queue,
+                settings=self.settings,
+                world=self._resolve_world(),
+            )
+            timer.mark("command_ctx_end")
+
+            timer.mark("cheats_start")
+            self.cheat_manager.process_frame(
+                input_frame,
+                context=command_context,
+                queue=self.command_queue,
+            )
+            timer.mark("cheats_end")
+
+            # Execute commands at the end of the frame (consistent write path)
+            timer.mark("cmd_exec_start")
+            for cmd in self.command_queue.drain():
+                cmd.execute(command_context)
+            timer.mark("cmd_exec_end")
+
+            timer.mark("render_start")
+            backend.begin_frame()
+            timer.mark("begin_frame_done")
+
+            for entry in self.services.scenes.visible_entries():
+                scene = entry.scene
+                packet = packet_cache.get(id(scene))
+                if packet is None:
+                    # bootstrap (first frame visible but not updated)
+                    packet = scene.tick(_neutral_input(frame_index, 0.0), 0.0)
+                    packet_cache[id(scene)] = packet
+
+                pipeline.draw_packet(backend, packet)
+
+            timer.mark("draw_done")
+            backend.end_frame()
+            timer.mark("end_frame_done")
+
+            timer.mark("sleep_start")
+            if target_dt > 0 and dt < target_dt:
+                sleep(target_dt - dt)
+            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}"
+                )
+
+            frame_index += 1
+
+        # pylint: enable=assignment-from-no-return
+
+        # exit remaining scenes
+        self.services.scenes.clean()
+
+    # pylint: enable=too-many-statements,too-many-locals
+
+    def _initialize_window(self):
+        """Initialize the game window based on the configuration."""
+        self.services.window.set_window_size(
+            self.config.window.width, self.config.window.height
+        )
+        self.services.window.set_title(self.config.window.title)
+
+        br, bg, bb = self.config.window.background_color
+        self.services.window.set_clear_color(br, bg, bb)
+
+    def _resolve_world(self) -> 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.services.scenes.visible_entries()):
+            scene = entry.scene
+            world = getattr(scene, "world", None)
+            if world is not None:
+                return world
+        return None
+
+
+# pylint: enable=too-many-instance-attributes

mini_arcade_core/engine/render/packet.py

@@ -0,0 +1,56 @@
+"""
+Render packet module.
+Defines the RenderPacket class and related types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Iterable, Protocol, runtime_checkable
+
+from mini_arcade_core.backend import Backend
+
+DrawOp = Callable[[Backend], None]
+
+
+@dataclass(frozen=True)
+class RenderPacket:
+    """
+    Minimal render packet for v1.
+
+    It is intentionally backend-agnostic: each op is a callable that knows
+    how to draw itself using the Backend instance.
+
+    Later you can replace DrawOp with typed primitives + passes.
+    """
+
+    ops: tuple[DrawOp, ...] = ()
+    meta: dict[str, object] = field(default_factory=dict)
+
+    @staticmethod
+    def from_ops(ops: Iterable[DrawOp], **meta: object) -> "RenderPacket":
+        """
+        Create a RenderPacket from an iterable of DrawOps and optional meta.
+
+        :param ops: Iterable of DrawOp callables.
+        :type ops: Iterable[DrawOp]
+
+        :return: RenderPacket instance.
+        :rtype: RenderPacket
+        """
+        return RenderPacket(ops=tuple(ops), meta=dict(meta))
+
+
+# TODO: Implement later
+@runtime_checkable
+class Renderable(Protocol):
+    """
+    Optional convenience: any object that can produce a RenderPacket.
+    """
+
+    def render(self) -> RenderPacket:
+        """
+        Produce a RenderPacket for this object.
+
+        :return: RenderPacket instance.
+        :rtype: RenderPacket
+        """

mini_arcade_core/engine/render/pipeline.py

@@ -0,0 +1,39 @@
+"""
+Render pipeline module.
+Defines the RenderPipeline class for rendering RenderPackets.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.engine.render.packet import RenderPacket
+
+
+@dataclass
+class RenderPipeline:
+    """
+    Minimal pipeline for v1.
+
+    Later you can expand this into passes:
+      - build draw list
+      - cull
+      - sort
+      - backend draw pass
+    """
+
+    def draw_packet(self, backend: Backend, packet: RenderPacket):
+        """
+        Draw the given RenderPacket using the provided Backend.
+
+        :param backend: Backend to use for drawing.
+        :type backend: Backend
+
+        :param packet: RenderPacket to draw.
+        :type packet: RenderPacket
+        """
+        if not packet:
+            return
+        for op in packet.ops:
+            op(backend)

mini_arcade_core/managers/__init__.py

@@ -1,14 +0,0 @@
-"""
-Managers module for Mini Arcade Core.
-Provides various manager classes for handling game entities and resources.
-"""
-
-from __future__ import annotations
-
-from mini_arcade_core.managers.entity_manager import EntityManager
-from mini_arcade_core.managers.overlay_manager import OverlayManager
-
-__all__ = [
-    "EntityManager",
-    "OverlayManager",
-]

mini_arcade_core/managers/cheats.py

@@ -0,0 +1,186 @@
+"""
+Cheats module for Mini Arcade Core.
+Provides cheat codes and related functionality.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Callable, Deque, Dict, Optional, Sequence, TypeVar
+
+from mini_arcade_core.engine.commands import Command, CommandQueue
+from mini_arcade_core.runtime.input_frame import InputFrame
+
+# Justification: We want to keep the type variable name simple here.
+# pylint: disable=invalid-name
+TContext = TypeVar("TContext")
+# pylint: enable=invalid-name
+
+
+@dataclass(frozen=True)
+class CheatCode:
+    """
+    Represents a registered cheat code.
+
+    :ivar name (str): Unique name of the cheat code.
+    :ivar sequence (tuple[str, ...]): Sequence of key strings that trigger the cheat.
+    :ivar action (CheatAction): BaseCheatCommand to call when the cheat is activated.
+    :ivar clear_buffer_on_match (bool): Whether to clear the input buffer after a match.
+    :ivar enabled (bool): Whether the cheat code is enabled.
+    """
+
+    name: str
+    sequence: tuple[str, ...]
+    command_factory: Optional[Callable[[TContext], Command]] = None
+    clear_buffer_on_match: bool = False
+    enabled: bool = True
+
+
+@dataclass
+class CheatManager:
+    """
+    Reusable cheat code matcher.
+    Keeps a rolling buffer of recent keys and triggers callbacks on sequence match.
+    """
+
+    buffer_size: int = 16
+    enabled: bool = True
+    _buffer: Deque[str] = field(default_factory=lambda: deque(maxlen=16))
+    _codes: Dict[str, CheatCode[TContext]] = field(default_factory=dict)
+
+    def __post_init__(self):
+        # ensure deque maxlen matches buffer_size
+        self._buffer = deque(maxlen=self.buffer_size)
+
+    # TODO: ISolve too-many-arguments warning later
+    # Justification: The method needs multiple optional parameters for flexibility.
+    # pylint: disable=too-many-arguments
+    def register(
+        self,
+        name: str,
+        *,
+        sequence: Sequence[str],
+        command_factory: Callable[[TContext], Command],
+        clear_buffer_on_match: bool = False,
+        enabled: bool = True,
+    ):
+        """
+        Register a new cheat code.
+
+        :param name: Unique name of the cheat code.
+        :type name: str
+
+        :param sequence: Sequence of key strings that trigger the cheat.
+        :type sequence: Sequence[str]
+
+        :param command_factory: Factory function to create the Command when the cheat is activated.
+        :type command_factory: Callable[[TContext], Command]
+
+        :param clear_buffer_on_match: Whether to clear the input buffer after a match.
+        :type clear_buffer_on_match: bool
+
+        :param enabled: Whether the cheat code is enabled.
+        :type enabled: bool
+
+        :raises ValueError: If name is empty or sequence is empty.
+        """
+        if not name:
+            raise ValueError("Cheat name must be non-empty.")
+        if not sequence:
+            raise ValueError(f"Cheat '{name}' sequence must be non-empty.")
+
+        norm_seq = tuple(self._norm(s) for s in sequence)
+        self._codes[name] = CheatCode(
+            name=name,
+            sequence=norm_seq,
+            command_factory=command_factory,
+            clear_buffer_on_match=clear_buffer_on_match,
+            enabled=enabled,
+        )
+
+    # pylint: enable=too-many-arguments
+
+    def process_frame(
+        self,
+        input_frame: InputFrame,
+        *,
+        context: TContext,
+        queue: CommandQueue,
+    ) -> list[str]:
+        """
+        Process an InputFrame for cheat code matches.
+
+        :param input_frame: InputFrame containing current inputs.
+        :type input_frame: InputFrame
+
+        :param context: Context to pass to command factories.
+        :type context: TContext
+
+        :param queue: CommandQueue to push matched commands into.
+        :type queue: CommandQueue
+
+        :return: List of names of matched cheat codes.
+        :rtype: list[str]
+        """
+        if not self.enabled:
+            return []
+
+        matched: list[str] = []
+        for key in input_frame.keys_pressed:
+            key_name = getattr(key, "name", str(key))
+            matched.extend(
+                self.process_key(key_name, context=context, queue=queue)
+            )
+        return matched
+
+    def process_key(
+        self, key: str, *, context: TContext, queue: CommandQueue
+    ) -> list[str]:
+        """
+        Process a single key input.
+
+        :param key: The key string to process.
+        :type key: str
+
+        :param context: Context to pass to command factories.
+        :type context: TContext
+
+        :param queue: CommandQueue to push matched commands into.
+        :type queue: CommandQueue
+
+        :return: List of names of matched cheat codes.
+        :rtype: list[str]
+        """
+        if not self.enabled:
+            return []
+
+        k = self._norm(key)
+        if not k:
+            return []
+
+        self._buffer.append(k)
+        buf = tuple(self._buffer)
+
+        matched: list[str] = []
+        for code in self._codes.values():
+            if not code.enabled:
+                continue
+
+            seq = code.sequence
+            if len(seq) > len(buf):
+                continue
+
+            if buf[-len(seq) :] == seq:
+                queue.push(code.command_factory(context))
+                matched.append(code.name)
+
+                if code.clear_buffer_on_match:
+                    self._buffer.clear()
+                    break
+
+        return matched
+
+    @staticmethod
+    def _norm(s: str) -> str:
+        return s.strip().upper()