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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-arcade-core
-Version: 0.9.8
+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.8 → mini_arcade_core-0.9.9}/pyproject.toml

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

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

@@ -14,7 +14,12 @@ 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,
@@ -108,6 +113,7 @@ __all__ = [
     "register_scene",
     "CheatManager",
     "CheatCode",
+    "SceneServices",
 ]
 
 PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml

mini_arcade_core-0.9.9/src/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-0.9.9/src/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-0.9.9/src/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-0.9.9/src/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-0.9.8 → mini_arcade_core-0.9.9}/src/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-0.9.9/src/mini_arcade_core/scenes/scene.py

@@ -0,0 +1,93 @@
+"""
+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
+
+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)."""
+
+    def __init__(
+        self,
+        game: Game,
+        *,
+        services: Optional[SceneServices] = None,
+    ):
+        """
+        :param game: Reference to the main Game object.
+        :type game: Game
+        """
+        self.game = game
+        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()
+        )
+
+    @abstractmethod
+    def on_enter(self):
+        """Called when the scene becomes active."""
+
+    @abstractmethod
+    def on_exit(self):
+        """Called when the scene is replaced."""
+
+    @abstractmethod
+    def handle_event(self, event: Event):
+        """
+        Handle input / events (e.g. pygame.Event).
+
+        :param event: The event to handle.
+        :type event: Event
+        """
+
+    @abstractmethod
+    def update(self, dt: float):
+        """
+        Update game logic. ``dt`` is the delta time in seconds.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+
+    @abstractmethod
+    def draw(self, surface: Backend):
+        """
+        Render to the main surface.
+
+        :param surface: The backend surface to draw on.
+        :type surface: Backend
+        """
+
+    def on_pause(self):
+        """Called when the game is paused."""
+
+    def on_resume(self):
+        """Called when the game is resumed."""

mini_arcade_core-0.9.8/src/mini_arcade_core/scenes/scene.py

@@ -1,149 +0,0 @@
-"""
-Base class for game scenes (states/screens).
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Callable, List
-
-from mini_arcade_core.backend import Backend, Event
-from mini_arcade_core.entity import Entity
-from mini_arcade_core.two_d import Size2D
-
-if TYPE_CHECKING:
-    from mini_arcade_core.game import Game
-
-OverlayFunc = Callable[[Backend], None]
-
-
-class Scene(ABC):
-    """Base class for game scenes (states/screens)."""
-
-    def __init__(self, game: Game):
-        """
-        :param game: Reference to the main Game object.
-        :type game: Game
-        """
-        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)
-
-    @abstractmethod
-    def on_enter(self):
-        """Called when the scene becomes active."""
-
-    @abstractmethod
-    def on_exit(self):
-        """Called when the scene is replaced."""
-
-    @abstractmethod
-    def handle_event(self, event: Event):
-        """
-        Handle input / events (e.g. pygame.Event).
-
-        :param event: The event to handle.
-        :type event: Event
-        """
-
-    @abstractmethod
-    def update(self, dt: float):
-        """
-        Update game logic. ``dt`` is the delta time in seconds.
-
-        :param dt: Time delta in seconds.
-        :type dt: float
-        """
-
-    @abstractmethod
-    def draw(self, surface: Backend):
-        """
-        Render to the main surface.
-
-        :param surface: The backend surface to draw on.
-        :type surface: Backend
-        """
-
-    def on_pause(self):
-        """Called when the game is paused."""
-
-    def on_resume(self):
-        """Called when the game is resumed."""