mini-arcade-native-backend 0.3.3__cp39-cp39-win_amd64.whl

mini_arcade_native_backend/__init__.py

@@ -0,0 +1,194 @@
+"""
+mini-arcade native backend package.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# --- 1) Make sure Windows can find SDL2.dll when using vcpkg ------------------
+
+if sys.platform == "win32":
+    vcpkg_root = os.environ.get("VCPKG_ROOT")
+    if vcpkg_root:
+        # Typical vcpkg layout: <VCPKG_ROOT>/installed/x64-windows/bin/SDL2.dll
+        sdl_bin = os.path.join(vcpkg_root, "installed", "x64-windows", "bin")
+        if os.path.isdir(sdl_bin):
+            # Python 3.8+ – add DLL search path before importing the extension
+            os.add_dll_directory(sdl_bin)
+
+# --- 2) Now import native extension and core types ----------------------------
+
+# Justification: Need to import core after setting DLL path on Windows
+# pylint: disable=wrong-import-position
+from mini_arcade_core import Backend, Event, EventType
+
+# Justification: Importing the native extension module
+# pylint: disable=import-self,no-name-in-module
+from . import _native as native
+
+# --- 2) Now import core + define NativeBackend as before ---
+
+
+__all__ = ["NativeBackend", "native"]
+
+
+_NATIVE_TO_CORE = {
+    native.EventType.Unknown: EventType.UNKNOWN,
+    native.EventType.Quit: EventType.QUIT,
+    native.EventType.KeyDown: EventType.KEYDOWN,
+    native.EventType.KeyUp: EventType.KEYUP,
+}
+
+
+class NativeBackend(Backend):
+    """Adapter that makes the C++ Engine usable as a mini-arcade backend."""
+
+    def __init__(self, font_path: str | None = None, font_size: int = 24):
+        """
+        :param font_path: Optional path to a TTF font file to load.
+        :type font_path: str | None
+
+        :param font_size: Font size in points to use when loading the font.
+        :type font_size: int
+        """
+        self._engine = native.Engine()
+        self._font_path = font_path
+        self._font_size = font_size
+
+    def init(self, width: int, height: int, title: str):
+        """
+        Initialize the backend with a window of given width, height, and title.
+
+        :param width: Width of the window in pixels.
+        :type width: int
+
+        :param height: Height of the window in pixels.
+        :type height: int
+
+        :param title: Title of the window.
+        :type title: str
+        """
+        self._engine.init(width, height, title)
+
+        # Load font if provided
+        if self._font_path is not None:
+            self._engine.load_font(self._font_path, self._font_size)
+
+    def set_clear_color(self, r: int, g: int, b: int):
+        """
+        Set the background/clear color used by begin_frame.
+
+        :param r: Red component (0-255).
+        :type r: int
+
+        :param g: Green component (0-255).
+        :type g: int
+
+        :param b: Blue component (0-255).
+        :type b: int
+        """
+        self._engine.set_clear_color(int(r), int(g), int(b))
+
+    def poll_events(self) -> list[Event]:
+        """
+        Poll for events from the backend and return them as a list of Event objects.
+
+        :return: List of Event objects representing the polled events.
+        :rtype: list[Event]
+        """
+        events: list[Event] = []
+        for ev in self._engine.poll_events():
+            core_type = _NATIVE_TO_CORE.get(ev.type, EventType.UNKNOWN)
+            key = ev.key if getattr(ev, "key", 0) != 0 else None
+            events.append(Event(type=core_type, key=key))
+        return events
+
+    def begin_frame(self):
+        """Begin a new frame for rendering."""
+        self._engine.begin_frame()
+
+    def end_frame(self):
+        """End the current frame for rendering."""
+        self._engine.end_frame()
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def draw_rect(
+        self,
+        x: int,
+        y: int,
+        w: int,
+        h: int,
+        color: tuple[int, ...] = (255, 255, 255),
+    ):
+        """
+        Draw a rectangle at the specified position with given width and height.
+
+        :param x: X coordinate of the rectangle's top-left corner.
+        :type x: int
+
+        :param y: Y coordinate of the rectangle's top-left corner.
+        :type y: int
+
+        :param w: Width of the rectangle.
+        :type w: int
+
+        :param h: Height of the rectangle.
+        :type h: int
+
+        :param color: Color of the rectangle as (r, g, b) or (r, g, b, a).
+        :type color: tuple[int, ...]
+        """
+        if len(color) == 3:
+            r, g, b = color
+            self._engine.draw_rect(x, y, w, h, r, g, b)
+        elif len(color) == 4:
+            r, g, b, a = color
+            self._engine.draw_rect_rgba(x, y, w, h, r, g, b, a)
+        else:
+            raise ValueError(
+                f"Color must be (r,g,b) or (r,g,b,a), got {color!r}"
+            )
+
+    # pylint: enable=too-many-arguments,too-many-positional-arguments
+
+    def draw_text(
+        self,
+        x: int,
+        y: int,
+        text: str,
+        color: tuple[int, int, int] = (255, 255, 255),
+    ):
+        """
+        Draw text at the given position using the loaded font.
+        If no font is loaded, this is a no-op.
+
+        :param x: X coordinate for the text position.
+        :type x: int
+
+        :param y: Y coordinate for the text position.
+        :type y: int
+
+        :param text: The text string to draw.
+        :type text: str
+
+        :param color: Color of the text as (r, g, b).
+        :type color: tuple[int, int, int]
+        """
+        # We rely on C++ side to no-op if font is missing
+        r, g, b = color
+        self._engine.draw_text(text, x, y, int(r), int(g), int(b))
+
+    def capture_frame(self, path: str | None = None) -> bool:
+        """
+        Capture the current frame.
+
+        :param path: Optional file path to save the captured frame (e.g., PNG).
+        :type path: str | None
+
+        :return: True if the frame was successfully captured (and saved if path provided),
+            False otherwise.
+        :rtype: bool
+        """
+        return self._engine.capture_frame(path)

mini_arcade_native_backend-0.3.3.dist-info/METADATA

@@ -0,0 +1,345 @@
+Metadata-Version: 2.2
+Name: mini-arcade-native-backend
+Version: 0.3.3
+Summary: Native SDL2 backend for mini-arcade-core using SDL2 + pybind11.
+Author-Email: Santiago Rincon <rincores@gmail.com>
+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.
+         
+Requires-Python: <3.12,>=3.9
+Requires-Dist: mini-arcade-core>=0.2.3
+Provides-Extra: dev
+Requires-Dist: pytest~=8.3; extra == "dev"
+Requires-Dist: pytest-cov~=6.0; extra == "dev"
+Requires-Dist: black~=24.10; extra == "dev"
+Requires-Dist: isort~=5.13; extra == "dev"
+Requires-Dist: mypy~=1.5; extra == "dev"
+Requires-Dist: pylint~=3.3; extra == "dev"
+Description-Content-Type: text/markdown
+
+# mini-arcade-native-backend
+
+Native SDL2 backend for **mini-arcade-core**, implemented in C++ with `SDL2` + `pybind11`
+and exposed to Python as a backend that plugs into your mini-arcade game framework.
+
+The goal of this repo is to provide a **native window + input + drawing layer** while
+keeping all game logic in Python (via `mini-arcade-core`).
+
+- C++ (`SDL2` + `pybind11`) ⇒ `_native` extension module
+- Python adapter ⇒ `NativeBackend` implementing `mini_arcade_core.backend.Backend`
+
+---
+
+## Features (current)
+
+- Opens an SDL window from Python
+- Basic event polling (Quit, KeyDown, KeyUp) mapped to `Event` / `EventType` in mini-core
+- Simple rendering:
+  - `begin_frame()` / `end_frame()`
+  - `draw_rect(x, y, w, h)` (filled rectangle)
+- Example script that shows a moving rectangle and exits on **ESC** or window close
+
+This is intentionally minimal and intended as a foundation for adding sprites, textures,
+audio, etc.
+
+---
+
+## Repository layout
+
+```text
+mini-arcade-native-backend/
+├─ cpp/
+│  ├─ engine.h                        # C++ Engine class (SDL wrapper)
+│  ├─ engine.cpp
+│  └─ bindings.cpp                    # pybind11 bindings for Engine / Event / EventType
+├─ src/
+│  └─ mini_arcade_native_backend/
+│     ├─ __init__.py                  # Python adapter (NativeBackend)
+│     └─ ...                          # (future helpers)
+├─ examples/
+│  └─ native_backend_demo.py          # example using NativeBackend directly
+├─ CMakeLists.txt                     # C++ build (pybind11 + SDL2)
+└─ pyproject.toml                     # Python package & build config (scikit-build-core)
+```
+
+---
+
+## Install modes
+
+There are **two ways** to consume this backend:
+
+1. **From PyPI (recommended for players / game users)**  
+   Prebuilt wheels for your platform (no C++ toolchain or vcpkg needed).
+2. **From source (for contributors / engine dev)**  
+   Build the C++ extension locally using CMake + vcpkg.
+
+---
+
+## 1. Using the backend from PyPI (no C++ build)
+
+Once wheels are published, you can simply do:
+
+```bash
+pip install mini-arcade-core
+pip install mini-arcade-native-backend
+```
+
+And in your game:
+
+```python
+from mini_arcade_core import Game, GameConfig, Scene
+from mini_arcade_core.backend import EventType
+from mini_arcade_native_backend import NativeBackend
+
+class MyScene(Scene):
+    def handle_event(self, event):
+        if event.type == EventType.KEYDOWN and event.key == 27:  # ESC
+            self.game.quit()
+
+    def update(self, dt: float):
+        ...
+
+    def draw(self, backend):
+        backend.draw_rect(100, 100, 200, 150)
+
+config = GameConfig(
+    width=800,
+    height=600,
+    title="Mini Arcade + Native SDL2",
+    backend_factory=lambda: NativeBackend(),
+)
+
+game = Game(config)
+scene = MyScene(game)
+game.run(scene)
+```
+
+For normal users of your games, this is the ideal path: **no vcpkg**, no CMake, no compiler.
+
+---
+
+## 2. Developing / building from source
+
+If you want to work on the native backend itself (C++ + Python), you’ll build the extension
+locally. For that, you need a C++ toolchain, CMake, and vcpkg.
+
+### 2.1. System requirements
+
+- **OS**: Windows 10 or later (current dev setup)
+- **Compiler**: MSVC via Visual Studio Build Tools or Visual Studio 2022
+  - Install the *“Desktop development with C++”* workload
+- **CMake**: 3.16+
+- **Python**: 3.9–3.11 (matching your `mini-arcade-core` version)
+- **vcpkg**: for `SDL2` and `pybind11`
+- (Optional but nice) **virtual environment** / Poetry for Python deps
+
+### 2.2. vcpkg + C++ libraries
+
+This project uses [vcpkg](https://github.com/microsoft/vcpkg) to manage C++ dependencies.
+
+#### Clone and bootstrap vcpkg
+
+```powershell
+cd C:\Users\<your_user>\work
+
+git clone https://github.com/microsoft/vcpkg.git
+cd vcpkg
+.\bootstrap-vcpkg.bat
+```
+
+#### Install dependencies via vcpkg
+
+```powershell
+# From the vcpkg folder:
+.\vcpkg.exe install sdl2 pybind11
+```
+
+You only need to do this once per machine (unless you wipe `vcpkg` or add new libraries).
+
+### 2.3. Linking CMake to vcpkg
+
+For builds in this repo, set the toolchain environment variable once per shell:
+
+```powershell
+$env:CMAKE_TOOLCHAIN_FILE = "C:/Users/<your_user>/work/vcpkg/scripts/buildsystems/vcpkg.cmake"
+```
+
+(Adjust the path if you cloned `vcpkg` somewhere else.)
+
+---
+
+## 3. Building & installing the package from source
+
+This project uses **[scikit-build-core](https://github.com/scikit-build/scikit-build-core)** as
+the build backend, which lets `pip` drive CMake for you.
+
+From the repo root (`mini-arcade-native-backend/`):
+
+### 3.1. Editable install (dev mode)
+
+```powershell
+# Activate your virtualenv (or use Poetry's venv)
+# Then, with CMAKE_TOOLCHAIN_FILE set:
+
+pip install -e .
+```
+
+What this does:
+
+- Runs CMake via scikit-build-core
+- Builds the `_native` extension
+- Installs the package in editable mode, so changes to `src/` are picked up immediately
+
+After this, you can test in Python:
+
+```python
+>>> from mini_arcade_native_backend import NativeBackend
+>>> backend = NativeBackend()
+>>> backend.init(800, 600, "Hello from native backend")
+```
+
+### 3.2. Building wheels / sdist
+
+To build distributable artifacts:
+
+```powershell
+python -m build
+```
+
+This will produce:
+
+```text
+dist/
+  mini-arcade-native-backend-0.1.0-*.whl
+  mini-arcade-native-backend-0.1.0.tar.gz
+```
+
+Those wheels can be uploaded to PyPI (e.g. via `twine`) and installed by anyone with:
+
+```bash
+pip install mini-arcade-native-backend
+```
+
+End users installing the wheel **do not** need vcpkg or a compiler.
+
+---
+
+## 4. Python usage & example
+
+The package exposes a `NativeBackend` that implements the `Backend` protocol from
+`mini-arcade-core` and wraps the C++ `Engine` underneath.
+
+```python
+from mini_arcade_native_backend import NativeBackend
+from mini_arcade_core.backend import EventType
+```
+
+A small standalone demo is provided under `examples/`:
+
+```bash
+python examples/native_backend_demo.py
+```
+
+That demo:
+
+- opens an 800×600 window,
+- moves a rectangle horizontally,
+- exits on ESC or window close.
+
+(When installed via `pip install -e .`, you can run this from the repo root.)
+
+---
+
+## 5. How it fits into mini-arcade-core
+
+On the C++ side (`cpp/engine.h` / `cpp/engine.cpp`):
+
+- `mini::Engine` wraps SDL:
+  - `init(width, height, title)`
+  - `begin_frame()` / `end_frame()`
+  - `draw_rect(x, y, w, h)`
+  - `poll_events()` → `std::vector<Event>`
+- `EventType` and `Event` are simple types mapping SDL events to something Python-friendly.
+
+On the Python side (`src/mini_arcade_native_backend/__init__.py`):
+
+- The compiled C++ module is imported as `._native` (installed into the same package)
+- `NativeBackend` implements `mini_arcade_core.backend.Backend`:
+  - `init(width, height, title)` → `_native.Engine.init(...)`
+  - `poll_events()` → converts `_native.Event` to core `Event`
+  - `begin_frame()` / `end_frame()` → pass-through
+  - `draw_rect(x, y, w, h)` → pass-through
+
+A minimal integration with mini-arcade-core:
+
+```python
+from mini_arcade_core import Game, GameConfig, Scene
+from mini_arcade_core.backend import Backend, Event, EventType
+from mini_arcade_native_backend import NativeBackend
+
+class MyScene(Scene):
+    def handle_event(self, event: Event) -> None:
+        if event.type == EventType.KEYDOWN and event.key == 27:  # ESC
+            self.game.quit()
+
+    def update(self, dt: float) -> None:
+        ...
+
+    def draw(self, backend: Backend) -> None:
+        backend.draw_rect(100, 100, 200, 150)
+
+config = GameConfig(
+    width=800,
+    height=600,
+    title="Mini Arcade + Native SDL2",
+    backend_factory=lambda: NativeBackend(),
+)
+
+game = Game(config)
+scene = MyScene(game)
+game.run(scene)
+```
+
+---
+
+## 6. Troubleshooting
+
+- **`ModuleNotFoundError: No module named '_native'`**  
+  - Ensure `pip install -e .` (or `python -m build`) completed successfully.
+  - Confirm that the wheel contains `mini_arcade_native_backend/_native.*.pyd`.
+
+- **DLL load error / Python version mismatch**  
+  - Make sure you are building and running with the **same Python version**.
+  - If you have multiple Python versions installed, ensure the one used by
+    `pip install -e .` is the one used to run your game.
+
+- **CMake can’t find SDL2 or pybind11**  
+  - Confirm vcpkg is installed and `sdl2` + `pybind11` are installed via vcpkg.
+  - Make sure `CMAKE_TOOLCHAIN_FILE` is set correctly in your shell.
+
+---
+
+## 7. Roadmap
+
+- Configurable clear color (per scene / per game)
+- Basic texture / sprite support
+- Simple audio playback
+- CI that builds wheels for Windows and uploads to PyPI
+- A `mini-arcade-core` example project that uses this backend as the default renderer

mini_arcade_native_backend-0.3.3.dist-info/RECORD

@@ -0,0 +1,6 @@
+mini_arcade_native_backend/__init__.py,sha256=Wc8QcUb39AUnwJMy1XEykBadAybJNgncld2HLvKUPWw,6118
+mini_arcade_native_backend/_native.cp39-win_amd64.pyd,sha256=MPpUieq0R-8NKlq6o4LZ47ZqVsVAsZgF1wb4bp9MIvk,219648
+mini_arcade_native_backend-0.3.3.dist-info/METADATA,sha256=N9TjTXkbNSu-U7wDgTg95W_B0yRAZu1ieucneBzGrUI,10519
+mini_arcade_native_backend-0.3.3.dist-info/WHEEL,sha256=9tsL4JT94eZPTkcS3bNng2riasYJMxXndrO9CxUfJHs,104
+mini_arcade_native_backend-0.3.3.dist-info/licenses/LICENSE,sha256=cZRgTdRJ3YASekMxkGAvylB2nROh4ov228DxAogK3yY,1115
+mini_arcade_native_backend-0.3.3.dist-info/RECORD,,

mini_arcade_native_backend-0.3.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.11.6
+Root-Is-Purelib: false
+Tag: cp39-cp39-win_amd64
+

mini_arcade_native_backend-0.3.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.