Planned interface

Everything a game needs from SimEngine, area by area: what works today, what is being built, and the interface we plan for the rest. We write the docs before the engine, so you and your agent can see where it is going. Nothing marked planned exists yet.

Last updated: 2026-10-30. Engine state: pre-release, M1 foundations done, M2 in progress.

Rules for agents

• Do not call anything on this page unless simengine_host --capabilities lists it. If a command, component or option is not in your build’s capability document, it does not exist, whatever this page says.
• Planned names are proposals. Command names, arguments and schemas below can change before they ship. The capability document of the build you run is the only contract.
• Do not emulate a planned feature. If a user asks for something that is only planned, say it is not available yet. Never edit engine sources, tests or examples to fake it.
• Available means available in the current pre-release build, and always subject to --capabilities.

Status legend

Status	Meaning
Available	In the current pre-release build. Confirm with --capabilities.
In progress	Being built on the engine roadmap (task IDs given).
Planned	On the engine roadmap, not started (milestone given).
Planned, not scheduled	In SimEngine’s scope, not yet given a roadmap task.
Later	Deferred until a concrete need justifies it (M8).

SimEngine has no editor by design. Every area below is driven the same way: versioned text, typed commands, seeded headless runs, captures and expectations an agent can check.

Overview

Area	Status	Roadmap
Agent control and discovery	Available, more planned	SIM-005 done; SIM-050 to SIM-054 (M6)
Scenes, entities and components	Available (basic), more planned	SIM-005 done; SIM-050 (M6)
Units, transforms and frames	Available	SIM-010 done; SIM-011 in review
Game loop and time	Available (headless ticks, desktop loop), more planned	SIM-076 done
Gameplay logic	Planned, model proposed	ADR 0007 (proposed)
Input	Planned, not scheduled	Core input in the PRD
Physics	In progress	SIM-014, SIM-070 (M2)
Rendering and cameras	Available (basic), more planned	SIM-006 done; SIM-040 to SIM-045 (M5)
Assets	Available (static glTF subset), in progress	SIM-030 (M4)
Animation	Planned, not scheduled
Audio	Planned	SIM-036 (M4)
Saves and checkpoints	Planned	SIM-034 (M4)
Navigation	Planned, not scheduled
Building and shipping a game	Planned	SIM-065 (M7)
Platforms	Windows 11 x64 available	Others later
Multiplayer	Later	M8

Agent control and discovery

Available. simengine_host --capabilities returns the scenario schema, units, frames, components, commands, limits, exit codes and an example valid for the build. --load validates all-or-nothing, --run executes a seeded scenario and returns one result document, --session gives JSON Lines control (load, step, inspect, command with dry run, expectations, capabilities, quit). Every failure has an exit code and a structured error.code.

Planned (M6). Complete typed operations with per-command discovery (SIM-050), coherent state, capture and performance inspection (SIM-051), isolated candidate builds with serialized acceptance (SIM-052), validated data and shader reload (SIM-053), and compatible native reload or checkpoint-and-restart recovery (SIM-054).

Planned interface:

Name	Kind	What it will do
simengine.api.describe	session operation	Full schema of one command or component: arguments, units, errors, version.
simengine.state.query	session operation	Read entities and components by id, component type or region, with a state version.
simengine.state.diff	session operation	Typed difference between two state versions or two run results.
reload	session operation	Apply validated data or shader changes at a safe point; refuse with a code if unsafe.
checkpoint / restore	session operations	Save and restore the full simulation state during a session.

Scenes, entities and components

Available. Scenarios (simengine.scenario v1) declare entities with explicit positions, generators (scatter_box), scheduled commands and expectations. Today the core command is simengine.entity.set_position; the optional point_mass module adds velocity, gravity, point_mass.apply_impulse and point_mass.set_velocity. Scenes for rendering are .sescene files that reference cooked .seasset meshes.

Planned (M6, SIM-050). A full entity lifecycle and component model driven by commands, so an agent can build any scene from text.

Name	What it will do
simengine.entity.create / simengine.entity.destroy	Create an entity with components, or remove it and its children.
simengine.entity.set_parent	Attach an entity to a parent with an explicit local transform.
simengine.entity.add_component / remove_component / set_component	Change an entity’s components with typed, versioned values.
simengine.template.instantiate	Spawn a reusable entity template (a prefab in text). Planned, not scheduled.

Expectations will cover any component value, entity existence and counts, not only positions.

Units, transforms and frames

Available. Every position carries a value, a unit and a frame. Frames are right-handed, +y up, and nested (SIM-010). Durations are nanoseconds.

In review. Continuity through frame and origin changes (SIM-011), so objects stay precise from a blood cell to a planetary orbit. Large-scale frames (star, planet, base, vehicle) are part of the optional spatial modules.

Game loop and time

Available. Headless scenarios run a fixed number of fixed-duration ticks. The Windows playground (simengine_desktop) runs a generic frame loop with windowed presentation (SIM-076).

Planned, not scheduled. A game loop for shipped games: fixed-step simulation with variable-rate rendering, pause and time scale. Safe time warp for large worlds is part of the optional spatial modules (SIM-016).

Name	What it will do
simengine.time.pause / simengine.time.resume	Stop and restart simulation time; rendering continues.
simengine.time.set_scale	Slow motion or fast forward within declared limits.

Gameplay logic

Planned; the authoring model is proposed, not decided (ADR 0007, repository private until release). The proposal is a staged hybrid:

1. Behaviors as data. Most gameplay is configured, not coded: behaviors are components selected and parameterized in versioned scenario data, validated field by field before anything runs, and reloadable at a safe point.
2. New rules in native C++. New behaviors are C++20 code in your application or an optional module, against the public API and the module contract, built and run as an isolated candidate.
3. A scripting layer only if measurements require it. Candidates for a later spike are Lua 5.4 or Luau, then QuickJS. None is adopted.

Planned interface (not scheduled):

Name	What it will do
behaviors (scenario section)	Attach behaviors to entities with typed parameters, for example a door that opens when something enters a trigger.
simengine.event.emit	Raise a named, typed event. Events are recorded in the trace.
simengine.timer.start	Fire an event after a duration in simulation time.
expect on events	Assert that an event happened, with its payload, before or after a tick.

Input

Planned, not scheduled. Input is a core facility in the engine’s requirements. The reference game’s flight controls (SIM-033) are application code on top of it.

For agents, input must be testable without a person at the keyboard:

Name	What it will do
simengine.input.define_action	Declare a named action (button or axis) the game reads.
simengine.input.bind	Bind keyboard, mouse or gamepad controls to actions, in versioned data.
input (scenario section)	A scripted timeline of action values per tick, so a headless run can play the game.
Input recording	Record a human play session as the same timeline, then replay it as a regression test.

Physics

In progress (M2). Local rigid bodies, contacts and constraints (SIM-014) are being integrated through an experimental adapter. It is off by default and needs two explicit build flags; Jolt is evaluated, not adopted. Its first bounds are 128 bodies and a 1/60 s step. A non-space physics sandbox validates it on the shared core (SIM-070). The optional point_mass module (velocity and gravity, no collisions) is available today.

Name	What it will do
physics.body / physics.collider (components)	Dynamic, kinematic or static bodies with box, sphere, capsule or mesh colliders and materials.
simengine.physics.apply_impulse / set_velocity	Push and steer bodies (today: point_mass.*).
simengine.physics.raycast / simengine.physics.overlap	Spatial queries with typed hits.
Contact and trigger events	Recorded in the trace, usable in expectations (“the ball hit the floor before tick 90”).
Joints	Fixed, hinge and slider constraints.

Rendering and cameras

Available. A forward PBR path with constant-factor metallic-roughness materials, one sun, constant ambient and manual exposure, rendered offscreen with simengine_capture (reverse-Z, 2560 x 1440 by default). A black, empty or background-only frame is a failure (exit 12).

In progress and planned (M4, M5). Textured assets (SIM-030), detailed PBR assets and a quality reference (SIM-040), lighting, shadows and reflections (SIM-041), clouds, dust and particle effects (SIM-043), temporal reconstruction (SIM-044) and visibility and draw scheduling (SIM-045). Atmosphere from ground to orbit is an optional spatial module (SIM-042).

Name	What it will do
render.camera (component)	Cameras as entities: projection, exposure, the camera a capture uses. Planned, not scheduled.
render.light (component)	Directional, point and spot lights with units (lux, lumens).
render.material (component)	Textured PBR materials referenced from cooked assets.
simengine_capture --camera ID	Capture from any camera in the scene, at any tick of a run.

Assets

Available. Offline cooking of a strict static glTF/GLB subset with constant materials into .seasset, with validation and provenance (ADR 0014). simengine_capture --check-scene validates scenes and assets without a GPU.

In progress (M4, SIM-030). The full import, cooking and validation path, including textures.

Planned, not scheduled. Skinned meshes and animation clips from glTF, and audio clips, through the same validated, versioned path.

Animation

Planned, not scheduled. Transform and skeletal animation imported from glTF, with blending and animation events.

Name	What it will do
anim.player (component)	Plays clips on an entity or skeleton.
simengine.anim.play / simengine.anim.stop	Start or stop a clip, with blend time.
simengine.anim.set_weight	Blend between clips.
Animation events and pose expectations	“The jump clip reached its landing frame by tick 40.”

Audio

Planned (M4, SIM-036). Minimal spatial audio and event feedback.

Name	What it will do
audio.source / audio.listener (components)	Positioned sounds and the listener.
simengine.audio.play / simengine.audio.stop	Trigger sounds from commands or behaviors.
Audio events in the trace	Headless runs record which sound played, when and where, so an agent can verify sound without hearing it.

Saves and checkpoints

Planned (M4, SIM-034). Versioned saves, player deltas and crash-safe checkpoints. Saves are engine-owned versioned data, never code memory, with explicit migrations.

Name	What it will do
simengine.save.write / simengine.save.load	Write and restore a save with its schema version.
Save expectations	“Loading this save restores the same state digest.”

Navigation

Planned, not scheduled. Navigation meshes built from static geometry, path queries and simple steering, for characters that move on their own.

Name	What it will do
simengine.nav.bake	Build a navigation mesh from tagged static geometry, offline and versioned.
simengine.nav.find_path	Return a path between two points with typed failures (unreachable, outside mesh).

Building and shipping a game

Planned (M7, SIM-065). A reproducible open-source engine package and a documented way for an independent application to consume it.

Planned, not scheduled. A player build of your game: one command that packages your application, cooked assets and the runtime into a build that runs without the development tools.

Name	What it will do
simengine_package	Produce a player build for a declared platform, with a manifest of every file and its provenance.

Platforms

Available. Windows 11 x64 with a Vulkan 1.3 GPU is the first runtime target. Linux runs the headless toolchain, tests and CI.

Later. Other platforms, each only with an accepted decision and a hardware contract.

Multiplayer

Later (M8). Networking is deferred until a concrete use case justifies it.

Not planned

• A visual editor or visual scripting. SimEngine is driven from text and commands; that is the point.
• An LLM inside the runtime. Development is LLM-driven; the shipped game is not.
• An in-engine UI designer. Nothing in SimEngine requires clicking through a tool.