[{"data":1,"prerenderedAt":18},["ShallowReactive",2],{"se-doc-cli":3},{"html":4,"toc":5},"\u003Cblockquote>\n\u003Cp>The complete command-line interface of SimEngine’s public tools, taken from their \u003Ccode>--help\u003C/code> text. Every command except \u003Ccode>--help\u003C/code> and \u003Ccode>--session\u003C/code> prints exactly one JSON document to stdout, including on failure. Diagnostics go to stderr as JSON Lines (\u003Ccode>simengine.diagnostic\u003C/code>, version 1).\u003C/p>\n\u003C/blockquote>\n\u003Cp>Last updated: 2026-10-29 (pre-release build \u003Ccode>0.0.0-dev\u003C/code>).\u003C/p>\n\u003Ch2 id=\"simengine-host\">simengine_host\u003C/h2>\n\u003Cp>The runtime host: build and device report, and the headless scenario runner.\u003C/p>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Cspan class=\"code__bar\">\u003Cspan class=\"code__lang\">text\u003C/span>\u003Cbutton type=\"button\" class=\"code__copy\" data-copy>Copy\u003C/button>\u003C/span>\u003Ccode>\u003Cspan class=\"tk-cmd\">simengine_host\u003C/span> \u003Cspan class=\"tk-flag\">--report\u003C/span> [\u003Cspan class=\"tk-flag\">--no-validation\u003C/span>] [\u003Cspan class=\"tk-flag\">--device\u003C/span> \u003Cspan class=\"tk-ph\">INDEX\u003C/span>]\n\u003Cspan class=\"tk-cmd\">simengine_host\u003C/span> \u003Cspan class=\"tk-flag\">--version\u003C/span>\n\u003Cspan class=\"tk-cmd\">simengine_host\u003C/span> \u003Cspan class=\"tk-flag\">--help\u003C/span>\n\u003Cspan class=\"tk-cmd\">simengine_host\u003C/span> \u003Cspan class=\"tk-flag\">--capabilities\u003C/span>\n\u003Cspan class=\"tk-cmd\">simengine_host\u003C/span> \u003Cspan class=\"tk-flag\">--load\u003C/span> \u003Cspan class=\"tk-ph\">FILE\u003C/span>\n\u003Cspan class=\"tk-cmd\">simengine_host\u003C/span> \u003Cspan class=\"tk-flag\">--run\u003C/span> \u003Cspan class=\"tk-ph\">FILE\u003C/span> \u003Cspan class=\"tk-flag\">--out\u003C/span> \u003Cspan class=\"tk-ph\">DIR\u003C/span> [\u003Cspan class=\"tk-flag\">--ticks\u003C/span> N] [\u003Cspan class=\"tk-flag\">--max-wall-ms\u003C/span> \u003Cspan class=\"tk-ph\">MS\u003C/span>] [\u003Cspan class=\"tk-flag\">--trace-every\u003C/span> N]\n\u003Cspan class=\"tk-cmd\">simengine_host\u003C/span> \u003Cspan class=\"tk-flag\">--session\u003C/span> [\u003Cspan class=\"tk-flag\">--max-wall-ms\u003C/span> \u003Cspan class=\"tk-ph\">MS\u003C/span>]\u003C/code>\u003C/pre>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Command\u003C/th>\n\u003Cth>What it does\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--report\u003C/code>\u003C/td>\n\u003Ctd>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. \u003Ccode>runtime.modules\u003C/code> lists the build-selected modules.\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--version\u003C/code>\u003C/td>\n\u003Ctd>Prints build identity as JSON without touching Vulkan.\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--capabilities\u003C/code>\u003C/td>\n\u003Ctd>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.\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--load FILE\u003C/code>\u003C/td>\n\u003Ctd>Validates a scenario (all-or-nothing) and prints its initial state. No Vulkan.\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--run FILE --out DIR\u003C/code>\u003C/td>\n\u003Ctd>Loads, steps and checks expectations. DIR must be new or empty. \u003Ccode>--ticks\u003C/code> overrides the scenario’s run length, \u003Ccode>--max-wall-ms\u003C/code> bounds the run (default 30000), \u003Ccode>--trace-every N\u003C/code> records a state digest every N ticks.\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--session\u003C/code>\u003C/td>\n\u003Ctd>JSON Lines control on stdin/stdout: \u003Ccode>load\u003C/code>, \u003Ccode>step\u003C/code>, \u003Ccode>inspect\u003C/code>, \u003Ccode>command\u003C/code> (dry run, expected state version), \u003Ccode>expectations\u003C/code>, \u003Ccode>capabilities\u003C/code>, \u003Ccode>quit\u003C/code>. Bounded by \u003Ccode>--max-wall-ms\u003C/code>.\u003C/td>\n\u003C/tr>\n\u003C/tbody>\n\u003C/table>\n\u003Cp>Options for \u003Ccode>--report\u003C/code>: \u003Ccode>--no-validation\u003C/code> (do not enable \u003Ccode>VK_LAYER_KHRONOS_validation\u003C/code>), \u003Ccode>--device INDEX\u003C/code> (physical device by enumeration index; default selection is discrete, then integrated, virtual, CPU), \u003Ccode>--inject-fault invalid-queue-priority\u003C/code> (negative control: with validation enabled the run must end with exit 8).\u003C/p>\n\u003Cp>Environment: \u003Ccode>SIMENGINE_VULKAN_LOADER\u003C/code> sets an explicit Vulkan loader path (diagnostic override).\u003C/p>\n\u003Ch3 id=\"exit-codes\">Exit codes\u003C/h3>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Code\u003C/th>\n\u003Cth>Name\u003C/th>\n\u003Cth>Meaning\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>0\u003C/td>\n\u003Ctd>ok\u003C/td>\n\u003Ctd>Success\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>1\u003C/td>\n\u003Ctd>internal_error\u003C/td>\n\u003Ctd>Unexpected exception inside the host\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>2\u003C/td>\n\u003Ctd>usage_error\u003C/td>\n\u003Ctd>Invalid command line\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>3\u003C/td>\n\u003Ctd>vulkan_loader_unavailable\u003C/td>\n\u003Ctd>No Vulkan loader library on this machine\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>4\u003C/td>\n\u003Ctd>vulkan_driver_unavailable\u003C/td>\n\u003Ctd>Loader present, no driver supporting Vulkan 1.3\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>5\u003C/td>\n\u003Ctd>no_vulkan_device\u003C/td>\n\u003Ctd>Instance created, zero physical devices\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>6\u003C/td>\n\u003Ctd>no_suitable_device\u003C/td>\n\u003Ctd>Devices exist, none meets the requirements\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>7\u003C/td>\n\u003Ctd>backend_initialization_failed\u003C/td>\n\u003Ctd>Other instance or device creation failure\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>8\u003C/td>\n\u003Ctd>validation_errors\u003C/td>\n\u003Ctd>Backend opened, the validation layer reported errors\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>9\u003C/td>\n\u003Ctd>runtime_self_check_failed\u003C/td>\n\u003Ctd>Backend fine, core runtime self-check failed\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>10\u003C/td>\n\u003Ctd>scenario_invalid\u003C/td>\n\u003Ctd>Validation failed; nothing ran\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>11\u003C/td>\n\u003Ctd>scenario_timeout\u003C/td>\n\u003Ctd>The wall-time bound stopped the run or session\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>12\u003C/td>\n\u003Ctd>scenario_expectation_failed\u003C/td>\n\u003Ctd>Run completed, an expectation failed\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>13\u003C/td>\n\u003Ctd>scenario_io_error\u003C/td>\n\u003Ctd>Input unreadable or output directory unusable\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>14\u003C/td>\n\u003Ctd>simulation_fault\u003C/td>\n\u003Ctd>A tick produced non-finite state (rolled back)\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>15\u003C/td>\n\u003Ctd>module_startup_failed\u003C/td>\n\u003Ctd>Optional modules could not be initialized\u003C/td>\n\u003C/tr>\n\u003C/tbody>\n\u003C/table>\n\u003Cp>A process killed by a signal (crash) prints no document; supervisors classify it.\u003C/p>\n\u003Ch2 id=\"simengine-capture\">simengine_capture\u003C/h2>\n\u003Cp>Offscreen render and capture with the forward PBR path.\u003C/p>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Cspan class=\"code__bar\">\u003Cspan class=\"code__lang\">text\u003C/span>\u003Cbutton type=\"button\" class=\"code__copy\" data-copy>Copy\u003C/button>\u003C/span>\u003Ccode>\u003Cspan class=\"tk-cmd\">simengine_capture\u003C/span> \u003Cspan class=\"tk-flag\">--scene\u003C/span> \u003Cspan class=\"tk-ph\">FILE\u003C/span> \u003Cspan class=\"tk-flag\">--out-dir\u003C/span> \u003Cspan class=\"tk-ph\">DIR\u003C/span> [options]\n\u003Cspan class=\"tk-cmd\">simengine_capture\u003C/span> \u003Cspan class=\"tk-flag\">--check-scene\u003C/span> \u003Cspan class=\"tk-ph\">FILE\u003C/span>\n\u003Cspan class=\"tk-cmd\">simengine_capture\u003C/span> \u003Cspan class=\"tk-flag\">--version\u003C/span>\n\u003Cspan class=\"tk-cmd\">simengine_capture\u003C/span> \u003Cspan class=\"tk-flag\">--help\u003C/span>\u003C/code>\u003C/pre>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Command\u003C/th>\n\u003Cth>What it does\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--scene FILE\u003C/code>\u003C/td>\n\u003Ctd>Loads a \u003Ccode>.sescene\u003C/code> file and its \u003Ccode>.seasset\u003C/code> files, renders offscreen, writes \u003Ccode>DIR/<scene_id>.png\u003C/code> and \u003Ccode>DIR/<scene_id>.capture.json\u003C/code>, prints the manifest (\u003Ccode>simengine.capture.manifest\u003C/code>, version 1).\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>--check-scene FILE\u003C/code>\u003C/td>\n\u003Ctd>Validates the scene and its assets only (units, axes, PBR subset, provenance, geometry). No Vulkan. Prints the manifest.\u003C/td>\n\u003C/tr>\n\u003C/tbody>\n\u003C/table>\n\u003Cp>Options for \u003Ccode>--scene\u003C/code>: \u003Ccode>--out-dir DIR\u003C/code> (required, created if missing), \u003Ccode>--width N --height N\u003C/code> (default 2560 x 1440), \u003Ccode>--warmup N\u003C/code> (timed warm-up frames excluded from steady statistics, default 3), \u003Ccode>--frames N\u003C/code> (measured steady frames, default 30), \u003Ccode>--label TEXT\u003C/code> (free-form machine label recorded in the manifest, not verified), \u003Ccode>--no-validation\u003C/code>, \u003Ccode>--no-sync-validation\u003C/code>, \u003Ccode>--device INDEX\u003C/code>, \u003Ccode>--inject-fault skip-layout-barrier|black-output\u003C/code> (negative controls: exit 8 and exit 12 respectively).\u003C/p>\n\u003Ch3 id=\"exit-codes-1\">Exit codes\u003C/h3>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Code\u003C/th>\n\u003Cth>Name\u003C/th>\n\u003Cth>Meaning\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>0\u003C/td>\n\u003Ctd>ok\u003C/td>\n\u003Ctd>Success\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>1\u003C/td>\n\u003Ctd>internal_error\u003C/td>\n\u003Ctd>Unexpected exception\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>2\u003C/td>\n\u003Ctd>usage_error\u003C/td>\n\u003Ctd>Invalid command line\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>3\u003C/td>\n\u003Ctd>vulkan_loader_unavailable\u003C/td>\n\u003Ctd>No Vulkan loader library on this machine\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>4\u003C/td>\n\u003Ctd>vulkan_driver_unavailable\u003C/td>\n\u003Ctd>Loader present, no driver supporting Vulkan 1.3\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>5\u003C/td>\n\u003Ctd>no_vulkan_device\u003C/td>\n\u003Ctd>Instance created, zero physical devices\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>6\u003C/td>\n\u003Ctd>no_suitable_device\u003C/td>\n\u003Ctd>Devices exist, none meets the requirements\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>7\u003C/td>\n\u003Ctd>backend_initialization_failed\u003C/td>\n\u003Ctd>Other instance or device creation failure\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>8\u003C/td>\n\u003Ctd>validation_errors\u003C/td>\n\u003Ctd>Rendered, but the validation layer reported errors\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>10\u003C/td>\n\u003Ctd>scene_invalid\u003C/td>\n\u003Ctd>Scene or asset rejected by the import path\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>11\u003C/td>\n\u003Ctd>render_failed\u003C/td>\n\u003Ctd>A Vulkan call failed or the device lacks a format\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>12\u003C/td>\n\u003Ctd>capture_content_invalid\u003C/td>\n\u003Ctd>The image is black, empty or background-only\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>13\u003C/td>\n\u003Ctd>output_write_failed\u003C/td>\n\u003Ctd>The PNG or manifest could not be written\u003C/td>\n\u003C/tr>\n\u003C/tbody>\n\u003C/table>\n\u003Ch2 id=\"simengine-desktop-windows-only\">simengine_desktop (Windows only)\u003C/h2>\n\u003Cp>A scene playground using the same persistent renderer: explore a generic PBR scene, select and move objects, save snapshots that \u003Ccode>simengine_capture\u003C/code> reproduces. It is not a game-authoring API.\u003C/p>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Cspan class=\"code__bar\">\u003Cspan class=\"code__lang\">text\u003C/span>\u003Cbutton type=\"button\" class=\"code__copy\" data-copy>Copy\u003C/button>\u003C/span>\u003Ccode>\u003Cspan class=\"tk-cmd\">simengine_desktop\u003C/span> \u003Cspan class=\"tk-flag\">--scene\u003C/span> \u003Cspan class=\"tk-ph\">FILE\u003C/span> [\u003Cspan class=\"tk-flag\">--out\u003C/span> \u003Cspan class=\"tk-ph\">DIR\u003C/span>] [\u003Cspan class=\"tk-flag\">--width\u003C/span> N] [\u003Cspan class=\"tk-flag\">--height\u003C/span> N]\u003C/code>\u003C/pre>\n\u003Cp>\u003Ccode>--out\u003C/code> must be new or empty; omitting it disables saved captures. \u003Ccode>--width\u003C/code>/\u003Ccode>--height\u003C/code> set the internal render resolution (default 1280 x 720). Requires Vulkan 1.3, one graphics/present queue, SRGB blit support and \u003Ccode>VK_EXT_swapchain_maintenance1\u003C/code>; 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 \u003Ccode>.sescene\u003C/code>, Escape exits. There is no collision response.\u003C/p>\n\u003Ch2 id=\"first-scene-py-example-driver\">first_scene.py (example driver)\u003C/h2>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Cspan class=\"code__bar\">\u003Cspan class=\"code__lang\">text\u003C/span>\u003Cbutton type=\"button\" class=\"code__copy\" data-copy>Copy\u003C/button>\u003C/span>\u003Ccode>\u003Cspan class=\"tk-cmd\">python\u003C/span> first_scene.py new \u003Cspan class=\"tk-ph\">DEST\u003C/span> [\u003Cspan class=\"tk-flag\">--name\u003C/span> \u003Cspan class=\"tk-ph\">NAME\u003C/span>] [\u003Cspan class=\"tk-flag\">--no-skills\u003C/span>]\n\u003Cspan class=\"tk-cmd\">python\u003C/span> first_scene.py check [\u003Cspan class=\"tk-flag\">--project\u003C/span> P] [\u003Cspan class=\"tk-flag\">--build\u003C/span> B \u003Cspan class=\"tk-punc\">|\u003C/span> \u003Cspan class=\"tk-flag\">--host\u003C/span> H \u003Cspan class=\"tk-flag\">--capture\u003C/span> C] [\u003Cspan class=\"tk-flag\">--scenario\u003C/span> S]\n\u003Cspan class=\"tk-cmd\">python\u003C/span> first_scene.py run   [\u003Cspan class=\"tk-flag\">--project\u003C/span> P] [\u003Cspan class=\"tk-flag\">--build\u003C/span> B \u003Cspan class=\"tk-punc\">|\u003C/span> \u003Cspan class=\"tk-flag\">--host\u003C/span> H \u003Cspan class=\"tk-flag\">--capture\u003C/span> C] [\u003Cspan class=\"tk-flag\">--scenario\u003C/span> S] [\u003Cspan class=\"tk-flag\">--out\u003C/span> \u003Cspan class=\"tk-ph\">DIR\u003C/span>] [\u003Cspan class=\"tk-flag\">--timeout\u003C/span> \u003Cspan class=\"tk-ph\">SEC\u003C/span>] [\u003Cspan class=\"tk-flag\">--label\u003C/span> \u003Cspan class=\"tk-ph\">TEXT\u003C/span>] [\u003Cspan class=\"tk-flag\">--skip-capture\u003C/span>]\n\u003Cspan class=\"tk-cmd\">python\u003C/span> first_scene.py verify [\u003Cspan class=\"tk-ph\">MANIFEST\u003C/span>] [\u003Cspan class=\"tk-flag\">--project\u003C/span> P] [\u003Cspan class=\"tk-flag\">--scenario\u003C/span> S] [\u003Cspan class=\"tk-flag\">--expect-outcome\u003C/span> \u003Cspan class=\"tk-ph\">PASS\u003C/span>\u003Cspan class=\"tk-punc\">|\u003C/span>\u003Cspan class=\"tk-ph\">FAIL\u003C/span>\u003Cspan class=\"tk-punc\">|\u003C/span>\u003Cspan class=\"tk-ph\">BLOCKED_ENVIRONMENT\u003C/span>]\u003C/code>\u003C/pre>\n\u003Cp>\u003Ccode>run\u003C/code> executes the full journey (load, run twice, pose, capture, verify, manifest). With \u003Ccode>--skip-capture\u003C/code> the render check is \u003Ccode>NOT_RUN\u003C/code>, never \u003Ccode>PASS\u003C/code>. The driver exits 21 (\u003Ccode>incompatible_engine\u003C/code>) when the engine’s interface versions differ from the ones its skills were written for.\u003C/p>\n",[6,9,12,15],{"id":7,"text":8},"simengine-host","simengine_host",{"id":10,"text":11},"simengine-capture","simengine_capture",{"id":13,"text":14},"simengine-desktop-windows-only","simengine_desktop (Windows only)",{"id":16,"text":17},"first-scene-py-example-driver","first_scene.py (example driver)",1793299074004]