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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 1.0.2
+Version: 1.1.0
 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "mini-arcade-core"
-version = "1.0.2"
+version = "1.1.0"
 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.0}/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)

{mini_arcade_core-1.0.2 → mini_arcade_core-1.1.0}/src/mini_arcade_core/engine/game.py

@@ -17,8 +17,11 @@ from mini_arcade_core.engine.commands import (
     QuitCommand,
     ToggleDebugOverlayCommand,
 )
+from mini_arcade_core.engine.render.context import RenderContext
+from mini_arcade_core.engine.render.frame_packet import FramePacket
 from mini_arcade_core.engine.render.packet import RenderPacket
 from mini_arcade_core.engine.render.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
@@ -188,6 +191,7 @@ class Game:
             files=LocalFilesAdapter(),
             capture=CaptureAdapter(self.backend),
             input=InputAdapter(),
+            render=RenderService(),
         )
 
         self.command_queue = CommandQueue()
@@ -304,23 +308,39 @@ 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,
+            )
 
-                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.0/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.0/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.0/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]
+        """

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

@@ -0,0 +1,28 @@
+"""
+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

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

@@ -0,0 +1,112 @@
+"""
+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, 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
+
+
+@dataclass
+class RenderPipeline:
+    """
+    Minimal pipeline for v1.
+
+    Later you can expand this into passes:
+        - 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,
+        packet: RenderPacket,
+        viewport_state: ViewportState,
+    ):
+        """
+        Draw the given RenderPacket using the provided Backend.
+
+        :param backend: Backend to use for drawing.
+        :type backend: Backend
+
+        :param packet: RenderPacket to draw.
+        :type packet: RenderPacket
+        """
+        if not packet:
+            return
+
+        backend.set_viewport_transform(
+            viewport_state.offset_x,
+            viewport_state.offset_y,
+            viewport_state.scale,
+        )
+
+        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:
+                op(backend)
+        finally:
+            backend.clear_clip_rect()
+            backend.clear_viewport_transform()

mini_arcade_core-1.1.0/src/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-1.1.0/src/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-1.0.2 → mini_arcade_core-1.1.0}/src/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-1.0.2 → mini_arcade_core-1.1.0}/src/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-1.0.2 → mini_arcade_core-1.1.0}/src/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-1.0.2 → mini_arcade_core-1.1.0}/src/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-1.0.2 → mini_arcade_core-1.1.0}/src/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/src/mini_arcade_core/engine/render/pipeline.py

@@ -1,63 +0,0 @@
-"""
-Render pipeline module.
-Defines the RenderPipeline class for rendering RenderPackets.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from mini_arcade_core.backend import Backend
-from mini_arcade_core.engine.render.packet import RenderPacket
-from mini_arcade_core.engine.render.viewport import ViewportState
-
-
-@dataclass
-class RenderPipeline:
-    """
-    Minimal pipeline for v1.
-
-    Later you can expand this into passes:
-      - build draw list
-      - cull
-      - sort
-      - backend draw pass
-    """
-
-    def draw_packet(
-        self,
-        backend: Backend,
-        packet: RenderPacket,
-        viewport_state: ViewportState,
-    ):
-        """
-        Draw the given RenderPacket using the provided Backend.
-
-        :param backend: Backend to use for drawing.
-        :type backend: Backend
-
-        :param packet: RenderPacket to draw.
-        :type packet: RenderPacket
-        """
-        if not packet:
-            return
-
-        backend.set_viewport_transform(
-            viewport_state.offset_x,
-            viewport_state.offset_y,
-            viewport_state.scale,
-        )
-
-        # 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:
-                op(backend)
-        finally:
-            backend.clear_clip_rect()
-            backend.clear_viewport_transform()