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

mini_arcade_core/engine/loop/hooks.py

@@ -0,0 +1,77 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable, Protocol
+
+from mini_arcade_core.backend.events import Event, EventType
+from mini_arcade_core.backend.keys import Key
+from mini_arcade_core.engine.commands import (
+    ToggleDebugOverlayCommand,
+    ToggleEffectCommand,
+)
+from mini_arcade_core.engine.render.effects.base import EffectStack
+from mini_arcade_core.utils import logger
+
+if TYPE_CHECKING:
+    from mini_arcade_core.engine.game import Game
+
+
+class LoopHooks(Protocol):
+    """
+    Protocol for custom loop hooks to handle events.
+    """
+
+    def on_events(self, events: Iterable[object]):
+        """
+        Docstring for on_events
+
+        :param events: Iterable of input events.
+        :type events: Iterable[object]
+        """
+
+
+class DefaultGameHooks:
+    """
+    Default implementation of LoopHooks for handling common events.
+
+    :param game: The Game instance.
+    :type game: Game
+    :param effects_stack: The EffectStack for post-processing effects.
+    :type effects_stack: EffectStack
+    """
+
+    def __init__(self, game: "Game", effects_stack: EffectStack):
+        self.game = game
+        self.effects_stack = effects_stack
+
+    def on_events(self, events: Iterable[Event]):
+        """
+        Handle common events such as window resize and debug toggles.
+
+        :param events: Iterable of input events.
+        :type events: Iterable[Event]
+        """
+        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.game.services.window.on_window_resized(w, h)
+
+            if e.type == EventType.KEYDOWN:
+                if e.key == Key.F1:
+                    self.game.managers.command_queue.push(
+                        ToggleDebugOverlayCommand()
+                    )
+                elif e.key == Key.F2:
+                    self.game.managers.command_queue.push(
+                        ToggleEffectCommand("crt")
+                    )
+                elif e.key == Key.F3:
+                    self.game.managers.command_queue.push(
+                        ToggleEffectCommand("vignette_noise")
+                    )
+                elif e.key == Key.F4:
+                    self.effects_stack.enabled = not self.effects_stack.enabled

mini_arcade_core/engine/loop/runner.py

@@ -0,0 +1,272 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+from time import sleep
+from typing import TYPE_CHECKING
+
+from mini_arcade_core.engine.commands import CommandContext, QuitCommand
+from mini_arcade_core.engine.loop.config import RunnerConfig
+from mini_arcade_core.engine.loop.hooks import LoopHooks
+from mini_arcade_core.engine.loop.state import FrameState
+from mini_arcade_core.engine.render.context import RenderContext
+from mini_arcade_core.engine.render.effects.base import EffectStack
+from mini_arcade_core.engine.render.frame_packet import FramePacket
+from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.engine.render.pipeline import RenderPipeline
+from mini_arcade_core.runtime.input_frame import InputFrame
+from mini_arcade_core.utils import FrameTimer
+
+if TYPE_CHECKING:
+    from mini_arcade_core.engine.game import Game
+
+
+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)
+
+
+# Justification: This class has many attributes for managing the loop.
+# pylint: disable=too-many-instance-attributes
+class EngineRunner:
+    """
+    Core engine runner responsible for the main loop execution.
+
+    :param game: The Game instance to run.
+    :type game: Game
+    :param pipeline: The RenderPipeline to use for rendering.
+    :type pipeline: RenderPipeline
+    :param effects_stack: The EffectStack for post-processing effects.
+    :type effects_stack: EffectStack
+    :param hooks: Optional LoopHooks for custom event handling.
+    :type hooks: LoopHooks | None
+    """
+
+    def __init__(
+        self,
+        game: "Game",
+        *,
+        pipeline: RenderPipeline,
+        effects_stack: EffectStack,
+        hooks: LoopHooks | None = None,
+    ):
+        self.game = game
+        self.backend = game.backend
+        self.services = game.services
+        self.managers = game.managers
+
+        self.pipeline = pipeline
+        self.effects_stack = effects_stack
+        self.hooks = hooks
+
+        self._running = False
+        self._packet_cache: dict[int, RenderPacket] = {}
+
+    def stop(self):
+        """Stop the engine runner loop."""
+        self._running = False
+
+    def run(self, *, cfg: RunnerConfig, timer: FrameTimer | None = None):
+        """
+        Run the main loop with the given configuration.
+
+        :param cfg: RunnerConfig instance.
+        :type cfg: RunnerConfig
+        :param timer: Optional FrameTimer for profiling.
+        :type timer: FrameTimer | None
+        """
+        self._running = True
+        frame = FrameState()
+
+        target_dt = 1.0 / cfg.fps if cfg.fps > 0 else 0.0
+
+        while self._running and self.game.running:
+            if (
+                cfg.max_frames is not None
+                and frame.frame_index >= cfg.max_frames
+            ):
+                break
+
+            if timer:
+                timer.clear()
+                timer.mark("frame_start")
+
+            frame.step_time()
+
+            events = self._poll_events(timer)
+            self._handle_events(events)
+
+            input_frame = self._build_input(events, frame=frame, timer=timer)
+            if self._should_quit(input_frame):
+                break
+
+            input_entry = self._input_entry()
+            if input_entry is None:
+                break
+
+            self._tick_scenes(
+                input_entry, input_frame, frame=frame, timer=timer
+            )
+            ctx = self._build_command_context(timer)
+            self._process_cheats(input_frame, ctx, timer)
+            self._execute_commands(ctx, timer)
+
+            self._render_frame(frame, timer)
+
+            self._sleep(target_dt, frame.dt, timer)
+
+            if timer and timer.should_report(frame.frame_index):
+                timer.emit(frame.frame_index)
+
+            frame.frame_index += 1
+
+        self.managers.scenes.clean()
+
+    def _poll_events(self, timer: FrameTimer | None):
+        # Poll input events from the backend.
+        events = list(self.backend.input.poll())
+        if timer:
+            timer.mark("events_polled")
+        return events
+
+    def _handle_events(self, events):
+        # Handle polled events via hooks if available.
+        if self.hooks:
+            self.hooks.on_events(events)
+
+    def _build_input(
+        self, events, *, frame: FrameState, timer: FrameTimer | None
+    ):
+        # Build InputFrame from events.
+        input_frame = self.services.input.build(
+            events, frame.frame_index, frame.dt
+        )
+        if timer:
+            timer.mark("input_built")
+        if input_frame.quit:
+            self.managers.command_queue.push(QuitCommand())
+        return input_frame
+
+    def _should_quit(self, input_frame: InputFrame) -> bool:
+        # Determine if the game should quit based on input.
+        return bool(input_frame.quit)
+
+    def _input_entry(self):
+        # Get the current input-focused scene entry.
+        return self.managers.scenes.input_entry()
+
+    def _tick_scenes(
+        self,
+        input_entry,
+        input_frame: InputFrame,
+        *,
+        frame: FrameState,
+        timer: FrameTimer | None,
+    ):
+        # Tick/update all scenes according to their policies.
+        if timer:
+            timer.mark("tick_start")
+        for entry in self.managers.scenes.update_entries():
+            effective_input = (
+                input_frame
+                if entry is input_entry
+                else _neutral_input(frame.frame_index, frame.dt)
+            )
+            packet = entry.scene.tick(effective_input, frame.dt)
+            self._packet_cache[id(entry.scene)] = packet
+        if timer:
+            timer.mark("tick_end")
+
+    def _build_command_context(
+        self, timer: FrameTimer | None
+    ) -> CommandContext:
+        # Build the command execution context.
+        if timer:
+            timer.mark("command_ctx_start")
+        ctx = CommandContext(
+            services=self.services,
+            managers=self.managers,
+            settings=self.game.settings,
+            world=self.game.resolve_world(),
+        )
+        if timer:
+            timer.mark("command_ctx_end")
+        return ctx
+
+    def _process_cheats(
+        self,
+        input_frame: InputFrame,
+        ctx: CommandContext,
+        timer: FrameTimer | None,
+    ):
+        # Process cheat codes based on the input frame.
+        if timer:
+            timer.mark("cheats_start")
+        self.managers.cheats.process_frame(
+            input_frame, context=ctx, queue=self.managers.command_queue
+        )
+        if timer:
+            timer.mark("cheats_end")
+
+    def _execute_commands(self, ctx: CommandContext, timer: FrameTimer | None):
+        # Execute all queued commands.
+        if timer:
+            timer.mark("cmd_exec_start")
+        for cmd in self.managers.command_queue.drain():
+            cmd.execute(ctx)
+        if timer:
+            timer.mark("cmd_exec_end")
+
+    def _render_frame(self, frame: FrameState, timer: FrameTimer | None):
+        # Render the current frame using the render pipeline.
+        if timer:
+            timer.mark("render_start")
+
+        vp = self.services.window.get_viewport()
+
+        frame_packets: list[FramePacket] = []
+        for entry in self.managers.scenes.visible_entries():
+            scene = entry.scene
+            packet = self._packet_cache.get(id(scene))
+            if packet is None:
+                packet = scene.tick(
+                    _neutral_input(frame.frame_index, 0.0), 0.0
+                )
+                self._packet_cache[id(scene)] = packet
+
+            frame_packets.append(
+                FramePacket(
+                    scene_id=entry.scene_id,
+                    is_overlay=entry.is_overlay,
+                    packet=packet,
+                )
+            )
+
+        render_ctx = RenderContext(
+            viewport=vp,
+            debug_overlay=getattr(self.game.settings, "debug_overlay", False),
+            frame_ms=frame.dt * 1000.0,
+        )
+        render_ctx.meta["frame_index"] = frame.frame_index
+        render_ctx.meta["time_s"] = frame.time_s
+        render_ctx.meta["effects_stack"] = self.effects_stack
+
+        self.services.render.last_frame_ms = render_ctx.frame_ms
+        self.services.render.last_stats = render_ctx.stats
+
+        self.pipeline.render_frame(self.backend, render_ctx, frame_packets)
+
+        if timer:
+            timer.mark("render_done")
+            timer.mark("end_frame_done")
+
+    def _sleep(self, target_dt: float, dt: float, timer: FrameTimer | None):
+        # Sleep to maintain target frame rate if necessary.
+        if timer:
+            timer.mark("sleep_start")
+        if target_dt > 0 and dt < target_dt:
+            sleep(target_dt - dt)
+        if timer:
+            timer.mark("sleep_end")

mini_arcade_core/engine/loop/state.py

@@ -0,0 +1,32 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from time import perf_counter
+
+
+@dataclass
+class FrameState:
+    """
+    State of the current frame in the main loop.
+
+    :ivar frame_index (int): The current frame index.
+    :ivar last_time (float): The timestamp of the last frame.
+    :ivar time_s (float): The total elapsed time in seconds.
+    :ivar dt (float): The delta time since the last frame in seconds.
+    """
+
+    frame_index: int = 0
+    last_time: float = field(default_factory=perf_counter)
+    time_s: float = 0.0
+    dt: float = 0.0
+
+    def step_time(self):
+        """Step the time forward by calculating dt."""
+        now = perf_counter()
+        self.dt = now - self.last_time
+        self.last_time = now
+        self.time_s += self.dt

mini_arcade_core/engine/managers.py

@@ -0,0 +1,24 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mini_arcade_core.engine.cheats import CheatManager
+from mini_arcade_core.engine.commands import CommandQueue
+from mini_arcade_core.engine.scenes.scene_manager import SceneAdapter
+
+
+@dataclass
+class EngineManagers:
+    """
+    Container for various game managers.
+
+    :ivar cheats (CheatManager): Manager for handling cheat codes.
+    """
+
+    cheats: CheatManager = field(default_factory=CheatManager)
+    command_queue: CommandQueue = field(default_factory=CommandQueue)
+    scenes: SceneAdapter | None = None

mini_arcade_core/engine/render/context.py

@@ -19,14 +19,12 @@ class RenderStats:
     :ivar ops (int): Number of rendering operations executed.
     :ivar draw_groups (int): Number of draw groups processed.
     :ivar renderables (int): Number of renderable objects processed.
-    :ivar draw_groups (int): Number of draw groups processed.
     """
 
     packets: int = 0
     ops: int = 0
     draw_groups: int = 0  # approx ok
     renderables: int = 0
-    draw_groups: int = 0
 
 
 @dataclass

mini_arcade_core/engine/render/effects/base.py

@@ -22,7 +22,7 @@ class Effect(Protocol):
 
     effect_id: str
 
-    def apply(self, backend: Backend, ctx: RenderContext) -> None:
+    def apply(self, backend: Backend, ctx: RenderContext):
         """
         Apply the effect to the current framebuffer.
 
@@ -75,7 +75,7 @@ class EffectStack:
         """
         return self.enabled and bool(self.active)
 
-    def toggle(self, effect_id: str) -> None:
+    def toggle(self, effect_id: str):
         """
         Toggle an effect on/off.
 

mini_arcade_core/engine/render/effects/crt.py

@@ -26,7 +26,7 @@ class CRTEffect:
 
     # Justification: This is PoC code for v1.
     # pylint: disable=too-many-locals
-    def apply(self, backend: Backend, ctx: RenderContext) -> None:
+    def apply(self, backend: Backend, ctx: RenderContext):
         """Apply the CRT effect to the current render context."""
         vp = ctx.viewport
         x0, y0 = vp.offset_x, vp.offset_y
@@ -48,7 +48,7 @@ class CRTEffect:
         wobble = float(params.wobble_speed)
 
         # Clip to viewport so it works with all viewport modes/resolutions
-        backend.set_clip_rect(x0, y0, w, h)
+        backend.render.set_clip_rect(x0, y0, w, h)
 
         # Scanlines: draw every N lines with low alpha
         # Note: assumes Backend supports alpha in color tuples.
@@ -61,8 +61,8 @@ class CRTEffect:
         for y in range(y0, y0 + h, spacing):
             # shift in pixels, -2..2-ish
             shift = int(2.0 * intensity * sin((y * 0.05) + (t * wobble)))
-            backend.draw_line(
+            backend.render.draw_line(
                 x0 + shift, y, x0 + w + shift, y, color=line_color
             )
 
-        backend.clear_clip_rect()
+        backend.render.clear_clip_rect()

mini_arcade_core/engine/render/effects/registry.py

@@ -19,7 +19,7 @@ class EffectRegistry:
 
     _effects: dict[str, Effect] = field(default_factory=dict)
 
-    def register(self, effect: Effect) -> None:
+    def register(self, effect: Effect):
         """
         Register a new effect in the registry.
 

mini_arcade_core/engine/render/effects/vignette.py

@@ -26,7 +26,7 @@ class VignetteNoiseEffect:
 
     # Justification: This is PoC code for v1.
     # pylint: disable=too-many-locals
-    def apply(self, backend: Backend, ctx: RenderContext) -> None:
+    def apply(self, backend: Backend, ctx: RenderContext):
         """Apply the Vignette + Noise effect to the current render context."""
         vp = ctx.viewport
         x0, y0 = vp.offset_x, vp.offset_y
@@ -43,7 +43,7 @@ class VignetteNoiseEffect:
         if intensity <= 0.0:
             return
 
-        backend.set_clip_rect(x0, y0, w, h)
+        backend.render.set_clip_rect(x0, y0, w, h)
 
         # Vignette approximation: draw edge rectangles with increasing alpha.
         # Not a true radial gradient, but good enough for v1.
@@ -56,13 +56,13 @@ class VignetteNoiseEffect:
             color = (0, 0, 0, alpha)
 
             # top
-            backend.draw_rect(x0, y0, w, t, color=color)
+            backend.render.draw_rect(x0, y0, w, t, color=color)
             # bottom
-            backend.draw_rect(x0, y0 + h - t, w, t, color=color)
+            backend.render.draw_rect(x0, y0 + h - t, w, t, color=color)
             # left
-            backend.draw_rect(x0, y0, t, h, color=color)
+            backend.render.draw_rect(x0, y0, t, h, color=color)
             # right
-            backend.draw_rect(x0 + w - t, y0, t, h, color=color)
+            backend.render.draw_rect(x0 + w - t, y0, t, h, color=color)
 
         # Noise: sprinkle a few pixels (or tiny 1x1 rects).
         # Use deterministic-ish seed per frame so it doesn't “swim” too much.
@@ -74,6 +74,6 @@ class VignetteNoiseEffect:
             px = x0 + random.randint(0, max(0, w - 1))
             py = y0 + random.randint(0, max(0, h - 1))
             a = random.randint(10, int(50 * intensity) + 10)
-            backend.draw_rect(px, py, 1, 1, color=(255, 255, 255, a))
+            backend.render.draw_rect(px, py, 1, 1, color=(255, 255, 255, a))
 
-        backend.clear_clip_rect()
+        backend.render.clear_clip_rect()

mini_arcade_core/engine/render/passes/begin_frame.py

@@ -24,4 +24,4 @@ class BeginFramePass:
         self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
     ):
         """Run the begin frame pass."""
-        backend.begin_frame()
+        backend.render.begin_frame()

mini_arcade_core/engine/render/passes/end_frame.py

@@ -25,4 +25,4 @@ class EndFramePass:
     ):
         """Run the end frame pass."""
         # Signal the end of the frame to the backend
-        backend.end_frame()
+        backend.render.end_frame()

mini_arcade_core/engine/render/passes/postfx.py

@@ -35,7 +35,7 @@ class PostFXPass:
 
         # Screen space: no transforms
         backend.clear_viewport_transform()
-        backend.clear_clip_rect()
+        backend.render.clear_clip_rect()
 
         reg = self.registry
         if reg is None:

mini_arcade_core/engine/render/passes/ui.py

@@ -24,7 +24,7 @@ class UIPass:
         """Run the UI render pass."""
         # UI overlays should be screen-space (no world transform / no clip unless you want it)
         backend.clear_viewport_transform()
-        backend.clear_clip_rect()
+        backend.render.clear_clip_rect()
 
         for fp in packets:
             if not fp.is_overlay:

mini_arcade_core/engine/render/passes/world.py

@@ -41,15 +41,15 @@ class WorldPass:
         backend.set_viewport_transform(
             ctx.viewport.offset_x, ctx.viewport.offset_y, ctx.viewport.scale
         )
-        backend.set_clip_rect(
-            ctx.viewport.offset_x,
-            ctx.viewport.offset_y,
-            ctx.viewport.viewport_w,
-            ctx.viewport.viewport_h,
+        backend.render.set_clip_rect(
+            0,
+            0,
+            ctx.viewport.virtual_w,
+            ctx.viewport.virtual_h,
         )
         try:
             for op in packet.ops:
                 op(backend)
         finally:
-            backend.clear_clip_rect()
+            backend.render.clear_clip_rect()
             backend.clear_viewport_transform()

mini_arcade_core/engine/render/pipeline.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass, field
 
 from mini_arcade_core.backend import Backend
 from mini_arcade_core.engine.render.context import RenderContext
+from mini_arcade_core.engine.render.frame_packet import FramePacket
 from mini_arcade_core.engine.render.packet import RenderPacket
 from mini_arcade_core.engine.render.passes.base import RenderPass
 from mini_arcade_core.engine.render.passes.begin_frame import BeginFramePass
@@ -56,10 +57,10 @@ class RenderPipeline:
     )
 
     def render_frame(
-        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+        self, backend: Backend, ctx: RenderContext, packets: list[FramePacket]
     ):
         """
-        Render a frame using the provided Backend, RenderContext, and list of RenderPackets.
+        Render a frame using the provided Backend, RenderContext, and list of FramePackets.
 
         :param backend: Backend to use for rendering.
         :type backend: Backend
@@ -67,8 +68,8 @@ class RenderPipeline:
         :param ctx: RenderContext containing rendering state.
         :type ctx: RenderContext
 
-        :param packets: List of RenderPackets to render.
-        :type packets: list[RenderPacket]
+        :param packets: List of FramePackets to render.
+        :type packets: list[FramePacket]
         """
         for p in self.passes:
             p.run(backend, ctx, packets)
@@ -98,8 +99,8 @@ class RenderPipeline:
         )
 
         backend.set_clip_rect(
-            viewport_state.offset_x,
-            viewport_state.offset_y,
+            0,
+            0,
             viewport_state.viewport_w,
             viewport_state.viewport_h,
         )

mini_arcade_core/engine/render/viewport.py

@@ -4,6 +4,7 @@ Viewport management for virtual to screen coordinate transformations.
 
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass
 from enum import Enum
 
@@ -130,10 +131,15 @@ class Viewport:
         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))
+        if self._mode == ViewportMode.FIT:
+            vw = int(math.floor(self._virtual_w * scale))
+            vh = int(math.floor(self._virtual_h * scale))
+        else:  # FILL
+            vw = int(math.ceil(self._virtual_w * scale))
+            vh = int(math.ceil(self._virtual_h * scale))
+
+        ox = (window_w - vw) // 2
+        oy = (window_h - vh) // 2
 
         self._state = ViewportState(
             virtual_w=self._virtual_w,