Iwsdk Migrate 0 5

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

• Inspect git status before editing. Preserve all existing work; never reset,

clean, or overwrite unrelated changes.

• 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.

• 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.

• 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.

• 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

| 0.4.x surface | 0.5.0 replacement |

| -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |

| GLXF levels and @iwsdk/glxf | Native scene selected by iwsdk.config.json (or explicit low-level WorldOptions.level) |

| Meta Spatial Editor and @iwsdk/vite-plugin-metaspatial | IWSDK managed editor in @iwsdk/vite-plugin-dev |

| @iwsdk/vite-plugin-uikitml generated JSON | Runtime parsing of source .uikitml files from public/ui/ |

| @iwsdk/vite-plugin-gltf-optimizer | Pre-optimized source assets or the normal IWSDK glTF asset pipeline |

| vite-plugin-mkcert | Cached, untrusted HTTPS certificate generated by iwsdkDev() |

| PanelUI.config: './ui/panel.json' | UIKitML manifest asset using a BASE_URL-safe source .uikitml URL |

| PanelUI.maxWidth / maxHeight | Entity transform scale plus the document's intrinsic dimensions |

| features.spatialUI.kits | features.spatialUI.kit and optional componentSets |

| GLXFComponentRegistry | defineComponents([...]) plus native scene component props |

| LevelGLXFImporter / LevelEntityCreator | World.loadLevel() for native scenes / World.createTransformEntity() for dynamic objects |

| iwsdkDev({ assetManifest, componentManifest, emulator }) | iwsdk.config.json plus bare iwsdkDev() |

| iwsdkDev({ ai, workspace }) | Launch-time iwsdk dev up session flags |

| Remote Chef starter recipes / @iwsdk/starter-assets | Common source, scenes, and guidance embedded in @iwsdk/create |

| xr.features.lightEstimation | Authored light components and IBLTexture/IBLGradient |

| render.defaultLighting and implicit gradients | Explicit dome and IBL components on each native scene root |

| Static entities created in the startup callback | Asset/component manifests plus native scene nodes |

| Ad hoc custom-component registration | defineComponents([...]), shared by runtime and editor |

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:

• Start the 0.5 dev server and wait for npx iwsdk dev status --json to report

browserConnected: true and browserCommandReady: true.

• Validate and open every native scene. Fix missing manifest assets,

components, entity references, and file paths.

• In Editor view, compare hierarchy, transforms, visibility, authored lights,

panels, player-space children, and representative camera views with the

pre-migration inventory.

• In Runtime view, test every interaction and inspect console logs. Browser

screenshots are runtime-only by design.

• Enter and exit XR through both the application UI and the emulator/session

controls. Confirm screen-space panels return after XR exit.

• Resize the desktop window and verify UIKit layout, clipping, fonts, rounded

corners, and perceived scale.

• If a physical headset is available, open the reported HTTPS network URL,

accept its self-signed-certificate warning, and enter XR.

• 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.