Native Scene Migration

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 scaffolded applications.

1. Establish One Runtime Entry Point

Create iwsdk.config.json, bind its scene field to one project-root-relative scene source, and pass virtual:iwsdk-project to the existing World.create bootstrap. Do not create a second World or renderer for authored content.

2. Inventory Declarative Content

Move asset references, prefab composition, lights, hierarchy, transforms, environment, and typed component data into scene JSON. Keep runtime behavior, animation, networking, and systems in code.

Keep model URLs, procedural geometry, and materials in the defineAssets() module selected by iwsdk.config.json. Scene nodes reference those application-global asset IDs with content.type: "asset"; scene resources contain prefabs only.

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:

1. scene_get_capabilities
2. scene_render_file for each module
3. scene_render_file for the root
4. scene_flatten_file to create an import-free runtime document
5. scene_open on the flattened file for live collaboration
6. scene_get_state for hashes, validation, conflict, and runtime readiness
7. exact scene_set_camera and scene_screenshot views

The editor automatically reloads valid changes to the opened import-free document. After flattening, edit that output as the canonical scene; the authoring root and modules are scratch inputs. Re-flatten only when intentionally regenerating the output, because overwrite replaces later flat-file edits. Invalid opened 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.