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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 1.1.0
+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.1.0 → 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.1.0"
+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.1.0 → 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.1.0 → mini_arcade_core-1.1.1}/src/mini_arcade_core/engine/commands.py

@@ -197,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.1.0 → mini_arcade_core-1.1.1}/src/mini_arcade_core/engine/game.py

@@ -16,8 +16,16 @@ 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
@@ -52,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:
     """
@@ -65,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"]
@@ -79,6 +101,7 @@ class GameSettings:
     """
 
     difficulty: Difficulty = "normal"
+    effects_stack: EffectStack | None = None
 
 
 def _neutral_input(frame_index: int, dt: float) -> InputFrame:
@@ -204,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.
@@ -222,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()
@@ -238,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()
@@ -255,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)
@@ -334,6 +390,10 @@ class Game:
                 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
 
             self.services.render.last_frame_ms = render_ctx.frame_ms
             self.services.render.last_stats = render_ctx.stats

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/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-1.1.0/src/mini_arcade_core/engine/render/passes/postfx.py

@@ -1,28 +0,0 @@
-"""
-Post-processing effects 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 PostFXPass:
-    """
-    PostFX Render Pass.
-    This pass handles post-processing effects like CRT simulation.
-    """
-
-    name: str = "PostFXPass"
-
-    # Justification: No implementation yet
-    # pylint: disable=unused-argument
-    def run(
-        self, backend: Backend, ctx: RenderContext, packets: list[RenderPacket]
-    ):
-        """Run the post-processing effects render pass."""
-        # hook/no-op for now (CRT later)
-        return