agentleFS
mirzaaghazadehmirzaaghazadeh/iwsdk-webxr-skills/skills/iwsdk-official/iwsdk-migrate-0-5/SKILL.md

iwsdk-migrate-0-5

Skill1 starsChanged 32 days agoMITView on GitHub

Migrate an existing IWSDK 0.4.x application to IWSDK 0.5.0. Use when upgrading across the 0.5 boundary, replacing Meta Spatial Editor or GLXF, removing retired Vite plugins, moving UIKitML to runtime-loaded assets, adopting native scene JSON, or resolving 0.5 migration errors.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

39 rules. About 0 are common, 15 are distinctive, and 24 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 24

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the project is already on 0.5.x, diagnose the reported issue without replaying the migration.

    line 21
  2. Very specific:

    If it is older than 0.4.x, apply the intervening release migrations first.

    line 23
  3. Very specific:

    If it is newer than 0.5.x, use the skill for that release boundary instead.

    line 24
  4. Distinctive:

    Create a recoverable checkpoint before transforming GLXF, scene files, or UI sources.

    line 32
  5. Distinctive:

    Do not claim that a GLXF or Meta Spatial scene was migrated merely because the app compiles.

    line 38
  6. Distinctive:

    Keep dynamic behavior in TypeScript/JavaScript.

    line 41
  7. Very specific:

    every @iwsdk/* dependency and its installed version.

    line 74
  8. Very specific:

    every import or config call involving glxf, metaspatial, compileUIKit, vite-plugin-uikitml, vite-plugin-gltf-optimizer, mkcert, or …

    line 75
  9. Very specific:

    every World.create, World.loadLevel, PanelUI, ScreenSpace, Visibility, render.defaultLighting, and features.spatialUI use.

    line 78
  10. Very specific:

    Update every IWSDK package already used by the application to 0.5.0.

    line 97
  11. Distinctive:

    Remove these retired packages when present:

    line 100
  12. Very specific:

    Do not add @iwsdk/scene-composition merely because it is new.

    line 110
  13. Very specific:

    After editing package.json, use the project's package manager to update the lockfile and installation.

    line 114
  14. Distinctive:

    Remove imports and plugin entries for mkcert, Meta Spatial, UIKitML compilation, and the glTF optimizer.

    line 119
  15. Very specific:

    Create iwsdk.config.json as the committed project authority.

    line 134
  16. Very specific:

    Use iwsdkDev({ https: false }) only when HTTP is intentional.

    line 145
  17. Distinctive:

    Keep asset and component modules free of system imports and side effects so the editor can load them in its own realm.

    line 147
  18. Distinctive:

    Remove obsolete generated-output ignore rules only after confirming nothing else creates those directories.

    line 150
  19. Distinctive:

    Do not place a prototype in the Three scene or parent it before registration.

    line 180
  20. Very specific:

    Do not also import the manifests into index.ts or configure them in iwsdkDev().

    line 218
  21. Distinctive:

    Delete GLXF registry setup and field mappers.

    line 221
  22. Very specific:

    Create public/scenes/main.iwsdk.scene.json.

    line 227
  23. Very specific:

    Use visible: false for authored initial visibility.

    line 277
  24. Very specific:

    Put fog, tone mapping, exposure, and shadow renderer settings under the scene environment object.

    line 279
  25. Very specific:

    Remove render.defaultLighting.

    line 283
  26. Distinctive:

    Use IWSDK light components on scene nodes for authored ambient, hemisphere, directional, point, spot, or rect-area lights.

    line 287
  27. Very specific:

    Remove maxWidth and maxHeight from PanelUI.

    line 309
  28. Very specific:

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

    line 340
  29. Very specific:

    Prefer RayInteractable over the deprecated Interactable alias.

    line 350
  30. Very specific:

    Remove xr.features.lightEstimation.

    line 351
  31. Very specific:

    If custom UIKitML components were passed through kits, migrate them to componentSets.

    line 360
  32. Very specific:

    If systems stored references to startup-created objects, replace static object plumbing with world.getSceneObject, requireSceneObject, …

    line 362
  33. Distinctive:

    Run the project's normal formatter, typecheck, tests, and production build.

    line 371
  34. Very specific:

    Start the 0.5 dev server and wait for npx @iwsdk/cli dev status --json to report browserConnected: true and browserCommandReady: true.

    line 374
  35. Distinctive:

    If a physical headset is available, open the reported HTTPS network URL, accept its self-signed-certificate warning, and enter XR.

    line 387
  36. Distinctive:

    Run a production build from a clean install using the committed lockfile.

    line 389
  37. Distinctive:

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

    line 391
  38. Very specific:

    After migration is green, consider these additions separately: signal helpers re-exported from @iwsdk/core, authored light components, raw …

    line 409
  39. Distinctive:

    Do not mix these refactors into the compatibility pass unless the user asks.

    line 413

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

0.4.x surface0.5.0 replacement
GLXF levels and @iwsdk/glxfNative scene selected by iwsdk.config.json (or explicit low-level WorldOptions.level)
Meta Spatial Editor and @iwsdk/vite-plugin-metaspatialIWSDK managed editor in @iwsdk/vite-plugin-dev
@iwsdk/vite-plugin-uikitml generated JSONRuntime parsing of source .uikitml files from public/ui/
@iwsdk/vite-plugin-gltf-optimizerPre-optimized source assets or the normal IWSDK glTF asset pipeline
vite-plugin-mkcertCached, untrusted HTTPS certificate generated by iwsdkDev()
PanelUI.config: './ui/panel.json'UIKitML manifest asset using a BASE_URL-safe source .uikitml URL
PanelUI.maxWidth / maxHeightEntity transform scale plus the document's intrinsic dimensions
features.spatialUI.kitsfeatures.spatialUI.kit and optional componentSets
GLXFComponentRegistrydefineComponents([...]) plus native scene component props
LevelGLXFImporter / LevelEntityCreatorWorld.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-assetsCommon source, scenes, and guidance embedded in @iwsdk/create
xr.features.lightEstimationAuthored light components and IBLTexture/IBLGradient
render.defaultLighting and implicit gradientsExplicit dome and IBL components on each native scene root
Static entities created in the startup callbackAsset/component manifests plus native scene nodes
Ad hoc custom-component registrationdefineComponents([...]), 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:

  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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.