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

mini_arcade_native_backend/__init__.py

@@ -0,0 +1,292 @@
+"""
+mini-arcade native backend package.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# --- 1) Make sure Windows can find SDL2.dll when using vcpkg ------------------
+
+if sys.platform == "win32":
+    # a) If running as a frozen PyInstaller exe (e.g. DejaBounce.exe),
+    #    SDL2.dll will live next to the executable. Add that dir.
+    if getattr(sys, "frozen", False):
+        exe_dir = Path(sys.executable).resolve().parent
+        try:
+            os.add_dll_directory(str(exe_dir))
+        except (FileNotFoundError, OSError):
+            # If this somehow fails, we still try other fallbacks.
+            pass
+
+    # b) Dev / vcpkg fallback: use VCPKG_ROOT if available.
+    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):
+            try:
+                os.add_dll_directory(sdl_bin)
+            except (FileNotFoundError, OSError):
+                pass
+
+# --- 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
+from mini_arcade_core.keymaps.sdl import SDL_KEYCODE_TO_KEY
+
+# 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,
+    native.EventType.MouseMotion: EventType.MOUSEMOTION,
+    native.EventType.MouseButtonDown: EventType.MOUSEBUTTONDOWN,
+    native.EventType.MouseButtonUp: EventType.MOUSEBUTTONUP,
+    native.EventType.MouseWheel: EventType.MOUSEWHEEL,
+    native.EventType.WindowResized: EventType.WINDOWRESIZED,
+    native.EventType.TextInput: EventType.TEXTINPUT,
+}
+
+
+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
+        self._default_font_id: int | None = None
+
+    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._default_font_id = 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))
+
+    # Justification: Many local variables needed for event mapping
+    # pylint: disable=too-many-locals
+    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]
+        """
+        out: list[Event] = []
+        for ev in self._engine.poll_events():
+            etype = _NATIVE_TO_CORE.get(ev.type, EventType.UNKNOWN)
+
+            key = None
+            key_code = None
+            scancode = None
+            mod = None
+            repeat = None
+
+            x = y = dx = dy = None
+            button = None
+            wheel = None
+            size = None
+            text = None
+
+            if etype in (EventType.KEYDOWN, EventType.KEYUP):
+                raw_key = int(getattr(ev, "key", 0) or 0)
+                key_code = raw_key if raw_key != 0 else None
+                key = SDL_KEYCODE_TO_KEY.get(raw_key) if raw_key != 0 else None
+
+                scancode = (
+                    int(ev.scancode) if getattr(ev, "scancode", 0) else None
+                )
+                mod = int(ev.mod) if getattr(ev, "mod", 0) else None
+
+                rep = int(getattr(ev, "repeat", 0) or 0)
+                repeat = bool(rep) if etype == EventType.KEYDOWN else None
+
+            elif etype == EventType.MOUSEMOTION:
+                x = int(ev.x)
+                y = int(ev.y)
+                dx = int(ev.dx)
+                dy = int(ev.dy)
+
+            elif etype in (EventType.MOUSEBUTTONDOWN, EventType.MOUSEBUTTONUP):
+                button = int(ev.button) if ev.button else None
+                x = int(ev.x)
+                y = int(ev.y)
+
+            elif etype == EventType.MOUSEWHEEL:
+                wx = int(ev.wheel_x)
+                wy = int(ev.wheel_y)
+                wheel = (wx, wy) if (wx or wy) else None
+
+            elif etype == EventType.WINDOWRESIZED:
+                w = int(ev.width)
+                h = int(ev.height)
+                size = (w, h) if (w and h) else None
+
+            elif etype == EventType.TEXTINPUT:
+                t = getattr(ev, "text", "")
+                text = t if t else None
+
+            out.append(
+                Event(
+                    type=etype,
+                    key=key,
+                    key_code=key_code,
+                    scancode=scancode,
+                    mod=mod,
+                    repeat=repeat,
+                    x=x,
+                    y=y,
+                    dx=dx,
+                    dy=dy,
+                    button=button,
+                    wheel=wheel,
+                    size=size,
+                    text=text,
+                )
+            )
+        return out
+
+    # pylint: enable=too-many-locals
+
+    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
+        font_id = (
+            self._default_font_id if self._default_font_id is not None else -1
+        )
+        self._engine.draw_text(text, x, y, int(r), int(g), int(b), font_id)
+
+    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.4.2.dist-info/METADATA

@@ -0,0 +1,345 @@
+Metadata-Version: 2.2
+Name: mini-arcade-native-backend
+Version: 0.4.2
+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.9
+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.4.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+mini_arcade_native_backend/__init__.py,sha256=R6N7QYH4Ez6mmZOtdJd3UcPqo4obAW9um7w9Hjsrv6o,9609
+mini_arcade_native_backend/_native.cp39-win_amd64.pyd,sha256=JLEP6P9GwAN5bAqZELyb564bdKecAfhtAS_G4ExEsPg,224768
+mini_arcade_native_backend-0.4.2.dist-info/METADATA,sha256=9xVRtkbI96F7nljlKYgChuP6Au-z1jA6-pAhteCitOk,10517
+mini_arcade_native_backend-0.4.2.dist-info/WHEEL,sha256=9tsL4JT94eZPTkcS3bNng2riasYJMxXndrO9CxUfJHs,104
+mini_arcade_native_backend-0.4.2.dist-info/licenses/LICENSE,sha256=cZRgTdRJ3YASekMxkGAvylB2nROh4ov228DxAogK3yY,1115
+mini_arcade_native_backend-0.4.2.dist-info/RECORD,,

mini_arcade_native_backend-0.4.2.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.4.2.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.