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

mini_arcade_core/scenes/debug_overlay.py

@@ -4,11 +4,12 @@ Debug overlay scene that displays FPS, window size, and scene stack information.
 
 from __future__ import annotations
 
+from mini_arcade_core.backend.backend import Backend
 from mini_arcade_core.engine.render.packet import RenderPacket
 from mini_arcade_core.runtime.context import RuntimeContext
 from mini_arcade_core.runtime.input_frame import InputFrame
 from mini_arcade_core.scenes.autoreg import register_scene
-from mini_arcade_core.sim.protocols import SimScene
+from mini_arcade_core.scenes.sim_scene import SimScene
 
 
 @register_scene("debug_overlay")
@@ -55,14 +56,14 @@ class DebugOverlayScene(SimScene):
         for e in stack:
             lines.append(f"  - {e.scene_id} overlay={e.is_overlay}")
 
-        def draw(backend):
+        def draw(backend: Backend):
             # translucent background panel
-            backend.draw_rect(
+            backend.render.draw_rect(
                 8, 8, 360, 18 * (len(lines) + 1), color=(0, 0, 0, 0.65)
             )
             y = 14
             for line in lines:
-                backend.draw_text(
+                backend.text.draw(
                     16, y, line, color=(255, 255, 255), font_size=14
                 )
                 y += 18

mini_arcade_core/scenes/registry.py

@@ -15,7 +15,7 @@ from mini_arcade_core.runtime.context import RuntimeContext
 from .autoreg import snapshot
 
 if TYPE_CHECKING:
-    from mini_arcade_core.sim.protocols import SimScene
+    from mini_arcade_core.scenes.sim_scene import SimScene
 
 
 class SceneFactory(Protocol):
@@ -34,6 +34,16 @@ class SceneRegistry:
 
     _factories: Dict[str, SceneFactory]
 
+    @property
+    def listed_scene_ids(self) -> list[str]:
+        """
+        Get a list of all registered scene IDs.
+
+        :return: A list of registered scene IDs.
+        :rtype: list[str]
+        """
+        return list(self._factories.keys())
+
     def register(self, scene_id: str, factory: SceneFactory):
         """
         Register a scene factory under a given scene ID.

mini_arcade_core/scenes/sim_scene.py

@@ -5,15 +5,23 @@ Defines the SimScene protocol for simulation scenes.
 
 from __future__ import annotations
 
-from typing import Protocol, runtime_checkable
+from dataclasses import dataclass
 
 from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.runtime.context import RuntimeContext
 from mini_arcade_core.runtime.input_frame import InputFrame
 
 
-@runtime_checkable
-class SimScene(Protocol):
-    """ "Protocol for a simulation scene in the mini arcade core."""
+@dataclass
+class SimScene:
+    """
+    Simulation-first scene protocol.
+    tick() advances the simulation and returns a RenderPacket for this scene.
+
+    :ivar context: RuntimeContext for this scene.
+    """
+
+    context: RuntimeContext
 
     def on_enter(self):
         """Called when the scene is entered."""
@@ -21,9 +29,9 @@ class SimScene(Protocol):
     def on_exit(self):
         """Called when the scene is exited."""
 
-    def tick(self, input_frame: InputFrame, dt: float):
+    def tick(self, input_frame: InputFrame, dt: float) -> RenderPacket:
         """
-        Advance the simulation by one tick.
+        Advance the simulation by dt seconds, processing input_frame.
 
         :param input_frame: Current input frame.
         :type input_frame: InputFrame
@@ -31,11 +39,3 @@ class SimScene(Protocol):
         :param dt: Delta time since last tick.
         :type dt: float
         """
-
-    def build_render_packet(self) -> RenderPacket:
-        """
-        Build the render packet for the current scene state.
-
-        :return: RenderPacket instance.
-        :rtype: RenderPacket
-        """

mini_arcade_core/ui/menu.py

@@ -15,8 +15,8 @@ from mini_arcade_core.engine.commands import Command, CommandQueue, QuitCommand
 from mini_arcade_core.engine.render.packet import RenderPacket
 from mini_arcade_core.runtime.context import RuntimeContext
 from mini_arcade_core.runtime.input_frame import InputFrame
+from mini_arcade_core.scenes.sim_scene import SimScene
 from mini_arcade_core.scenes.systems.system_pipeline import SystemPipeline
-from mini_arcade_core.sim.protocols import SimScene
 from mini_arcade_core.spaces.d2.geometry2d import Size2D
 
 
@@ -271,12 +271,15 @@ class Menu:
 
         # 0) Solid background (for main menus)
         if self.style.background_color is not None:
-            surface.draw_rect(0, 0, vw, vh, color=self.style.background_color)
+            surface.render.draw_rect(
+                0, 0, vw, vh, color=self.style.background_color
+            )
 
         # 1) Overlay (for pause, etc.)
         if self.style.overlay_color is not None:
-            surface.draw_rect(0, 0, vw, vh, color=self.style.overlay_color)
-
+            surface.render.draw_rect(
+                0, 0, vw, vh, color=self.style.overlay_color
+            )
         # 2) Compute menu content bounds (panel area)
         content_w, content_h, title_h = self._measure_content(surface)
 
@@ -292,7 +295,7 @@ class Menu:
 
         # 3) Panel (optional)
         if self.style.panel_color is not None:
-            surface.draw_rect(
+            surface.render.draw_rect(
                 x0, y0, panel_w, panel_h, color=self.style.panel_color
             )
 
@@ -357,7 +360,7 @@ class Menu:
         else:
             max_label_w = 0
             for it in self.items:
-                w, _ = surface.measure_text(
+                w, _ = surface.text.measure(
                     it.label, font_size=self.style.item_font_size
                 )
                 max_label_w = max(max_label_w, w)
@@ -384,18 +387,22 @@ class Menu:
             )
 
             # Border rect
-            surface.draw_rect(x - 4, y - 4, bw + 8, bh + 8, color=border)
+            surface.render.draw_rect(
+                x - 4, y - 4, bw + 8, bh + 8, color=border
+            )
             # Fill rect
-            surface.draw_rect(x, y, bw, bh, color=self.style.button_fill)
+            surface.render.draw_rect(
+                x, y, bw, bh, color=self.style.button_fill
+            )
 
             # Label color
             text_color = self.style.selected if selected else self.style.normal
-            tw, th = surface.measure_text(
+            tw, th = surface.text.measure(
                 item.label, font_size=self.style.item_font_size
             )
             tx = x + (bw - tw) // 2
             ty = y + (bh - th) // 2
-            surface.draw_text(
+            surface.text.draw(
                 tx,
                 ty,
                 item.label,
@@ -412,7 +419,7 @@ class Menu:
 
         # Title
         if self.title:
-            tw, th = surface.measure_text(
+            tw, th = surface.text.measure(
                 self.title, font_size=self.style.title_font_size
             )
             max_w = max(max_w, tw)
@@ -433,7 +440,7 @@ class Menu:
             else:
                 max_label_w = 0
                 for it in self.items:
-                    w, _ = surface.measure_text(
+                    w, _ = surface.text.measure(
                         it.label, font_size=self.style.item_font_size
                     )
                     max_label_w = max(max_label_w, w)
@@ -446,7 +453,7 @@ class Menu:
             items_h = len(self.items) * bh + (len(self.items) - 1) * gap
         else:
             for it in self.items:
-                w, _ = surface.measure_text(
+                w, _ = surface.text.measure(
                     it.label, font_size=self.style.item_font_size
                 )
                 max_w = max(max_w, w)
@@ -480,13 +487,33 @@ class Menu:
         color: Color,
         font_size: int | None = None,
     ):
-        w, _ = surface.measure_text(text, font_size=font_size)
-        surface.draw_text(
+        w, _ = surface.text.measure(text, font_size=font_size)
+        surface.text.draw(
             x_center - (w // 2), y, text, color=color, font_size=font_size
         )
 
     # pylint: enable=too-many-arguments
 
+    def set_viewport(self, viewport: Size2D):
+        """
+        Set the viewport size for the menu.
+
+        :param viewport: New viewport size.
+        :type viewport: Size2D
+        """
+        if self.viewport is None:
+            self.viewport = viewport
+            return
+
+        old_w, old_h = self.viewport
+        new_w, new_h = viewport
+        self.viewport = viewport
+
+        # If the viewport changed (especially shrinking), allow layout to shrink too.
+        if (new_w < old_w) or (new_h < old_h):
+            self._max_content_w_seen = 0
+            self._max_button_w_seen = 0
+
 
 # pylint: enable=too-many-instance-attributes
 
@@ -722,7 +749,7 @@ class BaseMenuScene(SimScene):
     def on_enter(self):
         self.menu = Menu(
             self._build_display_items(),
-            viewport=self.context.services.window.get_virtual_size(),
+            viewport=self.menu_viewport(),
             title=self.menu_title,
             style=self.menu_style(),
         )
@@ -738,6 +765,7 @@ class BaseMenuScene(SimScene):
         )
 
     def tick(self, input_frame: InputFrame, dt: float) -> RenderPacket:
+        self.menu.set_viewport(self.menu_viewport())
         items = self.menu_items()
         if not items:
             return RenderPacket()
@@ -761,6 +789,16 @@ class BaseMenuScene(SimScene):
         # always return packet from pipeline
         return ctx.packet or RenderPacket()
 
+    def menu_viewport(self) -> Size2D:
+        """
+        Get the viewport size for the menu.
+
+        :return: The Size2D representing the menu viewport.
+        :rtype: Size2D
+        """
+        # default: virtual space (fits your UI layout)
+        return self.context.services.window.get_virtual_size()
+
     def _build_display_items(self) -> list[MenuItem]:
         """
         Resolve dynamic labels (label_fn(ctx)) into the label field the Menu draws.

mini_arcade_core/utils/__init__.py

@@ -6,5 +6,6 @@ from __future__ import annotations
 
 from .deprecated_decorator import deprecated
 from .logging import logger
+from .profiler import FrameTimer
 
-__all__ = ["logger", "deprecated"]
+__all__ = ["logger", "deprecated", "FrameTimer"]

mini_arcade_core/utils/logging.py

@@ -82,6 +82,29 @@ LOGGER_FORMAT = (
 )
 
 
+class OnlyPerf(logging.Filter):
+    """Performance logger filter to include only perf logs."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.name.startswith("mini-arcade-core.perf")
+
+
+class ExcludePerf(logging.Filter):
+    """Performance logger filter to exclude perf logs."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not record.name.startswith("mini-arcade-core.perf")
+
+
+class PerfFormatter(logging.Formatter):
+    """Formatter for performance logs."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        # No global level color wrap; let the message carry its own ANSI
+        ts = self.formatTime(record, "%Y-%m-%d %H:%M:%S")
+        return f"{ts} [{record.levelname:<8}] [mini-arcade-core]\nprofiler:\n{record.getMessage()}"
+
+
 def _enable_windows_ansi():
     """
     Best-effort enable ANSI escape sequences on Windows terminals.
@@ -141,27 +164,33 @@ def configure_logging(level: int = logging.DEBUG):
     # Avoid duplicate handlers if reloaded/imported multiple times
     # We tag our handler so we can find it reliably.
     handler_tag = "_mini_arcade_core_console_handler"
+    perf_tag = "_mini_arcade_core_perf_handler"
 
+    # --- main console handler (your current one) ---
+    main_console = None
     for h in list(root.handlers):
         if getattr(h, handler_tag, False):
-            # Already configured
-            return
-
-    console = logging.StreamHandler(stream=sys.stdout)
-    setattr(console, handler_tag, True)
-
-    console.setFormatter(ConsoleColorFormatter(LOGGER_FORMAT))
-    console.addFilter(EnsureClassName())
-
-    # Important: don’t leave any basicConfig handlers around if someone called it earlier
-    # We remove only the plain StreamHandlers that don't have our tag.
-    for h in list(root.handlers):
-        if isinstance(h, logging.StreamHandler) and not getattr(
-            h, handler_tag, False
-        ):
-            root.removeHandler(h)
-
-    root.addHandler(console)
+            main_console = h
+            break
+
+    if main_console is None:
+        main_console = logging.StreamHandler(stream=sys.stdout)
+        setattr(main_console, handler_tag, True)
+        main_console.setFormatter(ConsoleColorFormatter(LOGGER_FORMAT))
+        main_console.addFilter(EnsureClassName())
+        root.addHandler(main_console)
+
+    # EXCLUDE perf logs from main handler (prevents duplicates)
+    main_console.addFilter(ExcludePerf())
+
+    # --- perf handler (new) ---
+    already = any(getattr(h, perf_tag, False) for h in root.handlers)
+    if not already:
+        perf_console = logging.StreamHandler(stream=sys.stdout)
+        setattr(perf_console, perf_tag, True)
+        perf_console.setFormatter(PerfFormatter())
+        perf_console.addFilter(OnlyPerf())
+        root.addHandler(perf_console)
 
 
 configure_logging()

mini_arcade_core/utils/profiler.py

@@ -0,0 +1,283 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+from dataclasses import dataclass, field
+from time import perf_counter
+from typing import Dict, Iterable, Mapping
+
+perf_logger = logging.getLogger("mini-arcade-core.perf")
+
+
+class Ansi(enum.Enum):
+    """
+    ANSI escape codes for terminal text formatting.
+
+    cvar RESET (str): Reset all formatting.
+    cvar BOLD (str): Bold text.
+    cvar DIM (str): Dim text.
+    cvar RED (str): Red text.
+    cvar GREEN (str): Green text.
+    cvar YELLOW (str): Yellow text.
+    cvar CYAN (str): Cyan text.
+    cvar MAGENTA (str): Magenta text.
+    cvar WHITE (str): White text.
+    """
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+
+    RED = "\033[91m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    CYAN = "\033[96m"
+    MAGENTA = "\033[95m"
+    WHITE = "\033[97m"
+
+
+def _c(text: str, *codes: str) -> str:
+    """Convenience function to wrap text with ANSI codes."""
+    return "".join(codes) + text + Ansi.RESET.value
+
+
+@dataclass(frozen=True)
+class FrameTimingReport:
+    """
+    Report of frame timing data.
+
+    :ivar frame_index (int): Index of the frame.
+    :ivar diffs_ms (Dict[str, float]): Dictionary of time differences in milliseconds.
+    :ivar total_ms (float): Total time in milliseconds.
+    :ivar budget_ms (float): Frame budget in milliseconds.
+    """
+
+    frame_index: int
+    diffs_ms: Dict[str, float]
+    total_ms: float
+    budget_ms: float
+
+
+@dataclass(frozen=True)
+class FrameTimingFormatter:
+    """
+    Formats a FrameTimingReport into a colored, multi-line table string.
+    Keeps FrameTimer lean and avoids pylint complexity in the timer itself.
+
+    :ivar target_fps (int): Target frames per second for budget calculation.
+    :ivar top_n (int): Number of top time-consuming segments to display.
+    :ivar min_ms (float): Minimum time in milliseconds to include in the top list.
+    :ivar phases (tuple[tuple[str, str], ...]): Tuples of (display name, mark key)
+        for table columns.
+    """
+
+    target_fps: int = 60
+    top_n: int = 6
+    min_ms: float = 0.05
+
+    # These are the “headline” segments you want as columns.
+    phases: tuple[tuple[str, str], ...] = (
+        ("events", "frame_start->events_polled"),
+        ("input", "events_polled->input_built"),
+        ("tick", "tick_start->tick_end"),
+        ("render", "render_start->render_done"),
+        ("sleep", "sleep_start->sleep_end"),
+    )
+
+    def make_report(
+        self, frame_index: int, diffs_ms: Dict[str, float]
+    ) -> FrameTimingReport:
+        """
+        Create a FrameTimingReport from the given diffs.
+
+        :param frame_index: Index of the frame.
+        :type frame_index: int
+        :param diffs_ms: Dictionary of time differences in milliseconds.
+        :type diffs_ms: Dict[str, float]
+        :return: FrameTimingReport instance.
+        :rtype: FrameTimingReport
+        """
+        total = sum(diffs_ms.values()) if diffs_ms else 0.0
+        budget = (1000.0 / self.target_fps) if self.target_fps > 0 else 0.0
+        return FrameTimingReport(
+            frame_index=frame_index,
+            diffs_ms=diffs_ms,
+            total_ms=total,
+            budget_ms=budget,
+        )
+
+    def format(self, report: FrameTimingReport) -> str:
+        """
+        Format the FrameTimingReport into a colored string.
+
+        :param report: FrameTimingReport instance.
+        :type report: FrameTimingReport
+        :return: Formatted string.
+        :rtype: str
+        """
+        header = self._format_header(report)
+        table = self._format_table(report.diffs_ms)
+        top = self._format_top(report.diffs_ms)
+        return f"{header}\n{table}\n{top}\n"
+
+    def _format_header(self, report: FrameTimingReport) -> str:
+        over = report.budget_ms > 0 and report.total_ms > report.budget_ms
+        status = (
+            _c("OVER", Ansi.BOLD.value, Ansi.RED.value)
+            if over
+            else _c("OK", Ansi.BOLD.value, Ansi.GREEN.value)
+        )
+
+        frame = _c(
+            f"[Frame {report.frame_index}]", Ansi.BOLD.value, Ansi.WHITE.value
+        )
+        total = _c(
+            f"{report.total_ms:.2f}ms", Ansi.BOLD.value, Ansi.WHITE.value
+        )
+        budget = _c(f"{report.budget_ms:.2f}ms", Ansi.DIM.value)
+        dim = Ansi.DIM.value
+
+        return (
+            f"{frame} {_c('total', dim)}={total} "
+            f"{_c('budget', dim)}={budget} {_c('status', dim)}={status}"
+        )
+
+    def _format_table(self, diffs: Mapping[str, float]) -> str:
+        # Header line
+        headers = [name for name, _ in self.phases]
+        line_h = self._pipe_row((_c(h, Ansi.DIM.value) for h in headers))
+
+        # Values line
+        values = [diffs.get(key, 0.0) for _, key in self.phases]
+        line_v = self._pipe_row(self._color_values(values))
+
+        return f"{line_h}\n{line_v}"
+
+    def _color_values(self, values: Iterable[float]) -> list[str]:
+        # Keep coloring policy centralized and easy to tweak.
+        # events/input: cyan, tick: yellow, render: magenta, sleep: green
+        colors = [
+            Ansi.CYAN.value,
+            Ansi.CYAN.value,
+            Ansi.YELLOW.value,
+            Ansi.MAGENTA.value,
+            Ansi.GREEN.value,
+        ]
+        out: list[str] = []
+        for v, col in zip(values, colors):
+            out.append(_c(f"{v:6.2f}", col))
+        return out
+
+    def _format_top(self, diffs: Mapping[str, float]) -> str:
+        dim = Ansi.DIM.value
+        items = [
+            (k, float(v)) for k, v in diffs.items() if float(v) >= self.min_ms
+        ]
+        items.sort(key=lambda kv: kv[1], reverse=True)
+        items = items[: self.top_n]
+
+        if not items:
+            return f"{_c('top:', dim)} (none >= {self.min_ms:.2f}ms)"
+
+        top_str = ", ".join(f"{k}:{v:.2f}ms" for k, v in items)
+        return f"{_c('top:', dim)} {top_str}"
+
+    @staticmethod
+    def _pipe_row(cells: Iterable[str]) -> str:
+        # Keeps lines short and avoids long f-strings.
+        return " | ".join(cells)
+
+
+@dataclass
+class FrameTimerConfig:
+    """
+    Configuration for FrameTimer.
+
+    :ivar enabled (bool): Whether timing is enabled.
+    :ivar report_every (int): Number of frames between reports.
+    """
+
+    enabled: bool = False
+    report_every: int = 60
+
+
+@dataclass
+class FrameTimer:
+    """
+    Simple frame timer for marking and reporting time intervals.
+
+    :ivar config (FrameTimerConfig): Configuration for the timer.
+    :ivar formatter (FrameTimingFormatter): Formatter for timing reports.
+    :ivar marks (Dict[str, float]): Recorded time marks.
+    """
+
+    config: FrameTimerConfig = field(default_factory=FrameTimerConfig)
+    formatter: FrameTimingFormatter = field(
+        default_factory=FrameTimingFormatter
+    )
+    marks: Dict[str, float] = field(default_factory=dict)
+
+    def clear(self):
+        """Clear all recorded marks."""
+        if not self.config.enabled:
+            return
+        self.marks.clear()
+
+    def mark(self, name: str):
+        """
+        Record a time mark with the given name.
+
+        :param name: Name of the mark.
+        :type name: str
+        """
+        if not self.config.enabled:
+            return
+        self.marks[name] = perf_counter()
+
+    def report_ms(self) -> Dict[str, float]:
+        """
+        Returns diffs between consecutive marks in insertion order.
+
+        :return: Dictionary mapping "start->end" to time difference in milliseconds.
+        :rtype: Dict[str, float]
+        """
+        if not self.config.enabled:
+            return {}
+        keys = list(self.marks.keys())
+        out: Dict[str, float] = {}
+        for a, b in zip(keys, keys[1:]):
+            out[f"{a}->{b}"] = (self.marks[b] - self.marks[a]) * 1000.0
+        return out
+
+    def should_report(self, frame_index: int) -> bool:
+        """
+        Determine if a report should be emitted for the given frame index.
+
+        :param frame_index: Current frame index.
+        :type frame_index: int
+        :return: True if a report should be emitted, False otherwise.
+        :rtype: bool
+        """
+        return (
+            self.config.enabled
+            and self.config.report_every > 0
+            and frame_index > 0
+            and (frame_index % self.config.report_every == 0)
+        )
+
+    def emit(self, frame_index: int):
+        """
+        Emit a timing report to the performance logger.
+
+        :param frame_index: Current frame index.
+        :type frame_index: int
+        """
+        if not self.config.enabled:
+            return
+        diffs = self.report_ms()
+        report = self.formatter.make_report(frame_index, diffs)
+        perf_logger.info(self.formatter.format(report))

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

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