# SimEngine > SimEngine is a pre-release, general-purpose C++20 / Vulkan 1.3 game engine built for coding agents. Agents drive it from the command line: typed commands, seeded headless scenarios, offscreen captures and one JSON document per command. No LLM in the runtime. MIT license; the repository opens with the first distributable milestone. Repository: https://github.com/romainsimon/SimEngine (private until the first distributable milestone; if cloning fails, stop and tell the user they need access). There is no hosted API, no API key and no MCP server: SimEngine is a set of local executables. Any agent that can run a shell command and read JSON can use it. Main includes textured static assets, the native SDK, input, directional shadows, MSAA and opt-in calibrated SDR output. The engine increments merged in PR #8; the external Relay Yard playable preview and its Windows player package passed separate independent review. These do not add host scenario commands; general rigid-body gameplay, audio and supported production distribution remain open. Repositories are still private. ## Start here - [Agent guide](https://indiega.me/simengine/agent-guide.md): setup, the agent loop, implementation contract, scenario format, run artifacts, session protocol, skills and exit codes. - [Copy-ready agent prompt](https://indiega.me/simengine/agent-prompt.txt): set up the engine, create a first scene, change it and prove the change. - [CLI reference](https://indiega.me/simengine/cli.md): every command and option of simengine_host, simengine_capture, simengine_desktop and the example driver. - [Planned interface](https://indiega.me/simengine/planned.md): every game-engine area with its status and the commands planned for it. NOTHING marked planned exists yet: call only what `--capabilities` lists. - [Full context](https://indiega.me/simengine/llms-full.txt): all of the above in one document. ## Skills - [simengine-create-project](https://indiega.me/simengine/skills/simengine-create-project/SKILL.md) - [simengine-modify-scene](https://indiega.me/simengine/skills/simengine-modify-scene/SKILL.md) - [simengine-run-capture-diagnose](https://indiega.me/simengine/skills/simengine-run-capture-diagnose/SKILL.md) ## Examples - [first_scene scenario](https://indiega.me/simengine/examples/first_scene/scenario.json): the reference scenario (schema simengine.scenario v1). ## Pages - [SimEngine](https://indiega.me/simengine): spec sheet, architecture, scale, roadmap. - [AI game engine](https://indiega.me/ai-game-engine): what an AI game engine is, comparison with Unity, Unreal and Godot, FAQ. - [Docs](https://indiega.me/simengine/docs): the human-readable version of these files, one page per document (agent guide, CLI reference, skills). - [Why we built SimEngine](https://indiega.me/blog/why-we-built-simengine) --- # SimEngine agent guide > Use this guide when a coding agent (Claude Code, Codex, Cursor, Copilot, Gemini CLI or any agent with a shell) builds, runs or changes a SimEngine project. It is written for agents first and humans second. Last updated: 2026-10-31. Engine state: private pre-release; M1/M2 foundations and a reviewed playable native preview. ## Read this first - **SimEngine is a local C++20 / Vulkan 1.3 game engine driven from the command line.** There is no hosted API, no API key, no account and no MCP server. Every tool is a local executable that prints one JSON document per command. - **The repository is [github.com/romainsimon/SimEngine](https://github.com/romainsimon/SimEngine), and it is not public yet.** It opens with the first distributable milestone (MIT license). Until then, this guide documents the interface so you can evaluate it; you can only run it with access to the repository. - **This is a private developer preview.** Main includes seeded headless scenarios, Vulkan capture, a Windows playground, textured static glTF/GLB cooking and the native SDK accepted in [PR #8](https://github.com/romainsimon/SimEngine/pull/8). The reviewed external Relay Yard preview exercises a small playable puzzle, input, orbit camera, opaque HUD, directional shadows and an application-specific save/package. MSAA and opt-in calibrated SDR output/filtering are implemented; bounded local-shadow quality merged in [PR #9](https://github.com/romainsimon/SimEngine/pull/9). Environment lighting is in development. Rigid-body physics on Jolt is available in the C++ game layer, not yet as scenario commands. These are not a supported production release. Audio, terrain and orbital propagation remain open. - **The runtime never calls an LLM.** You drive development; the engine never waits for you. ## How you work with SimEngine The loop the engine is optimized for. Every step is a command you run and a document you parse. 1. **Discover**: `simengine_host --capabilities` prints the scenario schema, units, frames, the components and commands of exactly the compiled-in modules, limits, the determinism scope, every exit and error code, and an example scenario valid for this build. Read it instead of guessing from documentation. 2. **Author**: edit versioned text. A scenario (`simengine.scenario`, version 1) declares a seed, a tick schedule, entities, scheduled commands and expectations. Every position states its value, unit and frame. 3. **Run headless**: `simengine_host --run scenario.json --out RUN_DIR` loads, steps and checks expectations, then writes the result and artifacts. 4. **See**: `simengine_capture --scene scene.sescene --out-dir CAPTURE_DIR` renders offscreen through Vulkan and writes a PNG plus a manifest. A black, empty or background-only image is a failure (exit 12), never a pass. 5. **Verify**: check independently specified expectations, intermediate states and captures. A gameplay change may change `final_state_sha256`; a refactor should normally preserve it, and a presentation change can preserve simulation state while changing pixels. A changed hash, a successful compile or one surviving tick is not acceptance. ## Setup Clone the engine next to (not inside) your projects, then read `AGENTS.md` first: ```sh git clone https://github.com/romainsimon/SimEngine.git cd SimEngine ``` If the clone fails with `Repository not found` or asks for credentials, the repository is still private and you do not have access: stop and report it. Do not search for mirrors or copies. Then use the maintained, rerunnable setup scripts that humans and CI also use: - **Linux**: `./tools/setup.sh --install-missing` detects the environment, installs only missing recorded prerequisites (Ubuntu/Debian), configures and builds the `linux-release` preset, runs the test suite and the host smoke check. - **Windows 11**: install Visual Studio 2022 (C++ x64), CMake 3.28+, Ninja and Python 3.12+, then run `tools/setup.ps1`. No Vulkan SDK is needed: the pinned Khronos headers are fetched and the loader is opened at run time. Expect zero failures among the selected CTest tests; report skips separately. The final smoke check prints one JSON summary naming the Vulkan device, or a structured `BLOCKED` outcome on a machine without a Vulkan 1.3 driver. Report failures verbatim with the exit code. Do not work around a failure silently. ## Implementation contract 1. **Start from capabilities.** Run `--capabilities` before writing a scenario. Use only the commands, components and modules it lists; a disabled module's commands do not exist and are rejected. 2. **Keep your project outside the engine checkout.** Never edit engine sources, tests or `examples/` to get a pass. 3. **Be explicit.** Positions are `{ "value": [x, y, z], "unit": "m", "frame": "world" }`. Frames are right-handed, `+y` up. Durations are nanoseconds (`"unit": "ns"`). 4. **Validate before you run.** `--load FILE` validates all-or-nothing and prints the initial state; `simengine_capture --check-scene FILE` validates a scene without a GPU. 5. **Use new or empty output directories.** Existing content is never overwritten. 6. **Classify outcomes by exit code, then by `error.code`.** Do not parse stderr prose. Diagnostics on stderr are JSON Lines (`simengine.diagnostic`, version 1). 7. **Do not retry blindly.** A failed expectation (exit 12) is a result, not a flake: read which expectation failed and why. Timeouts (exit 11) mean your `--max-wall-ms` bound was reached. 8. **Missing GPU is BLOCKED, not PASS.** Exit codes 3 to 5 mean no usable Vulkan device. Report `BLOCKED_ENVIRONMENT`; never fake a capture. 9. **Report evidence.** Finish with the commands run, exit codes, `final_state_sha256` values, PNG paths and what SimEngine could not do. ## Scenario format (simengine.scenario v1) This is the scenario of the `first_scene` example, abridged: ```json { "schema": "simengine.scenario", "schema_version": 1, "name": "first_scene", "seed": 20261027, "time": { "tick_duration": { "value": 16666667, "unit": "ns" }, "ticks": 120 }, "frame": { "id": "world", "kind": "cartesian", "handedness": "right", "up_axis": "+y" }, "entities": [ { "id": "table", "position": { "value": [0, 0, -1], "unit": "m", "frame": "world" } }, { "id": "ball", "position": { "value": [2, 0.25, 1.5], "unit": "m", "frame": "world" } } ], "generators": [ { "kind": "scatter_box", "id_prefix": "barrel_", "count": 3, "min": { "value": [1.5, 0, -3.5], "unit": "m", "frame": "world" }, "max": { "value": [3.5, 0, -2], "unit": "m", "frame": "world" } } ], "commands": [ { "at_tick": 60, "command": "simengine.entity.set_position", "version": 1, "args": { "entity": "ball", "position": { "value": [0.25, 1, -1], "unit": "m", "frame": "world" } } } ], "expect": [ { "name": "ball_on_table", "entity": "ball", "quantity": "position", "value": { "value": [0.25, 1, -1], "unit": "m", "frame": "world" }, "tolerance": { "value": 0, "unit": "m" } } ] } ``` The full file is at `/simengine/examples/first_scene/scenario.json`. Without the optional `point_mass` module, motion is a sequence of scheduled teleports; with it (`-DSIMENGINE_MODULES=point_mass`), entities gain `point_mass.body` (velocity) and the scene `point_mass.world` (gravity), with the commands `point_mass.apply_impulse` and `point_mass.set_velocity`. Always confirm with `--capabilities`. ## Run artifacts `simengine_host --run FILE --out DIR` writes into DIR: - `scenario.json`: a byte copy of the input - `initial_state.json` and `final_state.json` (`simengine.scene_state`); the result carries the SHA-256 of the final state - `trace.jsonl` when `--trace-every N` is set - `result.json`: the same `simengine.host.result` document printed to stdout Two runs of the same scenario on the same build and configuration give the same `final_state_sha256`. Cross-platform bitwise determinism is not promised. ## Interactive control: --session `simengine_host --session [--max-wall-ms MS]` reads JSON Lines requests on stdin and writes one `simengine.session.response` per request on stdout. Operations: `load`, `step`, `inspect`, `command` (with dry run and an expected state version), `expectations`, `capabilities` and `quit`. Use it when you need to step and inspect without re-running a whole scenario. ## The first_scene example and its skills `examples/first_scene` is the reference project. Its driver `first_scene.py` calls only the public tools, in separate processes, and verifies what they write: - `python first_scene.py new DEST` creates a project (and copies the three skills into `DEST/.claude/skills`) - `python first_scene.py check --project P --build B` validates engine compatibility, scene and scenario without a GPU - `python first_scene.py run --project P --build B` runs the full journey: load, run twice, capture, verify, manifest - `python first_scene.py verify [MANIFEST]` re-verifies a finished journey from its files Expected outcome for an unchanged project: `PASS`, 3 of 3 expectations, three PNG captures and a `manifest.json`. The driver stops with `incompatible_engine` (exit 21) if the engine reports interface versions the skills were not written for. Agent skills (load them; they are the procedures this guide summarizes): - [simengine-create-project](/simengine/skills/simengine-create-project/SKILL.md): create, check, run and verify a project - [simengine-modify-scene](/simengine/skills/simengine-modify-scene/SKILL.md): add an object, move it, add an expectation, prove the change - [simengine-run-capture-diagnose](/simengine/skills/simengine-run-capture-diagnose/SKILL.md): run, capture, and diagnose failures by exit code ## Exit codes `simengine_host` (also in the JSON `exit_code`; `error.code` names the failure): | Code | Name | Meaning | | --- | --- | --- | | 0 | ok | Success | | 1 | internal_error | Unexpected exception inside the host | | 2 | usage_error | Invalid command line | | 3 | vulkan_loader_unavailable | No Vulkan loader library on this machine | | 4 | vulkan_driver_unavailable | Loader present, no driver supporting Vulkan 1.3 | | 5 | no_vulkan_device | Instance created, zero physical devices | | 6 | no_suitable_device | Devices exist, none meets the requirements | | 7 | backend_initialization_failed | Other instance or device creation failure | | 8 | validation_errors | Backend opened, the validation layer reported errors | | 9 | runtime_self_check_failed | Backend fine, core runtime self-check failed | | 10 | scenario_invalid | Validation failed; nothing ran | | 11 | scenario_timeout | The wall-time bound stopped the run or session | | 12 | scenario_expectation_failed | Run completed, an expectation failed | | 13 | scenario_io_error | Input unreadable or output directory unusable | | 14 | simulation_fault | A tick produced non-finite state (rolled back) | | 15 | module_startup_failed | Optional modules could not be initialized | Codes 3 to 5 all mean "no usable Vulkan device". A process killed by a signal prints no document; your supervisor must classify it as a crash. Capture exit codes are in the [CLI reference](/simengine/cli.md). ## What not to do - Do not invent commands, flags, components or modules. If `--capabilities` does not list it, it does not exist in this build. - Do not edit engine code, tests or examples to make a check pass. - Do not treat "it compiled" or exit 0 from a partial step as done. - Do not fake or reuse a capture when the GPU is unavailable. - Do not add an LLM call, network call or API key to a game or to the runtime. - Do not invent scenario commands for native SDK features. Discover the host CLI with `--capabilities`; for the SDK preview use its installed headers, contract and external-game README. General rigid-body gameplay and audio are not supported by this scenario interface. ## Links - [llms.txt](/simengine/llms.txt) and [full context](/simengine/llms-full.txt) - [CLI reference](/simengine/cli.md) - [Planned interface](/simengine/planned.md): where every game-engine area stands and the commands planned for it. Planned items do not exist yet; call only what `--capabilities` lists. - [Copy-ready agent prompt](/simengine/agent-prompt.txt) - [What SimEngine is](https://indiega.me/simengine) and [why it is an AI game engine](https://indiega.me/ai-game-engine) --- # SimEngine CLI reference > The complete command-line interface of SimEngine's public tools, taken from their `--help` text. Every command except `--help` and `--session` prints exactly one JSON document to stdout, including on failure. Diagnostics go to stderr as JSON Lines (`simengine.diagnostic`, version 1). Last updated: 2026-10-29 (pre-release build `0.0.0-dev`). ## simengine_host The runtime host: build and device report, and the headless scenario runner. ```text simengine_host --report [--no-validation] [--device INDEX] simengine_host --version simengine_host --help simengine_host --capabilities simengine_host --load FILE simengine_host --run FILE --out DIR [--ticks N] [--max-wall-ms MS] [--trace-every N] simengine_host --session [--max-wall-ms MS] ``` | Command | What it does | | --- | --- | | `--report` | Opens the Vulkan backend headless (no window), prints one JSON report of build, settings, device and a core runtime self-check (clocks, jobs, handles, telemetry), then shuts down. `runtime.modules` lists the build-selected modules. | | `--version` | Prints build identity as JSON without touching Vulkan. | | `--capabilities` | Prints the machine-readable capability document: scenario schema, units, frames, components, commands, limits, exit codes and an example scenario valid for this build's modules. No Vulkan. | | `--load FILE` | Validates a scenario (all-or-nothing) and prints its initial state. No Vulkan. | | `--run FILE --out DIR` | Loads, steps and checks expectations. DIR must be new or empty. `--ticks` overrides the scenario's run length, `--max-wall-ms` bounds the run (default 30000), `--trace-every N` records a state digest every N ticks. | | `--session` | JSON Lines control on stdin/stdout: `load`, `step`, `inspect`, `command` (dry run, expected state version), `expectations`, `capabilities`, `quit`. Bounded by `--max-wall-ms`. | Options for `--report`: `--no-validation` (do not enable `VK_LAYER_KHRONOS_validation`), `--device INDEX` (physical device by enumeration index; default selection is discrete, then integrated, virtual, CPU), `--inject-fault invalid-queue-priority` (negative control: with validation enabled the run must end with exit 8). Environment: `SIMENGINE_VULKAN_LOADER` sets an explicit Vulkan loader path (diagnostic override). ### Exit codes | Code | Name | Meaning | | --- | --- | --- | | 0 | ok | Success | | 1 | internal_error | Unexpected exception inside the host | | 2 | usage_error | Invalid command line | | 3 | vulkan_loader_unavailable | No Vulkan loader library on this machine | | 4 | vulkan_driver_unavailable | Loader present, no driver supporting Vulkan 1.3 | | 5 | no_vulkan_device | Instance created, zero physical devices | | 6 | no_suitable_device | Devices exist, none meets the requirements | | 7 | backend_initialization_failed | Other instance or device creation failure | | 8 | validation_errors | Backend opened, the validation layer reported errors | | 9 | runtime_self_check_failed | Backend fine, core runtime self-check failed | | 10 | scenario_invalid | Validation failed; nothing ran | | 11 | scenario_timeout | The wall-time bound stopped the run or session | | 12 | scenario_expectation_failed | Run completed, an expectation failed | | 13 | scenario_io_error | Input unreadable or output directory unusable | | 14 | simulation_fault | A tick produced non-finite state (rolled back) | | 15 | module_startup_failed | Optional modules could not be initialized | A process killed by a signal (crash) prints no document; supervisors classify it. ## simengine_capture Offscreen render and capture with the forward PBR path. ```text simengine_capture --scene FILE --out-dir DIR [options] simengine_capture --check-scene FILE simengine_capture --version simengine_capture --help ``` | Command | What it does | | --- | --- | | `--scene FILE` | Loads a `.sescene` file and its `.seasset` files, renders offscreen, writes `DIR/.png` and `DIR/.capture.json`, prints the manifest (`simengine.capture.manifest`, version 1). | | `--check-scene FILE` | Validates the scene and its assets only (units, axes, PBR subset, provenance, geometry). No Vulkan. Prints the manifest. | Options for `--scene`: `--out-dir DIR` (required, created if missing), `--width N --height N` (default 2560 x 1440), `--warmup N` (timed warm-up frames excluded from steady statistics, default 3), `--frames N` (measured steady frames, default 30), `--label TEXT` (free-form machine label recorded in the manifest, not verified), `--no-validation`, `--no-sync-validation`, `--device INDEX`, `--inject-fault skip-layout-barrier|black-output` (negative controls: exit 8 and exit 12 respectively). ### Exit codes | Code | Name | Meaning | | --- | --- | --- | | 0 | ok | Success | | 1 | internal_error | Unexpected exception | | 2 | usage_error | Invalid command line | | 3 | vulkan_loader_unavailable | No Vulkan loader library on this machine | | 4 | vulkan_driver_unavailable | Loader present, no driver supporting Vulkan 1.3 | | 5 | no_vulkan_device | Instance created, zero physical devices | | 6 | no_suitable_device | Devices exist, none meets the requirements | | 7 | backend_initialization_failed | Other instance or device creation failure | | 8 | validation_errors | Rendered, but the validation layer reported errors | | 10 | scene_invalid | Scene or asset rejected by the import path | | 11 | render_failed | A Vulkan call failed or the device lacks a format | | 12 | capture_content_invalid | The image is black, empty or background-only | | 13 | output_write_failed | The PNG or manifest could not be written | ## simengine_desktop (Windows only) A scene playground using the same persistent renderer: explore a generic PBR scene, select and move objects, save snapshots that `simengine_capture` reproduces. It is not a game-authoring API. ```text simengine_desktop --scene FILE [--out DIR] [--width N] [--height N] ``` `--out` must be new or empty; omitting it disables saved captures. `--width`/`--height` set the internal render resolution (default 1280 x 720). Requires Vulkan 1.3, one graphics/present queue, SRGB blit support and `VK_EXT_swapchain_maintenance1`; failures are explicit JSON. Controls: W/A/S/D and Q/E move the camera, right-drag looks, Tab selects an object, arrows and Page Up/Down move it in metres, Space pauses, R resets, F12 saves a PNG and a replayable `.sescene`, Escape exits. There is no collision response. ## first_scene.py (example driver) ```text python first_scene.py new DEST [--name NAME] [--no-skills] python first_scene.py check [--project P] [--build B | --host H --capture C] [--scenario S] python first_scene.py run [--project P] [--build B | --host H --capture C] [--scenario S] [--out DIR] [--timeout SEC] [--label TEXT] [--skip-capture] python first_scene.py verify [MANIFEST] [--project P] [--scenario S] [--expect-outcome PASS|FAIL|BLOCKED_ENVIRONMENT] ``` `run` executes the full journey (load, run twice, pose, capture, verify, manifest). With `--skip-capture` the render check is `NOT_RUN`, never `PASS`. The driver exits 21 (`incompatible_engine`) when the engine's interface versions differ from the ones its skills were written for. --- # Copy-ready agent prompt ```text Set up SimEngine and build my first verified scene with it. Read https://indiega.me/simengine/llms.txt and https://indiega.me/simengine/agent-guide.md first, then AGENTS.md in the SimEngine checkout. Get the checkout with git clone https://github.com/romainsimon/SimEngine.git (keep it outside my project). The repository is private until the first distributable milestone: if the clone fails with "Repository not found" or asks for credentials, stop and tell me I need access, do not look for copies elsewhere. SimEngine is a local C++20 / Vulkan 1.3 engine driven from the command line: there is no hosted API, no API key and no MCP server. Every tool prints one JSON document per command; classify results by exit code, then by error.code. 1. Setup. On Linux run ./tools/setup.sh --install-missing; on Windows 11 (Visual Studio 2022 C++ x64, CMake 3.28+, Ninja, Python 3.12+) run tools/setup.ps1. Expect zero failures among the selected CTest tests and report skips separately. Show me the smoke summary JSON naming my Vulkan device, or the structured BLOCKED outcome. 2. Discover. Run simengine_host --capabilities and tell me the scenario schema version, the commands, components and modules this build has. Use nothing that is not listed. 3. Create. Follow the simengine-create-project skill (https://indiega.me/simengine/skills/simengine-create-project/SKILL.md): create my project OUTSIDE the engine checkout, check it, run it and verify it. Expect PASS, 3 of 3 expectations, three PNG captures and a manifest.json. 4. Change. Follow the simengine-modify-scene skill: add one object, move it with a scheduled command, add an expectation for where it ends, then check, run and verify again. Prove the change: the new final_state_sha256 differs, the new expectation passed and the new capture shows the object. 5. On failure, follow simengine-run-capture-diagnose: report the exit code, failure.code, failure.step and failure.message verbatim, fix only my project files, and say plainly if the render is BLOCKED_ENVIRONMENT (no Vulkan device). Never edit engine sources, tests or examples to get a pass, and never fake a capture. SimEngine is pre-release. This workflow covers headless scenarios and captures, not general gameplay authoring. Textured static assets and a separate native SDK are implemented; the reviewed external Relay Yard preview exercises input, a game loop and directional shadows. Do not infer scenario commands from those native features. General rigid-body gameplay and audio remain unavailable here. Finish with a short report: commands run, exit codes, digests, PNG paths, and what SimEngine could not do. For refactors preserve expected state; presentation changes can change pixels without changing the simulation digest. ``` --- # Skill: simengine-create-project --- name: simengine-create-project description: Create a new SimEngine project (a scene, a scenario and a project.json) from the first_scene example, check it against the engine build, run it headless, capture it offscreen to PNG and verify the result. Use when the user asks to start, create or scaffold a SimEngine scene, project or "first game", or to check that their SimEngine build can run one. --- # Create a SimEngine project This skill ships with the SimEngine `first_scene` example. It drives only SimEngine's public tools: the `simengine_host` scenario CLI, the `simengine_capture` offscreen renderer and the example driver `examples/first_scene/first_scene.py`, which calls those two executables in separate processes and verifies what they write. ## Compatible versions Written for, and verified against, a SimEngine build that reports: | Interface | Version | Where it is reported | | --- | --- | --- | | Scenario schema `simengine.scenario` | `schema_version` 1 | `simengine_host --capabilities` → `capabilities.scenario_schema.schema_version` | | Capability document `simengine.capabilities` | 1 | `capabilities.schema_version` | | Scene state `simengine.scene_state` | 1 | `capabilities.state_schema.schema_version` | | Simulation (module extension) contract | 1 | `capabilities.simulation_contract_version` | | Module contract | 1 | `simengine_host --report` → `runtime.modules.registry.contract_version` | | Scene / asset text formats | `simengine_scene 1`, `simengine_asset 1` | first line of `.sescene` / `.seasset` files | | Capture manifest `simengine.capture.manifest` | 1 | `simengine_capture --version` | | Example driver / project file | driver 1, `simengine.example_project` 1 | `first_scene.py`, `project.json` | The driver checks every one of these before it runs anything and stops with `incompatible_engine` (exit 21) on a mismatch. Do not work around that: the skill is out of date for that engine. ## What this scenario workflow supports Can: run a deterministic, seeded, headless scenario of point entities in one Cartesian frame (positions in meters, yaw orientations, scheduled `simengine.entity.set_position` commands, seeded `scatter_box` placement, end-of-run expectations), and render a static scene offscreen with a small PBR material subset to a PNG plus a JSON manifest. This driver does not expose gameplay input, rigid-body contacts, audio, a game loop, local lights or shadows. Motion without the optional `point_mass` module is a sequence of scheduled teleports. The separate desktop tool has an interactive camera; the offline cooker supports textured static glTF/GLB. A native SDK/Relay Yard candidate adds gameplay and directional shadows under review. Those capabilities do not add commands to this skill or to the host scenario schema. ## Before you start You need a built SimEngine checkout (`git clone https://github.com/romainsimon/SimEngine.git`; private until the first distributable milestone, so stop and report if you have no access). If `build/linux-release/apps/host/simengine_host` does not exist yet, run the setup script first (`./tools/setup.sh` on Linux, `tools/setup.ps1` on Windows) and report its result. The commands below use three variables. Shell tools often do not keep variables between calls: prefix each command with the assignments, or substitute absolute paths. ```text SIMENGINE_ROOT=/absolute/path/to/SimEngine # the checkout SIMENGINE_BUILD=$SIMENGINE_ROOT/build/linux-release # what tools/setup.sh builds PROJECT=/absolute/path/to/my_first_scene # a NEW directory, outside the checkout ``` Use `python` instead of `python3` where that is the Python 3 interpreter (Windows). ## Steps 1. Discover what this build can do. Read `capabilities.commands`, `capabilities.components` and `capabilities.modules`: a core-only build has one command (`simengine.entity.set_position`) and no components or modules. ```sh "$SIMENGINE_BUILD/apps/host/simengine_host" --capabilities > "$SIMENGINE_BUILD/capabilities.json" python3 -c "import json,sys; c=json.load(open(sys.argv[1]))['capabilities']; print('scenario schema', c['scenario_schema']['schema_version'], '| commands', [x['id'] for x in c['commands']], '| modules', [m['id'] for m in c['modules']])" "$SIMENGINE_BUILD/capabilities.json" ``` 2. Create the project. `new` copies the example scene, scenarios, assets and these skills (into `$PROJECT/.claude/skills/`) and prints one JSON line (`outcome`, `files`, `next`). ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" new "$PROJECT" ``` 3. Check it without a GPU: engine compatibility, scene import path, scenario validation. Expect `"outcome": "PASS"` and exit code 0. ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" check --project "$PROJECT" --build "$SIMENGINE_BUILD" ``` 4. Run the whole journey: two deterministic runs, the scene posed from the initial and final simulation states, three offscreen captures (two viewpoints), verification and `manifest.json` under `$PROJECT/runs/main-NNN/`. ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" run --project "$PROJECT" --build "$SIMENGINE_BUILD" ``` 5. Verify it independently from the files it wrote (hashes, PNG decode, sidecars). ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" verify --project "$PROJECT" ``` ## Verify what you produced Report these to the user, from the `run` and `verify` JSON lines, not from memory: - `outcome` is `PASS` and the exit code is 0 for `check`, `run` and `verify`; - `expectations`: 3 passed, 0 failed; `final_state_sha256` (64 hex characters); - `checks.deterministic_repeat` and `checks.motion_visible` are `PASS`; - three PNGs under `runs/main-NNN/captures/` (`initial-front`, `final-front`, `final-side`). Open `final-front` and look at it: a table with a red ball on it, two stacked crates, three barrels on a checkered ground. If the exit code is 77 (`BLOCKED_ENVIRONMENT`), the machine has no usable Vulkan device: the simulation was verified but nothing was rendered. Say so; it is not a pass. ## On failure The driver prints `failure.code`, `failure.step`, `failure.message` and a `failure.hint`. Quote them verbatim. Then: | Exit | `failure.code` | Do this | | --- | --- | --- | | 20 | `build_not_found` | Run the setup script, or pass the build directory that contains `apps/host` and `apps/capture`. | | 21 | `incompatible_engine` | Stop. Host and capture come from different builds, or the engine changed a version this skill was written for. Report it. | | 22 | `module_missing` | The scenario needs an optional module. Use a build configured with `-DSIMENGINE_MODULES=` or pick a core-only scenario. | | 23 | `scenario_invalid` | Use `simengine-modify-scene`: fix each `failure.detail.errors[]` entry at its JSON pointer `path`. | | 24 | `scene_invalid` | Fix the `.sescene`/`.seasset` line in `failure.detail` (`code`, `file`, `line`). | | 31 | `project_invalid` | `$PROJECT` already exists and is not empty, or `project.json` is malformed. Choose a new directory. | | other | see `simengine-run-capture-diagnose` | | Never edit engine sources, tests or the example's files under `$SIMENGINE_ROOT` to make a journey pass; change only the project. --- # Skill: simengine-modify-scene --- name: simengine-modify-scene description: Modify a SimEngine project made from the first_scene example — add, move or restyle objects in the scene, change the scripted motion (scheduled commands), seeds or expectations in the scenario, or switch to the point_mass behavior variant — then re-run, re-capture and prove the change with digests, expectations and images. Use when the user asks to add an entity or object, move something, animate it, change materials or the camera, or change a SimEngine scenario's behavior. --- # Modify a scene or behavior This skill ships with the SimEngine `first_scene` example and drives only public tools: `simengine_host` (scenario CLI), `simengine_capture` (offscreen render) and `examples/first_scene/first_scene.py` (the example driver). It assumes a project created with `simengine-create-project`. ## Compatible versions Scenario schema `simengine.scenario` **schema_version 1**; capability document 1; scene state 1; simulation contract 1; module contract 1; scene/asset text formats `simengine_scene 1` / `simengine_asset 1`; capture manifest 1; example driver 1 and `simengine.example_project` 1. The driver checks all of them (`incompatible_engine`, exit 21, on a mismatch). The authoritative field list is `simengine_host --capabilities` → `capabilities.scenario_schema`; the scene and asset formats are documented in `fixtures/README.md` of the SimEngine checkout. ## How a project fits together | File | Owns | Notes | | --- | --- | --- | | `scenario.json` | simulation: entities, seed, ticks, scheduled commands, expectations | validated all-or-nothing by `simengine_host --load` | | `scene.sescene` | presentation: which asset each object uses, material, scale, camera, sun | validated by `simengine_capture --check-scene` | | `project.json` | which scene and scenarios, viewpoints, capture size | read by the driver only | | `assets/*.seasset` | meshes and materials (text, meters, +Y up) | each file records its license and tool | The rule that binds them: **every scenario entity needs a scene instance with exactly the same name.** When the driver poses the scene, each such instance takes the entity's position and yaw from the simulation state; instances without an entity (the ground) stay where they are authored. Generated entities are named `id_prefix` + an index zero-padded to the width of `count - 1` (`barrel_0` … `barrel_2` for count 3, `crate_00` … for count 11 or more). Units and frame: meters, one Cartesian frame, right-handed, `up_axis "+y"` (the scene convention; the driver refuses any other). Orientations are quaternions `[x, y, z, w]` that must be pure yaw (rotation about +Y): `[0, sin(a/2), 0, cos(a/2)]`. Placement reference (asset origins): `crate` is a 0.5 m cube with its origin at the center of its base (on the ground: y = 0; on another crate: y = 0.5); `spheres` (mesh `sphere_r0p25`) has its origin at the center (on the ground: y = 0.25; on the table: y = 1.0); `barrel` (r 0.3 m, h 0.8 m) and `table` (top at y = 0.75 m, 1.2 m × 0.8 m) have their origin on the floor. Sphere materials: `dielectric_rough`, `dielectric_smooth`, `metal_rough`, `metal_smooth`. Motion in a core-only build is `simengine.entity.set_position` at a tick (a teleport, applied at the start of that tick, before systems, in document order). There is no velocity, interpolation, collision or rotation command. Expectations compare the state at the end of the run, component-wise, within `tolerance`. ## Variables ```text SIMENGINE_ROOT=/absolute/path/to/SimEngine SIMENGINE_BUILD=$SIMENGINE_ROOT/build/linux-release PROJECT=/absolute/path/to/my_first_scene ``` Prefix each command with them if your shell tool does not keep variables between calls. ## Steps 1. Record the baseline. Run it even if an earlier `run` already passed: step 5 compares against `runs/before.json`, which only this command writes (a `check` result has no digest or captures and is not a baseline). ```sh mkdir -p "$PROJECT/runs" python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" run --project "$PROJECT" --build "$SIMENGINE_BUILD" > "$PROJECT/runs/before.json" ``` 2. Make the change in both files. Worked example — add a third crate that starts on the ground and is stacked on top of the other two at tick 100: - `scenario.json`, append to `entities`: `{"id": "crate_c", "position": {"value": [-1.2, 0, 0.9], "unit": "m", "frame": "world"}}` - append to `commands`: `{"at_tick": 100, "command": "simengine.entity.set_position", "version": 1, "args": {"entity": "crate_c", "position": {"value": [-2, 1, -0.5], "unit": "m", "frame": "world"}}}` - append to `expect`: `{"name": "crate_c_on_top", "entity": "crate_c", "quantity": "position", "value": {"value": [-2, 1, -0.5], "unit": "m", "frame": "world"}, "tolerance": {"value": 0, "unit": "m"}}` - `scene.sescene`, after the other crates: `instance crate_c crate * position -1.2 0 0.9` Make these edits with your editor. The block below applies exactly the same edit (the example's automated test runs it): ```sh python3 - "$PROJECT" <<'EOF' import json, pathlib, sys project = pathlib.Path(sys.argv[1]) scenario_path = project / "scenario.json" scenario = json.loads(scenario_path.read_text(encoding="utf-8")) pos = lambda v: {"value": v, "unit": "m", "frame": "world"} scenario["entities"].append({"id": "crate_c", "position": pos([-1.2, 0, 0.9])}) scenario["commands"].append({"at_tick": 100, "command": "simengine.entity.set_position", "version": 1, "args": {"entity": "crate_c", "position": pos([-2, 1, -0.5])}}) scenario["expect"].append({"name": "crate_c_on_top", "entity": "crate_c", "quantity": "position", "value": pos([-2, 1, -0.5]), "tolerance": {"value": 0, "unit": "m"}}) scenario_path.write_text(json.dumps(scenario, indent=2) + "\n", encoding="utf-8") scene_path = project / "scene.sescene" lines = scene_path.read_text(encoding="utf-8").splitlines() at = max(i for i, line in enumerate(lines) if line.startswith("instance crate_")) lines.insert(at + 1, "instance crate_c crate * position -1.2 0 0.9") scene_path.write_text("\n".join(lines) + "\n", encoding="utf-8") EOF ``` 3. Check (no GPU). A mistake shows up here as `scenario_invalid` (23) with a JSON pointer per error, or `scene_invalid` (24) with file and line. Fix and repeat. ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" check --project "$PROJECT" --build "$SIMENGINE_BUILD" ``` 4. Run, capture and verify the changed project. ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" run --project "$PROJECT" --build "$SIMENGINE_BUILD" > "$PROJECT/runs/after.json" python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" verify --project "$PROJECT" ``` 5. Prove the change: the state digest changed, the new expectation is evaluated and passed, and the images exist. Then open the new `final-front` PNG and look at it. ```sh python3 - "$PROJECT/runs/before.json" "$PROJECT/runs/after.json" <<'EOF' import json, sys before, after = (json.load(open(p, encoding="utf-8")) for p in sys.argv[1:3]) assert before["outcome"] == "PASS" and after["outcome"] == "PASS", (before["failure"], after["failure"]) assert after["final_state_sha256"] != before["final_state_sha256"], "the simulation state did not change" assert after["expectations"]["failed"] == 0 and after["expectations"]["passed"] == before["expectations"]["passed"] + 1 print("changed:", before["final_state_sha256"][:12], "->", after["final_state_sha256"][:12], "| expectations", after["expectations"], "| images", [c["png"] for c in after["captures"]]) EOF ``` A presentation-only change (a material, the camera, `project.json` viewpoints) leaves `final_state_sha256` unchanged and changes the captured pixels (`pixels_sha256`); check that instead. ## Behavior with velocity and gravity: the `point_mass` variant `toss.scenario.json` tosses the ball under gravity with an impulse, using the optional `point_mass` test module (point kinematics, semi-implicit Euler; no collisions, so a body falls through the ground if you run long enough). It needs a build that compiles the module in; a core-only build stops with `module_missing` (22): ```text cmake --preset linux-release -B "$SIMENGINE_ROOT/build/linux-release-point_mass" -DSIMENGINE_MODULES=point_mass cmake --build "$SIMENGINE_ROOT/build/linux-release-point_mass" SIMENGINE_BUILD_POINT_MASS=$SIMENGINE_ROOT/build/linux-release-point_mass ``` ```sh point_mass python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" run --project "$PROJECT" --build "$SIMENGINE_BUILD_POINT_MASS" --scenario toss python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" verify --project "$PROJECT" --scenario toss ``` Its components and commands (`point_mass.body`, `point_mass.world`, `point_mass.apply_impulse`, `point_mass.set_velocity`) are listed by `--capabilities` of that build only. Expected values for its expectations follow the closed form of semi-implicit Euler: after n ticks of duration dt, v = v0 + n·g·dt and x = x0 + n·v0·dt + g·dt²·n(n+1)/2 (plus impulse/mass from the tick it is applied). ## On failure | Exit | `failure.code` | Do this | | --- | --- | --- | | 23 | `scenario_invalid` | For each `failure.detail.errors[]`: open the scenario at `line`/`column`, fix the field at `path` (`code` says what: `unit_mismatch`, `unknown_entity`, `unknown_command`, `unknown_component`, `non_normalized_orientation`, …; `expected`/`found` give the values). Nothing ran. | | 24 | `scene_invalid` | Fix the line in `failure.detail` (`code`, `file`, `line`): e.g. `unknown_mesh`, `syntax_error`, `invalid_scene`. | | 25 | `pose_mapping_failed` | Add the missing scene instances listed in `failure.detail.entities_without_instance` (same names), or fix a non-yaw orientation / non-`+y` frame. | | 27 | `expectation_failed` | Compare `failure.detail.failed[].expected` and `.actual`; fix whichever is wrong (the command or the expectation), never widen a tolerance just to pass. | | 22 | `module_missing` | Use the point_mass build or a core-only scenario. | | other | see `simengine-run-capture-diagnose` | | Change only the project's files. Never edit SimEngine sources, the example under `$SIMENGINE_ROOT/examples/`, or a tolerance to make a run pass. --- # Skill: simengine-run-capture-diagnose --- name: simengine-run-capture-diagnose description: Run a SimEngine project headless, capture it offscreen, read the structured results, and diagnose any failure from its documented exit code, error code and JSON pointer or file/line — using only the public simengine_host and simengine_capture tools, the run supervisor and the first_scene example driver. Use when the user asks to run, render, capture, screenshot, test or debug a SimEngine scene or scenario, or when a SimEngine command failed or exited non-zero. --- # Run, capture and diagnose This skill ships with the SimEngine `first_scene` example. It uses only public tools: `simengine_host` (headless scenario CLI), `simengine_capture` (offscreen render and PNG), `tools/run_scenario.py` (out-of-process run supervisor) and `examples/first_scene/first_scene.py` (the example driver that chains them and verifies what they write). ## Compatible versions Scenario schema `simengine.scenario` **schema_version 1**, capabilities 1, scene state 1, host result `simengine.host.result` 1, simulation contract 1, module contract 1, capture manifest `simengine.capture.manifest` 1, scene/asset formats 1, example driver 1 and `simengine.example_manifest` 1. Exit codes below are the ones those versions document (`simengine_host --help`, `simengine_capture --help`, `first_scene.py --help`). ## Variables ```text SIMENGINE_ROOT=/absolute/path/to/SimEngine SIMENGINE_BUILD=$SIMENGINE_ROOT/build/linux-release PROJECT=/absolute/path/to/my_first_scene ``` Prefix each command with them if your shell tool does not keep variables between calls. ## Run The full journey (two runs, posing, three captures, verification), then an independent re-verification from the files: ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" run --project "$PROJECT" --build "$SIMENGINE_BUILD" python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" verify --project "$PROJECT" ``` Simulation only (no GPU needed; the render check is reported `NOT_RUN`, never passed, and a later `verify` of that run reports `"render": "NOT_RUN"`): ```sh python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" run --project "$PROJECT" --build "$SIMENGINE_BUILD" --skip-capture ``` Each `run` prints one JSON line (`simengine.example_result`: `outcome`, `exit_code`, `failure`, `final_state_sha256`, `expectations`, `captures`, `checks`) and writes `$PROJECT/runs/-NNN/`: | Path | Content | | --- | --- | | `manifest.json` | The build/run/capture manifest: build identity and CMake settings, dependency graph, enabled and disabled modules with absence checks, every step (argv, exit code, wall time, peak RSS where the OS reports it), simulation digests and expectations, posing, captures, checks, warnings, `not_covered` | | `logs/NN-.stdout` / `.stderr` | each engine process's JSON result and its JSON Lines diagnostics | | `run-1/`, `run-2/` | `simengine_host --run` artifacts: `scenario.json`, `initial_state.json`, `final_state.json`, `trace.jsonl`, `result.json` | | `scenes/-.sescene` | the scene posed from a simulation state | | `captures/-/` | `.png` and `.capture.json` (device, timings, validation, content check) | Look at the PNGs yourself; a passing content check only means the image is not black or empty. ## Use the engine tools directly When you need more detail than the driver gives, call the same tools it calls. Each prints one JSON document on stdout (also on failure) and JSON Lines diagnostics on stderr. ```sh "$SIMENGINE_BUILD/apps/host/simengine_host" --load "$PROJECT/scenario.json" > "$PROJECT/runs/load.json" "$SIMENGINE_BUILD/apps/capture/simengine_capture" --check-scene "$PROJECT/scene.sescene" > "$PROJECT/runs/check-scene.json" python3 "$SIMENGINE_ROOT/tools/run_scenario.py" --host "$SIMENGINE_BUILD/apps/host/simengine_host" --scenario "$PROJECT/scenario.json" --out "$PROJECT/runs/supervised-$(date +%Y%m%d%H%M%S)" --timeout 60 ``` `run_scenario.py` classifies the outcome (`completed`, `invalid`, `timeout`, `expectation_failed`, `fault`, `crash`, `supervisor_timeout`, …) even when the host crashes. `simengine_host --run FILE --out NEW_DIR --trace-every 1` records a state digest per tick to find the first tick where two runs diverge. `simengine_host --report` shows the Vulkan device and the module registry. ## Diagnose: exit codes and what to do `first_scene.py` (`failure.code`; `failure.hint` repeats the action): | Exit | Code | Meaning → action | | --- | --- | --- | | 0 | — | Everything passed. Report digests, expectations and PNG paths. | | 1 | `internal_error` | Driver defect → keep the run directory, report it with the message. | | 2 | `usage_error` | Fix the command line (`first_scene.py --help`). | | 20 | `build_not_found` | Build first (`tools/setup.sh` / `tools/setup.ps1`), or fix `--build`. | | 21 | `incompatible_engine` | Different builds for host and capture, or a version this skill does not know → stop and report. | | 22 | `module_missing` | Scenario needs an optional module → build with `-DSIMENGINE_MODULES=` or use a core-only scenario. | | 23 | `scenario_invalid` | `failure.detail.errors[]`: fix each at its JSON pointer `path` (`line`, `column`, `expected`, `found`). Nothing ran. | | 24 | `scene_invalid` | Fix the scene/asset line in `failure.detail` (`code`, `file`, `line`). | | 25 | `pose_mapping_failed` | Entities without a same-named scene instance, a non-`+y` frame or a non-yaw orientation → fix the project. | | 26 | `run_failed` | `failure.detail.host_exit_code`: 11 timeout (fewer ticks or a larger `--timeout`), 13 I/O, 14 `simulation_fault` (non-finite state; rolled back), 15 module startup, negative = crash → report crashes. | | 27 | `expectation_failed` | Compare `failure.detail.failed[].expected` with `.actual`; fix the command or the expectation, never the tolerance alone. | | 28 | `nondeterministic` | Same build, same input, different digests: an engine defect → keep both run directories and report. | | 29 | `capture_failed` | `failure.detail.error.code`: `validation_errors` (8) or `render_failed` (11) → engine defect, report; `capture_content_invalid` (12) → the camera sees nothing, fix camera/target. | | 30 | `capture_check_failed` | PNG or manifest does not verify independently → report; do not regenerate silently. | | 31 | `project_invalid` | Malformed `project.json` or a non-empty `--out` directory. | | 77 | `blocked_environment` | No usable Vulkan 1.3 device (capture exit 3–6). Simulation verified; rendering `BLOCKED_ENVIRONMENT`, not passed. Install a GPU driver or Mesa lavapipe. | `simengine_host` exit codes (in `logs/*.stdout`, `error.code`): 2 `usage_error`, 10 `scenario_invalid`, 11 `scenario_timeout`, 12 `scenario_expectation_failed`, 13 `scenario_io_error` (input unreadable, or `--out` not new/empty), 14 `simulation_fault`, 15 `module_startup_failed`; 3–9 concern `--report` only. `simengine_capture` exit codes: 3–6 no usable Vulkan device, 7 `backend_initialization_failed`, 8 `validation_errors`, 10 `scene_invalid`, 11 `render_failed`, 12 `capture_content_invalid`, 13 `output_write_failed`. ## Diagnosis drill Practise the loop on a new, uniquely named copy: break one unit and see the located error. Keep that copy and its diagnostics for inspection; existing projects are preserved. ```sh DRILL=$(python3 - "$PROJECT" <<'EOF' import pathlib, shutil, sys, tempfile project = pathlib.Path(sys.argv[1]).resolve() drill = pathlib.Path(tempfile.mkdtemp(prefix=project.name + ".drill-", dir=project.parent)) shutil.copytree(project, drill, dirs_exist_ok=True, ignore=shutil.ignore_patterns("runs", ".git")) print(drill) EOF ) python3 - "$DRILL/scenario.json" <<'EOF' import json, sys path = sys.argv[1] scenario = json.load(open(path, encoding="utf-8")) scenario["entities"][0]["position"]["unit"] = "cm" # the schema accepts meters only json.dump(scenario, open(path, "w", encoding="utf-8"), indent=2) EOF set +e python3 "$SIMENGINE_ROOT/examples/first_scene/first_scene.py" check --project "$DRILL" --build "$SIMENGINE_BUILD" > "$DRILL/check.json" status=$? set -e python3 - "$DRILL/check.json" "$status" <<'EOF' import json, sys result = json.load(open(sys.argv[1], encoding="utf-8")) error = result["failure"]["detail"]["errors"][0] assert int(sys.argv[2]) == 23 and result["failure"]["code"] == "scenario_invalid", result["failure"] assert error["code"] == "unit_mismatch" and error["path"] == "/entities/0/position/unit", error print("diagnosed:", error["code"], "at", error["path"], "line", error["line"], "expected", error["expected"], "found", error["found"]) EOF printf 'Diagnosis files retained in %s\n' "$DRILL" ``` Report failures verbatim (code, step, message, the engine's own error object). Change only the project; never edit SimEngine sources, tests or tolerances to get a pass, and never describe a `BLOCKED_ENVIRONMENT` or `NOT_RUN` render as passed. --- # 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.