/hz-iwsdk-webxr

name: hz-iwsdk-webxr
license: Apache-2.0
description: Builds WebXR experiences for Meta VR and Horizon OS using the Immersive Web SDK (IWSDK) — ECS architecture, Three.js integration, spatial UI. Use when creating web-based VR/MR apps for Quest Browser.
allowed-tools: Bash(metavr:*), Bash(hzdb:*)

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.