Building Splitframe

Note: This page is generated from the slicecore/splitframe engine repository. Edit the source document there and let automation sync it into splitframe-io.

One path from a clean environment to a working Python + native install.

Prerequisites

• Python 3.10+
• CMake 3.20+ (for the native runtime)
• Vulkan SDK / development headers (for the native runtime)
• A C++17 compiler

Quick Start

# 1. Clone and enter the repo
git clone <repo-url> splitframe
cd splitframe

# 2. Create a virtual environment and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

# 3. Verify the Python package
pytest -q

This gives you a working splitframe install with all engine Python packages (splitframe, splitframe_api, splitframe_native_renderer) plus dev tooling (pytest, ruff, mypy).

Adding the Native Runtime

The native runtime provides the Vulkan renderer, host frame loop, and shader pipeline. Build it from the same environment:

# 4. Build the native module (minimal — no windowing or Vulkan bootstrap)
cmake -S native -B native/build -DCMAKE_BUILD_TYPE=Release
cmake --build native/build --config Release

# 5. Verify the native extension
python scripts/native/native_backend_smoke.py --module-dir native/build --json

For the full host-capable build (GLFW windowing + Vulkan bootstrap):

cmake -S native -B native/build -DCMAKE_BUILD_TYPE=Release \
  -DSPLITFRAME_NATIVE_USE_GLFW=ON \
  -DSPLITFRAME_NATIVE_USE_VULKAN_BOOTSTRAP=ON
cmake --build native/build --config Release

# Verify through the GameEngine host path
python scripts/native/native_game_engine_runtime_smoke.py --module-dir native/build --json
python scripts/native/native_simple_game_smoke.py --module-dir native/build --json

What CI Runs

CI executes exactly this flow in two jobs:

verify job — Python-only (steps 1–3 above), plus:

• Lint (ruff check)
• Boundary audit (scripts/audit_splitframe_boundaries.sh)
• Source compilation (compileall)
• Content validation (scripts/maturity/content_validate.py)
• Import smoke for all public packages

native-smoke job — Python install + native build (steps 1–5 above), plus the full native smoke suite covering backend selection, feature tiers, renderer submission, bridge threading, and the GameEngine host path.

Build Variants

Both variants produce the same splitframe_native Python extension module. The host-capable variant additionally links GLFW for native windowing and enables Vulkan instance/device bootstrap during renderer initialization.

Downstream Application Path

For downstream game/application code, the supported entry path is:

1. Build an EngineConfig
2. Create GameEngine
3. Let the engine own backend selection and native startup

The canonical example is examples/simple_game/. See docs/ENGINE.md for the full engine API and native/README.md for native-specific details.

Installed Layout

A pip install splitframe produces three Python packages:

Packaged data lands under splitframe/resources/ (currently themes/*.json). The native extension module (splitframe_native) is built separately via CMake and is not included in the Python package — it must be on sys.path or in the working directory at runtime.

splitframe.__version__ reflects the version from pyproject.toml.

Compatibility

Splitframe follows these compatibility rules during 0.x:

• The 38 symbols in splitframe.public (re-exported through splitframe.__init__) are the supported public surface. Changes to these symbols will be documented in release notes.
• Symbols accessible only through their owning modules (e.g. splitframe.physics.Vec2) may change without notice during 0.x.
• The cooked content manifest format (splitframe.content.cooked.asset.v1) is stable within a minor version. Re-cooking is expected across minor version upgrades.
• The native extension’s Python binding surface (splitframe_native_renderer) labels compatibility ingress and advanced mutation surface explicitly. Only RequestedFeatureTier and resolve_runtime_config() are supported for direct use; per-feature mutation is advanced/test-only.

Troubleshooting

Missing Vulkan headers — Install your platform’s Vulkan SDK. On Ubuntu: sudo apt install libvulkan-dev vulkan-tools.

Missing GLFW — Install libglfw3-dev or build with -DSPLITFRAME_NATIVE_USE_GLFW=OFF (default).

pygfx/wgpu import errors — The pygfx-based rendering subsystem is optional. Core engine functionality, tests, and the native renderer work without pygfx installed. If you need the pygfx renderer path, install pygfx and wgpu separately.