Splitframe Native runtime. Modular gameplay.
All docs
Guides Editorial guide Site-owned guide

Getting Started

Install Splitframe, run the engine locally, and understand the first runtime concepts.

Splitframe is best understood as a native-first engine with a Python gameplay layer, not as a loose Python framework that happens to render. The first goal is to get the engine running locally and understand the repo boundaries before you build anything larger.

What You Need

For a normal local engine checkout:

  • Python 3.11+ is recommended
  • a working virtual environment flow
  • C/C++ build tooling if you want to build the native runtime directly
  • Vulkan development libraries if you want the full native path locally

If you only want to inspect the Python engine surface and examples first, the editable Python install is enough to start.

Clone The Repositories

Splitframe is now separated into distinct products:

  • splitframe: the engine source, native runtime, engine docs, and examples
  • splitframe-io: the public website and site-owned guides
  • game repos such as gwoop: engine consumers

That separation is intentional. The engine should stand on its own, and game projects should consume it rather than define it.

Install The Engine

From the engine repo:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

That gives you the local Python engine package in editable mode.

Run The Example Project

Once the environment is active:

python examples/simple_game/main.py

The simple example is intentionally small. It is not meant to prove every part of the engine; it is meant to show the project shape:

  • engine bootstrap through GameEngine
  • project-owned scenes and entities
  • a game repo consuming engine surfaces instead of redefining them

Understand The Runtime Model Early

Before building project code, it helps to start with the engine’s runtime assumptions:

  • the native host owns frame lifecycle, presentation, and recovery
  • the Python layer owns gameplay, orchestration, and project logic
  • content, shader, and runtime policy are explicit contracts
  • plugins and mods are expected to live behind stable boundaries rather than random imports into engine internals

That means your mental model should be:

  1. the engine host and runtime are products in their own right
  2. gameplay code runs on top of those surfaces
  3. project packaging and content cooking are part of the build story, not something bolted on later

If you are new to Splitframe, read the docs in this order:

  1. this page, to understand the setup and repo model
  2. Runtime Architecture, to understand the host, systems, and Python layering
  3. Roadmap, to understand the target state the engine is moving toward
  4. the generated engine docs, especially Engine Overview and Building Splitframe

Where To Build Different Kinds Of Code

Use this rule of thumb:

  • engine code belongs in splitframe
  • technical engine docs belong in splitframe/docs
  • public product framing belongs in splitframe-io
  • game code belongs in a game repo
  • game-specific assets and content belong with the game repo

That boundary matters because Splitframe is trying to become a reusable engine with a stable runtime and extension surface, not a game-specific monolith.

Common Mistake To Avoid

Do not treat Splitframe like a script-first toy where the runtime can stay undefined until late in development.

If your project is going to rely on:

  • cooked content
  • native rendering
  • stable plugins or mods
  • editor/tooling support later
  • cross-platform packaging eventually

then the right move is to respect those contracts early instead of hoping they can be patched in after gameplay code sprawls.

Next Step

After the example runs, move on to Runtime Architecture. That page explains how the native host, engine systems, content pipeline, and Python gameplay layer fit together.