Splitframe Native runtime. Modular gameplay.
All docs
Engine Docs Synced doc Engine source of truth

Engine Overview

High-level engine layout, current core surfaces, and repository ownership.

Generated from slicecore/splitframe View source doc

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

Splitframe is being built as a native-first game engine with a Python gameplay layer, a deterministic content pipeline, and a first-class extension surface for plugins, mods, and future tooling.

The engine is strongest today as a 2D runtime, but the long-term target is broader than “another 2D framework.” The target state is:

  • native host ownership of frame lifecycle, device lifecycle, presentation, and recovery
  • Python-level iteration speed for gameplay, orchestration, and project logic
  • deterministic cooked-content and shader/runtime contracts
  • capability-gated plugin and modding boundaries
  • editor and tooling support built on the same engine data model
  • a credible path from 2D runtime strength to a more general 3D-capable engine
  • disciplined cross-platform packaging rather than many divergent runtimes

This document describes the actual engine shape that supports that direction.

Core Architectural Stances

The runtime host is authoritative

Splitframe does not treat the frame loop or renderer as an implementation detail hidden behind gameplay code. The native host owns:

  • frame begin/update/render/present lifecycle
  • renderer health, device loss, and recovery signaling
  • runtime profile application and policy enforcement
  • presentation and native backend compatibility checks

In practice that means the gameplay layer is important, but it is not the authority for runtime behavior.

Contracts beat convention

The engine is designed around explicit boundaries:

  • cooked content and runtime bundle validation
  • shader bundle activation and compatibility
  • backend compatibility and schema checks
  • plugin capability and dependency checks
  • versioned payloads between Python and native code

If two parts of the system need to cooperate, the preferred shape is a visible contract that can be validated and tested.

Code-first, not tooling-hostile

Splitframe should remain usable, testable, and automatable directly from code. That is not in conflict with editor ambitions. The intended model is:

  • code remains a first-class way to build and test projects
  • tooling and editor surfaces are built on top of engine-owned formats and services
  • the editor is a client of the engine model, not a separate source of truth

Extensions are product boundaries

Plugins and mods are not meant to rely on arbitrary engine internals. The engine already has the beginnings of a stable script ABI, manifest-based plugin loading, capability gates, and sandbox checks. The long-term goal is to turn that into a real extension platform.

The root splitframe package still exposes a large compatibility surface because older consumers import many symbols directly from it. That is not the shape we want new projects to copy.

New engine consumers should prefer splitframe.public, which curates the engine around a few stable concept groups:

  • runtime boot and scene/entity orchestration
  • content/runtime contract types
  • plugin and modding boundaries

That split keeps the root package stable for existing code while letting new code adopt a more intentional boundary immediately.

Current Engine Shape

The most important runtime surfaces live in:

  • splitframe/core.py
  • splitframe/scene.py
  • splitframe/system.py
  • splitframe/entity.py
  • splitframe/content/
  • splitframe/rendering/
  • splitframe_api/
  • native/

Runtime boot and policy

splitframe/core.py is the main engine entry point. It applies a runtime profile during startup, requires cooked content when policy says it must, and activates the runtime shader bundle for native backends before normal gameplay execution begins.

splitframe/runtime_profiles.py defines the profile-controlled environment policy for dev, perf, and release. That is part of the product stance: production behavior is shaped intentionally rather than left to ad hoc environment toggles.

Native runtime and rendering

The engine currently treats native_vulkan as the authoritative runtime backend. Backend selection is not framed as a broad abstraction layer with many equal options. The intent is a strong native path with explicit compatibility validation and health signaling.

The Python/native boundary is also contract-oriented. Rendering submission, schema validation, and runtime compatibility checks live under splitframe/rendering/ and native/.

Gameplay layer

Gameplay still lives comfortably in Python:

  • scenes and scene management
  • entities and state
  • input orchestration
  • game systems and progression logic
  • project-level bootstrap code

The stance is not “replace gameplay scripting.” The stance is to keep gameplay iteration fast without letting gameplay code implicitly own the runtime.

Systems and lifecycle

splitframe/system.py provides a structured system manager with dependency and lifecycle ordering. That is part of the engine’s modularity story: reusable subsystems should have explicit startup, update, and shutdown behavior instead of being wired together informally.

Content pipeline

splitframe/content/ owns deterministic asset manifests, cook graphs, cooked asset records, runtime bundle loading, and native shader bundle activation. The content pipeline is not an afterthought. It is part of how Splitframe intends to ship projects predictably.

Plugin and modding surfaces

splitframe_api/ defines the public script-facing ABI boundary between engine internals and Python-hosted gameplay or plugin modules.

splitframe/plugin_lifecycle.py, splitframe/script_plugins.py, and splitframe/modding_api.py provide the early foundation for:

  • manifest-based discovery
  • dependency-safe loading
  • capability-gated engine services
  • compatibility and version checks
  • extension lifecycle management

These surfaces are still early, but they are architecturally aligned with the engine’s target state.

Repository Ownership

This repository is the engine product, not a game workspace.

Engine-owned code includes:

  • splitframe/
  • splitframe_api/
  • splitframe_native_renderer/
  • native/
  • examples/simple_game/
  • docs/

Game-specific code belongs in game repositories such as gwoop. Import boundaries are enforced so the engine does not depend back on the game.

What Is Still In Progress

Splitframe’s architecture is ahead of its polish in a few places.

Notable follow-up work includes:

  • migrating downstream consumers from the oversized root import surface toward splitframe.public, then shrinking the compatibility table deliberately
  • finishing the native runtime transition from “scaffold/prototype language” to a fully productized description
  • removing remaining legacy gwoop naming from native symbols and docs
  • strengthening examples and tutorials so they reflect the native-first engine model consistently
  • continuing the path from strong 2D runtime architecture toward shared 2D/3D engine foundations
  • docs/BUILDING.md
  • docs/TESTING.md
  • docs/MIGRATION.md
  • native/README.md