Migrate IWSDK 0.4.x to 0.5.0

Upgrade an existing IWSDK application without losing behavior or authored content. This is a migration, not a rewrite: preserve working runtime logic, move only static composition into the native scene format, and prove parity in the live runtime.

User context is in $ARGUMENTS.

Scope

This skill is specifically for 0.4.x -> 0.5.0. First inspect the installed versions in package.json and the lockfile.

• If the project is already on 0.5.x, diagnose the reported issue without replaying the migration.
• If it is older than 0.4.x, apply the intervening release migrations first.
• If it is newer than 0.5.x, use the skill for that release boundary instead.

The public comparison baseline for this guide is IWSDK 0.4.2.

Non-negotiable safety rules

1. Inspect git status before editing. Preserve all existing work; never reset, clean, or overwrite unrelated changes.
2. Create a recoverable checkpoint before transforming GLXF, scene files, or UI sources. Use the project's established version-control workflow; do not commit unless the user authorized commits.
3. Inventory the app before deleting a package. A package is removable only after all of its imports, config hooks, scripts, and generated outputs have been replaced.
4. Do not claim that a GLXF or Meta Spatial scene was migrated merely because the app compiles. IWSDK 0.5 has no GLXF runtime fallback; reproduce and verify the authored hierarchy in native scene JSON.
5. Keep dynamic behavior in TypeScript/JavaScript. Native scenes own static composition, component values, transforms, lights, panels, and player-space attachments—not runtime-dependent entity counts or game logic.

Release boundary at a glance

The Interactable compatibility alias still exists, but new and migrated code should use RayInteractable.

Phase 1: Inventory before editing

Determine the package manager from the lockfile, then collect:

• every @iwsdk/* dependency and its installed version;
• every import or config call involving glxf, metaspatial, compileUIKit, vite-plugin-uikitml, vite-plugin-gltf-optimizer, mkcert, or IWSDK_DISABLE_MKCERT;
• every World.create, World.loadLevel, PanelUI, ScreenSpace, Visibility, render.defaultLighting, and features.spatialUI use;
• all .glxf, .uikitml, generated UI JSON, Meta Spatial project files, and generated glTF folders;
• static entity creation in startup code and the systems that later locate or manipulate those entities.

Classify each static object as one of:

• asset: glTF, UIKitML, or a parentless procedural Object3D prototype;
• scene node: a stable id, transform, asset reference, and component values;
• player-space child: content attached to player, camera/head, target-ray, or grip space;
• dynamic: keep in code because runtime state determines its existence.

Record the inventory in the migration report. This is the parity checklist.

Phase 2: Align packages

Update every IWSDK package already used by the application to 0.5.0. Keep IWSDK packages on one version; do not mix 0.4.x and 0.5.x packages.

Remove these retired packages when present:

@iwsdk/glxf
@iwsdk/vite-plugin-gltf-optimizer
@iwsdk/vite-plugin-metaspatial
@iwsdk/vite-plugin-uikitml
vite-plugin-mkcert

Do not add @iwsdk/scene-composition merely because it is new. It is already a core dependency; add it directly only if application code imports its document, validation, or composition APIs.

After editing package.json, use the project's package manager to update the lockfile and installation. Do not delete the lockfile as a shortcut.

Phase 3: Simplify Vite configuration

Remove imports and plugin entries for mkcert, Meta Spatial, UIKitML compilation, and the glTF optimizer. A migrated config should follow this shape:

import { iwsdkDev } from '@iwsdk/vite-plugin-dev';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [iwsdkDev()],
  server: { host: '0.0.0.0', open: false },
});

Important behavior:

• Create iwsdk.config.json as the committed project authority. It selects the scene plus extensionless assets.module and components.module paths and stores serializable world/emulator options.
• Manifest-first dev servers always expose the managed editor. Choose AI mode, headed/headless launch, open behavior, and screenshot size with iwsdk dev flags rather than committed Vite options.
• The managed browser is the browser surface. Keep Vite server.open false so it does not create a second unmanaged tab.
• HTTPS is on by default. IWSDK caches an untrusted certificate without installing a local CA. Managed Playwright accepts it automatically; a physical headset shows the expected certificate warning.
• Use iwsdkDev({ https: false }) only when HTTP is intentional. A custom server.https certificate takes precedence.
• Keep asset and component modules free of system imports and side effects so the editor can load them in its own realm.

Remove obsolete generated-output ignore rules only after confirming nothing else creates those directories. Common stale paths are generated UIKit JSON, Meta Spatial GLXF output, and plugin-generated glTF folders.

Phase 4: Create shared manifests

Move the asset catalog into a dedicated module:

// src/assets.ts
import { AssetType, defineAssets } from '@iwsdk/core';

const publicAssetUrl = (path: string) =>
  `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;

export default defineAssets({
  environment: {
    name: 'Environment',
    type: AssetType.GLTF,
    url: publicAssetUrl('models/environment.glb'),
  },
  'settings-panel': {
    name: 'Settings Panel',
    type: AssetType.UIKitML,
    url: publicAssetUrl('ui/settings.uikitml'),
  },
});

An asset manifest may also contain parentless procedural Object3D prototypes. Do not place a prototype in the Three scene or parent it before registration.

Declare application components separately:

// src/components.ts
import { defineComponents } from '@iwsdk/core';
import { MyBehavior } from './components/my-behavior.js';

export default defineComponents([MyBehavior]);

Point the project authority at both extensionless modules:

{
  "$schema": "./node_modules/@iwsdk/core/dist/schemas/iwsdk-project.v1.schema.json",
  "version": "iwsdk.project.v1",
  "scene": "./public/scenes/main.iwsdk.scene.json",
  "assets": { "module": "./src/assets" },
  "components": { "module": "./src/components" },
  "world": {
    "xr": { "mode": "vr", "offer": "always" },
    "features": { "spatialUI": true }
  },
  "dev": { "emulator": { "device": "metaQuest3" } }
}

The Vite virtual module supplies the same exact exports to World.create():

import { World } from '@iwsdk/core';
import projectOptions from 'virtual:iwsdk-project';

const world = await World.create(container, projectOptions);

Do not also import the manifests into index.ts or configure them in iwsdkDev(). iwsdk.config.json is the single runtime/editor authority.

Delete GLXF registry setup and field mappers. Native scene component objects store ordinary props keyed by the component id, and the shared component manifest supplies their schemas to both runtime and editor.

Phase 5: Replace GLXF or code-authored static layout

Create public/scenes/main.iwsdk.scene.json. A minimal asset-backed panel and model look like this:

{
  "version": "iwsdk.scene.v1",
  "units": "meters",
  "components": {},
  "resources": {},
  "nodes": [
    {
      "id": "environment",
      "content": { "type": "asset", "asset": "environment" },
      "transform": { "position": [0, 0, 0] },
      "components": { "LocomotionEnvironment": {} }
    },
    {
      "id": "settings-panel",
      "content": { "type": "asset", "asset": "settings-panel" },
      "transform": {
        "position": [0, 1.5, -2],
        "scale": 0.4
      },
      "components": {
        "RayInteractable": {},
        "ScreenSpace": {
          "top": "20px",
          "left": "20px",
          "width": "25vw",
          "height": "40vh"
        }
      }
    }
  ]
}

Migration rules:

• Node id is the stable runtime/editor identity. Preserve meaningful unique identifiers and use them from code; do not locate authored objects by array position or display name.
• Scene asset references must resolve in src/assets.ts.
• Move static component values into the scene. Keep systems and event logic in code.
• Preserve hierarchy with children. Use a node parent of type player-space for content attached to player, camera, head, target-ray, or grip spaces.
• Author the player origin under the top-level player.transform. Tracked head/controller transforms are runtime-owned and overridden by XR tracking.
• Use visible: false for authored initial visibility. Visibility and Transform are intrinsic editor properties, not ordinary add-component UI.
• Put fog, tone mapping, exposure, and shadow renderer settings under the scene environment object. Use DomeGradient/DomeTexture for the visible background and IBLGradient/IBLTexture for image-based lighting. There is no separate AR background policy; immersive AR remains transparent.
• Remove render.defaultLighting. IWSDK no longer injects either environment component. Author both gradient components for the former default look, or omit either independently when the scene intentionally has no background or no image-based lighting.
• Use IWSDK light components on scene nodes for authored ambient, hemisphere, directional, point, spot, or rect-area lights.

There is no supported 0.5 runtime path for .glxf. For a Meta Spatial/GLXF project, use the old scene and screenshots as the visual reference, recreate its static hierarchy in native scene JSON, then compare multiple editor and runtime views before deleting legacy sources. If parity cannot be established, stop and report that migration as incomplete.

Code-created dynamic entities can stay in code. It is valid to migrate the static shell first and leave gameplay spawning, effects, and variable-count objects in systems.

Phase 6: Migrate UIKitML

Move source UIKitML files into public/ui/ and delete the generated intermediate JSON once no code references it. Change panel URLs from .json to .uikitml.

For editor-authored panels, prefer an AssetType.UIKitML manifest entry and an asset-backed scene node, as shown above. PanelUI remains a compatibility path for code-created panels, but it is hidden from generic editor authoring.

Remove maxWidth and maxHeight from PanelUI; 0.5 no longer performs a second fit. The UIKitML document owns intrinsic dimensions and the entity transform owns world scale. Give ScreenSpace explicit CSS dimensions rather than relying on auto.

Replace spatial-UI kit configuration:

features: {
  spatialUI: {
    kit: 'horizon',
    componentSets: [],
  },
}

The default kit is horizon. UIKitML can load TTF fonts declared with @font-face, including remote HTTPS URLs. Keep font loading CORS-compatible and verify text after the document reports stable layout; do not add arbitrary frame-count sleeps.

Locate and manipulate an authored panel by stable scene and element ids:

import { UIKitMLAsset } from '@iwsdk/core';

const panel = world.requireSceneObject<UIKitMLAsset>('settings-panel');
const saveButton = panel.requireElementById('save-button');
saveButton.addEventListener('click', onSave);

Do not traverse the entire Three scene looking for an anonymous UIKitDocument, and do not key logic off generated JSON paths.

Phase 7: Resolve behavior-level compatibility

Audit these cases even when TypeScript compiles:

• createTransformEntity() now gives every transform entity intrinsic Visibility. If old code adds Visibility itself, change it to set the existing value or assign entity.object3D.visible.
• Prefer RayInteractable over the deprecated Interactable alias.
• Remove xr.features.lightEstimation; IWSDK 0.5 no longer requests the unsupported feature. Replace its visual role with authored lights and IBL.
• Immersive AR always hides authored dome/background visuals for passthrough while retaining IBL. Re-test any app that previously expected a virtual AR background.
• AssetManager.getGLTF() returns a fresh clone by default. Use { shared: true } only when shared mutable state is intentional.
• ScreenSpace width/height: 'auto' warns and falls back to viewport sizing. Author explicit dimensions and test browser resize plus XR exit.
• If custom UIKitML components were passed through kits, migrate them to componentSets; select the built-in collection with kit.
• If systems stored references to startup-created objects, replace static object plumbing with world.getSceneObject, requireSceneObject, getSceneEntity, or requireSceneEntity and stable node ids.
• Preserve cleanup functions for signal/query subscriptions and DOM/UIKit listeners. World.destroy() is now available for hot reload, tests, and multi-world hosts.

Phase 8: Verify in increasing scope

Run the project's normal formatter, typecheck, tests, and production build. Then verify the actual app:

1. Start the 0.5 dev server and wait for npx @iwsdk/cli dev status --json to report browserConnected: true and browserCommandReady: true.
2. Validate and open every native scene. Fix missing manifest assets, components, entity references, and file paths.
3. In Editor view, compare hierarchy, transforms, visibility, authored lights, panels, player-space children, and representative camera views with the pre-migration inventory.
4. In Runtime view, test every interaction and inspect console logs. Browser screenshots are runtime-only by design.
5. Enter and exit XR through both the application UI and the emulator/session controls. Confirm screen-space panels return after XR exit.
6. Resize the desktop window and verify UIKit layout, clipping, fonts, rounded corners, and perceived scale.
7. If a physical headset is available, open the reported HTTPS network URL, accept its self-signed-certificate warning, and enter XR.
8. Run a production build from a clean install using the committed lockfile.

Do not regenerate IWSDK's library reference corpus as part of an application migration.

Completion report

Return a concise report containing:

• detected source and target versions;
• package additions/removals;
• old GLXF/Meta Spatial/UIKit generated artifacts retained or deleted;
• scene, asset, component, and UIKitML files migrated;
• behavior changes made for compatibility;
• exact automated and live tests run;
• any visual or physical-headset checks still requiring a human;
• any unresolved parity gap that prevents calling the migration complete.

Optional 0.5 modernization (not required for parity)

After migration is green, consider these additions separately: signal helpers re-exported from @iwsdk/core, authored light components, raw XR frame/session and hit-test helpers, World.destroy(), World.loadSceneDocument(), renderable asset instantiation, player-space authoring, and managed scene review tools. Do not mix these refactors into the compatibility pass unless the user asks.