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 SimEngine can do today (and what it cannot)

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.

Cannot (do not promise or attempt it): a window or interactive camera, keyboard/mouse input, physics, collisions or contacts, audio, a game loop, textures or normal maps, glTF import, local lights or shadows. Motion without the optional point_mass module is a sequence of scheduled teleports.

Before you start

You need a built SimEngine checkout. 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.

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

shellCopy"$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).

shellCopypython3 "$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.

shellCopypython3 "$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/.

shellCopypython3 "$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).

shellCopypython3 "$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=<id> 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.