mini-arcade-core 0.9.6__tar.gz → 0.9.8__tar.gz

{mini_arcade_core-0.9.6 → mini_arcade_core-0.9.8}/PKG-INFO

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

{mini_arcade_core-0.9.6 → mini_arcade_core-0.9.8}/pyproject.toml

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

{mini_arcade_core-0.9.6 → mini_arcade_core-0.9.8}/src/mini_arcade_core/__init__.py

@@ -1,43 +1,16 @@
 """
 Entry point for the mini_arcade_core package.
 Provides access to core classes and a convenience function to run a game.
-
-mini_arcade_core/
-|-- __init__.py # main entry point
-|-- game.py # core game loop and management
-|-- entity.py # base entity classes
-|-- backend/ # backend abstraction layer
-|   |-- __init__.py
-|   |-- backend.py # abstract Backend class
-|   |-- events.py # event definitions
-|   |-- types.py # common types like Color
-|-- keymaps/ # key mapping utilities
-|   |-- __init__.py
-|   |-- keys.py # key definitions and keymaps
-|   |-- sdl.py # SDL keycode mappings
-|-- scenes/ # scene management
-|   |-- __init__.py
-|   |-- autoreg.py # automatic scene registration
-|   |-- registry.py # SceneRegistry class
-|   |-- scene.py # base Scene class
-|-- two_d/ # 2D utilities and types
-|   |-- __init__.py
-|   |-- boundaries2d.py # boundary behaviors
-|   |-- collision2d.py # collision detection
-|   |-- geometry2d.py # geometric types like Position2D, Size2D
-|   |-- kinematics2d.py # kinematic data structures
-|   |-- physics2d.py # physics-related types like Velocity2D
-|-- ui/ # user interface components
-|   |-- __init__.py
-|   |-- menu.py # menu components
 """
 
 from __future__ import annotations
 
 import logging
 from importlib.metadata import PackageNotFoundError, version
+from typing import Callable, Type, Union
 
 from mini_arcade_core.backend import Backend, Event, EventType
+from mini_arcade_core.cheats import CheatCode, CheatManager
 from mini_arcade_core.entity import Entity, KinematicEntity, SpriteEntity
 from mini_arcade_core.game import Game, GameConfig
 from mini_arcade_core.keymaps.keys import Key, keymap
@@ -55,19 +28,27 @@ from mini_arcade_core.two_d import (
     VerticalWrap,
 )
 
+SceneFactoryLike = Union[Type[Scene], Callable[[Game], Scene]]
+
 logger = logging.getLogger(__name__)
 
 
 def run_game(
-    initial_scene_cls: type[Scene],
+    scene: SceneFactoryLike | None = None,
     config: GameConfig | None = None,
     registry: SceneRegistry | None = None,
+    initial_scene: str = "main",
 ):
     """
     Convenience helper to bootstrap and run a game with a single scene.
 
-    :param initial_scene_cls: The Scene subclass to instantiate as the initial scene.
-    :type initial_scene_cls: type[Scene]
+    Supports both:
+      - run_game(SceneClass, cfg)            # legacy
+      - run_game(config=cfg, initial_scene="main", registry=...)  # registry-based
+      - run_game(cfg)                       # config-only
+
+    :param initial_scene: The Scene ID to start the game with.
+    :type initial_scene: str
 
     :param config: Optional GameConfig to customize game settings.
     :type config: GameConfig | None
@@ -77,14 +58,27 @@ def run_game(
 
     :raises ValueError: If the provided config does not have a valid Backend.
     """
+    # Handle run_game(cfg) where the first arg is actually a GameConfig
+    if isinstance(scene, GameConfig) and config is None:
+        config = scene
+        scene = None
+
     cfg = config or GameConfig()
-    if config.backend is None:
+    if cfg.backend is None:
         raise ValueError(
             "GameConfig.backend must be set to a Backend instance"
         )
+
+    # If user provided a Scene factory/class, ensure it's registered
+    if scene is not None:
+        if registry is None:
+            registry = SceneRegistry(_factories={})
+        registry.register(
+            initial_scene, scene
+        )  # Scene class is callable(game) -> Scene
+
     game = Game(cfg, registry=registry)
-    scene = initial_scene_cls(game)
-    game.run(scene)
+    game.run(initial_scene)
 
 
 __all__ = [
@@ -112,6 +106,8 @@ __all__ = [
     "keymap",
     "SceneRegistry",
     "register_scene",
+    "CheatManager",
+    "CheatCode",
 ]
 
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml
@@ -141,6 +137,3 @@ def get_version() -> str:
 
 
 __version__ = get_version()
-__version__ = get_version()
-__version__ = get_version()
-__version__ = get_version()

mini_arcade_core-0.9.8/src/mini_arcade_core/cheats.py

@@ -0,0 +1,235 @@
+"""
+Cheats module for Mini Arcade Core.
+Provides cheat codes and related functionality.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, Deque, Dict, Optional, Sequence, TypeVar
+
+# Justification: We want to keep the type variable name simple here.
+# pylint: disable=invalid-name
+TContext = TypeVar("TContext")
+# pylint: enable=invalid-name
+
+CheatCallback = Callable[[TContext], None]
+
+
+@dataclass(frozen=True)
+class CheatCode:
+    """
+    Represents a registered cheat code.
+
+    :ivar name (str): Unique name of the cheat code.
+    :ivar sequence (tuple[str, ...]): Sequence of key strings that trigger the cheat.
+    :ivar callback (CheatCallback): Function to call when the cheat is activated.
+    :ivar clear_buffer_on_match (bool): Whether to clear the input buffer after a match.
+    :ivar enabled (bool): Whether the cheat code is enabled.
+    """
+
+    name: str
+    sequence: tuple[str, ...]
+    callback: CheatCallback
+    clear_buffer_on_match: bool = False
+    enabled: bool = True
+
+
+class CheatManager:
+    """
+    Reusable cheat code matcher.
+    Keeps a rolling buffer of recent keys and triggers callbacks on sequence match.
+    """
+
+    def __init__(
+        self,
+        buffer_size: int = 16,
+        *,
+        enabled: bool = True,
+        normalize: Optional[Callable[[str], str]] = None,
+        key_getter: Optional[Callable[[object], Optional[str]]] = None,
+    ):
+        """
+        :param buffer_size: Maximum size of the input buffer.
+        :type buffer_size: int
+
+        :param enabled: Whether the cheat manager is enabled.
+        :type enabled: bool
+
+        :param normalize: Optional function to normalize key strings.
+        :type normalize: Callable[[str], str] | None
+
+        :param key_getter: Optional function to extract key string from event object.
+        :type key_getter: Callable[[object], Optional[str]] | None
+        """
+        self.enabled = enabled
+        self._buffer: Deque[str] = deque(maxlen=buffer_size)
+        self._codes: Dict[str, CheatCode] = {}
+
+        self._normalize = normalize or (lambda s: s.strip().upper())
+        # key_getter: how to extract a key from an engine/backend event object
+        self._key_getter = key_getter or self._default_key_getter
+
+    # Justification: We want to keep the number of arguments manageable here.
+    # pylint: disable=too-many-arguments
+    def register_code(
+        self,
+        name: str,
+        sequence: Sequence[str],
+        callback: CheatCallback,
+        *,
+        clear_buffer_on_match: bool = False,
+        enabled: bool = True,
+    ):
+        """
+        Register a new cheat code.
+
+        :param name: Unique name for the cheat code.
+        :type name: str
+
+        :param sequence: Sequence of key strings that trigger the cheat.
+        :type sequence: Sequence[str]
+
+        :param callback: Function to call when the cheat is activated.
+        :type callback: CheatCallback
+
+        :param clear_buffer_on_match: Whether to clear the input buffer after a match.
+        :type clear_buffer_on_match: bool
+
+        :param enabled: Whether the cheat code is enabled.
+        :type enabled: bool
+        """
+        if not name:
+            raise ValueError("Cheat code name must be non-empty.")
+        if not sequence:
+            raise ValueError(
+                f"Cheat code '{name}' sequence must be non-empty."
+            )
+
+        norm_seq = tuple(self._normalize(k) for k in sequence)
+        self._codes[name] = CheatCode(
+            name=name,
+            sequence=norm_seq,
+            callback=callback,
+            clear_buffer_on_match=clear_buffer_on_match,
+            enabled=enabled,
+        )
+
+    # pylint: enable=too-many-arguments
+
+    def unregister_code(self, name: str):
+        """
+        Unregister a cheat code by name.
+
+        :param name: Name of the cheat code to unregister.
+        :type name: str
+        """
+        self._codes.pop(name, None)
+
+    def clear_buffer(self):
+        """Clear the input buffer."""
+        self._buffer.clear()
+
+    def process_event(self, event: object, context: TContext) -> list[str]:
+        """
+        Call from Scene when a key is pressed.
+        Returns list of cheat names matched (often 0 or 1).
+
+        :param event: The event object from the backend/engine.
+        :type event: object
+
+        :param context: Context object passed to cheat callbacks.
+        :type context: TContext
+        """
+        if not self.enabled:
+            return []
+        key = self._key_getter(event)
+        if not key:
+            return []
+        return self.process_key(key, context)
+
+    def process_key(self, key: str, context: TContext) -> list[str]:
+        """
+        Pure method for tests: feed a key string directly.
+
+        :param key: The key string to process.
+        :type key: str
+
+        :param context: Context object passed to cheat callbacks.
+        :type context: TContext
+
+        :return: List of cheat names matched.
+        :rtype: list[str]
+        """
+        if not self.enabled:
+            return []
+
+        k = self._normalize(key)
+        if not k:
+            return []
+
+        self._buffer.append(k)
+        buf = tuple(self._buffer)
+
+        matched: list[str] = []
+        # Check if buffer ends with any cheat sequence
+        for code in self._codes.values():
+            if not code.enabled:
+                continue
+            seq = code.sequence
+            if len(seq) > len(buf):
+                continue
+            if buf[-len(seq) :] == seq:
+                code.callback(context)
+                matched.append(code.name)
+                if code.clear_buffer_on_match:
+                    self.clear_buffer()
+                    break  # buffer changed; stop early
+
+        return matched
+
+    @staticmethod
+    def _default_key_getter(event: object) -> Optional[str]:
+        """
+        Best-effort extraction:
+        - event.key
+        - event.key_code
+        - event.code
+        - event.scancode
+        - dict-like {"key": "..."}
+        Adjust/override with key_getter in your engine if needed.
+
+        :param event: The event object.
+        :type event: object
+
+        :return: Extracted key string, or None if not found.
+        :rtype: Optional[str]
+        """
+        if event is None:
+            return None
+
+        # dict-like
+        if isinstance(event, dict):
+            v = (
+                event.get("key")
+                or event.get("key_code")
+                or event.get("code")
+                or event.get("scancode")
+            )
+            if isinstance(v, Enum):
+                return v.name
+            return str(v) if v is not None else None
+
+        # object-like
+        for attr in ("key", "key_code", "code", "scancode"):
+            if hasattr(event, attr):
+                v = getattr(event, attr)
+                if v is None:
+                    continue
+                if isinstance(v, Enum):
+                    return v.name  # <-- THIS is the important bit
+                return str(v)
+
+        return None