IWSDK Scene Composer

Author native IWSDK assets and scene files. Application code owns geometry and materials; scene JSON owns composition; the managed editor provides visual feedback and human transform/component adjustment.

Read these references when relevant:

• scene-format.md before editing scene JSON;
• asset-authoring.md before creating or changing glTF or procedural assets;
• text-intake.md for text-only requests;
• image-intake.md for image or hybrid requests;
• composition-patterns.md for decomposition and repetition strategies;
• review-and-stop.md before final review.

Fixed Boundaries

• Use only iwsdk.scene.v1. There is no compatibility schema.
• Scene files are the composition source of truth. Create and edit them with normal filesystem tools under public/scenes/.
• Scene JSON has one renderable content kind: asset. It does not define models, primitive geometry, material resources, or material overrides.
• The default export of the configured application asset manifest is the asset source of truth. It may contain URL-backed glTF and UIKitML entries plus parentless Object3D prototypes with arbitrary Three.js geometry and materials.
• The application runtime and editor import the same manifest module independently. Never depend on shared object identity, iframe messaging, DOM state, or a live runtime world when defining assets.
• Humans use the editor for selection, hierarchy, transforms, components, root lighting, and preview visibility. They do not edit geometry or materials there.
• Agents may edit asset TypeScript and scene JSON, then use the editor to validate and render the result.

The public scene MCP surface is intentionally small:

scene_open
scene_render_file
scene_get_state
scene_get_capabilities
scene_screenshot
scene_select
scene_set_camera
scene_set_preview_visibility
scene_measure_image_regions

Document creation and mutation happen through direct file edits. Do not look for MCP create/add/update/remove/patch/save/compose/review/publish tools.

When MCP is unavailable, use the CLI equivalents:

npx iwsdk dev status
npx iwsdk dev up
npx iwsdk scene capabilities --raw
npx iwsdk scene render-file \
  --input-json '{"path":"public/scenes/room.iwsdk.scene.json","viewId":"hero"}' \
  --output-file artifacts/room.png
npx iwsdk scene open \
  --input-json '{"path":"public/scenes/room.iwsdk.scene.json"}' --raw
npx iwsdk scene state --raw

iwsdk dev up starts the server in the background, launches the configured managed editor browser, and waits for the command bridge. Do not edit vite.config.ts to change browser mode as an ad hoc startup workaround.

scene_render_file renders a file without replacing the editor's active document, but it still uses the managed editor browser for manifest evaluation and WebGL. If startup reports dev_browser_not_ready, inspect iwsdk dev status and iwsdk dev logs --tail 100. Retry only when the diagnostics indicate a transient startup failure. Do not invent a custom CPU or Playwright renderer and present it as authoritative editor evidence. Preserve the structured failure, continue type/schema/build checks that remain meaningful, and report the visual-verification gate as blocked.

Camera parameters are intentionally distinct: view accepts only the built-in presets (current, top, front, back, left, right, quarter, orbit), while viewId selects an exact camera declared in authoring.views. Once a level loads, its saved hero view owns runtime framing and supersedes the initial World.create({ render: { camera } }) pose.

Workflow

1. Specify

Turn the request into a compact implementation brief:

• required and optional features;
• source evidence regions for image input;
• silhouette, proportions, parts, negative space, contacts, and material response;
• hero and diagnostic views;
• measurable acceptance criteria;
• assumptions, uncertainty, and fidelity ceiling.

A single image proves visible composition, not hidden geometry. Do not silently invent occluded detail or lower requested fidelity.

2. Plan Assets And Modules

Call scene_get_capabilities once. Inspect src/assets.ts and existing asset modules. For every visible form, choose one of:

1. reuse an existing manifest asset;
2. add a glTF entry to the manifest;
3. register a UIKitML file with AssetType.UIKitML;
4. create a deterministic parentless Object3D prototype in code and register it;
5. assemble existing assets with a scene prefab or module.

Create custom geometry and materials in asset code, not JSON. Prefer separate *.scene-asset.ts modules for substantial procedural assets and import their prototypes into src/assets.ts.

Plan independent semantic groups as standalone scene modules. Give each module a local origin, size envelope, attachment points, required views, and asset IDs. Asset and component IDs are application-global; imported node and prefab IDs are namespaced.

3. Build

Author assets first, then scene JSON. Build in dependency order:

1. support/stage and representative lighting;
2. large composition masses;
3. identity-critical groups;
4. repeated secondary detail;
5. hero camera and final environment.

Use meters, stable descriptive IDs, deterministic ordering, and explicit transforms. Groups supply hierarchy, never visible mass. Use castShadow and receiveShadow on asset nodes only when needed. Use prefabs and patterns for repetition; keep repeated asset prototypes resource-sharing friendly.

4. Validate And Materialize

With the managed editor command-ready, call scene_render_file on every changed module, then the root. It composes imports, validates schema and manifest references, lowers the scene, and returns a PNG plus diagnostics without changing the active document. Fix failures in the owning asset or scene file.

After the root passes, call scene_open once for live collaboration. The editor watches the root and imported files. A valid file change swaps the preview atomically; an invalid change preserves the last valid render and reports diagnostics. Unsaved human edits produce a conflict instead of being overwritten.

Use scene_get_state for selection, hashes, diagnostics, dirty/conflict state, runtime readiness, and render statistics. Use camera, screenshot, selection, and preview visibility tools only when their live-editor context is useful.

5. Review And Refine

Review in three passes:

1. Layout: hierarchy, scale, support contacts, and arrangement.
2. Geometry: silhouette, proportions, parts, negative space, and alternate views.
3. Final: material response, color, lighting, environment, and hero framing.

Keep review orchestration and evidence outside the editor. The editor supplies authoritative screenshots, hashes, camera state, diagnostics, and render measurements. Derive comparisons, defect lists, lineage, and stop decisions in ordinary task files.

Fix the highest-impact defect in its owning asset or scene module, rerender that file, then rerender the root. Default to two focused correction rounds. Stop earlier on a repeated defect, oscillation, plateau, missing input/asset, or representation ceiling.

6. Finish

Finish only when:

• every root and module file validates and renders;
• the active editor state is clean and conflict-free;
• required views are nonblank and correctly framed;
• required features pass measurable and visual checks;
• manifest asset IDs resolve in both editor and application runtime;
• the application build and selected scene load without blocking errors.

If a required gate is unavailable, finish with an explicit blocked or accepted-with-gaps result. Passing a local schema check, production build, or custom diagnostic image does not substitute for authoritative editor renders and state.

Modular Composition

{
  "version": "iwsdk.scene.v1",
  "units": "meters",
  "imports": [
    {
      "id": "reading-nook",
      "src": "./modules/reading-nook.iwsdk.scene.json",
      "transform": { "position": [1.8, 0, -0.6] }
    }
  ],
  "resources": {},
  "nodes": []
}

Each module must be valid by itself. Imports resolve recursively in declaration order. The import entry becomes a transform group. The root owns global components, environment, metadata, and authoring settings. Cycles, unsafe IDs, missing files, duplicate namespaced IDs, and invalid modules fail composition.

For parallel work, assign one module file per worker. Never let two workers edit one file. Render modules independently, import only passing modules, then correct cross-module scale, contact, occlusion, lighting, and framing at the root.

Regeneration And Provenance

Preserve stable IDs and module boundaries when revising. Never overwrite unrelated human-authored files. Record the skill/runtime versions, input hashes, root/module paths, capability hash, source/composed/runtime hashes, assumptions, and fidelity ceiling in authoring metadata or adjacent task evidence.