mini-arcade-core 0.9.7__py3-none-any.whl → 0.9.9__py3-none-any.whl

mini_arcade_core/__init__.py

@@ -10,10 +10,16 @@ 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
-from mini_arcade_core.scenes import Scene, SceneRegistry, register_scene
+from mini_arcade_core.scenes import (
+    Scene,
+    SceneRegistry,
+    SceneServices,
+    register_scene,
+)
 from mini_arcade_core.two_d import (
     Bounds2D,
     KinematicData,
@@ -105,6 +111,9 @@ __all__ = [
     "keymap",
     "SceneRegistry",
     "register_scene",
+    "CheatManager",
+    "CheatCode",
+    "SceneServices",
 ]
 
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml

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

mini_arcade_core/managers/__init__.py

@@ -0,0 +1,14 @@
+"""
+Managers module for Mini Arcade Core.
+Provides various manager classes for handling game entities and resources.
+"""
+
+from __future__ import annotations
+
+from mini_arcade_core.managers.entity_manager import EntityManager
+from mini_arcade_core.managers.overlay_manager import OverlayManager
+
+__all__ = [
+    "EntityManager",
+    "OverlayManager",
+]

mini_arcade_core/managers/base.py

@@ -0,0 +1,91 @@
+"""
+Base manager classes for handling collections of items.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Generic, Iterable, List, Protocol, TypeVar
+
+from mini_arcade_core.backend.backend import Backend
+
+# ---- shared types ----
+T = TypeVar("T")
+OverlayFunc = Callable[[Backend], None]
+
+
+class Drawable(Protocol):
+    """Defines a drawable entity."""
+
+    def draw(self, surface: Backend):
+        """
+        Draw the entity on the given surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+
+
+class Updatable(Protocol):
+    """Defines an updatable entity."""
+
+    def update(self, dt: float):
+        """
+        Update the entity state.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+
+
+class EntityLike(Drawable, Updatable, Protocol):
+    """Defines a game entity."""
+
+
+@dataclass
+class ListManager(Generic[T]):
+    """
+    Generic manager for a list of items.
+
+    :ivar items (List[T]): List of managed items.
+    """
+
+    items: List[T] = field(default_factory=list)
+
+    def add(self, *items: T):
+        """
+        Add one or more items to the manager.
+
+        :param items: One or more items to add.
+        :type items: T
+        """
+        self.items.extend(items)
+
+    def add_many(self, items: Iterable[T]):
+        """
+        Add multiple items to the manager.
+
+        :param items: An iterable of items to add.
+        :type items: Iterable[T]
+        """
+        self.items.extend(items)
+
+    def remove(self, item: T):
+        """
+        Remove a single item from the manager, if present.
+
+        :param item: The item to remove.
+        :type item: T
+        """
+        if item in self.items:
+            self.items.remove(item)
+
+    def clear(self):
+        """Clear all items from the manager."""
+        self.items.clear()
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)

mini_arcade_core/managers/entity_manager.py

@@ -0,0 +1,38 @@
+"""
+Entity manager for handling a collection of entities.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.backend import Backend
+
+from .base import EntityLike, ListManager
+
+
+@dataclass
+class EntityManager(ListManager[EntityLike]):
+    """
+    Manages a collection of entities within a scene.
+    """
+
+    def update(self, dt: float):
+        """
+        Update all managed entities.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+        for ent in list(self.items):
+            ent.update(dt)
+
+    def draw(self, surface: "Backend"):
+        """
+        Draw all managed entities.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+        for ent in list(self.items):
+            ent.draw(surface)

mini_arcade_core/managers/overlay_manager.py

@@ -0,0 +1,33 @@
+"""
+Overlay manager for handling a collection of overlays.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.managers.base import ListManager
+
+if TYPE_CHECKING:
+    from mini_arcade_core.game import Game
+
+OverlayFunc = Callable[[Backend], None]
+
+
+@dataclass
+class OverlayManager(ListManager[OverlayFunc]):
+    """
+    Manages a collection of overlays within a scene.
+    """
+
+    def draw(self, surface: "Backend"):
+        """
+        Call all overlays. Scenes should call this at the end of draw().
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+        for overlay in self.items:
+            overlay(surface)

mini_arcade_core/scenes/__init__.py

@@ -7,6 +7,6 @@ from __future__ import annotations
 
 from .autoreg import register_scene
 from .registry import SceneRegistry
-from .scene import Scene
+from .scene import Scene, SceneServices
 
-__all__ = ["Scene", "register_scene", "SceneRegistry"]
+__all__ = ["Scene", "register_scene", "SceneRegistry", "SceneServices"]

mini_arcade_core/scenes/scene.py

@@ -5,22 +5,40 @@ Base class for game scenes (states/screens).
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Callable, List
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, List, Optional
 
 from mini_arcade_core.backend import Backend, Event
 from mini_arcade_core.entity import Entity
+from mini_arcade_core.managers import EntityManager, OverlayManager
 from mini_arcade_core.two_d import Size2D
 
 if TYPE_CHECKING:
     from mini_arcade_core.game import Game
 
-OverlayFunc = Callable[[Backend], None]
+
+@dataclass
+class SceneServices:
+    """
+    Container for scene services like entity and overlay managers.
+
+    :ivar entities: EntityManager for managing scene entities.
+    :ivar overlays: OverlayManager for managing scene overlays.
+    """
+
+    entities: EntityManager = field(default_factory=EntityManager)
+    overlays: OverlayManager = field(default_factory=OverlayManager)
 
 
 class Scene(ABC):
     """Base class for game scenes (states/screens)."""
 
-    def __init__(self, game: Game):
+    def __init__(
+        self,
+        game: Game,
+        *,
+        services: Optional[SceneServices] = None,
+    ):
         """
         :param game: Reference to the main Game object.
         :type game: Game
@@ -28,84 +46,10 @@ class Scene(ABC):
         self.game = game
         self.entities: List[Entity] = []
         self.size: Size2D = Size2D(game.config.width, game.config.height)
-        # overlays drawn on top of the scene
-        self._overlays: List[OverlayFunc] = []
-
-    def add_entity(self, *entities: Entity):
-        """
-        Register one or more entities in this scene.
-
-        :param entities: One or more Entity instances to add.
-        :type entities: Entity
-        """
-        self.entities.extend(entities)
-
-    def remove_entity(self, entity: Entity):
-        """
-        Unregister a single entity, if present.
-
-        :param entity: The Entity instance to remove.
-        :type entity: Entity
-        """
-        if entity in self.entities:
-            self.entities.remove(entity)
-
-    def clear_entities(self):
-        """Remove all entities from the scene."""
-        self.entities.clear()
-
-    def update_entities(self, dt: float):
-        """
-        Default update loop for all entities.
-
-        :param dt: Time delta in seconds.
-        :type dt: float
-        """
-        for ent in self.entities:
-            ent.update(dt)
-
-    def draw_entities(self, surface: Backend):
-        """
-        Default draw loop for all entities.
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-        for ent in self.entities:
-            ent.draw(surface)
 
-    def add_overlay(self, overlay: OverlayFunc):
-        """
-        Register an overlay (drawn every frame, after entities).
-
-        :param overlay: A callable that takes a Backend and draws on it.
-        :type overlay: OverlayFunc
-        """
-        self._overlays.append(overlay)
-
-    def remove_overlay(self, overlay: OverlayFunc):
-        """
-        Unregister a previously added overlay.
-
-        :param overlay: The overlay to remove.
-        :type overlay: OverlayFunc
-        """
-        if overlay in self._overlays:
-            self._overlays.remove(overlay)
-
-    def clear_overlays(self):
-        """Clear all registered overlays."""
-        self._overlays.clear()
-
-    def draw_overlays(self, surface: Backend):
-        """
-        Call all overlays. Scenes should call this at the end of draw().
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-        for overlay in self._overlays:
-            overlay(surface)
+        self.services: SceneServices = (
+            services if services is not None else SceneServices()
+        )
 
     @abstractmethod
     def on_enter(self):

{mini_arcade_core-0.9.7.dist-info → mini_arcade_core-0.9.9.dist-info}/METADATA

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

{mini_arcade_core-0.9.7.dist-info → mini_arcade_core-0.9.9.dist-info}/RECORD

@@ -1,17 +1,22 @@
-mini_arcade_core/__init__.py,sha256=Q6N1eJe5W8r3i_G88-WZ90B71P6eFuH-Zk5xw3p7SBs,3650
+mini_arcade_core/__init__.py,sha256=m9wELq1seQQE13tfU6DT7XinC07yzo5KTS1KEA0MQNs,3804
 mini_arcade_core/backend/__init__.py,sha256=w-6QTUngdIYZuvEU3B8zL-vXyKbyLDVucbt7yKZdLlc,379
 mini_arcade_core/backend/backend.py,sha256=dLXTtLn5qURftWOWOVQd2ouuZmJpbiOl11KMIDRk2us,4026
 mini_arcade_core/backend/events.py,sha256=usn2HTk5-5ZiaU2IjbrNRpEj_4uoaiqfY3qufQLYy0w,2929
 mini_arcade_core/backend/types.py,sha256=SuiwXGNmXCZxfPsww6zj3V_NK7k4jpoCuzMn19afS-g,175
+mini_arcade_core/cheats.py,sha256=J0HPLUC6sARXNl_CtUaWhWoo9A0vEjQcIHP6XJUPrNQ,7133
 mini_arcade_core/entity.py,sha256=vDe2v7GajyGaqckBYeD3cjs--pOTFrDNhMIdf7PZsJQ,1759
 mini_arcade_core/game.py,sha256=C8flMXn_DMHWDmr5FVrTey_nUHabwja8wSaialNMcLg,8526
 mini_arcade_core/keymaps/__init__.py,sha256=_5Y5_61XT5TsOhbb6p2EPzvjCNN9hCPoxTgj_TAfBvA,258
 mini_arcade_core/keymaps/keys.py,sha256=LTg20SwLBI3kpPIiTNpq2yBft_QUGj-iNFSNm9M-Fus,3010
 mini_arcade_core/keymaps/sdl.py,sha256=Tb0amkbmYjYkEkYnMZ6i9QWjwXBkEHIm13-gEMUYENM,2060
-mini_arcade_core/scenes/__init__.py,sha256=0zzGFejPZ4CkWHJSkhjRAWA7GbenyZbTGrKOrA5gON4,291
+mini_arcade_core/managers/__init__.py,sha256=ZpWVxqUq2lbLdrtPR75ipSmykp3fpm9nQrQHP15sGJI,352
+mini_arcade_core/managers/base.py,sha256=D2CCde_zbsrlLNzs3v3qgYpRu9QgmFlzOfdfFIwf5xs,2023
+mini_arcade_core/managers/entity_manager.py,sha256=mBgSFgdZ73f5ZZ-_GtvnqOFWuSySX5QJZrZ77sH4qes,831
+mini_arcade_core/managers/overlay_manager.py,sha256=LTywwhSigjGiCKqULBGjKJPT6xyYgeoKXfhPEoOw8Nk,801
+mini_arcade_core/scenes/__init__.py,sha256=MXaWaDvwf0ycd5GZ_9DhPQ7tWqsp-ECWTOZpGZarcRE,323
 mini_arcade_core/scenes/autoreg.py,sha256=b4V0jaA65I2hnT2f___rg_pT556OjrtoNjIRdZrXBaI,1009
 mini_arcade_core/scenes/registry.py,sha256=0B3iSvepydwMpELQz8cRaQeAU0pR1Fz9O1YtWshLjQw,3226
-mini_arcade_core/scenes/scene.py,sha256=nAYr-T1RW-7s0a8JrxesJY36iAtpZsA2cqeIZgZWIeU,3962
+mini_arcade_core/scenes/scene.py,sha256=MrHAHf-su6xrLXi4y1opxJWy0YF-yLfSN6rOvSHPqCc,2384
 mini_arcade_core/two_d/__init__.py,sha256=iWjm39RYDEshxSmiIWyGWa6Qr9O2gnHfOpzrl63FUro,626
 mini_arcade_core/two_d/boundaries2d.py,sha256=H1HkCR1422MkQIEve2DFKvnav4RpvtLx-qTMxzmdDMQ,2610
 mini_arcade_core/two_d/collision2d.py,sha256=jR5bOmqUaedxRzwFoKBgn7k-ozwklB4RP9pUTVk6aUw,1716
@@ -20,7 +25,7 @@ mini_arcade_core/two_d/kinematics2d.py,sha256=NFMiIzDYqDquyg_EhD7EQBJ_Sz4RncmkEj
 mini_arcade_core/two_d/physics2d.py,sha256=qIq86qWVuvcnLIMEPH6xx7XQO4tQhfiMZY6FseuVOR8,1636
 mini_arcade_core/ui/__init__.py,sha256=RmcZXfBFFmL09j_Bo1LHagRjiKYajuySPilIUNjc3KQ,248
 mini_arcade_core/ui/menu.py,sha256=J3hYY46xOHLN65WSet4-cnQU7L5pu48scjLJUW9IkEM,13681
-mini_arcade_core-0.9.7.dist-info/METADATA,sha256=ghW7JHVtzj3xDdaQHOvhHmo0JjtLM5Rqpk0K-05RqOI,8188
-mini_arcade_core-0.9.7.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-mini_arcade_core-0.9.7.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
-mini_arcade_core-0.9.7.dist-info/RECORD,,
+mini_arcade_core-0.9.9.dist-info/METADATA,sha256=G7IK6yFjXiaGPHQr9_DcedeRXQAmhWlgXCcjyHslr1U,8188
+mini_arcade_core-0.9.9.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mini_arcade_core-0.9.9.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-0.9.9.dist-info/RECORD,,