mini-arcade-core 0.2.3__py3-none-any.whl

mini_arcade_core/__init__.py

@@ -0,0 +1,32 @@
+"""
+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
+
+from .entity import Entity, SpriteEntity
+from .game import Game, GameConfig
+from .scene import Scene
+
+
+def run_game(initial_scene_cls: type[Scene], config: GameConfig | None = None):
+    """
+    Convenience helper to bootstrap and run a game with a single scene.
+
+    :param initial_scene_cls: The Scene subclass to instantiate as the initial scene.
+    :param config: Optional GameConfig to customize game settings.
+    """
+    game = Game(config or GameConfig())
+    scene = initial_scene_cls(game)
+    game.run(scene)
+
+
+__all__ = [
+    "Game",
+    "GameConfig",
+    "Scene",
+    "Entity",
+    "SpriteEntity",
+    "run_game",
+]

mini_arcade_core/entity.py

@@ -0,0 +1,51 @@
+"""
+Entity base classes for mini_arcade_core.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Entity:
+    """Entity base class for game objects."""
+
+    def update(self, dt: float):
+        """
+        Advance the entity state by ``dt`` seconds.
+
+        :param dt: Time delta in seconds.
+        :type dt: float
+        """
+
+    def draw(self, surface: Any):
+        """
+        Render the entity to the given surface.
+
+        :param surface: The surface to draw on.
+        :type surface: Any
+        """
+
+
+class SpriteEntity(Entity):
+    """Entity with position and size."""
+
+    def __init__(self, x: float, y: float, width: int, height: int):
+        """
+        :param x: X position.
+        :type x: float
+
+        :param y: Y position.
+        :type y: float
+
+        :param width: Width of the entity.
+        :type width: int
+
+        :param height: Height of the entity.
+        :type height: int
+        """
+        self.x = x
+        self.y = y
+        self.width = width
+        self.height = height
+        # TODO: velocity, color, etc.

mini_arcade_core/game.py

@@ -0,0 +1,66 @@
+"""
+Game core module defining the Game class and configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # avoid runtime circular import
+    from .scene import Scene
+
+
+@dataclass
+class GameConfig:
+    """
+    Configuration options for the Game.
+
+    :ivar width: Width of the game window in pixels.
+    :ivar height: Height of the game window in pixels.
+    :ivar title: Title of the game window.
+    :ivar fps: Target frames per second.
+    :ivar background_color: RGB background color.
+    """
+
+    width: int = 800
+    height: int = 600
+    title: str = "Mini Arcade Game"
+    fps: int = 60
+    background_color: tuple[int, int, int] = (0, 0, 0)
+
+
+class Game:
+    """Core game object responsible for managing the main loop and active scene."""
+
+    def __init__(self, config: GameConfig):
+        """
+        :param config: Game configuration options.
+        """
+        self.config = config
+        self._current_scene: Scene | None = None
+        self._running: bool = False
+
+    def change_scene(self, scene: Scene):
+        """
+        Swap the active scene. Concrete implementations should call
+        ``on_exit``/``on_enter`` appropriately.
+
+        :param scene: The new scene to activate.
+        """
+        raise NotImplementedError(
+            "Game.change_scene must be implemented by a concrete backend."
+        )
+
+    def run(self, initial_scene: Scene):
+        """
+        Run the main loop starting with the given scene.
+
+        This is intentionally left abstract so you can plug pygame, pyglet,
+        or another backend.
+
+        :param initial_scene: The scene to start the game with.
+        """
+        raise NotImplementedError(
+            "Game.run must be implemented by a concrete backend."
+        )

mini_arcade_core/scene.py

@@ -0,0 +1,40 @@
+"""
+Base class for game scenes (states/screens).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .game import Game
+
+
+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
+
+    @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: object):
+        """Handle input / events (e.g. pygame.Event)."""
+
+    @abstractmethod
+    def update(self, dt: float):
+        """Update game logic. ``dt`` is the delta time in seconds."""
+
+    @abstractmethod
+    def draw(self, surface: object):
+        """Render to the main surface."""

mini_arcade_core-0.2.3.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: mini-arcade-core
+Version: 0.2.3
+Summary: Tiny scene-based game loop core for small arcade games.
+License: Copyright (c) 2025 Santiago Rincón
+           
+           Permission is hereby granted, free of charge, to any person obtaining a copy
+           of this software and associated documentation files (the "Software"), to deal
+           in the Software without restriction, including without limitation the rights
+           to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+           copies of the Software, and to permit persons to whom the Software is
+           furnished to do so, subject to the following conditions:
+           
+           The above copyright notice and this permission notice shall be included in all
+           copies or substantial portions of the Software.
+           
+           THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+           IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+           FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+           AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+           LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+           OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+           SOFTWARE.
+License-File: LICENSE
+Author: Santiago Rincon
+Author-email: rincores@gmail.com
+Requires-Python: >=3.9,<3.12
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Provides-Extra: dev
+Requires-Dist: black (>=24.10,<25.0) ; extra == "dev"
+Requires-Dist: isort (>=5.13,<6.0) ; extra == "dev"
+Requires-Dist: mypy (>=1.5,<2.0) ; extra == "dev"
+Requires-Dist: pylint (>=3.3,<4.0) ; extra == "dev"
+Requires-Dist: pytest (>=8.3,<9.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=6.0,<7.0) ; extra == "dev"
+Description-Content-Type: text/markdown
+
+# mini-arcade-core 🎮
+
+Tiny Python game core for building simple scene-based arcade games  
+(Pong, Breakout, Space Invaders, etc.).
+
+> Minimal, opinionated abstractions: **Game**, **Scene**, and **Entity** – nothing else.
+
+---
+
+## Features
+
+- 🎯 **Tiny API surface**
+  - `GameConfig` – basic window & FPS configuration
+  - `Game` – abstract game core to plug your own backend (e.g. pygame)
+  - `Scene` – base class for screens/states (menus, gameplay, pause)
+  - `Entity` / `SpriteEntity` – simple game object primitives
+  - `run_game()` – convenience helper once a concrete `Game` backend is wired
+
+- 🧩 **Backend-agnostic**
+  - The core doesn’t depend on any specific rendering/input library.
+  - You can build backends using `pygame`, `pyglet`, or something custom.
+
+- 🕹️ **Perfect for small arcade projects**
+  - Pong, Breakout, Snake, Asteroids-likes, runners, flappy-likes, etc.
+  - Great for learning, experiments, and portfolio-friendly mini games.
+
+---
+
+## Installation
+
+> **Note:** Adjust this once it’s on PyPI.
+
+```bash
+# From a local checkout
+pip install -e .
+```
+
+Or, once published:
+
+```bash
+pip install mini-arcade-core
+```
+
+Requires Python 3.9–3.11.
+
+---
+
+## Core Concepts
+
+### ``GameConfig``
+
+Basic configuration for your game:
+
+```python
+from mini_arcade_core import GameConfig
+
+config = GameConfig(
+    width=800,
+    height=600,
+    title="My Mini Arcade Game",
+    fps=60,
+    background_color=(0, 0, 0),  # RGB
+)
+```
+
+### ``Game``
+
+Abstract base class that owns:
+
+- the main loop
+- the active ``Scene``
+- high-level control like ``run()`` and ``change_scene()``
+
+You subclass ``Game`` to plug in your rendering/input backend.
+
+### ``Scene``
+
+Represents one state of your game (menu, gameplay, pause, etc.):
+
+```python
+from mini_arcade_core import Scene, Game
+
+class MyScene(Scene):
+    def on_enter(self) -> None:
+        print("Scene entered")
+
+    def on_exit(self) -> None:
+        print("Scene exited")
+
+    def handle_event(self, event: object) -> None:
+        # Handle input / events from your backend
+        pass
+
+    def update(self, dt: float) -> None:
+        # Game logic
+        pass
+
+    def draw(self, surface: object) -> None:
+        # Rendering via your backend
+        pass
+```
+
+### ``Entity`` & ``SpriteEntity``
+
+Lightweight game object primitives:
+
+```python
+from mini_arcade_core import Entity, SpriteEntity
+
+class Ball(Entity):
+    def __init__(self) -> None:
+        self.x = 100.0
+        self.y = 100.0
+        self.vx = 200.0
+        self.vy = 150.0
+
+    def update(self, dt: float) -> None:
+        self.x += self.vx * dt
+        self.y += self.vy * dt
+
+    def draw(self, surface: object) -> None:
+        # Use your backend to draw the ball on `surface`
+        pass
+
+paddle = SpriteEntity(x=50.0, y=300.0, width=80, height=16)
+```
+
+---
+
+### Example: Minimal pygame Backend
+
+``mini-arcade-core`` doesn’t force any backend.
+Here’s a minimal example using pygame as a backend:
+
+```python
+# example_pygame_game.py
+
+import pygame
+from mini_arcade_core import Game, GameConfig, Scene
+
+
+class PygameGame(Game):
+    def __init__(self, config: GameConfig) -> None:
+        super().__init__(config)
+        pygame.init()
+        self._screen = pygame.display.set_mode(
+            (config.width, config.height)
+        )
+        pygame.display.set_caption(config.title)
+        self._clock = pygame.time.Clock()
+
+    def change_scene(self, scene: Scene) -> None:
+        if self._current_scene is not None:
+            self._current_scene.on_exit()
+        self._current_scene = scene
+        self._current_scene.on_enter()
+
+    def run(self, initial_scene: Scene) -> None:
+        self.change_scene(initial_scene)
+        self._running = True
+
+        while self._running:
+            dt = self._clock.tick(self.config.fps) / 1000.0
+
+            for event in pygame.event.get():
+                if event.type == pygame.QUIT:
+                    self._running = False
+                elif self._current_scene is not None:
+                    self._current_scene.handle_event(event)
+
+            if self._current_scene is not None:
+                self._current_scene.update(dt)
+                self._screen.fill(self.config.background_color)
+                self._current_scene.draw(self._screen)
+                pygame.display.flip()
+
+        pygame.quit()
+
+
+class PongScene(Scene):
+    def __init__(self, game: Game) -> None:
+        super().__init__(game)
+        self.x = 100.0
+        self.y = 100.0
+        self.vx = 200.0
+        self.vy = 150.0
+        self.radius = 10
+
+    def on_enter(self) -> None:
+        print("Pong started")
+
+    def on_exit(self) -> None:
+        print("Pong finished")
+
+    def handle_event(self, event: object) -> None:
+        # no input yet
+        pass
+
+    def update(self, dt: float) -> None:
+        self.x += self.vx * dt
+        self.y += self.vy * dt
+
+        width = self.game.config.width
+        height = self.game.config.height
+
+        if self.x < self.radius or self.x > width - self.radius:
+            self.vx *= -1
+        if self.y < self.radius or self.y > height - self.radius:
+            self.vy *= -1
+
+    def draw(self, surface: pygame.Surface) -> None:  # type: ignore[override]
+        pygame.draw.circle(
+            surface, (255, 255, 255), (int(self.x), int(self.y)), self.radius
+        )
+
+
+if __name__ == "__main__":
+    cfg = GameConfig(width=640, height=360, title="Mini Arcade - Pong")
+    game = PygameGame(cfg)
+    scene = PongScene(game)
+    game.run(scene)
+```
+
+Once you have a shared backend like PygameGame in its own package (or inside your game repo), you can also wire run_game() to use it instead of the abstract Game.
+
+---
+
+## Testing
+
+This project uses pytest for tests.
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+### Roadmap
+
+[ ] First concrete backend (e.g. ``mini-arcade-pygame``)
+[ ] Example games: Pong, Breakout, Snake, Asteroids-lite, Endless Runner
+[ ] Packaging the example games as separate repos using this core
+
+## License
+
+![License: MIT License](https://img.shields.io/badge/License-mit-blue.svg) — feel free to use this as a learning tool, or as a base for your own mini arcade projects.
+

mini_arcade_core-0.2.3.dist-info/RECORD

@@ -0,0 +1,8 @@
+mini_arcade_core/__init__.py,sha256=rtRWWmwC-yFNPHCLDI4C7P9i4ZYItDp7TP8i8cBUgmk,795
+mini_arcade_core/entity.py,sha256=mAkedH0j14giBQFRpQjaym46uczbQDln6nbxy0WFAqU,1077
+mini_arcade_core/game.py,sha256=j9savb7y3NPgQsiX3xeRTrEadP7xzIpfsekE74s8AAY,1825
+mini_arcade_core/scene.py,sha256=FEtywrnOBU8p0-t8oWGDELYBRRXOs4-Phe0dF7iSjKI,927
+mini_arcade_core-0.2.3.dist-info/METADATA,sha256=bK_wXGKvvBIXY0E-KRDuGXK9_gtGoA74blCPZ7qJX-8,8296
+mini_arcade_core-0.2.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mini_arcade_core-0.2.3.dist-info/licenses/LICENSE,sha256=3lHAuV0584cVS5vAqi2uC6GcsVgxUijvwvtZckyvaZ4,1096
+mini_arcade_core-0.2.3.dist-info/RECORD,,

mini_arcade_core-0.2.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mini_arcade_core-0.2.3.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Santiago Rincón
+  
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+  
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+  
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.