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

mini_arcade_core/backend/backend.py

@@ -289,3 +289,36 @@ class Backend(Protocol):
     def clear_clip_rect(self):
         """Clear any clipping rectangle."""
         raise NotImplementedError
+
+    # Justification: Simple drawing API for now
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def draw_line(
+        self,
+        x1: int,
+        y1: int,
+        x2: int,
+        y2: int,
+        color: tuple[int, ...] = (255, 255, 255),
+    ):
+        """
+        Draw a line between two points in some default color.
+
+        :param x1: X position of the start point.
+        :type x1: int
+
+        :param y1: Y position of the start point.
+        :type y1: int
+
+        :param x2: X position of the end point.
+        :type x2: int
+
+        :param y2: Y position of the end point.
+        :type y2: int
+
+        :param color: RGB color tuple.
+        :type color: tuple[int, ...]
+        """
+        raise NotImplementedError
+
+
+# pylint: enable=too-many-arguments,too-many-positional-arguments

mini_arcade_core/engine/commands.py

@@ -173,11 +173,15 @@ class ChangeSceneCommand(Command):
 
 @dataclass(frozen=True)
 class ToggleDebugOverlayCommand(Command):
-    """Toggle the debug overlay scene."""
+    """
+    Toggle the debug overlay scene.
+
+    :cvar DEBUG_OVERLAY_ID: str: Identifier for the debug overlay scene.
+    """
 
     DEBUG_OVERLAY_ID = "debug_overlay"
 
-    def execute(self, context: CommandContext) -> None:
+    def execute(self, context: CommandContext):
         scenes = context.services.scenes
         if scenes.has_scene(self.DEBUG_OVERLAY_ID):
             scenes.remove_scene(self.DEBUG_OVERLAY_ID)
@@ -193,3 +197,22 @@ class ToggleDebugOverlayCommand(Command):
                 receives_input=False,
             ),
         )
+
+
+@dataclass(frozen=True)
+class ToggleEffectCommand(Command):
+    """
+    Toggle a post-processing effect on or off.
+
+    :ivar effect_id (str): Identifier of the effect to toggle.
+    """
+
+    effect_id: str
+
+    def execute(self, context: CommandContext) -> None:
+        # 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)
+        if stack is None:
+            return
+        stack.toggle(self.effect_id)

mini_arcade_core/engine/game.py

@@ -16,9 +16,20 @@ from mini_arcade_core.engine.commands import (
     CommandQueue,
     QuitCommand,
     ToggleDebugOverlayCommand,
+    ToggleEffectCommand,
 )
+from mini_arcade_core.engine.render.context import RenderContext
+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.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.engine.render.render_service import RenderService
 from mini_arcade_core.managers.cheats import CheatManager
 from mini_arcade_core.runtime.audio.audio_adapter import SDLAudioAdapter
 from mini_arcade_core.runtime.capture.capture_adapter import CaptureAdapter
@@ -49,6 +60,19 @@ class WindowConfig:
     title: str
 
 
+@dataclass
+class PostFXConfig:
+    """
+    Configuration for post-processing effects.
+
+    :ivar enabled (bool): Whether post effects are enabled by default.
+    :ivar active (list[str]): List of active effect IDs by default.
+    """
+
+    enabled: bool = True
+    active: list[str] = field(default_factory=list)
+
+
 @dataclass
 class GameConfig:
     """
@@ -62,6 +86,7 @@ class GameConfig:
     window: WindowConfig | None = None
     fps: int = 60
     backend: Backend | None = None
+    postfx: PostFXConfig = field(default_factory=PostFXConfig)
 
 
 Difficulty = Literal["easy", "normal", "hard", "insane"]
@@ -76,6 +101,7 @@ class GameSettings:
     """
 
     difficulty: Difficulty = "normal"
+    effects_stack: EffectStack | None = None
 
 
 def _neutral_input(frame_index: int, dt: float) -> InputFrame:
@@ -188,6 +214,7 @@ class Game:
             files=LocalFilesAdapter(),
             capture=CaptureAdapter(self.backend),
             input=InputAdapter(),
+            render=RenderService(),
         )
 
         self.command_queue = CommandQueue()
@@ -200,6 +227,9 @@ class Game:
     # 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
+    # TODO: Fix too-many-branches warning
+    # Justification: Complex control flow in main loop.
+    # pylint: disable=too-many-branches
     def run(self, initial_scene_id: str):
         """
         Run the main loop starting with the given scene.
@@ -218,6 +248,26 @@ class Game:
 
         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
         target_dt = 1.0 / self.config.fps if self.config.fps > 0 else 0.0
         last_time = perf_counter()
@@ -234,6 +284,7 @@ class Game:
         # & self.services.scenes.input_entry
         # Justification: These methods are expected to return values.
         # pylint: disable=assignment-from-no-return
+        time_s = 0.0
 
         while self._running:
             timer.clear()
@@ -251,8 +302,17 @@ class Game:
                     logger.debug(f"Window resized event: {w}x{h}")
                     self.services.window.on_window_resized(w, h)
                 # if F1 pressed, toggle debug overlay
-                if e.type == EventType.KEYDOWN and e.key == Key.F1:
-                    self.command_queue.push(ToggleDebugOverlayCommand())
+                if e.type == EventType.KEYDOWN:
+                    if e.key == Key.F1:
+                        self.command_queue.push(ToggleDebugOverlayCommand())
+                    elif e.key == Key.F2:
+                        self.command_queue.push(ToggleEffectCommand("crt"))
+                    elif e.key == Key.F3:
+                        self.command_queue.push(
+                            ToggleEffectCommand("vignette_noise")
+                        )
+                    elif e.key == Key.F4:
+                        effects_stack.enabled = not effects_stack.enabled
             timer.mark("events_polled")
 
             input_frame = self.services.input.build(events, frame_index, dt)
@@ -304,23 +364,43 @@ class Game:
                 cmd.execute(command_context)
             timer.mark("cmd_exec_end")
 
+            # ---------------- TO REPLACE WITH RENDERING PIPELINE ----------------
             timer.mark("render_start")
-            backend.begin_frame()
-            timer.mark("begin_frame_done")
 
             vp = self.services.window.get_viewport()
+
+            # gather visible packets
+            frame_packets: list[RenderPacket] = []
             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
+                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.settings, "debug_overlay", False),
+                frame_ms=dt * 1000.0,
+            )
+            time_s += dt
+            render_ctx.meta["frame_index"] = frame_index
+            render_ctx.meta["time_s"] = time_s
+            render_ctx.meta["effects_stack"] = effects_stack
 
-                pipeline.draw_packet(backend, packet, vp)
+            self.services.render.last_frame_ms = render_ctx.frame_ms
+            self.services.render.last_stats = render_ctx.stats
+            pipeline.render_frame(backend, render_ctx, frame_packets)
 
-            timer.mark("draw_done")
-            backend.end_frame()
+            timer.mark("render_done")
+            # ---------------- END RENDERING PIPELINE ----------------------------
             timer.mark("end_frame_done")
 
             timer.mark("sleep_start")

mini_arcade_core/engine/render/context.py

@@ -0,0 +1,48 @@
+"""
+Render context and stats for a single frame render.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from mini_arcade_core.engine.render.viewport import ViewportState
+
+
+@dataclass
+class RenderStats:
+    """
+    Statistics about the rendering process for a single frame.
+
+    :ivar packets (int): Number of render packets processed.
+    :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
+class RenderContext:
+    """
+    Context for rendering a single frame.
+
+    :ivar viewport: ViewportState: Current viewport state.
+    :ivar debug_overlay: bool: Whether to render debug overlays.
+    :ivar frame_ms: float: Time taken to render the frame in milliseconds.
+    :ivar stats: RenderStats: Statistics about the rendering process.
+    :ivar meta: dict[str, Any]: Additional metadata for rendering.
+    """
+
+    viewport: ViewportState
+    debug_overlay: bool = False
+    frame_ms: float = 0.0
+    stats: RenderStats = field(default_factory=RenderStats)
+    meta: dict[str, Any] = field(default_factory=dict)

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) -> None:
+        """
+        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) -> None:
+        """
+        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) -> None:
+        """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.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.draw_line(
+                x0 + shift, y, x0 + w + shift, y, color=line_color
+            )
+
+        backend.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) -> None:
+        """
+        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) -> None:
+        """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.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.draw_rect(x0, y0, w, t, color=color)
+            # bottom
+            backend.draw_rect(x0, y0 + h - t, w, t, color=color)
+            # left
+            backend.draw_rect(x0, y0, t, h, color=color)
+            # right
+            backend.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.draw_rect(px, py, 1, 1, color=(255, 255, 255, a))
+
+        backend.clear_clip_rect()

mini_arcade_core/engine/render/frame_packet.py

@@ -0,0 +1,26 @@
+"""
+Frame packet for rendering.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.engine.render.packet import RenderPacket
+
+
+@dataclass(frozen=True)
+class FramePacket:
+    """
+    A packet representing a frame to be rendered, associated with a specific scene
+    and indicating whether it is an overlay.
+
+
+    :ivar scene_id (str): Identifier of the scene.
+    :ivar is_overlay (bool): Whether the frame is an overlay.
+    :ivar packet (RenderPacket): The render packet containing rendering operations.
+    """
+
+    scene_id: str
+    is_overlay: bool
+    packet: RenderPacket

mini_arcade_core/engine/render/passes/base.py

@@ -0,0 +1,37 @@
+"""
+Render pass base protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+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
+
+
+class RenderPass(Protocol):
+    """
+    Render pass protocol.
+
+    :ivar name: str: Name of the render pass.
+    """
+
+    name: str
+
+    def run(
+        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+    ):
+        """
+        Run the render pass.
+
+        :param backend: Backend: The rendering backend.
+        :type backend: Backend
+
+        :param ctx: RenderContext: The rendering context.
+        :type ctx: RenderContext
+
+        :param packets: list[RenderPacket]: List of render packets to process.
+        :type packets: list[RenderPacket]
+        """

mini_arcade_core/engine/render/passes/begin_frame.py

@@ -0,0 +1,27 @@
+"""
+Begin Frame Render Pass
+"""
+
+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
+
+
+@dataclass
+class BeginFramePass:
+    """
+    Begin Frame Render Pass.
+    This pass signals the start of a new frame to the backend.
+    """
+
+    name: str = "BeginFrame"
+
+    # Justification: some arguments are unused but required by the protocol
+    # pylint: disable=unused-argument
+    def run(
+        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+    ):
+        """Run the begin frame pass."""
+        backend.begin_frame()

mini_arcade_core/engine/render/passes/end_frame.py

@@ -0,0 +1,28 @@
+"""
+End Frame render pass implementation.
+"""
+
+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
+
+
+@dataclass
+class EndFramePass:
+    """
+    End Frame Render Pass.
+    This pass signals the end of the current frame to the backend.
+    """
+
+    name: str = "EndFrame"
+
+    # Justification: some arguments are unused but required by the protocol
+    # pylint: disable=unused-argument
+    def run(
+        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+    ):
+        """Run the end frame pass."""
+        # Signal the end of the frame to the backend
+        backend.end_frame()

mini_arcade_core/engine/render/passes/lighting.py

@@ -0,0 +1,28 @@
+"""
+Lighting render pass implementation.
+"""
+
+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
+
+
+@dataclass
+class LightingPass:
+    """
+    Lighting Render Pass.
+    This pass handles scene lighting effects.
+    """
+
+    name: str = "LightingPass"
+
+    # Justification: No implementation yet
+    # pylint: disable=unused-argument
+    def run(
+        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+    ):
+        """Run the lighting render pass."""
+        # hook/no-op for now
+        return

mini_arcade_core/engine/render/passes/postfx.py

@@ -0,0 +1,49 @@
+"""
+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.effects.registry import EffectRegistry
+from mini_arcade_core.engine.render.frame_packet import FramePacket
+
+
+@dataclass
+class PostFXPass:
+    """
+    PostFX Render Pass.
+    This pass handles post-processing effects like CRT simulation.
+    """
+
+    name: str = "PostFXPass"
+    registry: EffectRegistry | None = None
+
+    # Justification: No implementation yet
+    # pylint: disable=unused-argument
+    def run(
+        self, backend: Backend, ctx: RenderContext, packets: list[FramePacket]
+    ):
+        """Run the post-processing effects render pass."""
+        # 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.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)

mini_arcade_core/engine/render/passes/ui.py

@@ -0,0 +1,41 @@
+"""
+UI render pass implementation.
+"""
+
+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.frame_packet import FramePacket
+
+
+@dataclass
+class UIPass:
+    """
+    UI Render Pass.
+    This pass handles rendering of UI overlays.
+    """
+
+    name: str = "UIPass"
+
+    def run(
+        self, backend: Backend, ctx: RenderContext, packets: list[FramePacket]
+    ):
+        """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()
+
+        for fp in packets:
+            if not fp.is_overlay:
+                continue
+            if not fp.packet or not fp.packet.ops:
+                continue
+
+            # count overlays too (optional; I’d count them)
+            ctx.stats.packets += 1
+            ctx.stats.renderables += len(fp.packet.ops)
+            ctx.stats.draw_groups += 1
+
+            for op in fp.packet.ops:
+                op(backend)

mini_arcade_core/engine/render/passes/world.py

@@ -0,0 +1,55 @@
+"""
+World render pass implementation.
+"""
+
+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.frame_packet import FramePacket
+from mini_arcade_core.engine.render.packet import RenderPacket
+
+
+@dataclass
+class WorldPass:
+    """
+    World Render Pass.
+    This pass handles rendering of world-space objects.
+    """
+
+    name: str = "WorldPass"
+
+    def run(
+        self, backend: Backend, ctx: RenderContext, packets: list[FramePacket]
+    ):
+        """Run the world render pass."""
+        for fp in packets:
+            if fp.is_overlay:
+                continue
+            self._draw_packet(backend, ctx, fp.packet)
+
+    def _draw_packet(
+        self, backend: Backend, ctx: RenderContext, packet: RenderPacket
+    ):
+        if not packet or not packet.ops:
+            return
+
+        ctx.stats.packets += 1
+        ctx.stats.renderables += len(packet.ops)
+        ctx.stats.draw_groups += 1  # approx: 1 group per packet
+
+        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,
+        )
+        try:
+            for op in packet.ops:
+                op(backend)
+        finally:
+            backend.clear_clip_rect()
+            backend.clear_viewport_transform()

mini_arcade_core/engine/render/pipeline.py

@@ -3,12 +3,30 @@ Render pipeline module.
 Defines the RenderPipeline class for rendering RenderPackets.
 """
 
+# Justification: This code is duplicated in multiple places for clarity and separation
+# of concerns.
+# try:
+#     for op in packet.ops:
+#         op(backend)
+# finally:
+#     backend.clear_clip_rect()
+#     backend.clear_viewport_transform() (duplicate-code)
+# pylint: disable=duplicate-code
+
 from __future__ import annotations
 
-from dataclasses import dataclass
+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.packet import RenderPacket
+from mini_arcade_core.engine.render.passes.base import RenderPass
+from mini_arcade_core.engine.render.passes.begin_frame import BeginFramePass
+from mini_arcade_core.engine.render.passes.end_frame import EndFramePass
+from mini_arcade_core.engine.render.passes.lighting import LightingPass
+from mini_arcade_core.engine.render.passes.postfx import PostFXPass
+from mini_arcade_core.engine.render.passes.ui import UIPass
+from mini_arcade_core.engine.render.passes.world import WorldPass
 from mini_arcade_core.engine.render.viewport import ViewportState
 
 
@@ -18,12 +36,43 @@ class RenderPipeline:
     Minimal pipeline for v1.
 
     Later you can expand this into passes:
-      - build draw list
-      - cull
-      - sort
-      - backend draw pass
+        - build draw list
+        - cull
+        - sort
+        - backend draw pass
+
+    :cvar passes: list[RenderPass]: List of render passes to execute in order.
     """
 
+    passes: list[RenderPass] = field(
+        default_factory=lambda: [
+            BeginFramePass(),
+            WorldPass(),
+            LightingPass(),
+            UIPass(),
+            PostFXPass(),
+            EndFramePass(),
+        ]
+    )
+
+    def render_frame(
+        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
+    ):
+        """
+        Render a frame using the provided Backend, RenderContext, and list of RenderPackets.
+
+        :param backend: Backend to use for rendering.
+        :type backend: Backend
+
+        :param ctx: RenderContext containing rendering state.
+        :type ctx: RenderContext
+
+        :param packets: List of RenderPackets to render.
+        :type packets: list[RenderPacket]
+        """
+        for p in self.passes:
+            p.run(backend, ctx, packets)
+
     def draw_packet(
         self,
         backend: Backend,
@@ -48,12 +97,12 @@ class RenderPipeline:
             viewport_state.scale,
         )
 
-        # backend.set_clip_rect(
-        #     viewport_state.offset_x,
-        #     viewport_state.offset_y,
-        #     viewport_state.viewport_w,
-        #     viewport_state.viewport_h,
-        # )
+        backend.set_clip_rect(
+            viewport_state.offset_x,
+            viewport_state.offset_y,
+            viewport_state.viewport_w,
+            viewport_state.viewport_h,
+        )
 
         try:
             for op in packet.ops:

mini_arcade_core/engine/render/render_service.py

@@ -0,0 +1,22 @@
+"""
+Render service definition.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.engine.render.context import RenderStats
+
+
+@dataclass
+class RenderService:
+    """
+    Render Service.
+    This service manages rendering statistics and state.
+    :ivar last_frame_ms (float): Time taken for the last frame in milliseconds.
+    :ivar last_stats (RenderStats): Rendering statistics from the last frame.
+    """
+
+    last_frame_ms: float = 0.0
+    last_stats: RenderStats = RenderStats()

mini_arcade_core/runtime/render/render_port.py

@@ -0,0 +1,22 @@
+"""
+Render service definition.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from mini_arcade_core.engine.render.context import RenderStats
+
+
+class RenderServicePort(Protocol):
+    """
+    Render Service.
+    This service manages rendering statistics and state.
+
+    :ivar last_frame_ms (float): Time taken for the last frame in milliseconds.
+    :ivar last_stats (RenderStats): Rendering statistics from the last frame.
+    """
+
+    last_frame_ms: float
+    last_stats: RenderStats

mini_arcade_core/runtime/scene/scene_adapter.py

@@ -116,7 +116,7 @@ class SceneAdapter(ScenePort):
     def has_scene(self, scene_id: str) -> bool:
         return any(item.entry.scene_id == scene_id for item in self._stack)
 
-    def remove_scene(self, scene_id: str) -> None:
+    def remove_scene(self, scene_id: str):
         # remove first match from top (overlay is usually near top)
         for i in range(len(self._stack) - 1, -1, -1):
             if self._stack[i].entry.scene_id == scene_id:

mini_arcade_core/runtime/scene/scene_port.py

@@ -161,7 +161,7 @@ class ScenePort:
         :rtype: bool
         """
 
-    def remove_scene(self, scene_id: str) -> None:
+    def remove_scene(self, scene_id: str):
         """
         Remove a scene with the given ID from the stack.
 

mini_arcade_core/runtime/services.py

@@ -10,6 +10,7 @@ from mini_arcade_core.runtime.audio.audio_port import AudioPort
 from mini_arcade_core.runtime.capture.capture_port import CapturePort
 from mini_arcade_core.runtime.file.file_port import FilePort
 from mini_arcade_core.runtime.input.input_port import InputPort
+from mini_arcade_core.runtime.render.render_port import RenderServicePort
 from mini_arcade_core.runtime.scene.scene_port import ScenePort
 from mini_arcade_core.runtime.window.window_port import WindowPort
 
@@ -33,3 +34,4 @@ class RuntimeServices:
     files: FilePort
     capture: CapturePort
     input: InputPort
+    render: RenderServicePort

mini_arcade_core/scenes/debug_overlay.py

@@ -39,10 +39,13 @@ class DebugOverlayScene(SimScene):
         vp = services.window.get_viewport()
         stack = services.scenes.visible_entries()
         # pylint: enable=assignment-from-no-return
-
+        rs = services.render
         lines = [
             f"FPS: {self._fps:5.1f}",
             f"dt:  {dt*1000.0:5.2f} ms",
+            f"frame: {rs.last_frame_ms:5.2f} ms",
+            f"renderables: {rs.last_stats.renderables}",
+            f"draw_groups~: {rs.last_stats.draw_groups}",
             f"virtual: {vp.virtual_w}x{vp.virtual_h}",
             f"window:   {vp.window_w}x{vp.window_h}",
             f"scale: {vp.scale:.3f}",

mini_arcade_core/scenes/registry.py

@@ -15,8 +15,7 @@ from mini_arcade_core.runtime.context import RuntimeContext
 from .autoreg import snapshot
 
 if TYPE_CHECKING:
-    from mini_arcade_core.engine.commands import CommandQueue
-    from mini_arcade_core.sim import SimScene
+    from mini_arcade_core.sim.protocols import SimScene
 
 
 class SceneFactory(Protocol):

{mini_arcade_core-1.0.2.dist-info → mini_arcade_core-1.1.1.dist-info}/METADATA

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

{mini_arcade_core-1.0.2.dist-info → mini_arcade_core-1.1.1.dist-info}/RECORD

@@ -1,17 +1,33 @@
 mini_arcade_core/__init__.py,sha256=axwl7fiQ2Zu2vPOTMUxwnvR746gI9RhpBWpBCId_yqo,3686
 mini_arcade_core/backend/__init__.py,sha256=E9uOCttCkXwdN_5MlcFHUmG3Bj6RYMatNNOno4C_6aI,312
-mini_arcade_core/backend/backend.py,sha256=RpFclQFDOLSaqCACWR0sT_OQYjDIfYzQaFvnHzURLvI,7788
+mini_arcade_core/backend/backend.py,sha256=1-lgjkcftYaeusWKhQrDTwgfbwH6y9S-PP-miy7tRNE,8619
 mini_arcade_core/backend/events.py,sha256=5Ohve3CQ6n2CztiOhbCoz6yFDY4z0j4v4R9FBKRDRjc,2929
 mini_arcade_core/backend/keys.py,sha256=LTg20SwLBI3kpPIiTNpq2yBft_QUGj-iNFSNm9M-Fus,3010
 mini_arcade_core/backend/sdl_map.py,sha256=_yBRtvaFUcQKy1kcoIf-SPhbbKEW7dzvzBcI6TLmKjc,2060
 mini_arcade_core/backend/types.py,sha256=SuiwXGNmXCZxfPsww6zj3V_NK7k4jpoCuzMn19afS-g,175
 mini_arcade_core/bus.py,sha256=2Etpoa-UWhk33xJjqDlY5YslPDJEjxNoIEVtF3C73vs,1558
 mini_arcade_core/engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/engine/commands.py,sha256=5caisiwWhLWO5w18rOvEaeYStOUT8mvrTP0O5gpgeoA,4772
-mini_arcade_core/engine/game.py,sha256=stb75hlqY-DsOqXz7zOFpfSR-jtF8rD0Hpmy1qPuSzE,12409
+mini_arcade_core/engine/commands.py,sha256=SfhncRQvuwTQg5BEyS8yeFTaq5mixiFsvFUZSBK9y1Q,5420
+mini_arcade_core/engine/game.py,sha256=HaLCew31UD8ujz3yOHGjWPzjpD7dkeQSMDdnMFD9JtI,15588
 mini_arcade_core/engine/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/engine/render/context.py,sha256=1zzycXDbQnK3wuk79cMjSewu8FinAp-EsFal7bbJFnI,1414
+mini_arcade_core/engine/render/effects/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/engine/render/effects/base.py,sha256=yq8qRZMbp4VTi02WnVbyHS3RYc56vvP69MzPbCO3m2s,2373
+mini_arcade_core/engine/render/effects/crt.py,sha256=D8_7Bqzt_VeLusyXzeLQynxTIZwQ45NisSImTB-4Hpg,2141
+mini_arcade_core/engine/render/effects/registry.py,sha256=ie1nuLJbQq9Ecb9tea3oGvSD9QaydbFFhH8ggEf-9uU,1220
+mini_arcade_core/engine/render/effects/vignette.py,sha256=ogLTgaJ9srpiA59Lc7_nBD7wZk7y6t9HnHYNoK7YeSE,2569
+mini_arcade_core/engine/render/frame_packet.py,sha256=nYHvR7CHlIZa6ZazmPO2dU2P91vEkBjBzUVQGrOkaYc,624
 mini_arcade_core/engine/render/packet.py,sha256=OiAPwGoVHo04OcUWMAoA_N1AFPUMyf8yxNgJthGj4-c,1440
-mini_arcade_core/engine/render/pipeline.py,sha256=XdnzAXNle8_CJOPzYJaEy9Dp_UgoCgJwIh-GpW9-n5E,1516
+mini_arcade_core/engine/render/passes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/engine/render/passes/base.py,sha256=LWgWhfafbCvRKIFbt3koW-ibjYxMfKOIXyLNazCakcM,864
+mini_arcade_core/engine/render/passes/begin_frame.py,sha256=Yzlk8bv7mgjlnM1jH_kYjJ_d8469i8aPriEqv7hm9gE,699
+mini_arcade_core/engine/render/passes/end_frame.py,sha256=ONFcNQJhYvaN-BK6wyxxsLDBUUHx-b-mvOYH__QXJJ4,760
+mini_arcade_core/engine/render/passes/lighting.py,sha256=ugmHHNNZWArL_Xs6-1SQIxLptUTQwe4M2sSPEk8X-7s,677
+mini_arcade_core/engine/render/passes/postfx.py,sha256=OWcayjffZr5xT7cNIsbm4gzxmGfYiQyLgycV2dC6Jsg,1417
+mini_arcade_core/engine/render/passes/ui.py,sha256=JxMXI900le45nOZF2SzDuniVqUOJYvAbSDRxYcIFFkc,1122
+mini_arcade_core/engine/render/passes/world.py,sha256=QPKDVkKk-AA7ZR1HCo-JfzjxjUT6vmxXbqo1BYpebiU,1550
+mini_arcade_core/engine/render/pipeline.py,sha256=bp2pOuwwBvJjYWZJgNe6xTfEBwdEm5WiBnM8infV_AI,3268
+mini_arcade_core/engine/render/render_service.py,sha256=1ueir8MZ6Six5gAHt5StoICPAbyppX4DqzWb8HEuS9g,531
 mini_arcade_core/engine/render/viewport.py,sha256=fbzH3_rc27IGUtDalmxz5cukwHnpt1kopIeVqmTab20,5784
 mini_arcade_core/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/managers/cheats.py,sha256=jMx2a8YnaNCkCG5MPmIzz4uHuS7-_aYf0J45cv2-3v0,5569
@@ -31,17 +47,19 @@ mini_arcade_core/runtime/input/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5
 mini_arcade_core/runtime/input/input_adapter.py,sha256=vExQiwFIWTI3zYD8lmnD9TvoQPZvJfI6IINPJUqAdQ0,1467
 mini_arcade_core/runtime/input/input_port.py,sha256=d4ptftwf92_LJdyaUMFxIsLHXBINzQyJACHn4laNyxQ,746
 mini_arcade_core/runtime/input_frame.py,sha256=34-RAfOD-YScVLyRQrarpm7byFTHjsWM77lIH0JsmT8,2384
+mini_arcade_core/runtime/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/runtime/render/render_port.py,sha256=Sqp-JBh-iRzzGtgnO_nU1KiJEqyrTYPRDQbg04HdR0A,507
 mini_arcade_core/runtime/scene/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mini_arcade_core/runtime/scene/scene_adapter.py,sha256=I2kWc76fU05pNpt2bO-1_aeR6KwkkmZLD2-9fr_UAn8,3481
-mini_arcade_core/runtime/scene/scene_port.py,sha256=F_KtHO-N5O3EgVAE3HaYYHqoc7zpUnCwn6wQdsl1iTA,4481
-mini_arcade_core/runtime/services.py,sha256=9LX7O-AYFTxKgBDewzu0B_D01EJ41WVAdl8U1ZcvEYg,1061
+mini_arcade_core/runtime/scene/scene_adapter.py,sha256=RthYyp_G3c9YVVQlnCuvtgFFtp9zvdjcykc0fXEpmic,3473
+mini_arcade_core/runtime/scene/scene_port.py,sha256=t6-REznEVvxcJoq2DJXcDs8sg0nC9fww6J5NwGpweg8,4473
+mini_arcade_core/runtime/services.py,sha256=dtatQisOAdWgdqGjrH0cO1GA6ZDt4CiXjOEzlaNL51E,1165
 mini_arcade_core/runtime/window/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/runtime/window/window_adapter.py,sha256=_yCcJwvHN0gEPh0rkgLEKtPZ50qRbONsUTbgtV1m7Y8,2689
 mini_arcade_core/runtime/window/window_port.py,sha256=JbSH549De7fa4ifQ0EH5QQoq03Got1n9C4qViLgciUU,2682
 mini_arcade_core/scenes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/scenes/autoreg.py,sha256=wsuY7YUSZFmDyToKHFriAG78OU48-7J4BfL_X6T5GBg,1037
-mini_arcade_core/scenes/debug_overlay.py,sha256=N4sGQ_3pMz-ZvJZX63kqtylpS9U1PTpWeImrkfmVnus,2230
-mini_arcade_core/scenes/registry.py,sha256=taWyLUDLRe7RJN0kqF_qpqRSiGCcbzEeCpcKlmPUFnE,3428
+mini_arcade_core/scenes/debug_overlay.py,sha256=pe5eXmxVl0itBdlt5Q-TEyGNiONMztMeck6Vq93QCmo,2423
+mini_arcade_core/scenes/registry.py,sha256=SKjaw1e2EHvLimxe4ixf0DFxQTJRVQxRi96MujGgCao,3376
 mini_arcade_core/scenes/sim_scene.py,sha256=b2JsOvPFkHCdCf8pMLJZ90qB0JJ6B8Ka3o5QK4cVshI,1055
 mini_arcade_core/scenes/systems/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mini_arcade_core/scenes/systems/base_system.py,sha256=GfMrXsO8ynW3xOxWeav7Ug5XUbRnbF0vo8VzmG7gpec,1075
@@ -61,7 +79,7 @@ mini_arcade_core/ui/menu.py,sha256=pUC6qfG3lNXa1Ga2Kz_cSgjiAfAWVMRevum61G_RE8k,2
 mini_arcade_core/utils/__init__.py,sha256=3Q9r6bTyqImYix8BnOGwWjAz25nbTQezGcRq3m5KEYE,189
 mini_arcade_core/utils/deprecated_decorator.py,sha256=yrrW2ZqPskK-4MUTyIrMb465Wc54X2poV53ZQutZWqc,1140
 mini_arcade_core/utils/logging.py,sha256=YyirsGRSpGtxegUl3HWz37mGNngK3QkYm2_aZjXJC84,5279
-mini_arcade_core-1.0.2.dist-info/METADATA,sha256=CtAYloxC_GLDTJT53Ap5Sz8JSF3b_2iTPJuo_Kc4vSg,8188
-mini_arcade_core-1.0.2.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-mini_arcade_core-1.0.2.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-1.0.2.dist-info/RECORD,,
+mini_arcade_core-1.1.1.dist-info/METADATA,sha256=uLI8iX6Z3XyhoHBQDw4vmWfXRkk-09IXqUvHMvwHrJQ,8188
+mini_arcade_core-1.1.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+mini_arcade_core-1.1.1.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-1.1.1.dist-info/RECORD,,