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

mini_arcade_core/__init__.py

@@ -9,24 +9,21 @@ 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 import backend  # noqa: F401
+from mini_arcade_core import keymaps  # noqa: F401
+from mini_arcade_core import managers  # noqa: F401
+from mini_arcade_core import spaces  # noqa: F401
+from mini_arcade_core import ui  # noqa: F401
+from mini_arcade_core.bus import event_bus
+from mini_arcade_core.commands import (
+    BaseCommand,
+    BaseGameCommand,
+    BaseSceneCommand,
+    QuitGameCommand,
+)
 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.two_d import (
-    Bounds2D,
-    KinematicData,
-    Position2D,
-    RectCollider,
-    RectKinematic,
-    RectSprite,
-    Size2D,
-    Velocity2D,
-    VerticalBounce,
-    VerticalWrap,
-)
+from mini_arcade_core.scenes import Scene, SceneRegistry
 
 SceneFactoryLike = Union[Type[Scene], Callable[[Game], Scene]]
 
@@ -84,30 +81,20 @@ def run_game(
 __all__ = [
     "Game",
     "GameConfig",
-    "Scene",
     "Entity",
     "SpriteEntity",
-    "run_game",
-    "Backend",
-    "Event",
-    "EventType",
-    "Velocity2D",
-    "Position2D",
-    "Size2D",
     "KinematicEntity",
-    "KinematicData",
-    "RectCollider",
-    "VerticalBounce",
-    "Bounds2D",
-    "VerticalWrap",
-    "RectSprite",
-    "RectKinematic",
-    "Key",
-    "keymap",
-    "SceneRegistry",
-    "register_scene",
-    "CheatManager",
-    "CheatCode",
+    "BaseCommand",
+    "BaseGameCommand",
+    "BaseSceneCommand",
+    "QuitGameCommand",
+    "event_bus",
+    "run_game",
+    "backend",
+    "keymaps",
+    "managers",
+    "spaces",
+    "ui",
 ]
 
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml

mini_arcade_core/bus.py

@@ -0,0 +1,57 @@
+"""
+Event bus module.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, ClassVar, Dict, List, Optional
+
+
+class EventBus:
+    """
+    Simple event bus for managing event subscriptions and emissions.
+    """
+
+    _instance: ClassVar[Optional["EventBus"]] = None
+    _subscribers: Dict[str, List[Callable]]
+
+    def __new__(cls):
+        if cls._instance is None:
+            inst = super().__new__(cls)
+            inst._subscribers = {}
+            cls._instance = inst
+        return cls._instance
+
+    def on(self, event_type: str, handler: Callable):
+        """
+        Subscribe a handler to an event type.
+
+        :param event_type: The type of event to subscribe to.
+        :type event_type: str
+
+        :param handler: The handler function to call when the event is emitted.
+        :type handler: Callable
+        """
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+        self._subscribers[event_type].append(handler)
+
+    def emit(self, event_type: str, **kwargs):
+        """
+        Emit an event of a given type, calling all subscribed handlers.
+
+        :param event_type: The type of event to emit.
+        :type event_type: str
+
+        :param kwargs: Additional keyword arguments to pass to handlers.
+        """
+        handlers = self._subscribers.get(event_type, [])
+        for handler in handlers:
+            handler(**kwargs)
+
+    def clear(self):
+        """Clear all subscribers from the event bus."""
+        self._subscribers.clear()
+
+
+event_bus = EventBus()

mini_arcade_core/commands.py

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

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from mini_arcade_core.two_d import (
+from mini_arcade_core.spaces.d2 import (
     KinematicData,
     Position2D,
     RectCollider,
@@ -63,9 +63,10 @@ class KinematicEntity(SpriteEntity):
             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.position.x, self.position.y, dt * self.time_scale
         )

mini_arcade_core/game.py

@@ -14,7 +14,7 @@ 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 import SceneRegistry
+from mini_arcade_core.scenes.registry import SceneRegistry
 
 if TYPE_CHECKING:  # avoid runtime circular import
     from mini_arcade_core.scenes import Scene

mini_arcade_core/managers/__init__.py

@@ -0,0 +1,22 @@
+"""
+Managers module for Mini Arcade Core.
+Provides various manager classes for handling game entities and resources.
+"""
+
+from __future__ import annotations
+
+from .cheats import BaseCheatCommand, CheatCode, CheatManager
+from .entities import EntityManager
+from .inputs import InputManager
+from .overlays import OverlayManager
+from .system import SystemManager
+
+__all__ = [
+    "EntityManager",
+    "OverlayManager",
+    "CheatCode",
+    "CheatManager",
+    "BaseCheatCommand",
+    "InputManager",
+    "SystemManager",
+]

mini_arcade_core/managers/base.py

@@ -0,0 +1,132 @@
+"""
+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 Overlay(Protocol):
+    """
+    Defines an overlay function.
+
+    :ivar enabled (bool): Whether the overlay is enabled.
+    """
+
+    enabled: bool
+
+    def update(self, dt: float):
+        """
+        Update the overlay state.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+
+    def draw(self, surface: "Backend"):
+        """
+        Draw the overlay on the given surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+
+
+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 get(self, item: T) -> T | None:
+        """
+        Get an item from the manager.
+
+        :param item: The item to get.
+        :type item: T
+
+        :return: The item if found, else None.
+        :rtype: T | None
+        """
+        for it in self.items:
+            if it == item:
+                return it
+        return None
+
+    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/{cheats.py → managers/cheats.py}

@@ -5,17 +5,78 @@ Provides cheat codes and related functionality.
 
 from __future__ import annotations
 
+from abc import ABC, abstractmethod
 from collections import deque
 from dataclasses import dataclass
 from enum import Enum
-from typing import Callable, Deque, Dict, Optional, Sequence, TypeVar
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Deque,
+    Dict,
+    Generic,
+    Optional,
+    Protocol,
+    Sequence,
+    TypeVar,
+)
+
+from mini_arcade_core.backend import Event, EventType
+from mini_arcade_core.scenes.system import BaseSceneSystem
+
+if TYPE_CHECKING:
+    from mini_arcade_core.scenes import Scene
 
 # Justification: We want to keep the type variable name simple here.
 # pylint: disable=invalid-name
 TContext = TypeVar("TContext")
+TScene = TypeVar("TScene", bound="Scene")
 # pylint: enable=invalid-name
 
-CheatCallback = Callable[[TContext], None]
+
+@dataclass
+class BaseCheatCommand(ABC, Generic[TContext]):
+    """
+    Base class for cheat codes.
+
+    :ivar enabled (bool): Whether the cheat code is enabled.
+    """
+
+    enabled: bool = True
+
+    def __call__(self, context: TContext) -> None:
+        """
+        Execute the cheat code with the given context.
+
+        :param context: Context object for cheat execution.
+        :type context: TContext
+        """
+        if not self.enabled:
+            return False
+        self.execute(context)
+        return True
+
+    @abstractmethod
+    def execute(self, context: TContext):
+        """
+        Execute the cheat code with the given context.
+
+        :param context: Context object for cheat execution.
+        :type context: TContext
+        """
+        raise NotImplementedError("CheatCommand.execute must be overridden.")
+
+
+class CheatAction(Protocol[TContext]):
+    """
+    Protocol for cheat code actions.
+
+    :ivar enabled: Whether the cheat action is enabled.
+    """
+
+    enabled: bool
+
+    def __call__(self, ctx: TContext) -> bool: ...
 
 
 @dataclass(frozen=True)
@@ -25,14 +86,14 @@ class CheatCode:
 
     :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 action (CheatAction): BaseCheatCommand 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
+    action: CheatAction[TContext]
     clear_buffer_on_match: bool = False
     enabled: bool = True
 
@@ -74,17 +135,17 @@ class CheatManager:
 
     # Justification: We want to keep the number of arguments manageable here.
     # pylint: disable=too-many-arguments
-    def register_code(
+    def register_command(
         self,
         name: str,
         sequence: Sequence[str],
-        callback: CheatCallback,
+        command: BaseCheatCommand[TContext],
         *,
         clear_buffer_on_match: bool = False,
         enabled: bool = True,
     ):
         """
-        Register a new cheat code.
+        Register a new cheat code that triggers a BaseCheatCommand.
 
         :param name: Unique name for the cheat code.
         :type name: str
@@ -92,8 +153,8 @@ class CheatManager:
         :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 command: BaseCheatCommand to execute when the cheat is activated.
+        :type command: BaseCheatCommand[TContext]
 
         :param clear_buffer_on_match: Whether to clear the input buffer after a match.
         :type clear_buffer_on_match: bool
@@ -112,7 +173,7 @@ class CheatManager:
         self._codes[name] = CheatCode(
             name=name,
             sequence=norm_seq,
-            callback=callback,
+            action=command,
             clear_buffer_on_match=clear_buffer_on_match,
             enabled=enabled,
         )
@@ -182,7 +243,7 @@ class CheatManager:
             if len(seq) > len(buf):
                 continue
             if buf[-len(seq) :] == seq:
-                code.callback(context)
+                code.action(context)
                 matched.append(code.name)
                 if code.clear_buffer_on_match:
                     self.clear_buffer()
@@ -233,3 +294,62 @@ class CheatManager:
                 return str(v)
 
         return None
+
+
+class CheatSystem(BaseSceneSystem, Generic[TScene]):
+    """
+    Scene system for handling cheat codes.
+
+    :ivar priority (int): Priority of the system (lower runs first).
+    :ivar enabled (bool): Whether the system is enabled.
+    """
+
+    priority = 10
+
+    def __init__(self, scene: TScene, buffer_size=16):
+        """
+        :param buffer_size: Size of the cheat input buffer.
+        :type buffer_size: int
+        """
+        super().__init__(scene)
+        self.cheats = CheatManager(buffer_size=buffer_size)
+
+    def register(self, name: str, seq: list[str], cmd: Callable, **kwargs):
+        """
+        Helper to register a cheat command.
+
+        :param name: Unique name for the cheat code.
+        :type name: str
+
+        :param seq: Sequence of key strings that trigger the cheat.
+        :type seq: list[str]
+
+        :param cmd: Callable to execute when the cheat is activated.
+        :type cmd: Callable
+
+        :param kwargs: Additional keyword arguments for cheat registration.
+        """
+        self.cheats.register_command(name, seq, cmd, **kwargs)
+
+    def on_enter(self):
+        """
+        Called when the scene is entered.
+        """
+        # register codes here (or via a builder)
+
+    def handle_event(self, event: Event) -> bool:
+        """
+        Handle an event.
+
+        :param event: The event to handle.
+        :type event: Event
+
+        :param scene: The scene receiving the event.
+        :type scene: TScene
+
+        :return: True if the event was handled, False otherwise.
+        :rtype: bool
+        """
+        if event.type == EventType.KEYDOWN:
+            self.cheats.process_event(event, self.scene)
+        return False  # usually don't consume

mini_arcade_core/managers/entities.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)