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

mini_arcade_core/managers/inputs.py

@@ -0,0 +1,282 @@
+"""
+Input manager for handling input bindings and commands.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable, Dict, Optional
+
+from mini_arcade_core.backend import Event, EventType
+from mini_arcade_core.commands import BaseCommand, BaseSceneCommand
+from mini_arcade_core.keymaps import Key
+
+if TYPE_CHECKING:
+    from mini_arcade_core.scenes.scene import Scene
+
+logger = logging.getLogger(__name__)
+
+
+Predicate = Callable[["Event"], bool]
+
+
+@dataclass(frozen=True)
+class InputBinding:
+    """
+    Defines an input binding.
+
+    :ivar action (str): The action name.
+    :ivar command (BaseCommand): The command to execute.
+    :ivar predicate (Predicate): Predicate to match events.
+    """
+
+    action: str
+    command: BaseCommand
+    predicate: Predicate  # decides whether this binding matches an event
+
+
+class InputManager:
+    """
+    Manager for handling input bindings and commands.
+    """
+
+    def __init__(self):
+        # event_type -> key -> action -> command
+        self._bindings: Dict[EventType, Dict[Key, Dict[str, BaseCommand]]] = {}
+
+    # Justification: The method needs multiple optional parameters for flexibility.
+    # pylint: disable=too-many-arguments
+    def bind(
+        self,
+        event_type: EventType,
+        action: str,
+        command: BaseCommand,
+        *,
+        key: Optional[Key] = None,
+        button: Optional[int] = None,
+        predicate: Optional[Predicate] = None,
+    ):
+        """
+        Generic binding.
+
+        You can filter by:
+        - key: for KEYDOWN/KEYUP
+        - button: for MOUSEBUTTONDOWN/MOUSEBUTTONUP (if your Event exposes it)
+        - predicate: custom matcher (for anything)
+
+        :param event_type: The type of event to bind to.
+        :type event_type: EventType
+
+        :param action: The action name for the binding.
+        :type action: str
+
+        :param command: The command to execute when the binding is triggered.
+        :type command: BaseCommand
+
+        :param key: Optional key to filter KEYDOWN/KEYUP events.
+        :type key: Key | None
+
+        :param button: Optional button to filter MOUSEBUTTONDOWN/MOUSEBUTTONUP events.
+        :type button: int | None
+
+        :param predicate: Optional custom predicate to match events.
+        :type predicate: Predicate | None
+        """
+        logger.debug(
+            f"Binding {action} to {event_type} with key={key}, button={button}"
+        )
+
+        def default_predicate(ev: Event) -> bool:
+            if key is not None and getattr(ev, "key", None) != key:
+                return False
+            if button is not None and getattr(ev, "button", None) != button:
+                return False
+            return True
+
+        pred = predicate or default_predicate
+        self._bindings.setdefault(event_type, []).append(
+            InputBinding(action=action, command=command, predicate=pred)
+        )
+
+    # pylint: enable=too-many-arguments
+
+    def unbind(self, event_type: EventType, action: str):
+        """
+        Remove bindings by action for an event type.
+
+        :param event_type: The type of event to unbind from.
+        :type event_type: EventType
+
+        :param action: The action name of the binding to remove.
+        :type action: str
+        """
+        lst = self._bindings.get(event_type, [])
+        self._bindings[event_type] = [b for b in lst if b.action != action]
+
+    def clear(self):
+        """Clear all input bindings."""
+        self._bindings.clear()
+
+    def handle_event(self, event: Event, scene: Scene):
+        """
+        Handle an incoming event, executing any matching commands.
+
+        :param event: The event to handle.
+        :type event: Event
+
+        :param scene: The current scene context.
+        :type scene: Scene
+        """
+        et = event.type
+
+        for binding in self._bindings.get(et, []):
+            if binding.predicate(event):
+                to_inject = (
+                    scene.model
+                    if isinstance(binding.command, BaseSceneCommand)
+                    else scene.game
+                )
+                binding.command.execute(to_inject)
+
+    # --- Convenience API ------------------------------------------------------
+
+    def on_quit(self, command: BaseCommand, action: str = "quit"):
+        """
+        Bind a command to the QUIT event.
+
+        :param command: The command to execute on quit.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.QUIT, action=action, command=command)
+
+    def on_key_down(self, key: Key, command: BaseCommand, action: str):
+        """
+        Bind a command to a key down event.
+
+        :param key: The key to bind to.
+        :type key: Key
+
+        :param command: The command to execute on key down.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.KEYDOWN, key=key, action=action, command=command)
+
+    def on_key_up(self, key: Key, command: BaseCommand, action: str):
+        """
+        Bind a command to a key up event.
+
+        :param key: The key to bind to.
+        :type key: Key
+
+        :param command: The command to execute on key up.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.KEYUP, key=key, action=action, command=command)
+
+    def on_mouse_button_down(
+        self, button: int, command: BaseCommand, action: str
+    ):
+        """
+        Bind a command to a mouse button down event.
+
+        :param button: The mouse button to bind to.
+        :type button: int
+
+        :param command: The command to execute on mouse button down.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(
+            EventType.MOUSEBUTTONDOWN,
+            button=button,
+            action=action,
+            command=command,
+        )
+
+    def on_mouse_button_up(
+        self, button: int, command: BaseCommand, action: str
+    ):
+        """
+        Bind a command to a mouse button up event.
+
+        :param button: The mouse button to bind to.
+        :type button: int
+
+        :param command: The command to execute on mouse button up.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(
+            EventType.MOUSEBUTTONUP,
+            button=button,
+            action=action,
+            command=command,
+        )
+
+    def on_mouse_motion(
+        self, command: BaseCommand, action: str = "mouse_motion"
+    ):
+        """
+        Bind a command to mouse motion events.
+
+        :param command: The command to execute on mouse motion.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.MOUSEMOTION, action=action, command=command)
+
+    def on_mouse_wheel(
+        self, command: BaseCommand, action: str = "mouse_wheel"
+    ):
+        """
+        Bind a command to mouse wheel events.
+
+        :param command: The command to execute on mouse wheel.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.MOUSEWHEEL, action=action, command=command)
+
+    def on_window_resized(
+        self, command: BaseCommand, action: str = "window_resized"
+    ):
+        """
+        Bind a command to window resized events.
+
+        :param command: The command to execute on window resize.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.WINDOWRESIZED, action=action, command=command)
+
+    def on_text_input(self, command: BaseCommand, action: str = "text_input"):
+        """
+        Bind a command to text input events.
+
+        :param command: The command to execute on text input.
+        :type command: BaseCommand
+
+        :param action: The action name for the binding.
+        :type action: str
+        """
+        self.bind(EventType.TEXTINPUT, action=action, command=command)

mini_arcade_core/managers/overlays.py

@@ -0,0 +1,53 @@
+"""
+Overlay manager for handling a collection of overlays.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.managers.base import ListManager, Overlay, OverlayFunc
+
+OverlayType = Union[Overlay, OverlayFunc]
+
+
+@dataclass
+class OverlayManager(ListManager[OverlayType]):
+    """
+    Manages a collection of overlays within a scene.
+    """
+
+    def update(self, dt: float):
+        """
+        Update all managed overlays.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+        for ov in list(self.items):
+            # class overlays only
+            if hasattr(ov, "update") and hasattr(ov, "draw"):
+                if getattr(ov, "enabled", True):
+                    ov.update(dt)
+
+    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
+        """
+
+        def prio(o: OverlayType) -> int:
+            """Priority for sorting overlays."""
+            return getattr(o, "priority", 0)
+
+        for ov in sorted(list(self.items), key=prio):
+            if hasattr(ov, "draw"):
+                if getattr(ov, "enabled", True):
+                    ov.draw(surface)
+            else:
+                # function overlay
+                ov(surface)

mini_arcade_core/managers/system.py

@@ -0,0 +1,26 @@
+"""
+Manager for scene systems.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mini_arcade_core.managers.base import ListManager
+from mini_arcade_core.scenes.system import BaseSceneSystem
+
+
+@dataclass
+class SystemManager(ListManager[BaseSceneSystem]):
+    """
+    Manager for scene systems.
+    """
+
+    def sorted(self) -> list[BaseSceneSystem]:
+        """
+        Get systems sorted by priority.
+
+        :return: List of systems sorted by priority.
+        :rtype: list[BaseSceneSystem]
+        """
+        return sorted(self.items, key=lambda s: getattr(s, "priority", 0))

mini_arcade_core/scenes/__init__.py

@@ -6,7 +6,17 @@ Provides the base Scene class and related functionality.
 from __future__ import annotations
 
 from .autoreg import register_scene
+from .model import SceneModel
 from .registry import SceneRegistry
-from .scene import Scene, SceneServices
+from .runtime import SceneRuntime
+from .scene import Scene
+from .system import BaseSceneSystem
 
-__all__ = ["Scene", "register_scene", "SceneRegistry", "SceneServices"]
+__all__ = [
+    "Scene",
+    "register_scene",
+    "SceneRegistry",
+    "SceneRuntime",
+    "SceneModel",
+    "BaseSceneSystem",
+]

mini_arcade_core/scenes/model.py

@@ -0,0 +1,34 @@
+"""
+Scene base model module.
+Provides the Scene class and related services.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Any
+
+
+@dataclass
+class SceneModel:
+    """
+    Basic data model for a scene.
+    """
+
+    @staticmethod
+    def _serialize_dataclass(obj) -> dict[str, Any]:
+        out = {}
+        for f in fields(obj):
+            if f.metadata.get("serialize", True) is False:
+                continue
+            out[f.name] = getattr(obj, f.name)
+        return out
+
+    def to_dict(self) -> dict:
+        """
+        Convert the SceneModel to a dictionary.
+
+        :return: Dictionary representation of the SceneModel.
+        :rtype: dict
+        """
+        return self._serialize_dataclass(self)

mini_arcade_core/scenes/runtime.py

@@ -0,0 +1,29 @@
+"""
+Container for scene services like entity and overlay managers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mini_arcade_core.managers.entities import EntityManager
+from mini_arcade_core.managers.inputs import InputManager
+from mini_arcade_core.managers.overlays import OverlayManager
+from mini_arcade_core.managers.system import SystemManager
+
+
+@dataclass
+class SceneRuntime:
+    """
+    Container for scene services like entity and overlay managers.
+
+    :ivar input (InputManager): InputManager for handling input bindings and commands.
+    :ivar entities (EntityManager): EntityManager for managing scene entities.
+    :ivar overlays (OverlayManager): OverlayManager for managing scene overlays.
+    :ivar systems (SystemManager): SystemManager for managing scene systems.
+    """
+
+    input: InputManager = field(default_factory=InputManager)
+    entities: EntityManager = field(default_factory=EntityManager)
+    overlays: OverlayManager = field(default_factory=OverlayManager)
+    systems: SystemManager = field(default_factory=SystemManager)

mini_arcade_core/scenes/scene.py

@@ -5,39 +5,29 @@ Base class for game scenes (states/screens).
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-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
+from mini_arcade_core.scenes.model import SceneModel
+from mini_arcade_core.spaces.d2 import Size2D
+
+from .runtime import SceneRuntime
 
 if TYPE_CHECKING:
     from mini_arcade_core.game import Game
 
 
-@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)."""
 
+    model: SceneModel
+
     def __init__(
         self,
         game: Game,
         *,
-        services: Optional[SceneServices] = None,
+        services: Optional[SceneRuntime] = None,
     ):
         """
         :param game: Reference to the main Game object.
@@ -47,8 +37,8 @@ class Scene(ABC):
         self.entities: List[Entity] = []
         self.size: Size2D = Size2D(game.config.width, game.config.height)
 
-        self.services: SceneServices = (
-            services if services is not None else SceneServices()
+        self.services: SceneRuntime = (
+            services if services is not None else SceneRuntime()
         )
 
     @abstractmethod
@@ -86,6 +76,32 @@ class Scene(ABC):
         :type surface: Backend
         """
 
+    def _systems_on_enter(self):
+        for sys in self.services.systems.sorted():
+            if getattr(sys, "enabled", True):
+                sys.on_enter()
+
+    def _systems_on_exit(self):
+        for sys in self.services.systems.sorted():
+            if getattr(sys, "enabled", True):
+                sys.on_exit()
+
+    def _systems_handle_event(self, event: Event) -> bool:
+        for sys in self.services.systems.sorted():
+            if getattr(sys, "enabled", True) and sys.handle_event(event):
+                return True
+        return False
+
+    def _systems_update(self, dt: float):
+        for sys in self.services.systems.sorted():
+            if getattr(sys, "enabled", True):
+                sys.update(dt)
+
+    def _systems_draw(self, surface: Backend):
+        for sys in self.services.systems.sorted():
+            if getattr(sys, "enabled", True):
+                sys.draw(surface)
+
     def on_pause(self):
         """Called when the game is paused."""
 

mini_arcade_core/scenes/system.py

@@ -0,0 +1,69 @@
+"""
+Protocol for scene systems.
+A scene system is a modular component that can hook into the scene lifecycle
+methods (on_enter, on_exit, handle_event, update, draw) to provide additional
+functionality.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from mini_arcade_core.backend import Backend, Event
+
+if TYPE_CHECKING:
+    from mini_arcade_core.scenes.scene import Scene
+
+
+@dataclass
+class BaseSceneSystem:
+    """
+    Protocol for scene systems.
+
+    :ivar enabled (bool): Whether the system is enabled.
+    :ivar priority (int): Priority of the system (lower runs first).
+    """
+
+    enabled: bool = True
+    priority: int = 0  # lower runs first
+
+    def __init__(self, scene: "Scene"):
+        self.scene = scene
+
+    def on_enter(self):
+        """
+        Called when the scene is entered.
+        """
+
+    def on_exit(self):
+        """
+        Called when the scene is exited.
+        """
+
+    def handle_event(self, event: "Event") -> bool:
+        """
+        Handle an event.
+
+        :param event: The event to handle.
+        :type event: Event
+
+        :return: True if the event was handled, False otherwise.
+        :rtype: bool
+        """
+
+    def update(self, dt: float):
+        """
+        Update the system.
+
+        :param dt: Delta time since last update.
+        :type dt: float
+        """
+
+    def draw(self, surface: "Backend"):
+        """
+        Draw the system.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """

mini_arcade_core/spaces/__init__.py

@@ -0,0 +1,12 @@
+"""
+Mini Arcade Core Spaces Module
+This module contains different space definitions for the Mini Arcade Core framework.
+"""
+
+from __future__ import annotations
+
+from . import d2
+
+__all__ = [
+    "d2",
+]

mini_arcade_core/{two_d → spaces/d2}/kinematics2d.py

@@ -27,6 +27,7 @@ class KinematicData:
     position: Position2D
     size: Size2D
     velocity: Velocity2D
+    time_scale: float = 1.0
     color: Optional[Color] = None  # future use
 
     # Justification: Convenience factory with many params.
@@ -40,6 +41,7 @@ class KinematicData:
         height: int,
         vx: float = 0.0,
         vy: float = 0.0,
+        time_scale: float = 1.0,
         color: Optional[Color] = None,
     ) -> "KinematicData":
         """
@@ -73,6 +75,7 @@ class KinematicData:
             position=Position2D(float(x), float(y)),
             size=Size2D(int(width), int(height)),
             velocity=Velocity2D(float(vx), float(vy)),
+            time_scale=time_scale,
             color=color,
         )
 

mini_arcade_core/ui/__init__.py

@@ -5,10 +5,22 @@ Includes buttons, labels, and layout management.
 
 from __future__ import annotations
 
-from .menu import Menu, MenuItem, MenuStyle
+from .menu import (
+    BaseMenuScene,
+    Menu,
+    MenuItem,
+    MenuModel,
+    MenuStyle,
+    MenuSystem,
+)
+from .overlays import BaseOverlay
 
 __all__ = [
     "Menu",
     "MenuItem",
     "MenuStyle",
+    "MenuModel",
+    "MenuSystem",
+    "BaseMenuScene",
+    "BaseOverlay",
 ]