Docs /Reference

Planned interface

Everything a game needs, area by area: what works today, what is being built, and the commands planned for the rest. Docs before the engine.

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-11-04. Engine state: private pre-release, M1/M2 foundations and a reviewed playable preview.

Two interfaces, two scopes. Main includes textured static glTF/GLB assets and the native SDK accepted in PR #8, which is merged with green CI. The reviewed external Relay Yard preview is a three-level puzzle with input, orbit camera, opaque HUD, directional shadows, application saves and a Windows package. The engine also implements native MSAA (SIM-081) and native-resolution output with opt-in calibrated SDR color/filtering (SIM-082). These features do not add the speculative host commands below and are not a released product.

Delivery priorities (ADR 0019). SimEngine has to show a measured advantage over Godot, Unreal and hand-written C++ before it grows in scope. These are the steps so far, with what each one measured.

  1. A compact game layer (SIM-092/093), accepted. Window, frame loop, entities, glTF scenes, cameras, input and a character controller in a few lines.
    • Relay Yard rewritten on the layer takes 224 lines instead of 1,456.
    • The first-person courtyard walk takes 40 lines instead of 859.
  2. A scalable renderer data path (SIM-094), accepted. View culling, instancing and indirect draws.
    • With 100,000 moving spheres, SimEngine’s frame time is 1.6 to 2.4 times lower than Godot 4.7.2 (GDScript MultiMesh), on an RTX 4070 Ti.
  3. The HDR lighting tier (SIM-096 to SIM-100), on main and awaiting tracker review:
    • HDR with bloom and tone mapping;
    • image-based lighting from an HDR sky;
    • up to 256 clustered point and spot lights;
    • temporal anti-aliasing;
    • four-cascade sun shadows.
  4. A blind review against Godot and Unreal (SIM-101).
    • Method: three fixed scenes, with exposure matched on a gray card and labels shuffled.
    • Mean realism: SimEngine 2.3/5, Godot 3.3, Unreal 5.0 (Lumen with hardware ray tracing).
    • Daylight: SimEngine scores 4, like Godot.
    • Gaps: shadows for local lights, and global illumination.
  5. Agent tokens (SIM-095). Two pilot briefs, one attempt each. The crate puzzle used 21% more tokens than Godot for an equivalent game. The bouncing-balls toy, with physics, used 3.8× as many, mostly because SimEngine’s agent checked and fixed the toy headless. Rerun with the one-command build and a fuller reference, the same toy took 303,233 tokens ($0.24) in 9 turns: the same cost as Godot, 1.6× its tokens. The owner accepted all three games. One run is not a result; five briefs with three attempts each are next.

Now: a complete engine before better lighting. The owner set this order on 2026-11-04.

  • Physics: done in the game API on Jolt (SIM-105). On a 2,000-box pile it costs 5.7 ms per frame against 7.2 ms in Godot, also on Jolt.
  • Sound and saves: in the game API (SIM-106, SIM-108), described below.
  • Next: skeletal animation (SIM-107, in progress), then input, queries, UI and text, and packaging a game (SIM-110…114). The five-brief token comparison runs once its protocol is frozen. An audit on 2026-11-10 found no token advantage over Godot yet.
  • Later: shadows for local lights, ambient occlusion and global illumination (SIM-102 to SIM-104), which are specified but scheduled after these.

The first unfamiliar-agent experiment SIM-080 is closed as a reviewed experiment, including its failed structured-error step and the separately reviewed diagnostic correction. This does not establish a successful fresh installation or a complete unassisted onboarding journey. A supplementary GPT executor preflight still produced no observable tool execution, so cross-model productivity rankings remain unavailable. Opus-only observations do not establish an Opus-versus-GPT advantage.

Rules for agents

  • For the host scenario interface, use only what simengine_host --capabilities lists. Native SDK features are documented by the installed SDK headers and contracts; each application’s CLI has its own discovery. Do not infer host commands from SDK or application features.
  • 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 implemented on main in the stated interface. Preview, in review means a candidate, not accepted main. Confirm the exact build and interface before use.

Status legend

Status Meaning
Available Implemented on main in the stated interface; confirm the build’s CLI capabilities or native contract.
Preview, in review Implemented candidate awaiting integration; not an accepted main feature.
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 Reviewed native puzzle preview; general authoring planned SIM-079 done; ADR 0007
Input Available (bounded native actions/replay); general bindings planned SIM-079 done
Physics Available in the game layer on Jolt: bodies, joints, triggers, collision events; scenario commands planned SIM-014 done; SIM-105, SIM-070 (M2)
Rendering and cameras Available: HDR, image-based lighting, clustered lights, TAA, cascaded shadows; GI planned SIM-094 done; SIM-096 to SIM-104; SIM-040 to SIM-045 (M5)
Assets Available (textured static glTF/GLB subset), full pipeline in progress SIM-030 (M4)
Animation In progress: skeletal clips from glTF, GPU skinning SIM-107
Audio Available in the game layer: 3D voices, generated or decoded sounds, offline mix for checks SIM-106; SIM-036 (M4)
Saves and checkpoints Game saves in the game layer; engine-wide schema and checkpoints planned SIM-108; SIM-034 (M4)
Navigation Planned, not scheduled
Building and shipping a game Reviewed private SDK/player preview and limited onboarding experiment; fresh whole journey open SIM-079/080 done; 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).

Reviewed private preview (SIM-079). Relay Yard uses a native application loop with the same authoritative rules for windowed and scripted play. It is an external consumer, not a generic host gameplay framework.

Planned. General pause and time-scale controls in the host gameplay interface remain open beyond the native puzzle loop. 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

Reviewed private preview (SIM-079). Relay Yard implements discrete grid moves, blocked pushes, goals, three-level progression, restart and undo in native application C++. Rules stay outside the engine; this is not rigid-body physics or a general behavior graph.

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

Reviewed private preview (SIM-079). Public native action sampling/replay and Win32 keyboard/mouse input serve Relay Yard. Camera-relative movement, right-drag orbit, wheel zoom and reset are application controls. This does not supply gamepad support, a general binding editor or the proposed host commands below. The reference game’s flight controls (SIM-033) remain separate application work.

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

Available in the game layer (M2). Jolt Physics is the adopted local rigid-body library (ADR 0020), part of every build.

  • The engine service (SIM-014, accepted). Bounds are configurable and reported instead of fatal. Drop, stack, joint, CCD, 1:1000 mass-ratio and resource-exhaustion fixtures pass. The solver runs on worker threads with bit-identical results.
  • The game API (SIM-105). make_dynamic, make_kinematic and make_trigger take the shape from the mesh. Also: impulses and forces, bounce and friction, hinge (with motor), fixed and distance joints, and the collisions of each frame in f.hits(). Characters push crates and raycasts name the body hit. Eleven contract fixtures pass.
  • Measured against Godot (also Jolt):
    • a pile of 2,000 boxes costs 5.7 ms per frame against 7.2 ms;
    • SimEngine runs 30 solver iterations against Godot’s 10;
    • its pile takes 4.0 s to fall asleep against 1.3 s.
  • Still open:
    • characters standing on moving bodies;
    • compound shapes and rolling resistance;
    • the scenario-level commands below;
    • a non-space physics sandbox (SIM-070).
Name (scenario interface) 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. Forward metallic-roughness PBR with constant or textured materials (base color, metallic/roughness, normal and AO maps with offline mips), one sun, constant ambient and manual exposure. simengine_capture renders offscreen (reverse-Z, 2560 x 1440 by default). A black, empty or background-only frame is a failure (exit 12).

Available native preview (SIM-079/081/082/083). The persistent native renderer provides optional bounded directional shadows with reviewed contact/filtering/stability, opaque HUD rectangles and explicit 4x MSAA with unchanged engine 1x defaults. Native-resolution presentation, opt-in calibrated SDR tone mapping and anisotropic filtering are also accepted. Relay Yard exercises these native APIs; they are not new host components. GPU validation and scoped shadow timing/memory measurements exist. Available on main (SIM-096 to SIM-100):

  • an HDR target with bloom and tone mapping;
  • split-sum image-based lighting and a visible sky from an equirectangular HDR map;
  • up to 256 clustered point and spot lights, with no shadows yet;
  • temporal anti-aliasing with motion vectors;
  • four-cascade, texel-snapped sun shadows.

TAA and cascades are opt-in in games. There is no global illumination or ambient occlusion yet. In the SIM-101 blind review, these gaps put SimEngine at 2.3/5 against Unreal’s 5.0.

In progress and planned (M4, M5). Asset compression/streaming (SIM-030), detailed PBR assets and a quality reference (SIM-040), full lighting/shadows/reflections (SIM-041), clouds, dust and particle effects (SIM-043), temporal reconstruction (SIM-044) and visibility/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 into .seasset, including bounded PNG decoding, RGBA8 mip generation and textured PBR materials (ADRs 0014/0015). The native runtime reads cooked texels, not PNG files. simengine_capture --check-scene validates scenes and assets without a GPU.

In progress (M4, SIM-030). Compression, GPU-format fallbacks, streaming and full performance-profile acceptance remain open.

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

Animation

In progress (SIM-107). Skeletal clips imported from glTF, GPU skinning, and a game API to play, loop and cross-fade clips. Animation events come later.

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

Available in the game layer (SIM-106). Sound runs on miniaudio (ADR 0022):

  • app.sound(file) loads WAV, MP3 or FLAC, and app.sound(samples) takes generated audio, so an agent with no sound files can still make sounds;
  • app.play(sound, {volume, pitch, loop, at, follow}) plays a sound, in 3D at a point or on a moving entity, with the listener on the camera;
  • headless runs mix offline, frame by frame: --audio-out mix.wav saves the mix and --report gives levels and dropped voices, so an agent can check sound without hearing it;
  • the simulation is identical with sound on or off, and voices and memory are bounded.

Still planned: music streaming, effects such as reverb, SpaceSim feedback rules (SIM-036), and the scenario-level commands below.

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

Reviewed private preview (SIM-079). Relay Yard has versioned application saves, malformed-save rejection and save/resume regression checks. This does not implement generic scene persistence or the proposed commands below.

Available in the game layer (SIM-108). A Save holds a game’s own values and entity snapshots (transform, plus physics velocities). Writes are atomic, so a crash keeps the previous save; truncated, edited or newer files are rejected with a clear error. A physics scene reloaded mid-run stays within 0.24 mm of the uninterrupted run over 2 s.

Planned (M4, SIM-034). Engine-wide 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.”

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

Reviewed private preview (SIM-079). An installable native CMake SDK and Relay Yard’s relocatable Windows player exercise an external consumer without private headers or provider credentials. The preview is compiler/configuration specific, not a stable ABI. The first unfamiliar-agent experiment (SIM-080, reviewed and closed) completed a data-only puzzle change and relocation checks but failed its structured-error step. A subsequent diagnostic fix passed separate review; the original trial remains a recorded failure at that step, and a fresh trial is needed before claiming corrected onboarding succeeds unassisted. Repository publication remains an owner decision.

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.