Hz Iwsdk Webxr

IWSDK WebXR Skill

Build immersive WebXR experiences for Meta VR using Meta's Immersive Web SDK (IWSDK). This skill covers the current package layout, ECS architecture, Three.js integration, spatial UI development, XR input handling, and the recommended Vite-based development loop.

When to Use This Skill

Use this skill when you need to:

• Build a WebXR experience targeting Meta VR using IWSDK
• Create 3D scenes using the ECS architecture on top of Three.js
• Design spatial UI panels with UIKitML and PanelUI
• Handle XR input from controllers, hands, and world-space pointers
• Run a closed-loop edit, reload, observe, and fix workflow for IWSDK apps
• Optimize WebXR performance for Meta VR hardware
• Debug and test WebXR applications with IWSDK's Vite dev tooling and Quest Browser

This skill applies to Meta VR Glasses with gaze-pinch input, and to all Meta Quest headsets with Quest Browser.

What Is IWSDK

The Immersive Web SDK (IWSDK) is Meta's framework for building WebXR experiences. It provides:

• Entity Component System (ECS): a data-oriented architecture built on typed component storage and query-driven systems
• Three.js integration: IWSDK manages the renderer, scene, camera, and XR session lifecycle so app code can focus on content
• Spatial UI toolkit: UIKitML plus PanelUI, PanelDocument, and UIKitDocument for in-world and screen-space UI
• XR input management: unified handling of controllers, hand tracking, pointers, and grabbing
• Locomotion and interaction systems: opt-in grabbing, teleport, slide, and turning features
• Asset management: manifest-based preloading and keyed access through AssetManager

IWSDK runs in the browser via the WebXR Device API. Applications are standard web pages that are usually served by Vite during development and opened in Quest Browser for on-device validation.

Current Packaging And Tooling

These details are important because older pre-release guidance is now wrong:

• The main runtime package is @iwsdk/core
• The official scaffold command is npm create @iwsdk@latest
• The default dev loop uses @iwsdk/vite-plugin-dev
• Local HTTPS is typically handled with vite-plugin-mkcert
• Current IWSDK packages require Node.js >=20.19.0
• @iwsdk/core re-exports @iwsdk/xr-input and @iwsdk/locomotor

Quick Start

1. Create A New Project

npm create @iwsdk@latest my-project
cd my-project

If you are starting from the official create flow, it can also install dependencies and initialize git for you.

2. Install Dependencies

npm install

If you are setting up manually, use @iwsdk/core, three, @iwsdk/vite-plugin-dev, and vite-plugin-mkcert instead of the old @meta-quest/iwsdk package.

3. Start The Dev Server

npm run dev

The standard IWSDK Vite setup gives you a secure local dev server, hot module replacement, and an emulator/dev browser workflow through @iwsdk/vite-plugin-dev.

4. Test In XR

There are two normal validation paths:

• Quest Browser: open the secure dev URL on the headset and launch XR there
• IWSDK dev tooling: use the Vite plugin's emulator/dev browser path for quick desktop iteration

Quest Browser testing requires HTTPS. If the app works on desktop but will not enter XR on-device, confirm that the dev server URL is secure and headset reachable. When XR still won't enter, metavr log from the headset often names the failing check (HTTPS, WebXR flags, GPU process).

AI-Assisted Development Loop

IWSDK is a strong fit for coding agents because the development loop is already web-native: edit source, reload the page, observe behavior, and iterate.

Recommended loop:

1. Verify API and platform details against current docs before coding
2. Edit the code and run the Vite dev server
3. Reload in Quest Browser or the IWSDK emulator/dev browser
4. Observe logs, screenshots, and runtime state
5. Iterate until runtime behavior matches the request

If you are pairing a native Meta VR frontend with a host-side coding agent, keep the frontend thin. Let the host machine own the repository, file edits, dependency installs, tests, build steps, and metavr tool calls.

Project Structure

A typical IWSDK project looks like this:

my-project/
  src/
    index.ts              # Entry point: World.create, scene setup, XR controls
    systems/              # Optional ECS systems
      movement.ts
    components/           # Optional ECS components
      velocity.ts
  public/
    models/               # GLTF / GLB assets
    textures/             # Textures and images
    audio/                # Audio assets
    ui/                   # Compiled UIKitML JSON output
  ui/
    welcome.uikitml       # Source UIKitML files
  vite.config.ts
  package.json
  tsconfig.json

Key Patterns

Creating A Component

import { Types, createComponent } from '@iwsdk/core';

export const Velocity = createComponent(
  'Velocity',
  {
    x: { type: Types.Float32, default: 0 },
    y: { type: Types.Float32, default: 0 },
    z: { type: Types.Float32, default: 0 },
  },
  'Linear velocity in meters per second',
);

Writing A System

import { createSystem } from '@iwsdk/core';
import { Velocity } from './components/velocity';

export class MovementSystem extends createSystem({
  moving: { required: [Velocity] },
}) {
  update(delta: number) {
    this.queries.moving.entities.forEach((entity) => {
      if (!entity.object3D) {
        return;
      }
      entity.object3D.position.x += Velocity.data.x[entity.index] * delta;
      entity.object3D.position.y += Velocity.data.y[entity.index] * delta;
      entity.object3D.position.z += Velocity.data.z[entity.index] * delta;
    });
  }
}

Spawning An Entity With A Three.js Mesh

import * as THREE from 'three';
import { Velocity } from './components/velocity';

function spawnCube(world) {
  const mesh = new THREE.Mesh(
    new THREE.BoxGeometry(0.5, 0.5, 0.5),
    new THREE.MeshStandardMaterial({ color: 0x00aaff }),
  );

  const entity = world.createTransformEntity(mesh);
  entity.object3D!.position.set(0, 1.5, -2);
  entity.addComponent(Velocity, { x: 0, y: 0, z: 0 });
}

Creating The World And Launching XR

import {
  ReferenceSpaceType,
  SessionMode,
  World,
} from '@iwsdk/core';

const container = document.getElementById('scene-container') as HTMLDivElement;
const world = await World.create(container, {
  xr: {
    sessionMode: SessionMode.ImmersiveVR,
    referenceSpace: ReferenceSpaceType.LocalFloor,
    offer: 'none',
  },
});

world.registerSystem(MovementSystem);
world.launchXR();

World.create(...) already wires the renderer, core systems, asset loading, and render loop. Do not teach agents to use new World(), createWorld(), world.start(), or the older enterXR(...) path.