Develop

Chapter 9: Native Scene Editor

Updated: Sep 4, 2026
IWSDK loads native scene JSON directly. The scene file is the authoring source. The managed editor provides selection, transforms, hierarchy editing, component editing, and screenshots.

Select the active scene

Keep scene files under public/scenes/. Select the flattened, import-free runtime scene in iwsdk.config.json:
{
  "version": "iwsdk.project.v1",
  "scene": "./public/scenes/main.iwsdk.scene.json",
  "assets": {
    "module": "./src/assets"
  },
  "world": {
    "xr": {
      "mode": "vr"
    }
  }
}
The application loads the same project settings:
import { World } from '@iwsdk/core';
import projectOptions from 'virtual:iwsdk-project';

const world = await World.create(
  document.getElementById('scene-container') as HTMLDivElement,
  projectOptions,
);
Keep runtime systems, networking, animation, and procedural behavior in code.

Use the native scene format

Use iwsdk.scene.v1. A node’s content.type can be group, asset, instance, or pattern.
An asset node refers to an ID from the manifest-selected asset module:
{
  "version": "iwsdk.scene.v1",
  "units": "meters",
  "resources": {},
  "nodes": [
    {
      "id": "robot",
      "name": "Robot",
      "content": {
        "type": "asset",
        "asset": "robot"
      },
      "transform": {
        "position": [0, 0.8, -2],
        "scale": 0.5
      }
    }
  ]
}
The resources object stores reusable prefabs. Asset definitions and procedural Three.js objects remain in src/assets.ts.

Compose scene modules

A root scene can import standalone scene files:
{
  "version": "iwsdk.scene.v1",
  "units": "meters",
  "imports": [
    {
      "id": "reading-nook",
      "src": "./modules/reading-nook.iwsdk.scene.json",
      "transform": {
        "position": [2, 0, -1]
      }
    }
  ],
  "resources": {},
  "nodes": []
}
The src path resolves from the importing file. Imported nodes and prefabs receive a namespace based on the import ID. Keep this authoring root in a separate file such as main.composition.iwsdk.scene.json.
Imports support composition during authoring, but the runtime and editable editor require an import-free scene. Render each module, render the composed root, then use scene_flatten_file to write main.iwsdk.scene.json. Open only that flattened output in the editor, and keep the manifest’s scene field pointed at the flattened file.

Use the managed editor

The managed browser can switch between Runtime and Editor. The editor watches only the active import-free file. It does not watch an authoring root or its imported modules.
A valid change to the active file replaces the preview. An invalid change keeps the last valid preview and reports the error. A conflicting unsaved edit is not overwritten. After changing a module or composition root, render the source files again, flatten them again, and continue with the refreshed flattened output.
Agents edit scene files through normal file operations. People can use the editor controls for visual adjustments.

Use scene tools

The scene tools used in this workflow are:
scene_render_file
scene_flatten_file
scene_open
scene_get_state
scene_get_capabilities
scene_screenshot
scene_select
scene_set_camera
scene_set_preview_visibility
scene_render_file validates and renders a file without changing the active editor. scene_get_state reports the current file, selection, hashes, validation state, conflicts, runtime state, and render statistics.
The CLI exposes the same operations:
npx iwsdk scene render-file \
  --input-json '{"path":"public/scenes/main.composition.iwsdk.scene.json","view":"quarter"}' \
  --output-file artifacts/main.png

npx iwsdk scene flatten \
  --input-json '{"path":"public/scenes/main.composition.iwsdk.scene.json","outputPath":"public/scenes/main.iwsdk.scene.json"}' --raw

npx iwsdk scene open \
  --input-json '{"path":"public/scenes/main.iwsdk.scene.json"}' --raw

Review a scene

Use saved or canonical camera views for repeatable screenshots. Use captureMode: "render" for a clean scene image. Use captureMode: "editor" when you need editor overlays.
Validate the live application separately after the editor view passes review.
Nav Logo
English (US)
© 2026 Meta