mini-arcade-core 0.10.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

mini_arcade_core/utils/logging.py

@@ -0,0 +1,168 @@
+"""
+Logging utilities for Mini Arcade Core.
+Provides a console logger with colored output and class/function context.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Optional
+
+
+def _classname_from_locals(locals_: dict) -> Optional[str]:
+    """Retrieve the class name from locals dict, if available."""
+    self_obj = locals_.get("self")
+    if self_obj is not None:
+        return type(self_obj).__name__
+    cls_obj = locals_.get("cls")
+    if isinstance(cls_obj, type):
+        return cls_obj.__name__
+    return None
+
+
+class EnsureClassName(logging.Filter):
+    """
+    Populate record.classname by finding the *emitting* frame:
+    match by (pathname, funcName) and read self/cls from its locals.
+    Falls back to "-" when not in a class context.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        # record_factory ensures classname exists, but allow explicit override
+        if getattr(record, "classname", None) not in (None, "-"):
+            return True
+
+        target_path = record.pathname
+        target_func = record.funcName
+
+        # Justification: Seems pretty obvious here.
+        # pylint: disable=protected-access
+        f = sys._getframe()
+        # pylint: enable=protected-access
+
+        for _ in range(200):
+            if f is None:
+                break
+            code = f.f_code
+            if code.co_filename == target_path and code.co_name == target_func:
+                record.classname = _classname_from_locals(f.f_locals) or "-"
+                return True
+            f = f.f_back
+
+        record.classname = "-"
+        return True
+
+
+class ConsoleColorFormatter(logging.Formatter):
+    """
+    Console formatter with ANSI colors by log level.
+    """
+
+    COLORS = {
+        logging.DEBUG: "\033[96m",  # Cyan
+        logging.INFO: "\033[92m",  # Green
+        logging.WARNING: "\033[93m",  # Yellow
+        logging.ERROR: "\033[91m",  # Red
+        logging.CRITICAL: "\033[95m",  # Magenta
+        "RESET": "\033[0m",
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        color = self.COLORS.get(record.levelno, self.COLORS["RESET"])
+        msg = super().format(record)
+        return f"{color}{msg}{self.COLORS['RESET']}"
+
+
+LOGGER_FORMAT = (
+    "%(asctime)s [%(levelname)-8.8s] [%(name)s] "
+    "%(module)s.%(classname)s.%(funcName)s: "
+    "%(message)s (%(filename)s:%(lineno)d)"
+)
+
+
+def _enable_windows_ansi():
+    """
+    Best-effort enable ANSI escape sequences on Windows terminals.
+    Newer Windows 10/11 terminals usually support this already.
+    """
+    if os.name != "nt":
+        return
+    try:
+        # Enables VT100 sequences in some consoles; harmless if unsupported
+        # Justification: Importing ctypes only on Windows is acceptable.
+        # pylint: disable=import-outside-toplevel
+        import ctypes
+
+        # pylint: enable=import-outside-toplevel
+
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        handle = kernel32.GetStdHandle(-11)  # STD_OUTPUT_HANDLE = -11
+        mode = ctypes.c_uint32()
+        if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            # ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+            kernel32.SetConsoleMode(handle, mode.value | 0x0004)
+    # Justification: We want to catch all exceptions here.
+    # pylint: disable=broad-exception-caught
+    except Exception:
+        # If it fails, we just keep going without breaking logging.
+        pass
+    # pylint: enable=broad-exception-caught
+
+
+def _install_record_factory_defaults():
+    """
+    Ensure every LogRecord has `classname` so formatters never crash.
+    Safe to call multiple times; we keep the current factory chain.
+    """
+    old_factory = logging.getLogRecordFactory()
+
+    def record_factory(*args, **kwargs):
+        record = old_factory(*args, **kwargs)
+        if not hasattr(record, "classname"):
+            record.classname = "-"
+        return record
+
+    logging.setLogRecordFactory(record_factory)
+
+
+def configure_logging(level: int = logging.DEBUG):
+    """
+    Configure logging once for the whole app (root logger).
+    Call this early (app entrypoint). Safe to call multiple times.
+    """
+    _enable_windows_ansi()
+    _install_record_factory_defaults()
+
+    root = logging.getLogger()
+    root.setLevel(level)
+
+    # 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"
+
+    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)
+
+
+configure_logging()
+logger = logging.getLogger("mini-arcade-core")

{mini_arcade_core-0.10.0.dist-info → mini_arcade_core-1.0.1.dist-info}/METADATA

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

mini_arcade_core-1.0.1.dist-info/RECORD

@@ -0,0 +1,66 @@
+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/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=1g7XBWmiVYxe2IUggPpUs5uaZP9PHZKfr6cQuhez8eg,4044
+mini_arcade_core/engine/game.py,sha256=hq7cYdiQrPFNagc1BbARhzXYMBtFzCaTcTKQnNBDqy0,12137
+mini_arcade_core/engine/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+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/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
+mini_arcade_core/managers/inputs.py,sha256=9HZ0BnJyUX-elfGETPhhPZnTkz2bK83pEKj7GHPbPFU,8523
+mini_arcade_core/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/runtime/audio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/runtime/audio/audio_adapter.py,sha256=9ithbInYUB72ErwvlNrbIlI55uw0DT2QD33geYNXT3c,522
+mini_arcade_core/runtime/audio/audio_port.py,sha256=3Mqv7TchEVkmd-RVjUpCD-EqA-yiL0Jf2Sj3rQwP678,907
+mini_arcade_core/runtime/capture/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/runtime/capture/capture_adapter.py,sha256=qJ2JiOLJHbP00IesbAyyPGPBxSaxwPJRTMaMjMU4bXs,4660
+mini_arcade_core/runtime/capture/capture_port.py,sha256=NVxMJrQJELiSYuUJ29tvsdIcCBq4f1dTT2rDLZs6gnI,1230
+mini_arcade_core/runtime/context.py,sha256=IQpAhtbN0ZqJVXG6KXFq3FPk0sIGyPmyNgBYviqZl7A,1632
+mini_arcade_core/runtime/file/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/runtime/file/file_adapter.py,sha256=09q7G9Qijml9d4AAjo6HLC1yuoVTjE_7xaT8apT4mk0,523
+mini_arcade_core/runtime/file/file_port.py,sha256=p1MouCSHXZw--rWNMw3aYBLU-of8mXaT_suopczPtM8,608
+mini_arcade_core/runtime/input/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+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/scene/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/runtime/scene/scene_adapter.py,sha256=dYkqFWN3FcRmf9tsZ5wz1QZX67CUntndiNMOWrO578U,2523
+mini_arcade_core/runtime/scene/scene_port.py,sha256=uDFrN7fudIldNkivEkagQd9-b1HVI71BpTpSv5Oh6JI,3854
+mini_arcade_core/runtime/services.py,sha256=9LX7O-AYFTxKgBDewzu0B_D01EJ41WVAdl8U1ZcvEYg,1061
+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/registry.py,sha256=EF5qaAgoLwJa3IV_3wclvjHpE3jZt-KHB3GOJS9lQy8,3390
+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
+mini_arcade_core/scenes/systems/system_pipeline.py,sha256=Cy9y1DclbMLZZ-yx7OKYe34ORoGLNa6dReQfOdiO8SY,1642
+mini_arcade_core/sim/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/sim/protocols.py,sha256=b7d2WAKRokTNbteNhUaWdGx9vc9Fnccxb-5rPwozDaA,1099
+mini_arcade_core/sim/runner.py,sha256=ZF-BZJw-NcaFrg4zsUu1zOUUBZwZbRYflqcdF1jDcmM,7446
+mini_arcade_core/spaces/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/spaces/d2/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/spaces/d2/boundaries2d.py,sha256=xeTnd0pW5DKfqaKsfSBXnufeb45aXNIspgHRyLXWejo,2804
+mini_arcade_core/spaces/d2/collision2d.py,sha256=5IvgLnyVb8i0uzzZuum1noWsNhoxcvHOLaHkmrTMTxQ,1710
+mini_arcade_core/spaces/d2/geometry2d.py,sha256=FuYzef-XdOyb1aeGLJbxINxr0WJHnqFFBgtbPi1WonY,1716
+mini_arcade_core/spaces/d2/kinematics2d.py,sha256=AJ3DhPXNgm6wZYwCljMIE4_2BYx3E2rPcwhXTgQALkU,2030
+mini_arcade_core/spaces/d2/physics2d.py,sha256=OQT7r-zMtmoKD2aWCSNmRAdI0OGIpxGX-pLR8LcAMbQ,1854
+mini_arcade_core/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mini_arcade_core/ui/menu.py,sha256=pUC6qfG3lNXa1Ga2Kz_cSgjiAfAWVMRevum61G_RE8k,24646
+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.1.dist-info/METADATA,sha256=zon5lZWKZ3_tLUoLgjItQRCTWBxLEzHSOp1IyhNGH14,8188
+mini_arcade_core-1.0.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+mini_arcade_core-1.0.1.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-1.0.1.dist-info/RECORD,,

{mini_arcade_core-0.10.0.dist-info → mini_arcade_core-1.0.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.2.1
+Generator: poetry-core 2.3.0
 Root-Is-Purelib: true
 Tag: py3-none-any

mini_arcade_core/commands.py

@@ -1,84 +0,0 @@
-"""
-Command protocol for executing commands with a given context.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Generic, Protocol, TypeVar
-
-from mini_arcade_core.game import Game
-from mini_arcade_core.scenes.model import SceneModel
-
-if TYPE_CHECKING:
-    from mini_arcade_core.scenes.scene import Scene
-
-# Justification: Generic type for context
-# pylint: disable=invalid-name
-TContext = TypeVar("TContext")
-# pylint: enable=invalid-name
-
-
-class BaseCommand(Protocol, Generic[TContext]):
-    """
-    Protocol for a command that can be executed with a given context.
-    """
-
-    def __call__(self, context: TContext) -> None:
-        """
-        Execute the cheat code with the given context.
-
-        :param context: Context object for cheat execution.
-        :type context: TContext
-        """
-        self.execute(context)
-
-    def execute(self, context: TContext):
-        """
-        Execute the command with the given context.
-
-        :param context: Context object for command execution.
-        :type context: TContext
-        """
-
-
-class BaseGameCommand(BaseCommand[Game]):
-    """
-    Base class for commands that operate on the Game context.
-    """
-
-    def execute(self, context: Game) -> None:
-        """
-        Execute the command with the given Game context.
-
-        :param context: Game context for command execution.
-        :type context: Game
-        """
-        raise NotImplementedError(
-            "Execute method must be implemented by subclasses."
-        )
-
-
-class BaseSceneCommand(BaseCommand[SceneModel]):
-    """
-    Base class for commands that operate on the Scene SceneModel context within a scene.
-    """
-
-    def execute(self, context: SceneModel) -> None:
-        """
-        Execute the command with the given Scene Model context.
-
-        :param context: Scene Model context for command execution.
-        :type context: SceneModel
-        """
-        raise NotImplementedError(
-            "Execute method must be implemented by subclasses."
-        )
-
-
-class QuitGameCommand(BaseGameCommand):
-    """
-    Command to quit the game.
-    """
-
-    def execute(self, context: Game) -> None:
-        context.quit()

mini_arcade_core/entity.py

@@ -1,72 +0,0 @@
-"""
-Entity base classes for mini_arcade_core.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from mini_arcade_core.spaces.d2 import (
-    KinematicData,
-    Position2D,
-    RectCollider,
-    Size2D,
-)
-
-
-class Entity:
-    """Entity base class for game objects."""
-
-    def update(self, dt: float):
-        """
-        Advance the entity state by ``dt`` seconds.
-
-        :param dt: Time delta in seconds.
-        :type dt: float
-        """
-
-    def draw(self, surface: Any):
-        """
-        Render the entity to the given surface.
-
-        :param surface: The surface to draw on.
-        :type surface: Any
-        """
-
-
-class SpriteEntity(Entity):
-    """Entity with position and size."""
-
-    def __init__(self, position: Position2D, size: Size2D):
-        """
-        :param position: Top-left position of the entity.
-        :type position: Position2D
-
-        :param size: Size of the entity.
-        :type size: Size2D
-        """
-        self.position = Position2D(float(position.x), float(position.y))
-        self.size = Size2D(int(size.width), int(size.height))
-        self.collider = RectCollider(self.position, self.size)
-
-
-class KinematicEntity(SpriteEntity):
-    """SpriteEntity with velocity-based movement."""
-
-    def __init__(self, kinematic_data: KinematicData):
-        """
-        :param kinematic_data: Kinematic data for the entity.
-        :type kinematic_data: KinematicData
-        """
-        super().__init__(
-            position=kinematic_data.position,
-            size=kinematic_data.size,
-        )
-
-        self.time_scale = kinematic_data.time_scale
-        self.velocity = kinematic_data.velocity
-
-    def update(self, dt: float):
-        self.position.x, self.position.y = self.velocity.advance(
-            self.position.x, self.position.y, dt * self.time_scale
-        )

mini_arcade_core/game.py

@@ -1,287 +0,0 @@
-"""
-Game core module defining the Game class and configuration.
-"""
-
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-from datetime import datetime
-from pathlib import Path
-from time import perf_counter, sleep
-from typing import TYPE_CHECKING, Literal, Union
-
-from PIL import Image  # type: ignore[import]
-
-from mini_arcade_core.backend import Backend
-from mini_arcade_core.scenes.registry import SceneRegistry
-
-if TYPE_CHECKING:  # avoid runtime circular import
-    from mini_arcade_core.scenes import Scene
-
-SceneOrId = Union["Scene", str]
-
-
-@dataclass
-class GameConfig:
-    """
-    Configuration options for the Game.
-
-    :ivar width: Width of the game window in pixels.
-    :ivar height: Height of the game window in pixels.
-    :ivar title: Title of the game window.
-    :ivar fps: Target frames per second.
-    :ivar background_color: RGB background color.
-    :ivar backend: Optional Backend instance to use for rendering and input.
-    """
-
-    width: int = 800
-    height: int = 600
-    title: str = "Mini Arcade Game"
-    fps: int = 60
-    background_color: tuple[int, int, int] = (0, 0, 0)
-    backend: Backend | None = None
-
-
-Difficulty = Literal["easy", "normal", "hard", "insane"]
-
-
-@dataclass
-class GameSettings:
-    """
-    Game settings that can be modified during gameplay.
-
-    :ivar difficulty: Current game difficulty level.
-    """
-
-    difficulty: Difficulty = "normal"
-
-
-@dataclass
-class _StackEntry:
-    scene: "Scene"
-    as_overlay: bool = False
-
-
-class Game:
-    """Core game object responsible for managing the main loop and active scene."""
-
-    def __init__(
-        self, config: GameConfig, registry: SceneRegistry | None = None
-    ):
-        """
-        :param config: Game configuration options.
-        :type config: GameConfig
-
-        :param registry: Optional SceneRegistry for scene management.
-        :type registry: SceneRegistry | None
-
-        :raises ValueError: If the provided config does not have a valid Backend.
-        """
-        self.config = config
-        self._current_scene: Scene | None = None
-        self._running: bool = False
-
-        if config.backend is None:
-            raise ValueError(
-                "GameConfig.backend must be set to a Backend instance"
-            )
-        self.backend: Backend = config.backend
-        self.registry = registry or SceneRegistry(_factories={})
-        self._scene_stack: list[_StackEntry] = []
-        self.settings = GameSettings()
-
-    def current_scene(self) -> "Scene | None":
-        """
-        Get the currently active scene.
-
-        :return: The active Scene instance, or None if no scene is active.
-        :rtype: Scene | None
-        """
-        return self._scene_stack[-1].scene if self._scene_stack else None
-
-    def change_scene(self, scene: SceneOrId):
-        """
-        Swap the active scene. Concrete implementations should call
-        ``on_exit``/``on_enter`` appropriately.
-
-        :param scene: The new scene to activate.
-        :type scene: SceneOrId
-        """
-        scene = self._resolve_scene(scene)
-
-        while self._scene_stack:
-            entry = self._scene_stack.pop()
-            entry.scene.on_exit()
-
-        self._scene_stack.append(_StackEntry(scene=scene, as_overlay=False))
-        scene.on_enter()
-
-    def push_scene(self, scene: SceneOrId, as_overlay: bool = False):
-        """
-        Push a scene on top of the current one.
-        If as_overlay=True, underlying scene(s) may still be drawn but never updated.
-
-        :param scene: The scene to push onto the stack.
-        :type scene: SceneOrId
-
-        :param as_overlay: Whether to treat the scene as an overlay.
-        :type as_overlay: bool
-        """
-        scene = self._resolve_scene(scene)
-
-        top = self.current_scene()
-        if top is not None:
-            top.on_pause()
-
-        self._scene_stack.append(
-            _StackEntry(scene=scene, as_overlay=as_overlay)
-        )
-        scene.on_enter()
-
-    def pop_scene(self) -> "Scene | None":
-        """
-        Pop the top scene. If stack becomes empty, quit.
-
-        :return: The popped Scene instance, or None if the stack is now empty.
-        :rtype: Scene | None
-        """
-        if not self._scene_stack:
-            return None
-
-        popped = self._scene_stack.pop()
-        popped.scene.on_exit()
-
-        top = self.current_scene()
-        if top is None:
-            self.quit()
-            return popped.scene
-
-        top.on_resume()
-        return popped.scene
-
-    def _visible_stack(self) -> list["Scene"]:
-        """
-        Return the list of scenes that should be drawn (base + overlays).
-        We draw from the top-most non-overlay scene upward.
-        """
-        if not self._scene_stack:
-            return []
-
-        # find top-most base scene (as_overlay=False)
-        base_idx = 0
-        for i in range(len(self._scene_stack) - 1, -1, -1):
-            if not self._scene_stack[i].as_overlay:
-                base_idx = i
-                break
-
-        return [e.scene for e in self._scene_stack[base_idx:]]
-
-    def quit(self):
-        """Request that the main loop stops."""
-        self._running = False
-
-    def run(self, initial_scene: SceneOrId):
-        """
-        Run the main loop starting with the given scene.
-
-        This is intentionally left abstract so you can plug pygame, pyglet,
-        or another backend.
-
-        :param initial_scene: The scene to start the game with.
-        :type initial_scene: SceneOrId
-        """
-        backend = self.backend
-        backend.init(self.config.width, self.config.height, self.config.title)
-
-        br, bg, bb = self.config.background_color
-        backend.set_clear_color(br, bg, bb)
-
-        self.change_scene(initial_scene)
-
-        self._running = True
-        target_dt = 1.0 / self.config.fps if self.config.fps > 0 else 0.0
-        last_time = perf_counter()
-
-        while self._running:
-            now = perf_counter()
-            dt = now - last_time
-            last_time = now
-
-            top = self.current_scene()
-            if top is None:
-                break
-
-            for ev in backend.poll_events():
-                top.handle_event(ev)
-
-            top.update(dt)
-
-            backend.begin_frame()
-            for scene in self._visible_stack():
-                scene.draw(backend)
-            backend.end_frame()
-
-            if target_dt > 0 and dt < target_dt:
-                sleep(target_dt - dt)
-
-        # exit remaining scenes
-        while self._scene_stack:
-            entry = self._scene_stack.pop()
-            entry.scene.on_exit()
-
-    @staticmethod
-    def _convert_bmp_to_image(bmp_path: str, out_path: str) -> bool:
-        """
-        Convert a BMP file to another image format using Pillow.
-
-        :param bmp_path: Path to the input BMP file.
-        :type bmp_path: str
-
-        :param out_path: Path to the output image file.
-        :type out_path: str
-
-        :return: True if conversion was successful, False otherwise.
-        :rtype: bool
-        """
-        try:
-            img = Image.open(bmp_path)
-            img.save(out_path)  # Pillow chooses format from extension
-            return True
-        # Justification: Pillow can raise various exceptions on failure
-        # pylint: disable=broad-exception-caught
-        except Exception:
-            return False
-        # pylint: enable=broad-exception-caught
-
-    def screenshot(
-        self, label: str | None = None, directory: str = "screenshots"
-    ) -> str | None:
-        """
-        Ask backend to save a screenshot. Returns the file path or None.
-
-        :param label: Optional label to include in the filename.
-        :type label: str | None
-
-        :param directory: Directory to save screenshots in.
-        :type directory: str
-
-        :return: The file path of the saved screenshot, or None on failure.
-        :rtype: str | None
-        """
-        os.makedirs(directory, exist_ok=True)
-        stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        label = label or "shot"
-        filename = f"{stamp}_{label}"
-        bmp_path = os.path.join(directory, f"{filename}.bmp")
-
-        if self.backend.capture_frame(bmp_path):
-            out_path = Path(directory) / f"{filename}.png"
-            self._convert_bmp_to_image(bmp_path, str(out_path))
-            return str(out_path)
-        return None
-
-    def _resolve_scene(self, scene: SceneOrId) -> "Scene":
-        if isinstance(scene, str):
-            return self.registry.create(scene, self)
-        return scene