hz-iwsdk-webxr

IWSDK WebXR スキル

Meta の Immersive Web SDK（IWSDK）を使用して、Meta VR 向けの没入型 WebXR 体験を構築します。このスキルでは、現在のパッケージ構成、ECS アーキテクチャ、 Three.js との統合、空間 UI の開発、XR 入力の処理、Vite ベースの推奨開発 ループについて説明します。

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• IWSDK を使用して、Meta VR 向けの WebXR 体験を構築する
• Three.js の上に構築された ECS アーキテクチャを使用して 3D シーンを作成する
• UIKitML と PanelUI を使用して空間 UI パネルを設計する
• コントローラー、手、ワールド空間ポインターからの XR 入力を処理する
• IWSDK アプリの編集、再読み込み、確認、修正を繰り返すワークフローを実行する
• Meta VR ハードウェア向けに WebXR のパフォーマンスを最適化する
• IWSDK の Vite 開発ツールと Quest Browser を使用して WebXR アプリケーションをデバッグ、テストする

このスキルは、視線とピンチ操作で入力する Meta VR Glasses、および Quest Browser を搭載したすべての Meta Quest ヘッドセットに適用されます。

IWSDK とは

Immersive Web SDK（IWSDK）は、WebXR 体験を構築するための Meta のフレームワークです。次の機能を提供します。

• エンティティ・コンポーネント・システム（ECS）：型付きコンポーネントストレージとクエリ駆動型システムを基盤とする、データ指向のアーキテクチャ
• Three.js との統合：IWSDK がレンダラー、シーン、カメラ、XR セッションのライフサイクルを管理するため、アプリのコードはコンテンツに集中できます
• 空間 UI ツールキット：ワールド空間およびスクリーン空間の UI に対応する UIKitML と PanelUI、PanelDocument、UIKitDocument
• XR 入力管理：コントローラー、ハンドトラッキング、ポインター、グラブ操作を統一して処理します
• 移動とインタラクションのシステム：オプトインで利用できるグラブ、テレポート、スライド、旋回機能
• アセット管理：マニフェストに基づく事前読み込みと、AssetManager を介したキー指定によるアクセス

IWSDK は、WebXR Device API を介してブラウザーで動作します。アプリケーションは標準的な Web ページであり、通常は開発中に Vite で配信し、デバイス上での検証には Quest Browser で開きます。

現在のパッケージ構成とツール

以前のプレリリース版向けの手順は現在では正しくないため、次の点が重要です。

• メインのランタイムパッケージは @iwsdk/core です
• 公式のスキャフォールドコマンドは npm create @iwsdk@latest です
• デフォルトの開発ループでは @iwsdk/vite-plugin-dev を使用します
• ローカル HTTPS は通常、vite-plugin-mkcert で処理します
• 現在の IWSDK パッケージには Node.js >=20.19.0 が必要です
• @iwsdk/core は @iwsdk/xr-input と @iwsdk/locomotor を再エクスポートします

クイックスタート

1. 新しいプロジェクトを作成する

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

公式の作成フローから開始する場合は、依存関係のインストールと git の初期化も実行できます。

2. 依存関係をインストールする

npm install

手動でセットアップする場合は、古い @meta-quest/iwsdk パッケージの代わりに、@iwsdk/core、three、@iwsdk/vite-plugin-dev、vite-plugin-mkcert を使用してください。

3. 開発サーバーを起動する

npm run dev

標準的な IWSDK Vite セットアップでは、安全なローカル開発サーバー、ホットモジュール置換、および @iwsdk/vite-plugin-dev を介したエミュレーター／開発ブラウザーのワークフローが利用できます。

4. XR でテストする

通常、検証方法は次の 2 つです。

• Quest Browser：ヘッドセットで安全な開発 URL を開き、そこで XR を起動します
• IWSDK 開発ツール：Vite プラグインのエミュレーター／開発ブラウザーを使用して、デスクトップ上ですばやく反復します

Quest Browser でのテストには HTTPS が必要です。デスクトップではアプリが動作するのに、デバイス上で XR を開始できない場合は、開発サーバーの URL が安全で、ヘッドセットからアクセス可能であることを確認してください。それでも XR を開始できない場合は、ヘッドセットで metavr log を実行すると、失敗したチェック（HTTPS、WebXR フラグ、GPU プロセス）が示されることがよくあります。

AI 支援開発ループ

IWSDK は、開発ループがすでに Web ネイティブであるため、コーディングエージェントに適しています。ソースを編集し、ページを再読み込みして、動作を確認しながら反復できます。

推奨されるループ：

1. コーディングを始める前に、最新のドキュメントで API とプラットフォームの詳細を確認します
2. コードを編集し、Vite 開発サーバーを実行します
3. Quest Browser または IWSDK エミュレーター／開発用ブラウザーで再読み込みします
4. ログ、スクリーンショット、ランタイムの状態を確認します
5. ランタイムの動作がリクエストに合うまで反復します

ネイティブの Meta VR フロントエンドとホスト側のコーディングエージェントを組み合わせる場合は、フロントエンドを薄く保ちます。リポジトリの管理、ファイル編集、依存関係のインストール、テスト、ビルド手順、metavr ツールの呼び出しはホストマシンに任せます。

プロジェクト構成

一般的な IWSDK プロジェクトは次のようになります。

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

主なパターン

コンポーネントの作成

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',
);

システムの作成

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;
    });
  }
}

Three.js メッシュを使ったエンティティの生成

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 });
}

ワールドの作成と 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(...) は、レンダラー、コアシステム、アセットの読み込み、レンダーループをすでに設定します。エージェントに new World()、createWorld()、world.start()、または旧式の enterXR(...) を使うよう教えないでください。

注意点

Meta VR 向けの IWSDK WebXR アプリを構築する際、予期しない失敗やデバッグ時間の浪費につながるよくある落とし穴を紹介します。

• デバイス上の WebXR には HTTPS が必要です -- WebXR Device API は HTTPS（または localhost）経由でのみ動作します。開発ビルドを通常の HTTP で配信し、Quest Browser で開くと、「Enter VR」ボタンが表示されません。開発中に HTTPS をトンネルするには、ngrok、自己署名証明書、または Vite の --https フラグを使用してください。
• Quest Browser はデスクトップ Chrome ではなく Chromium です -- 機能のサポート状況が異なります。SharedArrayBuffer、一部の WebGL2 拡張機能、OffscreenCanvas の動作が異なったり、利用できなかったりする場合があります。IWER エミュレーターを使ったデスクトップ Chrome だけでなく、必ず実際の Quest Browser でもテストしてください。
• デフォルトは 90 Hz ではなく 72 Hz です -- Quest Browser の WebXR セッションは、デフォルトで 72 Hz です。セッション開始後に xrSession.updateTargetFrameRate(90) を呼び出して、明示的に高いフレームレートを要求する必要があります。これを忘れると、WebXR アプリがネイティブビルドと比べて「動作が遅い」と感じられることが最もよくあります。
• ドローコールの予算はネイティブよりかなり少なくなります -- Quest 2 では 50～80 回未満、Quest 3 では 100～120 回未満を目指してください。ドローコールあたりの JavaScript オーバーヘッドは、ネイティブより大きくなります。ジオメトリをバッチ化し、インスタンスレンダリングを使用して、マテリアルを積極的に統合してください。
• テクスチャメモリの制限 -- Quest Browser の GPU メモリ上限は、ネイティブアプリより低くなっています。大きな非圧縮テクスチャ（4K 以上）は、無言の OOM クラッシュや表示の破損を引き起こす場合があります。圧縮テクスチャ（Basis Universal または ETC2 を使用した KTX2）を使い、テクスチャメモリの合計を 256 MB 未満に抑えてください。
• requestAnimationFrame と XR フレームループ -- XR セッション開始後は、window.requestAnimationFrame ではなく xrSession.requestAnimationFrame を使用する必要があります。誤った方を使うと、シーンがフリーズしたり、誤ったレートでレンダリングされたりします。
• ハンドトラッキングのピンチしきい値 -- WebXR ハンドトラッキング API は、ピンチを連続値（0.0～1.0）として報告します。多くの開発者はしきい値を 0.5 に設定しますが、Meta VR デバイスで安定して有効化されるしきい値は、0.7～0.8 に近い値です。しきい値が低いと、特に指差しジェスチャー中に誤検出が発生します。
• HMR によって XR セッションが壊れる場合があります -- ホットモジュール置換が、WebXR セッションの適切な終了と再作成に失敗することがあります。HMR 更新後にシーンが真っ暗になった場合は、原因不明のレンダリング問題を調べるのではなく、ページ全体を再読み込みしてください。
• CORS によって VR でのアセット読み込みがブロックされます -- CDN から GLTF／GLB モデルやテクスチャを読み込む際は、適切な CORS ヘッダーが設定されていることを確認してください。Quest Browser は CORS を厳密に適用します。ヘッダーがないとアセットの読み込みが無言で失敗し、DevTools を接続しないと診断が困難です。
• canvas のみの WebXR ページでは、LCP に依存する結果を Lighthouse で取得できません -- <canvas> が LCP 候補になることはないため、Lighthouse の largest-contentful-paint、interactive／TTI、total-blocking-time の監査は LanternError: NO_LCP で中断します。CDP のロングタスクとネットワークデータから TTI を自分で算出し、ハードウェア ANGLE バックエンド（Windows では --use-angle=d3d11、Linux では --use-angle=gl）を使ってヘッドレス Chromium を起動してください。そうしないと、実際のフレーム時間の 10 倍かかる SwiftShader ソフトウェアラスタライザーで、気付かないままプロファイルが行われます。デスクトップの読み込みプロファイリングを参照してください。

開発のヒント

• ランタイムの制御には World.create(...)、world.launchXR()、world.exitXR() を使用します
• Quest Browser での開発では、WebXR がセキュアコンテキストに制限されるため、HTTPS を有効にしておきます
• まず @iwsdk/vite-plugin-dev と Quest Browser で検証し、その後、より高速に反復できるようエミュレーター／開発用ブラウザのワークフローを追加します
• 最近検証していない API を使ってコーディングする前に、Meta のドキュメントを検索して取得します
• デスクトップエミュレーションでは入力、快適性、パフォーマンスに関する問題をすべて把握できないため、早い段階から頻繁に実際の Meta VR デバイスでテストします
• Meta VR ハードウェアで滑らかに動作するよう、ドローコールを少なく（おおよそ 100 回未満に）抑えます

参考資料

スキルリファレンス

• AI 支援開発 -- クローズドループの編集／再読み込み／観察ワークフロー、Quest Browser のテスト、ホストエージェントのアーキテクチャ
• ECS アーキテクチャ -- コンポーネント、エンティティ、システム、クエリ、World
• 空間 UI -- UIKitML、PanelUI、PanelDocument、レイアウト、UI のベストプラクティス
• 入力処理 -- コントローラー、手、ポインター、つかむ操作、移動
• パフォーマンスのヒント -- フレームレートの目標、最適化手法、プロファイリングツール
• デスクトップ負荷のプロファイリング -- ヘッドレスの Playwright／Lighthouse、キャンバスのみのページの TTI の算出、ハードウェア GPU フラグ