mini-arcade-core 1.0.2__tar.gz → 1.1.1__tar.gz

{mini_arcade_core-1.0.2 → mini_arcade_core-1.1.1}/PKG-INFO

@@ -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 → mini_arcade_core-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "1.0.2"
+version = "1.1.1"
 description = "Tiny scene-based game loop core for small arcade games."
 authors = [
     { name = "Santiago Rincon", email = "rincores@gmail.com" },

{mini_arcade_core-1.0.2 → mini_arcade_core-1.1.1}/src/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-1.0.2 → mini_arcade_core-1.1.1}/src/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-1.0.2 → mini_arcade_core-1.1.1}/src/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-1.1.1/src/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-1.1.1/src/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-1.1.1/src/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-1.1.1/src/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-1.1.1/src/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-1.1.1/src/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-1.1.1/src/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]
+        """