Develop

Chapter 9a: Native Scene Migration

Updated: Sep 4, 2026

Use this checklist to move generated or procedural level content into native iwsdk.scene.v1 files under public/scenes/.

For a complete 0.4.x to 0.5.0 agent workflow, download the IWSDK 0.5 migration skill⁠. Release migration skills are documentation artifacts and are intentionally not copied into newly generated applications.

1. Establish One Runtime Entry Point

Create iwsdk.config.json and bind its scene field to one flattened, project-relative runtime scene:

{
  "version": "iwsdk.project.v1",
  "scene": "./public/scenes/main.iwsdk.scene.json",
  "world": {
    "xr": {
      "mode": "vr"
    }
  }
}

Pass virtual:iwsdk-project to the existing World.create() call. Do not create a second world or renderer for authored content.

2. Inventory Declarative Content

Move hierarchy, transforms, environment settings, light components, and other typed component values into scene JSON. Declare GLTF files, UIKitML documents, and procedural Three.js objects in the asset module selected by iwsdk.config.json, then reference those asset IDs from scene nodes. Keep runtime behavior, animation, networking, and systems in code.

3. Split Independent Modules

Create valid standalone modules for independent semantic groups, then add them to the root with top-level imports. Give each import a safe ID and optional wrapper transform. Avoid shared-file authoring when groups can be owned independently.

Render every module with scene_render_file, then render the composed root. Fix module-local defects in the module and cross-module placement/camera defects in the root.

4. Preserve Runtime Components

Translate existing declarative component data into the node components map using the exact component schemas returned by scene_get_capabilities. Do not guess field names or encode application systems into scene metadata.

5. Validate Through The File Boundary

Create and edit files directly. Use:

scene_get_capabilities

scene_render_file for each module

scene_render_file for the composed root

scene_flatten_file to produce an import-free runtime scene

scene_open on only the flattened output for live collaboration

scene_get_state for hashes, validation, conflict, and runtime readiness

exact scene_set_camera and scene_screenshot views

The editor watches only the active import-free file. After changing a module or the composed root, repeat the render checks, flatten the scene again, and continue with the refreshed flattened output. Invalid active files retain the last valid viewport and expose diagnostics.

6. Verify Runtime Parity

Check that the application loads the intended root and expected runtime hash. Inspect console, shader, WebGL, material, and resource errors. Compare representative editor and runtime screenshots at the same camera/aspect ratio.

Remove obsolete generated-level files only after the application build and runtime verification pass. Preserve unrelated user-authored code and assets.