### Install and Run Example Project

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/14-environment-raycast.md

Instructions for installing dependencies, building the SDK, and running the environment raycast example project.

```bash
cd immersive-web-sdk
pnpm install
pnpm run build:tgz
cd examples/environment-raycast
npm install
npm run dev

```

--------------------------------

### Run Example with Local TGZ Packages

Source: https://github.com/facebook/immersive-web-sdk/blob/main/README.md

Navigate to an example directory, run a fresh install from local tgz packages, and start the development server.

```bash
cd examples/locomotion && npm run fresh:dev
```

--------------------------------

### Run Physics Example Project

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/12-physics.md

Commands to navigate to the physics example project, install dependencies, and run the development server. This project demonstrates basic physics setup, dynamic sphere creation, and force application.

```bash
cd examples/physics
pnpm install
pnpm dev
```

--------------------------------

### Install and Run Example Project

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/13-camera-access.md

Instructions to install dependencies and run the 'cami' example project, which demonstrates a full AR camera app.

```bash
cd examples/cami
pnpm install
pnpm dev
```

--------------------------------

### Install and Run Example Project

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/15-depth-occlusion.md

Instructions for setting up and running the depth occlusion example project from the SDK repository.

```bash
cd immersive-web-sdk
pnpm install
pnpm run build:tgz
cd examples/depth-occlusion
npm install
npm run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/grab/README.md

Installs the necessary project dependencies for the grab example.

```bash
cd immersive-web-sdk/examples/grab
npm install
```

--------------------------------

### Quick Start: Enable Scene Understanding

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/11-scene-understanding.md

A minimal example to set up scene understanding, including plane and mesh detection, and registering custom systems and components.

```javascript
import {
  World,
  SceneUnderstandingSystem,
  XRPlane,
  XRMesh,
  XRAnchor,
  SessionMode,
} from '@iwsdk/core';

// React to detected planes
class PlaneProcessSystem extends createSystem({
  planeEntities: { required: [XRPlane] },
}) {
  init() {
    this.queries.planeEntities.subscribe('qualify', (entity) => {
      console.log('New plane detected!', entity.object3D?.position);
    });
  }

  update() {
    this.queries.planeEntities.entities.forEach((entity) => {
      console.log('Existing plane: ', entity.object3D?.position);
    });
  }
}

// Create world with AR session and required features
World.create(document.getElementById('scene-container'), {
  assets,
  xr: {
    sessionMode: SessionMode.ImmersiveAR,
    features: {
      planeDetection: true,
      meshDetection: true,
      anchors: true,
    },
  },
}).then((world) => {
  // Register the scene understanding system
  world
    .registerSystem(SceneUnderstandingSystem)
    .registerComponent(XRPlane)
    .registerComponent(XRMesh)
    .registerComponent(XRAnchor)
    .registerSystem(PlaneProcessSystem);
});
```

--------------------------------

### CI Workflow Example

Source: https://github.com/facebook/immersive-web-sdk/blob/main/RELEASE.md

Example of a GitHub Action workflow to automate installation, building, and publishing.

```yaml
name: CI

on:
  push:
    branches:
      - main

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Dependencies
        run: pnpm install
      - name: Build Packages
        run: pnpm -r build
      - name: Publish Packages
        run: pnpm changeset publish
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```

--------------------------------

### Quick Start: Initialize Camera in XR Scene

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/13-camera-access.md

A minimal example to set up camera access and create a camera entity within an XR scene. It optionally requests camera permission early for a better user experience.

```javascript
import { World, CameraSource, CameraUtils, SessionMode } from '@iwsdk/core';

// Optional: Request camera permission early for better UX
CameraUtils.getDevices()
  .then(() => console.log('Cameras ready'))
  .catch((error) => console.warn('Camera unavailable'));

World.create(document.getElementById('scene-container'), {
  xr: {
    sessionMode: SessionMode.ImmersiveAR,
  },
  features: {
    camera: true, // Enable CameraSystem
  },
}).then((world) => {
  // Create camera entity
  const cameraEntity = world.createEntity();
  cameraEntity.addComponent(CameraSource, {
    facing: 'back',
    width: 1920,
    height: 1080,
    frameRate: 30,
  });

  // Store for later access
  world.globals.cameraEntity = cameraEntity;
});
```

--------------------------------

### Quick Start: Initialize Physics System and Create a Dynamic Sphere

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/12-physics.md

A minimal example to get physics working. It registers the PhysicsSystem with custom gravity, creates a sphere mesh, and adds it to the scene with PhysicsShape and PhysicsBody components for dynamic behavior.

```javascript
import {
  World,
  PhysicsSystem,
  PhysicsBody,
  PhysicsShape,
  PhysicsState,
  PhysicsShapeType,
  Mesh,
  SphereGeometry,
  MeshStandardMaterial,
} from '@iwsdk/core';

// 1. Register the physics system with customized gravity
world
  .registerSystem(PhysicsSystem, { configData: { gravity: [0, -10, 0] } })
  .registerComponent(PhysicsBody)
  .registerComponent(PhysicsShape);

// 2. Create a mesh
const sphere = new Mesh(
  new SphereGeometry(0.5),
  new MeshStandardMaterial({ color: 0xff0000 }),
);
sphere.position.set(0, 5, 0);
scene.add(sphere);

// 3. Create entity and add physics components
const entity = world.createTransformEntity(sphere);
entity.addComponent(PhysicsShape, {
  shape: PhysicsShapeType.Auto, // Automatically detects sphere
});
entity.addComponent(PhysicsBody, {
  state: PhysicsState.Dynamic, // Falls due to gravity
});
```

--------------------------------

### Quick Start: Setting Up Depth Occlusion

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/15-depth-occlusion.md

A minimal example demonstrating how to initialize the world with depth sensing enabled, register the depth sensing system and occludable component, and create an occludable virtual sphere.

```javascript
import {
  World,
  SessionMode,
  ReferenceSpaceType,
  DepthSensingSystem,
  DepthOccludable,
  Mesh,
  SphereGeometry,
  MeshStandardMaterial,
} from '@iwsdk/core';

World.create(document.getElementById('scene-container'), {
  xr: {
    sessionMode: SessionMode.ImmersiveAR,
    referenceSpace: ReferenceSpaceType.Unbounded,
    features: {
      depthSensing: {
        required: true,
        usage: 'gpu-optimized',
        format: 'float32',
      },
      anchors: { required: true },
      unbounded: { required: true },
    },
  },
}).then((world) => {
  scene.background = null; // Transparent background for AR

  // Register the depth sensing system
  world.registerSystem(DepthSensingSystem).registerComponent(DepthOccludable);

  // Create a virtual sphere
  const sphere = new Mesh(
    new SphereGeometry(0.2),
    new MeshStandardMaterial({ color: 0xff4444, transparent: true }),
  );
  sphere.position.set(0, 1.0, -1.0);
  world.scene.add(sphere);

  // Mark it as occludable — it will now hide behind real-world surfaces
  const entity = world.createTransformEntity(sphere);
  entity.addComponent(DepthOccludable);
});
```

--------------------------------

### Quick Start: Environment Raycasting

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/14-environment-raycast.md

A minimal example demonstrating how to set up environment raycasting. It creates a reticle that follows the right controller's raycast to real-world surfaces and orients to the surface normal.

```typescript
import {
  World,
  SessionMode,
  EnvironmentRaycastTarget,
  RaycastSpace,
} from '@iwsdk/core';

World.create(document.getElementById('scene-container'), {
  xr: {
    sessionMode: SessionMode.ImmersiveAR,
    features: {
      hitTest: { required: true }, // Enable WebXR hit-test
    },
  },
  features: {
    environmentRaycast: true, // Enable EnvironmentRaycastSystem
  },
}).then((world) => {
  // Create a reticle that follows the raycast
  const reticleMesh = createReticleMesh(); // Your reticle geometry
  const reticle = world.createTransformEntity(reticleMesh);

  reticle.addComponent(EnvironmentRaycastTarget, {
    space: RaycastSpace.Right, // Use right controller
    maxDistance: 10, // Maximum raycast distance in meters
  });

  // The reticle now automatically:
  // - Moves to where the controller points at real surfaces
  // - Orients to match the surface normal
  // - Hides when there's no hit
});
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/02-testing-experience.md

Run this command to install all necessary packages if you did not do so during project creation.

```bash
npm install
```

--------------------------------

### Start the Development Server

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/ai/getting-started.md

Run this command in your terminal to start the development server. This command routes through `iwsdk dev up --open --foreground`, allowing the CLI to manage the dev-server lifecycle, MCP adapter sync, and browser opening.

```bash
npm run dev
```

--------------------------------

### Interactive Project Creation Example

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/create/README.md

An example of the interactive prompts you will encounter when running the create-iwsdk CLI, showing user selections for project configuration.

```bash
$ npm create @iwsdk@latest

===============================================
IWSDK Create CLI v0.2.2
Node v20.19.0

? Project name › iwsdk-app
? Which language do you want to use? › TypeScript
? What type of experience are you building? › Virtual Reality
? Enable Hand Tracking? › Optional
? Enable WebXR Layers? › Optional
? Enable locomotion? › Yes
? Deploy locomotion engine on a Worker? › Yes (recommended)
? Enable grabbing (one/two-hand, distance)? › Yes
? Enable physics simulation (Havok)? › No
? Enable Meta Spatial Editor integration? › No (Can change later)
? Set up a Git repository? › Yes
? Install dependencies now? › Yes

```

--------------------------------

### Install XR Input SDK

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/xr-input/README.md

Install the XR input SDK and Three.js using npm.

```bash
npm install @iwsdk/xr-input three
```

--------------------------------

### Install Dependencies for Development

Source: https://github.com/facebook/immersive-web-sdk/blob/main/README.md

Install all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install Immersive Web SDK Core and Three.js

Source: https://github.com/facebook/immersive-web-sdk/blob/main/README.md

Install the core SDK and Three.js into an existing project.

```bash
npm install @iwsdk/core three
```

--------------------------------

### Start Development Server

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/depth-occlusion/README.md

Starts the development server with HTTPS enabled for testing on AR devices. Use `pnpm build` for production builds and `pnpm preview` to preview production builds.

```bash
# Start development server with HTTPS
pnpm dev

# Build for production
pnpm build

# Preview production build
pnpm preview
```

--------------------------------

### Basic VR Development Example

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/vite-plugin-dev/README.md

Configure the plugin for basic VR development by specifying the desired XR device.

```javascript
iwsdkDev({
  emulator: { device: 'metaQuest3' },
});
```

--------------------------------

### Install @iwsdk/glxf and Three.js

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/glxf/README.md

Install the GLXF loader and Three.js using npm. Ensure Three.js version is compatible.

```bash
npm install @iwsdk/glxf three
```

--------------------------------

### Start Development Server

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/grab/README.md

Starts the development server with HTTPS enabled for local testing. Use 'npm run build' for production builds and 'npm run preview' to preview the production build.

```bash
# Start development server with HTTPS
npm run dev


# Build for production
npm run build


# Preview production build
npm run preview
```

--------------------------------

### Install Dependencies Prompt

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/01-project-setup.md

This prompt determines whether to install project dependencies and display the dev server command. 'Yes' is recommended.

```bash
Install dependencies now? (We will print the command to start the dev server.) (Y/n)
```

--------------------------------

### Install @iwsdk/vite-plugin-metaspatial

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/vite-plugin-metaspatial/README.md

Install the plugin as a development dependency.

```bash
npm install -D @iwsdk/vite-plugin-metaspatial
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/02-testing-experience.md

Use this command to change into your project's root directory before starting the development server.

```bash
cd my-iwsdk-app  # Replace with your actual project name
```

--------------------------------

### Start Development Server

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/scene-understanding/README.md

Command to start the development server with Hot Module Replacement (HMR) and HTTPS enabled for local WebXR testing.

```bash
pnpm dev
```

--------------------------------

### Run Development and Build Commands

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/locomotion/README.md

Commands to start the development server with HTTPS, build for production, and preview the production build locally.

```bash
# Start development server with HTTPS
pnpm dev

# Build for production
pnpm build

# Preview production build locally
pnpm preview
```

--------------------------------

### Install Vite UIKitML Plugin

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/vite-plugin-uikitml/README.md

Install the plugin as a development dependency using npm.

```bash
npm install -D @iwsdk/vite-plugin-uikitml
```

--------------------------------

### Install the Vite Plugin

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/vite-plugin-gltf-optimizer/README.md

Install the plugin as a development dependency using npm.

```bash
npm install -D @iwsdk/vite-plugin-gltf-optimizer
```

--------------------------------

### Install Vite Plugins for Development

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/core/README.md

Install necessary Vite plugins for an enhanced development experience, including XR emulation and GLTF optimization.

```bash
npm install -D @iwsdk/vite-plugin-dev @iwsdk/vite-plugin-gltf-optimizer @iwsdk/vite-plugin-uikitml
```

--------------------------------

### Install and Run gh-pages for Manual Deployment

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/08-build-deploy.md

Install the `gh-pages` package as a development dependency and use it to deploy the contents of your `dist/` folder to the `gh-pages` branch.

```bash
# Install deployment tool
npm install -D gh-pages

# Build and deploy
npm run build
npx gh-pages -d dist
```

--------------------------------

### AR Development with Synthetic Environment Example

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/vite-plugin-dev/README.md

Set up AR development by enabling a synthetic environment alongside device emulation.

```javascript
iwsdkDev({
  emulator: {
    device: 'metaQuest3',
    environment: 'living_room',
  },
});
```

--------------------------------

### UIKitML Structure Example

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/concepts/spatial-ui/uikitml.md

This example demonstrates the structure of UIKitML, using nested containers, text, and input elements with classes, IDs, and inline styles.

```html
<container id="menu" class="panel" style="padding: 12; gap: 8">
  <text class="title" style="fontSize: 24">Settings</text>
  <container class="row" style="flexDirection: row; gap: 6">
    <text>Music</text>
    <input id="music" />
  </container>
</container>
```

--------------------------------

### Enable Grab and Locomotion Systems

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/06-built-in-interactions.md

Configure `World.create()` to enable the grabbing and locomotion features. This is a one-time setup for your scene.

```javascript
// Update your existing World.create() call in src/index.ts
World.create(document.getElementById('scene-container'), {
  assets,
  xr: {
    sessionMode: SessionMode.ImmersiveVR,
    features: { handTracking: true },
  },
  features: {
    grabbing: true, // Enable grab system
    locomotion: true, // Enable locomotion system
    // ... other existing features
  },
}).then((world) => {
  // ... your existing setup
});
```

--------------------------------

### System Setup: Create Camera Entity

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/13-camera-access.md

Creates a camera entity and adds the CameraSource component with desired configuration. The camera activates only when the XR session is visible.

```javascript
const cameraEntity = world.createEntity();
cameraEntity.addComponent(CameraSource, {
  deviceId: '', // Empty = auto-select based on facing
  facing: 'back', // 'front' | 'back'
  width: 1920,
  height: 1080,
  frameRate: 30,
});
```

--------------------------------

### Run Development Server

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/audio/README.md

Starts the development server with HTTPS support. The local URL will be reported by Vite or `npx iwsdk dev status`.

```bash
# Start development server with HTTPS
pnpm dev


# Build for production
pnpm build


# Preview production build locally
pnpm preview
```

--------------------------------

### System Setup: Enable Camera Feature

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/13-camera-access.md

Enables the CameraSystem and CameraSource components by setting the 'camera' feature to true when creating the World.

```javascript
World.create(container, {
  features: {
    camera: true, // Registers CameraSystem and CameraSource
  },
});
```

--------------------------------

### Build All Packages as TGZ Files

Source: https://github.com/facebook/immersive-web-sdk/blob/main/README.md

Build all packages in the project and create .tgz archives. This is useful for local development and testing of examples.

```bash
npm run build:tgz
```

--------------------------------

### Reference Assets in Code

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/locomotion/README.md

Example of how to reference assets using root-relative paths. Assets are served from the Vite `public/` directory.

```javascript
// Reference assets using root-relative paths (Vite serves public/ at root)
const assets = {
  scene: { url: '/glxf/my-scene.glxf', type: AssetType.GLXF },
  model: { url: '/gltf/my-model.gltf', type: AssetType.GLTF },
  texture: { url: '/textures/my-texture.png', type: AssetType.Texture },
};
```

--------------------------------

### Basic Immersive World Setup with Grabbable Cube

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/core/README.md

Create an immersive world and a grabbable cube using the SDK. Ensure the 'app' element exists in your HTML.

```typescript
import { World, OneHandGrabbable } from '@iwsdk/core';
import { BoxGeometry, Mesh, MeshStandardMaterial } from 'three';

// Create an immersive world
const world = await World.create(document.getElementById('app'), {
  features: {
    grabbing: true,
    locomotion: true,
  },
});

// Create a grabbable cube
const geometry = new BoxGeometry(0.5, 0.5, 0.5);
const material = new MeshStandardMaterial({ color: 0x00ff00 });
const mesh = new Mesh(geometry, material);

const cube = world.createTransformEntity(mesh);
cube.addComponent(OneHandGrabbable, { rotate: true, translate: true });
```

--------------------------------

### Set Up Git Repository Prompt

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/01-project-setup.md

This prompt asks whether to initialize a Git repository for version control. 'Yes' is recommended.

```bash
Set up a Git repository? (Y/n)
```

--------------------------------

### Define a System with Queries and Config

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/concepts/ecs/systems.md

This example shows the basic structure of a system, including defining entity queries and configuration schema. Use this as a template for creating new systems.

```typescript
import { Types, createSystem } from '@iwsdk/core';

export class MySystem extends createSystem(
  {
    groupA: { required: [CompA], excluded: [CompB] },
    groupB: { required: [CompC] },
  },
  {
    speed: { type: Types.Float32, default: 1 },
  },
) {
  init() {
    this.queries.groupA.subscribe('qualify', (e) => {
      /*…*/
    });
  }
  update(dt: number) {
    for (const e of this.queries.groupB.entities) {
      /*…*/
    }
  }
  destroy() {
    /* cleanup */
  }
}
```

--------------------------------

### Warmup Reference Server

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/ai/index.md

Installs and prepares the local reference server for semantic code search and API knowledge. Run this once to download models and corpus. Ensure IWSDK_REFERENCE_ASSETS_BASE_URL is set if hosting the corpus payload separately.

```bash
npx iwsdk reference warmup
```

--------------------------------

### Install Dependencies

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/audio/README.md

Installs project dependencies using pnpm. Ensure Node.js 20.19.0+ and pnpm are installed.

```bash
cd audio
pnpm install
```

--------------------------------

### Starter Dev Commands

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/01-project-setup.md

Lists essential commands for managing the development server and runtime environment for an Immersive Web SDK project.

```bash
npm run dev
npm run dev:runtime
npx iwsdk dev status
npx iwsdk dev down
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/locomotion/README.md

Installs project dependencies using pnpm. Ensure Node.js 20.19.0+ is installed.

```bash
cd locomotion
pnpm install
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/depth-occlusion/README.md

Installs project dependencies using pnpm. Ensure Node.js 20.19.0+ is installed.

```bash
cd depth-occlusion
pnpm install
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/scene-understanding/README.md

Installs project dependencies using pnpm. Ensure Node.js 20.19.0+ and pnpm are installed.

```bash
cd scene-understanding
pnpm install
```

--------------------------------

### Install @iwsdk/vite-plugin-dev

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/vite-plugin-dev/README.md

Install the plugin as a development dependency using npm.

```bash
npm install -D @iwsdk/vite-plugin-dev
```

--------------------------------

### Install @iwsdk/locomotor

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/locomotor/README.md

Install the locomotor package along with its peer dependencies.

```bash
npm install @iwsdk/locomotor three three-mesh-bvh
```

--------------------------------

### Build Starter Assets

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/starter-assets/README.md

Use this command to generate variant source files and build assets for distribution. It synchronizes starter templates and processes binary assets.

```bash
pnpm --filter @iwsdk/starter-assets build
```

--------------------------------

### Create a New iwsdk Project with Other Package Managers

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/create/README.md

Alternative commands for creating a new Immersive Web SDK project using pnpm, yarn, or bun.

```bash
# pnpm
pnpm create @iwsdk@latest
```

```bash
# yarn
yarn create @iwsdk
```

```bash
# bun
bun create @iwsdk
```

--------------------------------

### Create iwsdk Project with Command Line Options

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/create/README.md

Use command-line flags to provide project name directly or skip all prompts by using default settings.

```bash
# Provide project name directly
npm create @iwsdk@latest my-app
```

```bash
# Skip all prompts and use defaults
npm create @iwsdk@latest my-app -- -y
```

```bash
# Use custom CDN for recipes/assets
npm create @iwsdk@latest -- --assets-base https://my-cdn.com/iwsdk
```

--------------------------------

### Initialize and Render UIKit Root

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/concepts/spatial-ui/uikit.md

Demonstrates the direct usage of UIKit by initializing a Root component with camera and renderer, adding a basic container with text, and setting up the animation loop. Ensure the renderer's transparent sort is configured.

```typescript
import { Root, Container, Text, reversePainterSortStable } from '@pmndrs/uikit';

const root = new Root(camera, renderer, {
  width: 1000,
  height: 500,
  padding: 10,
});
scene.add(root);

const panel = new Container({ flexDirection: 'row', gap: 8 });
panel.add(new Text({ text: 'Hello XR' }));
root.add(panel);

renderer.setTransparentSort(reversePainterSortStable);
renderer.setAnimationLoop((t) => root.update(t));
```

--------------------------------

### UIKitML CSS Class Example

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/concepts/spatial-ui/uikitml.md

This example shows how CSS classes can be defined in UIKitML, including properties like `backgroundColor`, `padding`, and conditional styles for `hover` states.

```css
.panel {
  backgroundcolor: rgba(0, 0, 0, 0.6);
  sm: {
    padding: 8;
  }
}
.title {
  hover: {
    color: #fff;
  }
}
```

--------------------------------

### Preview Production Build

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/scene-understanding/README.md

Command to preview the production build locally.

```bash
pnpm preview
```

--------------------------------

### List All Systems

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/starter-assets/claude-injections/skills/iwsdk-debug/SKILL.md

Use this command to view all available systems and their execution priorities. This is useful for identifying potential system conflicts or understanding system order.

```javascript
ecs_list_systems()
```

--------------------------------

### Build for Production

Source: https://github.com/facebook/immersive-web-sdk/blob/main/examples/scene-understanding/README.md

Command to create a production-ready build of the application.

```bash
pnpm build
```

--------------------------------

### Dynamic Difficulty Adjustment Example

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/concepts/ecs/queries.md

This example demonstrates a `DifficultySystem` that uses multiple queries with value predicates to adjust enemy difficulty based on player proximity and enemy health. It dynamically modifies entity component values.

```typescript
export class DifficultySystem extends createSystem({
  // Only enemies that need difficulty scaling
  weakEnemies: {
    required: [Health, Enemy],
    where: [lt(Health, 'current', 20)],
  },
  strongEnemies: {
    required: [Health, Enemy],
    where: [gt(Health, 'current', 80)],
  },
  playerNearby: {
    required: [Player, Transform],
    where: [lt(Transform, 'distanceToPlayer', 10)],
  },
}) {
  update() {
    const playerCount = this.queries.playerNearby.entities.size;

    // Buff weak enemies when players are close
    if (playerCount > 0) {
      for (const enemy of this.queries.weakEnemies.entities) {
        const current = enemy.getValue(Health, 'current')!;
        enemy.setValue(Health, 'current', Math.min(100, current + 5));
      }
    }
  }
}
```

--------------------------------

### Step 3: Configure Scene Understanding System Options

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/11-scene-understanding.md

Configure the SceneUnderstandingSystem with options such as enabling wireframe visualization for detected geometry.

```javascript
world.registerSystem(SceneUnderstandingSystem, {
  configData: {
    showWireFrame: true, // Show/hide wireframe visualization for detected planes and meshes
  },
});
```

--------------------------------

### Get Device Transform

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/starter-assets/PROJECT_CLAUDE.md

Reads the current position and orientation of a specified device in the XR scene.

```bash
mcp__iwsdk-runtime__xr_get_transform
```

--------------------------------

### Preset Optimization Levels

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/vite-plugin-gltf-optimizer/README.md

Configure the plugin using predefined optimization levels for quick setup.

```javascript
optimizeGLTF({
  level: 'light', // High quality, basic optimization
  level: 'medium', // Balanced quality/size (default)
  level: 'aggressive', // Maximum compression
});
```

--------------------------------

### Build a Specific Package

Source: https://github.com/facebook/immersive-web-sdk/blob/main/README.md

Build a single package, for example, the core SDK, using pnpm with a filter.

```bash
pnpm --filter @iwsdk/core build
```

--------------------------------

### Enable and Configure Grabbing System

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/concepts/grabbing/index.md

This example shows how to enable the grabbing system and create a one-hand grabbable entity with rotation and translation constraints. Ensure the 'enableGrabbing' feature is set to true when initializing the World.

```typescript
import { World, SessionMode } from '@iwsdk/core';
import { Interactable, OneHandGrabbable } from '@iwsdk/core';

// Enable grabbing system
World.create(document.getElementById('scene-container'), {
  xr: {
    sessionMode: SessionMode.ImmersiveVR,
  },
  features: {
    enableGrabbing: true, // This enables the grab system
  },
}).then((world) => {
  // Create grabbable object
  const entity = world.createTransformEntity(mesh);
  entity.addComponent(Interactable);
  entity.addComponent(OneHandGrabbable, {
    rotate: true,
    translate: true,
    rotateMin: [-Math.PI / 4, -Math.PI, -Math.PI / 4],
    rotateMax: [Math.PI / 4, Math.PI, Math.PI / 4],
  });
});
```

--------------------------------

### Run Production Build with Vite

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/08-build-deploy.md

Execute this command in your project directory to create an optimized static site in the `dist/` folder.

```bash
npm run build
```

--------------------------------

### Get Full Device State

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/starter-assets/PROJECT_CLAUDE.md

Retrieves the complete state of all XR devices, including the headset, controllers, and hands.

```bash
mcp__iwsdk-runtime__xr_get_device_state
```

--------------------------------

### Get Level Root Entity

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/05-environment-lighting.md

Retrieve the root entity of the active level to attach environment lighting components.

```javascript
const levelRoot = world.activeLevel.value;
```

--------------------------------

### Create a System with Queries and Config

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/concepts/ecs/index.md

Define a system using `createSystem`, specifying required components for queries and configuration options that become reactive signals.

```typescript
export class DamageSystem extends createSystem(
  {
    ticking: { required: [Health, DamageOverTime] },
  },
  {
    tickRate: { type: Types.Float32, default: 10 },
  },
) {
  private timeAcc = 0;

  init() {
    this.queries.ticking.subscribe('qualify', (e) =>
      console.log('Damage starts', e.index),
    );
  }

  update(dt: number) {
    this.timeAcc += dt;
    const step = 1 / this.config.tickRate.peek();
    while (this.timeAcc >= step) {
      this.timeAcc -= step;
      for (const e of this.queries.ticking.entities) {
        const dps = e.getValue(DamageOverTime, 'dps')!;
        const cur = e.getValue(Health, 'current')!;
        e.setValue(Health, 'current', Math.max(0, cur - dps * step));
      }
    }
  }
}
```

--------------------------------

### Initialize World with Configuration

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/starter-assets/claude-injections/skills/iwsdk-planner/SKILL.md

Configure and create a new world instance with specified rendering, assets, level, XR settings, and feature systems. Ensure only necessary features are enabled for optimal performance.

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

const world = await World.create(container, {
  render: {
    fov: 50,
    near: 0.1,
    far: 200,
    defaultLighting: true, // Auto-creates DomeGradient + IBLGradient on level roots
    stencil: false, // Enable stencil buffer if needed
  },

  assets: {
    myModel: { url: '/models/scene.glb', type: AssetType.GLTF },
  },

  level: '/glxf/MyScene.glxf',

  xr: {
    sessionMode: SessionMode.ImmersiveVR,
    referenceSpaceType: 'local-floor',
    requiredFeatures: ['hand-tracking'],
    optionalFeatures: ['plane-detection'],
    offer: 'once', // 'none' | 'once' | 'always' (default: 'always')
  },

  // Enable feature systems - ONLY what you need!
  features: {
    locomotion: true, // Only if scene has collision geometry
    // OR object form:
    // locomotion: {
    //   useWorker: true,
    //   initialPlayerPosition: [0, 0, 0],
    //   comfortAssist: 0.5,
    //   turningMethod: TurningMethod.SnapTurn,
    //   enableJumping: true,
    // },
    grabbing: true, // Only if objects are grabbable
    // OR object form: grabbing: { useHandPinchForGrab: true },
    physics: true, // Only if using dynamic physics
    sceneUnderstanding: true, // OR: { showWireFrame: true }
    environmentRaycast: true, // AR hit-test against real-world surfaces
    camera: true, // Camera video access (requires XR session)
    spatialUI: {
      forwardHtmlEvents: true,
      preferredColorScheme: 'dark',
    },
  },
});

// Register custom systems
world.registerSystem(MySystem);

// Launch/exit XR
world.launchXR();
world.exitXR();
```

--------------------------------

### Define a Custom System with Queries and Config

Source: https://github.com/facebook/immersive-web-sdk/blob/main/docs/guides/07-custom-systems.md

Create a system using `createSystem`, defining regular, excluded, and value-predicate queries, along with an optional configuration schema.

```typescript
import { createSystem, eq, Types } from '@iwsdk/core';

export class MySystem extends createSystem(
  {
    // Regular query - entities with specific components
    myQuery: { required: [ComponentA, ComponentB] },

    // Query with exclusion - has ComponentA but NOT ComponentC
    specialQuery: { required: [ComponentA], excluded: [ComponentC] },

    // Query with value predicate - matches specific component values
    configQuery: {
      required: [PanelUI, PanelDocument],
      where: [eq(PanelUI, 'config', '/ui/welcome.json')],
    },
  },
  {
    // Optional config schema - system-level configuration
    speed: { type: Types.Float32, default: 1.0 },
    enabled: { type: Types.Boolean, default: true },
  },
) {
  // System implementation
}
```

--------------------------------

### Reload Browser Page

Source: https://github.com/facebook/immersive-web-sdk/blob/main/packages/starter-assets/PROJECT_CLAUDE.md

Reloads the browser page to reset the application state. Useful for starting fresh or after significant changes.

```bash
mcp__iwsdk-runtime__browser_reload_page
```

--------------------------------

### Create New Immersive Web SDK Project

Source: https://github.com/facebook/immersive-web-sdk/blob/main/README.md

Use this command to scaffold a new project with the Immersive Web SDK.

```bash
npm create @iwsdk@latest
```