mini-arcade-core 0.3.1__tar.gz

mini_arcade_core-0.3.1/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.

mini_arcade_core-0.3.1/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: mini-arcade-core
+Version: 0.3.1
+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.3.1/README.md

@@ -0,0 +1,245 @@
+# 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.3.1/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "mini-arcade-core"
+version = "0.3.1"
+description = "Tiny scene-based game loop core for small arcade games."
+authors = [
+    { name = "Santiago Rincon", email = "rincores@gmail.com" },
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9,<3.12"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest~=8.3",
+    "pytest-cov~=6.0",
+    "black~=24.10",
+    "isort~=5.13",
+    "mypy~=1.5",
+    "pylint~=3.3",
+]
+
+[tool.black]
+line-length = 79
+target-version = ["py39"]
+force-exclude = '''(
+^\.venv
+|^venv
+|^env
+|^\.env
+|^build
+|^dist
+|^docs
+)'''
+
+[tool.isort]
+profile = "black"
+line_length = 79
+known_first_party = ["mini_arcade_core"]
+skip = [".venv", "venv", "env", "build", "dist", "docs"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --color=yes"
+
+[tool.mypy]
+python_version = "3.9"
+packages = ["mini_arcade_core"]
+ignore_missing_imports = true
+strict = false
+
+[tool.pylint.messages_control]
+disable = [
+    # Justification: Allow classes with few public methods for simplicity.
+    "too-few-public-methods",
+    # Justification: TODOs are acceptable during development.
+    "fixme",
+]
+
+[tool.pylint.MAIN]
+ignore-paths = [
+    "^\\.venv",
+    "^venv",
+    "^tests",
+    "^env",
+    "^build",
+    "^dist",
+    "^docs",
+]
+
+[tool.poetry]
+packages = [{ include = "mini_arcade_core", from = "src" }]

mini_arcade_core-0.3.1/src/mini_arcade_core/__init__.py

@@ -0,0 +1,36 @@
+"""
+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 .backend import Backend, Event, EventType
+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",
+    "Backend",
+    "Event",
+    "EventType",
+]

mini_arcade_core-0.3.1/src/mini_arcade_core/backend.py

@@ -0,0 +1,75 @@
+"""
+Backend interface for rendering and input.
+This is the only part of the code that talks to SDL/pygame directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Iterable, Protocol
+
+
+class EventType(Enum):
+    """High-level event types understood by the core."""
+
+    UNKNOWN = auto()
+    QUIT = auto()
+    KEYDOWN = auto()
+    KEYUP = auto()
+
+
+@dataclass(frozen=True)
+class Event:
+    """
+    Core event type.
+
+    For now we only care about:
+    - type: what happened
+    - key: integer key code (e.g. ESC = 27), or None if not applicable
+
+    :ivar type (EventType): The type of event.
+    :ivar key (int | None): The key code associated with the event, if any.
+    """
+
+    type: EventType
+    key: int | None = None
+
+
+class Backend(Protocol):
+    """
+    Interface that any rendering/input backend must implement.
+
+    mini-arcade-core only talks to this protocol, never to SDL/pygame directly.
+    """
+
+    def init(self, width: int, height: int, title: str) -> None:
+        """
+        Initialize the backend and open a window.
+
+        Should be called once before the main loop.
+        """
+
+    def poll_events(self) -> Iterable[Event]:
+        """
+        Return all pending events since last call.
+
+        Concrete backends will translate their native events into core Event objects.
+        """
+
+    def begin_frame(self) -> None:
+        """
+        Prepare for drawing a new frame (e.g. clear screen).
+        """
+
+    def end_frame(self) -> None:
+        """
+        Present the frame to the user (swap buffers).
+        """
+
+    def draw_rect(self, x: int, y: int, w: int, h: int) -> None:
+        """
+        Draw a filled rectangle in some default color.
+
+        We'll keep this minimal for now; later we can extend with colors/sprites.
+        """

mini_arcade_core-0.3.1/src/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-0.3.1/src/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-0.3.1/src/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."""