# 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-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](https://github.com/romainsimon/SimEngine/pull/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](https://github.com/romainsimon/SimEngine/blob/main/docs/adr/0019-prove-a-concrete-advantage.md)).** 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](https://github.com/romainsimon/SimEngine/blob/main/docs/audits/2026-11-10/README.md) 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](https://github.com/romainsimon/SimEngine/blob/main/docs/adr/0007-gameplay-authoring-model.md), 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](https://github.com/romainsimon/SimEngine/blob/main/docs/adr/0020-adopt-jolt-local-physics.md)), 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](https://github.com/mackron/miniaudio) ([ADR 0022](https://github.com/romainsimon/SimEngine/blob/main/docs/adr/0022-adopt-miniaudio.md)):
- `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." |

## 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

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