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

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

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

{mini_arcade_core-0.9.9 → mini_arcade_core-1.0.0}/pyproject.toml

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

mini_arcade_core-1.0.0/src/mini_arcade_core/__init__.py

@@ -0,0 +1,109 @@
+"""
+Entry point for the mini_arcade_core package.
+Provides access to core classes and a convenience function to run a game.
+"""
+
+from __future__ import annotations
+
+import traceback
+from importlib.metadata import PackageNotFoundError, version
+from typing import Callable, Type, Union
+
+from mini_arcade_core.engine.game import Game, GameConfig, WindowConfig
+from mini_arcade_core.scenes.registry import SceneRegistry
+from mini_arcade_core.scenes.sim_scene import SimScene
+from mini_arcade_core.utils import logger
+
+SceneFactoryLike = Union[Type[SimScene], Callable[[Game], SimScene]]
+
+
+# TODO: Improve exception handling and logging in run_game
+def run_game(
+    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.
+
+    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 SimScene ID to start the game with.
+    :type initial_scene: str
+
+    :param config: Optional GameConfig to customize game settings.
+    :type config: GameConfig | None
+
+    :param registry: Optional SceneRegistry for scene management.
+    :type registry: SceneRegistry | None
+
+    :raises ValueError: If the provided config does not have a valid Backend.
+    """
+    try:
+        # 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 cfg.backend is None:
+            raise ValueError(
+                "GameConfig.backend must be set to a Backend instance"
+            )
+
+        # If user provided a SimScene factory/class, ensure it's registered
+        if scene is not None:
+            if registry is None:
+                registry = SceneRegistry(_factories={})
+            registry.register(
+                initial_scene, scene
+            )  # SimScene class is callable(game) -> SimScene
+
+        game = Game(cfg, registry=registry)
+        game.run(initial_scene)
+    # Justification: We need to catch all exceptions while we improve error handling.
+    # pylint: disable=broad-exception-caught
+    except Exception as e:
+        logger.exception(f"Unhandled exception in game loop: {e}")
+        logger.debug(traceback.format_exc())
+    # pylint: enable=broad-exception-caught
+
+
+PACKAGE_NAME = "mini-arcade-core"  # or whatever is in your pyproject.toml
+
+
+def get_version() -> str:
+    """
+    Return the installed package version.
+
+    This is a thin helper around importlib.metadata.version so games can do:
+
+        from mini_arcade_core import get_version
+        print(get_version())
+
+    :return: The version string of the installed package.
+    :rtype: str
+
+    :raises PackageNotFoundError: If the package is not installed.
+    """
+    try:
+        return version(PACKAGE_NAME)
+    except PackageNotFoundError:  # if running from source / editable
+        logger.warning(
+            f"Package '{PACKAGE_NAME}' not found. Returning default version '0.0.0'."
+        )
+        return "0.0.0"
+
+
+__all__ = [
+    "Game",
+    "GameConfig",
+    "WindowConfig",
+    "run_game",
+]
+
+__version__ = get_version()

{mini_arcade_core-0.9.9 → mini_arcade_core-1.0.0}/src/mini_arcade_core/backend/__init__.py

@@ -7,12 +7,7 @@ This is the only part of the code that talks to SDL/pygame directly.
 from __future__ import annotations
 
 from .backend import Backend
-from .events import Event, EventType
-from .types import Color
 
 __all__ = [
     "Backend",
-    "Event",
-    "EventType",
-    "Color",
 ]

{mini_arcade_core-0.9.9 → mini_arcade_core-1.0.0}/src/mini_arcade_core/backend/backend.py

@@ -33,6 +33,15 @@ class Backend(Protocol):
         :type title: str
         """
 
+    def set_window_title(self, title: str):
+        """
+        Set the window title.
+
+        :param title: The new title for the window.
+        :type title: str
+        """
+        raise NotImplementedError
+
     def poll_events(self) -> Iterable[Event]:
         """
         Return all pending events since last call.

{mini_arcade_core-0.9.9 → mini_arcade_core-1.0.0}/src/mini_arcade_core/backend/events.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from enum import Enum, auto
 from typing import Optional, Tuple
 
-from mini_arcade_core.keymaps.keys import Key
+from mini_arcade_core.backend.keys import Key
 
 
 class EventType(Enum):

mini_arcade_core-0.9.9/src/mini_arcade_core/keymaps/sdl.py → mini_arcade_core-1.0.0/src/mini_arcade_core/backend/sdl_map.py

@@ -8,7 +8,7 @@ Maps SDL keycodes to mini arcade core Key enums.
 
 from __future__ import annotations
 
-from mini_arcade_core.keymaps.keys import Key
+from mini_arcade_core.backend.keys import Key
 
 # SDL keycodes you need (minimal set)
 _SDLK_ESCAPE = 27

mini_arcade_core-1.0.0/src/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-1.0.0/src/mini_arcade_core/engine/commands.py

@@ -0,0 +1,169 @@
+"""
+Command protocol for executing commands with a given context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, List, Optional, Protocol, TypeVar
+
+if TYPE_CHECKING:
+    from mini_arcade_core.runtime.services import RuntimeServices
+
+# Justification: Generic type for context
+# pylint: disable=invalid-name
+TContext = TypeVar("TContext")
+# pylint: enable=invalid-name
+
+
+@dataclass
+class CommandContext:
+    """
+    Context for command execution.
+
+    :ivar services (RuntimeServices): The runtime services.
+    :ivar commands (CommandQueue | None): Optional command queue.
+    :ivar settings (object | None): Optional settings object.
+    :ivar world (object | None): The world object (can be any type).
+    """
+
+    services: RuntimeServices
+    commands: Optional["CommandQueue"] = None
+    settings: Optional[object] = None
+    world: Optional[object] = None
+
+
+class Command(Protocol):
+    """
+    A command is the only allowed "write path" from input/systems into:
+    - scene operations (push/pop/change/quit)
+    - capture
+    - global game lifecycle
+    - later: world mutations (if you pass a world reference)
+
+    For now we keep it simple: commands only need RuntimeServices.
+    """
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        """
+        Execute the command with the given world and runtime services.
+
+        :param services: Runtime services for command execution.
+        :type services: RuntimeServices
+
+        :param commands: Optional command queue for command execution.
+        :type commands: object | None
+
+        :param settings: Optional settings object for command execution.
+        :type settings: object | None
+
+        :param world: The world object (can be any type).
+        :type world: object | None
+        """
+
+
+@dataclass
+class CommandQueue:
+    """
+    Queue for storing and executing commands.
+    """
+
+    _items: List[Command] = field(default_factory=list)
+
+    def push(self, cmd: Command):
+        """
+        Push a command onto the queue.
+
+        :param cmd: Command to be added to the queue.
+        :type cmd: Command
+        """
+        self._items.append(cmd)
+
+    def drain(self) -> List[Command]:
+        """
+        Drain and return all commands from the queue.
+
+        :return: List of commands that were in the queue.
+        :rtype: list[Command]
+        """
+        items = self._items
+        self._items = []
+        return items
+
+
+@dataclass(frozen=True)
+class QuitCommand(Command):
+    """Quit the game."""
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.quit()
+
+
+@dataclass(frozen=True)
+class ScreenshotCommand(Command):
+    """
+    Take a screenshot.
+
+    :ivar label (str | None): Optional label for the screenshot file.
+    """
+
+    label: str | None = None
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.capture.screenshot(label=self.label, mode="manual")
+
+
+@dataclass(frozen=True)
+class PushSceneCommand(Command):
+    """
+    Push a new scene onto the scene stack.
+
+    :ivar scene_id (str): Identifier of the scene to push.
+    :ivar as_overlay (bool): Whether to push the scene as an overlay.
+    """
+
+    scene_id: str
+    as_overlay: bool = False
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.push(self.scene_id, as_overlay=self.as_overlay)
+
+
+@dataclass(frozen=True)
+class PopSceneCommand(Command):
+    """Pop the current scene from the scene stack."""
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.pop()
+
+
+@dataclass(frozen=True)
+class ChangeSceneCommand(Command):
+    """
+    Change the current scene to the specified scene.
+
+    :ivar scene_id (str): Identifier of the scene to switch to.
+    """
+
+    scene_id: str
+
+    def execute(
+        self,
+        context: CommandContext,
+    ):
+        context.services.scenes.change(self.scene_id)