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 import surface is curated

The root splitframe package now exports exactly the same 38 symbols as splitframe.public. Both modules present the same curated surface organized around a few stable concept groups:

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

All other subsystem symbols were removed from root re-exports. They remain accessible via their owning modules (e.g. from splitframe.combat import CombatWorld). Subsystem families such as AI are consolidated under intentional namespace packages (splitframe.ai).

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.

For the native runtime, the supported default host path is:

  1. construct EngineConfig
  2. create GameEngine
  3. let the engine build the native startup manifest and backend-selection contract internally

Lower-level seams such as direct splitframe_native_renderer construction or raw backend-selection helpers still exist for tooling and contract tests, but they are not the preferred downstream boot story.

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/.

For most engine consumers, that boundary should be reached through GameEngine, not by wiring native startup objects by hand. Direct native facade usage is the lower-level surface that engine bootstrap and smoke tooling exercise underneath the preferred host path.

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 downstream game repositories. Import boundaries are enforced so the engine does not depend back on game code.

What Is Still In Progress

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

Notable follow-up work includes:

  • making simple_game consume cooked content instead of constructing data procedurally, so the canonical example demonstrates the full cooked runtime path
  • removing raw-data fallbacks from production runtime paths and treating cooked bundles as the only release-path source of truth
  • 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