Develop

Workflows

Updated: Sep 4, 2026
These workflows combine direct file edits with the public iwsdk-runtime tools. Ask the agent to inspect each tool’s installed schema before calling it.

Check the correct readiness signal

Start the session, then run:
npx iwsdk dev status
StatusMeaning
Development server is reachable
The application server can respond. Browser tools might still be unavailable.
state.browserCommandReady is true
The registered session can accept browser commands.
state.session.browser.commandReady is true
The managed browser reports command readiness.
Wait for both command-readiness fields before starting an MCP workflow. A session started with --no-open has no registered managed browser, so every iwsdk-runtime tool call remains unavailable. iwsdk mcp inspect can still display schemas.

Author a native scene from files

Use files under public/scenes/ as the authoring surface. The current iwsdk.scene.v1 document supports group, asset, instance, and pattern node content. Refer to project-manifest asset identifiers instead of embedding ad hoc geometry or material objects in the scene file.
Follow this sequence:
  1. Call scene_get_capabilities({full: true}) to read the current scene contract.
  2. Create or edit the root scene and any imported module files with normal file-editing tools.
  3. Call scene_render_file for every changed module. Fix all returned diagnostics.
  4. Call scene_render_file for the composed root. This validates the resolved composition without replacing the active Editor document.
  5. Call scene_flatten_file once to write a final import-free scene to the path selected by iwsdk.config.json.
  6. Call scene_open with the flattened path. Do not pass an import-bearing composition to scene_open.
  7. Call scene_get_state and confirm that diagnostics are empty and the Editor is clean and conflict-free. Record each hash by name; source-document, composed-document, and runtime hashes represent different projections and need not match.
  8. Set a reproducible view with scene_set_camera, then capture Editor evidence with scene_screenshot.
  9. Reload or exercise the application, then capture runtime evidence with browser_screenshot and browser_get_console_logs.
A typical flatten call writes to the configured runtime scene path:
{
  "path": "public/scenes/main.composition.iwsdk.scene.json",
  "outputPath": "public/scenes/main.iwsdk.scene.json",
  "overwrite": true
}
The example assumes iwsdk.config.json names ./public/scenes/main.iwsdk.scene.json as its scene. If you choose another output, update the manifest and restart the session before runtime verification. A successful flatten writes only after confirming that its sourceRuntimeHash and outputRuntimeHash match. scene_render_file returns hashes, dependencies, render statistics, and a preview image for a valid file. An invalid render returns diagnostics without a preview image.

Split scene work across agents

Use one imported scene module per independent task. Give each worker ownership of a different file, then use one integration owner for the root:
  1. Each worker edits and renders its module until it is valid.
  2. The integration owner updates and renders the composed root.
  3. The integration owner flattens the root once.
  4. Open and evaluate only the flattened output.
The editable Editor opens only the import-free output. Changes to the separate composition or imported modules do not update that flat file automatically; render the changed files and root again, then flatten and reopen the output. For external changes to the open flat file, an invalid update preserves the last valid render and reports diagnostics, while unsaved human changes produce a conflict instead of being overwritten.

Inspect and frame a scene

Use the native Editor tools for authored layout:
  1. Call scene_get_state to identify the active file, selection, diagnostics, and current hashes.
  2. Call scene_select({nodeIds: [...]}) to replace the selection. The tool does not accept a selection mode.
  3. Use scene_set_preview_visibility for temporary context, solo, ghost, hide, show, lock, or saved-arrangement views.
  4. Use scene_set_camera to choose a named view, step an orbit, or provide an explicit camera.
  5. Call scene_screenshot with captureMode: "render" for a clean scene image or captureMode: "editor" to include selection and editing overlays. Read structured validation, dirty, conflict, and runtime-readiness diagnostics from scene_get_state, not from screenshot pixels.
Preview visibility does not replace a source-file edit. Keep persistent scene content in the scene files.

Verify application behavior

Use Runtime evidence for behavior driven by systems, input, or application code:
  1. Call browser_get_console_logs and record the initial errors.
  2. Call browser_reload_page after changing code or runtime-loaded assets.
  3. Wait for browser command readiness again after the reload.
  4. Reproduce the behavior through XR or ECS tools.
  5. Call browser_screenshot and then read the console logs again.
browser_screenshot always captures the application runtime. It switches the managed workspace from Editor to Runtime when necessary and does not accept a target argument.

Exercise an XR interaction

Use this sequence when the application offers an immersive session:
  1. Call xr_get_session_status.
  2. Call xr_accept_session if a session is offered but not active.
  3. Call xr_set_input_mode with controller or hand.
  4. Call xr_set_connected with connected: true for each emulated input device that the interaction requires.
  5. Call scene_get_runtime_hierarchy to locate the live object.
  6. Call scene_get_object_transform with its runtime UUID or native scene node ID.
  7. Use the returned XR-relative position with xr_look_at for a connected controller or hand.
  8. Call xr_select for a complete press and release, or use xr_set_select_value for a held interaction.
  9. Capture the result with browser_screenshot and inspect console logs.
Do not claim interaction behavior from an Editor screenshot. Pose and input calls are meaningful only while the XR session is active.

Inspect live scene performance

Call scene_get_render_stats after the runtime bridge is ready. It reports calls, triangles, points, lines, geometries, textures, programs, meshCount, materialCount, shadowCasters, worldBounds, framingBounds, environment, and scene asset, environment, light, and material summaries. It does not return the Editor-only objectCount, nodeCount, geometryCount, visibleNodeIds, or frameTimeSamplesMs fields.
The tool returns available: false when the measurement bridge is not installed. Treat that as missing runtime evidence, not as zero work.

Debug ECS state deterministically

Use a pause, inspect, change, and compare sequence:
  1. Call ecs_list_systems and ecs_list_components to discover the current runtime contract.
  2. Call ecs_find_entities, then ecs_query_entity for a focused entity.
  3. Call ecs_pause.
  4. Store a labeled ecs_snapshot.
  5. Use ecs_step to advance a controlled number of fixed-timestep frames, or use ecs_set_component after checking the field schema and current value.
  6. Store a second labeled snapshot and compare it with ecs_diff.
  7. Call ecs_resume, even when the investigation finds no defect.
The render loop continues while ECS updates are paused, so runtime screenshots remain available.

Preview UIKitML assets

  1. Call ui_list_assets to discover the project’s UIKitML assets.
  2. Inspect the current ui_render_preview schema.
  3. Call ui_render_preview for the selected asset and review the returned preview.
  4. Make persistent changes in project source files, then render the preview again.
Preview rendering does not insert the result into a native scene automatically.

Record review decisions outside Editor

The public Editor surface provides scene state, diagnostics, selection, preview controls, and screenshots. Keep comparison history, defect prioritization, approvals, and stop or release decisions in your task artifact or version-control review. Do not infer those decisions from Editor state alone.
Nav Logo
English (US)
© 2026 Meta