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

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

@@ -0,0 +1,88 @@
+"""
+Screen-space post effects base classes and protocols.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.engine.render.context import RenderContext
+
+
+@runtime_checkable
+class Effect(Protocol):
+    """
+    Screen-space post effect.
+
+    IMPORTANT: Effects should draw ONLY using ctx.viewport (screen-space),
+    and must not assume anything about world-space transforms.
+    """
+
+    effect_id: str
+
+    def apply(self, backend: Backend, ctx: RenderContext):
+        """
+        Apply the effect to the current framebuffer.
+
+        :param backend: Backend to use for rendering.
+        :type backend: Backend
+
+        :param ctx: Render context with viewport info.
+        :type ctx: RenderContext
+        """
+
+
+@dataclass
+class EffectParams:
+    """
+    Shared params (Material-ish controls) for v1.
+
+    :ivar intensity (float): Effect intensity.
+    :ivar wobble_speed (float): Speed factor for animated distortion.
+    :ivar tint (tuple[int, int, int, int] | None): Optional RGBA tint.
+    """
+
+    intensity: float = 1.0
+    wobble_speed: float = 1.0
+    tint: tuple[int, int, int, int] | None = None
+
+
+@dataclass
+class EffectStack:
+    """
+    Runtime state: what effects are enabled + their params.
+
+    Zero-overhead path:
+        - if enabled=False OR active is empty => PostFXPass returns immediately.
+
+    :ivar enabled (bool): Master toggle for post effects.
+    :ivar active (list[str]): List of active effect IDs.
+    :ivar params (dict[str, EffectParams]): Per-effect parameters.
+    """
+
+    enabled: bool = False
+    active: list[str] = field(default_factory=list)
+    params: dict[str, EffectParams] = field(default_factory=dict)
+
+    def is_active(self) -> bool:
+        """
+        Check if any effects are active.
+
+        :return: True if effects are enabled and at least one is active.
+        :rtype: bool
+        """
+        return self.enabled and bool(self.active)
+
+    def toggle(self, effect_id: str):
+        """
+        Toggle an effect on/off.
+
+        :param effect_id: ID of the effect to toggle.
+        :type effect_id: str
+        """
+        if effect_id in self.active:
+            self.active.remove(effect_id)
+        else:
+            self.active.append(effect_id)

mini_arcade_core/engine/render/effects/crt.py

@@ -0,0 +1,68 @@
+"""
+CRT screen-space post effect.
+"""
+
+# Justification: PoC code for v1.
+# pylint: disable=duplicate-code
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import sin
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.engine.render.context import RenderContext
+from mini_arcade_core.engine.render.effects.base import EffectParams
+
+
+@dataclass
+class CRTEffect:
+    """
+    CRT screen-space post effect.
+    Simulates CRT scanlines with optional wobble.
+    """
+
+    effect_id: str = "crt"
+
+    # Justification: This is PoC code for v1.
+    # pylint: disable=too-many-locals
+    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
+        w, h = vp.viewport_w, vp.viewport_h
+
+        stack = ctx.meta.get("effects_stack")
+        params: EffectParams = (
+            stack.params.get(self.effect_id, EffectParams())
+            if stack
+            else EffectParams()
+        )
+
+        intensity = max(0.0, min(1.0, params.intensity))
+        if intensity <= 0.0:
+            return
+
+        # Use a time value from ctx.meta (added in Game.run below)
+        t = float(ctx.meta.get("time_s", 0.0))
+        wobble = float(params.wobble_speed)
+
+        # Clip to viewport so it works with all viewport modes/resolutions
+        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.
+        spacing = 2  # tweakable
+        base_alpha = 120  # int(40 * intensity)  # subtle
+        line_color = (255, 255, 255, base_alpha)
+
+        # "Wobble": tiny horizontal shift that animates over time
+        # Keep it tiny to avoid looking like a bug.
+        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.render.draw_line(
+                x0 + shift, y, x0 + w + shift, y, color=line_color
+            )
+
+        backend.render.clear_clip_rect()

mini_arcade_core/engine/render/effects/registry.py

@@ -0,0 +1,50 @@
+"""
+Screen-space post effects registry.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mini_arcade_core.engine.render.effects.base import Effect
+
+
+@dataclass
+class EffectRegistry:
+    """
+    Registry of available screen-space post effects.
+
+    :ivar _effects: dict[str, Effect]: Internal mapping of effect IDs to effects.
+    """
+
+    _effects: dict[str, Effect] = field(default_factory=dict)
+
+    def register(self, effect: Effect):
+        """
+        Register a new effect in the registry.
+
+        :param effect: Effect to register.
+        :type effect: Effect
+        """
+        self._effects[effect.effect_id] = effect
+
+    def get(self, effect_id: str) -> Effect | None:
+        """
+        Get an effect by its ID.
+
+        :param effect_id: ID of the effect to retrieve.
+        :type effect_id: str
+
+        :return: Effect instance or None if not found.
+        :rtype: Effect | None
+        """
+        return self._effects.get(effect_id)
+
+    def all_ids(self) -> list[str]:
+        """
+        Get a list of all registered effect IDs.
+
+        :return: List of effect IDs.
+        :rtype: list[str]
+        """
+        return list(self._effects.keys())

mini_arcade_core/engine/render/effects/vignette.py

@@ -0,0 +1,79 @@
+"""
+Vignette noise screen-space post effect.
+"""
+
+# Justification: PoC code for v1.
+# pylint: disable=duplicate-code
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.engine.render.context import RenderContext
+from mini_arcade_core.engine.render.effects.base import EffectParams
+
+
+@dataclass
+class VignetteNoiseEffect:
+    """
+    Vignette + noise screen-space post effect.
+    Simulates a vignette effect with added noise/grain.
+    """
+
+    effect_id: str = "vignette_noise"
+
+    # Justification: This is PoC code for v1.
+    # pylint: disable=too-many-locals
+    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
+        w, h = vp.viewport_w, vp.viewport_h
+
+        stack = ctx.meta.get("effects_stack")
+        params: EffectParams = (
+            stack.params.get(self.effect_id, EffectParams())
+            if stack
+            else EffectParams()
+        )
+
+        intensity = max(0.0, min(1.0, params.intensity))
+        if intensity <= 0.0:
+            return
+
+        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.
+        steps = 10
+        max_alpha = int(110 * intensity)  # subtle
+        for i in range(steps):
+            # thickness grows inward
+            t = i + 1
+            alpha = int(max_alpha * (t / steps))
+            color = (0, 0, 0, alpha)
+
+            # top
+            backend.render.draw_rect(x0, y0, w, t, color=color)
+            # bottom
+            backend.render.draw_rect(x0, y0 + h - t, w, t, color=color)
+            # left
+            backend.render.draw_rect(x0, y0, t, h, color=color)
+            # right
+            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.
+        frame = int(ctx.meta.get("frame_index", 0))
+        random.seed(frame * 1337)
+
+        dots = int(200 * intensity)  # tweak
+        for _ in range(dots):
+            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.render.draw_rect(px, py, 1, 1, color=(255, 255, 255, a))
+
+        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

@@ -2,11 +2,14 @@
 Post-processing effects render pass implementation.
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 
 from mini_arcade_core.backend import Backend
 from mini_arcade_core.engine.render.context import RenderContext
-from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.engine.render.effects.registry import EffectRegistry
+from mini_arcade_core.engine.render.frame_packet import FramePacket
 
 
 @dataclass
@@ -17,12 +20,30 @@ class PostFXPass:
     """
 
     name: str = "PostFXPass"
+    registry: EffectRegistry | None = None
 
     # Justification: No implementation yet
     # pylint: disable=unused-argument
     def run(
-        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+        self, backend: Backend, ctx: RenderContext, packets: list[FramePacket]
     ):
         """Run the post-processing effects render pass."""
-        # hook/no-op for now (CRT later)
-        return
+        # Zero overhead path (no effects configured)
+        stack = ctx.meta.get("effects_stack")
+        if stack is None or not stack.is_active():
+            return
+
+        # Screen space: no transforms
+        backend.clear_viewport_transform()
+        backend.render.clear_clip_rect()
+
+        reg = self.registry
+        if reg is None:
+            # no registry => nothing to do
+            return
+
+        for effect_id in list(stack.active):
+            effect = reg.get(effect_id)
+            if effect is None:
+                continue
+            effect.apply(backend, ctx)