Claude Media
Claude CodeにMeta VRプラグインを入れる — Questアプリ開発の使い方
Claude CodeClaude連携チュートリアル

Claude CodeにMeta VRプラグインを入れる — Questアプリ開発の使い方

Meta公式のmeta-vrプラグインは、Quest・Horizon OSアプリ開発向けのスキル群とmetavr CLIを束ねます。導入手順、ビルド経路ごとのスキルの選び方、ストア提出までの流れを扱います。

読了目安 約24分

meta-vrプラグインは、Meta Platforms, Inc.が公開しているQuest・Horizon OSアプリ開発向けのプラグインです。Claude Codeに入れると、Spatial SDK、Unity、WebXRといった開発経路ごとのスキルと、実機を操作するmetavr CLIの使い方が加わります。バージョンは2.0.0、ライセンスはApache-2.0です。

先に押さえておく点が1つあります。プラグインの中身は手順書(スキル)で、実機の操作は別途入れるmetavr CLIが担います。CLIを入れずにプラグインだけ入れても、実機に触れる作業は進みません。

meta-vrプラグインが束ねる3つの部品

リポジトリのREADMEは、これを「Meta VRとHorizon OS開発向けのエージェント用スキルとツール」と説明しています。中身は次の3つです。

構成

プラグインの構成

  • スキル群

    Spatial SDK、Unity、WebXR、Platform SDK、ストア提出、性能調査などの手順書です。必要な場面でClaude Codeが読み込みます。

  • metavr CLI

    実機の一覧、アプリのインストール、ログ、スクリーンショット、Perfettoトレースの取得、ドキュメント検索までを1本のコマンドにまとめたCLIです。

  • metavr MCPサーバー

    CLIの機能をMCP経由で呼べるようにしたものです。READMEでは40以上のツールを持つと説明されています。

プラグインのルートには、npx -y metavr mcp serverでMCPサーバーを起動する.mcp.jsonが置かれています。Claude Codeはプラグインルートの.mcp.jsonを読み込むので、導入後は/mcpでmetavrが並んでいるかを見ると、MCPが有効になったかどうかが分かります。

導入手順 — CLIを先に、プラグインを後に

順序は「metavr CLI → プラグイン → 実機の準備」です。

手順

導入の流れ

  1. 1

    metavr CLIを入れる

    macOS・Linuxはインストーラー、WindowsはPowerShellのインストーラー、またはnpm経由のnpx -y metavrが選べます。

  2. 2

    プラグインを入れる

    Claude Codeのセッションでマーケットプレイスを追加し、プラグインを入れます。

  3. 3

    実機をつなぐ

    Developer Modeを有効にしたQuestをUSBでつなぎ、metavr device listで見えるかを確かめます。

CLIの入れ方は、READMEに次の形で載っています。

# macOS・Linux
curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh
 
# インストールなしで試す場合(Node.js 16以上)
npx -y metavr --version

npx経由で使う場合、READMEのコマンド例にあるmetavrはnpx -y metavrに読み替えます。スタンドアロン版はmetavr updateで更新できます。

プラグインの導入は、Claude Codeのセッション内で次の2行です。

/plugin marketplace add meta-quest/agentic-tools
/plugin install meta-vr@meta-vr

/plugin installはセッション内では即時には入らず、プラグインの詳細パネルが開きます。そこで内容を確認し、スコープを選んで導入します。マーケットプレイスの追加と@の後ろの名前の関係は、プラグインマーケットプレイスの必須化と自動更新の記事で整理しています。

シェルから一括で進めたい場合は、metavr initが使えます。READMEによると、インストール済みのエージェントを検出し、スキルとmetavr MCPサーバーをまとめて設定します。MCPだけ入れたいときはmetavr mcp install claude-codeです。

実機の前提

実機を使うスキルには、共通の前提があります。

  • 実機でDeveloper Modeを有効にしている(Meta Horizonアプリの端末設定から)
  • データ転送に対応したUSB-Cケーブルでつないでいる(充電専用ケーブルは不可)
  • 初回接続時に、ヘッドセット側で「USBデバッグを許可」を承認している

metavr device listが空のときは、この3点を上から見直します。

どのスキルが働くか — ビルド経路で決まる

Quest向けの開発には、Androidアプリ、Spatial SDK、Unity、Unreal、ネイティブOpenXR、WebXRという6つの経路があります。プラグインはまず経路を分類し、経路ごとのスキルに振り分けます。この分類役がhz-quest-verify-firstです。

ビルド経路見分けるサイン担当スキル
通常のAndroid見分けるサインActivity、Compose、React Native、Expo担当スキルhz-android-2d-porting、hz-react-native-expo
Meta Spatial SDK見分けるサインcom.meta.spatialの依存担当スキルhz-spatial-sdk
Unity見分けるサインUnityプロジェクト、com.meta.xr.*担当スキルhz-unity-project-analyzer、hz-unity-meta-core-sdk
Unreal Engine見分けるサイン.uproject担当スキル新規作成のみhz-new-project-creation。専用スキルなし
ネイティブOpenXR見分けるサインNDKからOpenXRローダーを直接使う担当スキル専用スキルなし
WebXR見分けるサインIWSDK、ブラウザ配信担当スキルhz-iwsdk-webxr、hz-store-pwa

信号が重なったときの優先順位も決まっています。com.meta.spatialがあればSpatial SDK、次にUnity、Unreal、ネイティブOpenXR、WebXR、残りが通常のAndroidです。通常のAndroidアプリは、Questを対象にしただけではSpatial SDKに載せ替えません。

経路をまたぐ共通のスキルもあります。実機の不具合調査はhz-vr-debug、性能はhz-perfetto-debugとhz-simpleperf-debug、ストア提出はhz-store-submit、SDKの更新はhz-api-upgradeが受け持ちます。

hz-quest-verify-first — 記憶で答えさせない仕組み

この中で最も特徴的なのがhz-quest-verify-firstです。説明文は「Quest関連の質問に答える前、コードを書く前の必須の事前確認」とされ、Quest関連のプロジェクトでは自動で読み込まれる設計になっています。

理由はスキル本文に書かれています。Metaのドキュメントは更新が速く、SDKは数週間単位で出て、APIは公開前に改名されます。学習データのまま答えると、非推奨のAPIや、ストアで弾かれるAndroidManifestを出してしまうという前提です。

確認の流れは4段階です。

  1. ビルド経路を分類する
  2. vr_docs_search(MCP)またはmetavr docs search(CLI)で公式ドキュメントを引く
  3. metavr device listで、実際につながっている端末を確かめる
  4. 使えるサブコマンドが不明ならcli_helpで調べ、フラグを作り上げない

たとえば、旧来のOVR名前空間や「Oculus Integration」パッケージを案内しがちな点が、失敗例として挙げられています。Unityのメニュー経路やパッケージ名が版ごとに変わる点も同じです。確認なしで書かせるより、まずドキュメント検索を挟ませるほうが、Quest固有の記述では外しにくくなります。

MCPが入っていない環境では、同じ確認をmetavr docs search "<query>"で行います。条文のような正確さが要る箇所(マニフェストの権限名、ストアポリシーなど)は、検索結果の抜粋を言い換えず、metavr docs fetchで全文を取るよう求めています。

Claude Code側の設定 — 読み取りは許可、書き込みは確認

スキルとは別に、Claude Code側で持っておきたい設定があります。metavrは実機にアプリを入れ、ファイルを消し、ストアへビルドを上げられるCLIです。読み取り系は自動承認、破壊的な操作は毎回確認という分け方が現実的です。

{
  "permissions": {
    "allow": [
      "Bash(metavr device list)",
      "Bash(metavr log *)",
      "Bash(metavr docs *)",
      "Bash(metavr perf *)"
    ],
    "ask": [
      "Bash(metavr app uninstall *)",
      "Bash(metavr files rm *)",
      "Bash(metavr store dist upload *)"
    ]
  }
}

ルールの書式は、Claude Codeの権限設定の仕様に沿っています。*を末尾に置くとサブコマンド以降の引数に一致し、askはallowより優先されます。許可と確認の振り分けは一例です。チームの運用に合わせて入れ替えてください。

プロジェクトのCLAUDE.mdには、スキルが拾えない前提を短く書いておきます。

# Quest開発の前提
- ビルド経路: Meta Spatial SDK(Kotlin)
- 対象端末: Quest 3 / Quest 3S
- パッケージID: com.example.mytool
- Quest固有のAPI・マニフェスト・ストア要件は、記憶で答えず
  metavr docs search で確かめてから書く
- 実機へのインストールは metavr app install を使い、adb を直接叩かない

ビルド経路とパッケージIDが書いてあれば、経路の分類で迷う回数が減ります。

Spatial SDKでKotlinアプリを作る

Kotlinで書くネイティブな空間アプリにはhz-spatial-sdkが使われます。Spatial SDKはAndroidのActivityライフサイクルの上に乗り、アプリは通常のAPKとして配布されます。UnityやUnrealのエンジンとは別の立ち位置です。

スキルが説明する要素は次のとおりです。

要素役割
Entity役割コンポーネントをまとめるID。単体では振る舞いを持たない
Component役割エンティティに付けるデータ(Transform、Mesh、Panelなど)
System役割SystemBaseを継承し、execute()で毎フレーム実行するロジック
Panel役割Jetpack ComposeやViewで描く2D UI。空間内の面として表示される

パネルの登録は、スキルが次の形で示しています。公式の例に沿った形です。

override fun registerPanels(): List<PanelRegistration> {
  return listOf(
    ComposeViewPanelRegistration(
      registrationId = R.id.main_panel,
      composeViewCreator = { _, context ->
        ComposeView(context).apply { setContent { MainScreen() } }
      },
      settingsCreator = {
        UIPanelSettings(
          shape = QuadShapeOptions(width = 0.8f, height = 0.6f),
          display = DpDisplayOptions(width = 592f, height = 444f),
        )
      },
    )
  )
}

設計上の注意も書かれています。ツール型のアプリでは、AppSystemActivityのサブクラスを1つだけ置き、シーン、パネル、ECSのシステムをその中に持たせるのが基本です。通常のAndroidアプリのようにActivityを増やすのは、特別な理由があるときに限ります。UIの状態は、同じActivityの中で切り替えます。

前提として、Android Studioに「Meta Horizon」プラグインを入れる必要があります。3Dシーンを視覚的に組むSpatial Editorもこのプラグインに含まれ、.glxfファイルを出力します。ビルドと実機への配置は、GradleでAPKを作り、metavr app installで入れてmetavr app launchで起動する流れです。

Unityプロジェクトを性能の観点でレビューさせる

Unityの場合、hz-unity-code-reviewがC#コードとプロジェクト設定のレビュー観点を持っています。Meta VRの新規プロジェクトでは、Universal Render Pipelineを前提に、次のような設定を点検対象にします。

  • Single-pass multiviewを有効にする
  • Vulkanを主要なグラフィックスAPIにする
  • カラースペースはLinear、URPのHDRは無効
  • ポストプロセスは最小限か無効

描画の負荷は、端末世代ごとのドローコール目安で見ます。スキルが挙げる目安は次のとおりです。

負荷の種類Quest 2 / Quest ProQuest 3 / Quest 3S
重い(busy simulation)Quest 2 / Quest Pro80〜200Quest 3 / Quest 3S200〜300
中程度Quest 2 / Quest Pro200〜300Quest 3 / Quest 3S400〜600
軽いQuest 2 / Quest Pro400〜600Quest 3 / Quest 3S700〜1000

SetPass callsの目安は、Quest 2系が50未満、Quest 3系が80未満です。この数値はスキルに載っている目安で、実際の予算はアプリごとの計測で決めます。

コード側の指摘で多いのは、Update()内のGC割り当てです。Camera.main、GameObject.Find、GetComponent<T>()の毎フレーム呼び出し、LINQ、文字列連結が例に挙がっています。レビューを頼むときは、対象のファイルと「VR向けの観点で」という指定があれば足ります。

Assets/Scripts/ 配下のC#を、Quest 3向けの性能の観点でレビューして。
Update内のGC割り当てとカメラ参照のキャッシュ漏れを優先して。

Unityの実行環境そのものをClaude Codeから動かす方法は、Claude CodeでUnityゲーム開発を進める手順で扱っています。Editorを開いたまま操作する経路はUnity MCPの接続手順にあります。hz-unity-meta-core-sdkは、稼働中のEditorにunity-cliで触れながらOVRManagerやパススルーの設定を進めるスキルです。

性能調査 — Perfettoトレースを取って読む

フレーム落ちの調査にはhz-perfetto-debugが使われます。まず、リフレッシュレートごとの1フレームの予算を押さえておくと、トレースの数字が読みやすくなります。

リフレッシュレート1フレームの予算
120Hz1フレームの予算8.3ms
90Hz1フレームの予算11.1ms
72Hz1フレームの予算13.9ms

予算を外すと、コンポジターは再投影(reprojection)で古いフレームを出します。スキルでは、この古いフレームが全体の10%を超えると深刻な性能問題の目安、と整理されています。

トレースの取得から読み取りまでは、次のコマンドで進みます。

# 前面のVRアプリを10秒、GPUレンダーステージ付きで取得
metavr perf capture --duration 10000 --gpu-render-stage
 
# 取得済みトレースを読み込み、性能の概況を出す
metavr perf load <trace-file>
metavr perf context

perf contextは、CPUとGPUのフレーム時間の統計、スレッドごとの稼働率、検出されたボトルネックをまとめます。深掘りが必要なら、metavr perf queryでPerfettoのSQLを直接実行できます。

SQLを書かせるときの落とし穴も、スキルが先に列挙しています。

  • スレッドの結合にはtidでなくutidを使う(tidは再利用される)
  • タイムスタンプの単位はナノ秒。ミリ秒にするには1e6で割る
  • UnityのPhaseSyncやOpenXRのxrWaitFrameの待ちは、意図したフレームペーシングなので、無駄な時間として報告しない
  • カウンターの値は期間の平均ではなく、その瞬間のサンプル

特に3つ目は、トレースを読む側が誤って「アイドルが多い」と読みやすい箇所です。この注意が最初から入っている点が、スキルを使う価値の一部です。

CPUのホットスポットをさらに掘る場合はhz-simpleperf-debugが、アプリがCPU律速かメモリ律速かI/O律速かの分類から始めます。

ストア提出 — CLIでできる範囲を見誤らない

hz-store-submitは、ビルド検証、ストア要件のチェック、素材の準備、アップロード、審査の追跡までを順に案内します。ここは、CLIの限界がスキルに明記されている点が実用的です。

metavr store dist uploadが担当するのは、リリースチャネルへのビルド配布です。アプリの新規作成、ストア掲載情報の入力、ポリシー質問への回答、審査への提出は含まれません。審査提出はDeveloper Dashboardの操作で、CLIのアップロードが成功しても提出は完了していません。

metavr store dist apps --org <ORGANIZATION_ID>
metavr store dist channels --app-id <APP_ID>
 
# --publish を付けない限り、アップロードは下書き扱い
metavr store dist upload \
  --app-id <APP_ID> \
  --channel ALPHA \
  --apk path/to/release.apk \
  --notes "What changed in this build"

検証中のビルドはALPHA、BETA、RCのいずれかに上げます。LIVEはストアのリリースチャネルに当たりますが、そこに上げても審査提出にはなりません。--publishは、アップロードしたビルドを選んだチャネルに即時公開したいときだけ付けます。metavr store distのコマンドが失敗した場合、IDを変えて再試行せず、Dashboardからアップロードするよう書かれています。

提出前のチェックとして、スキルが挙げる主な項目は次のとおりです。

  • リリース署名のAPK(APK Signature Scheme v2。v1のみは拒否)
  • targetSdkVersionは32以上(2Dパネルアプリは34以上)、minSdkVersionは29以上
  • ARM64のみ。x86やARM32は含めない
  • 起動Activityにcom.oculus.intent.category.VRのインテントカテゴリを宣言する
  • バージョンコードは、過去にアップロードしたどのビルドよりも大きい
  • 禁止されている権限(CALL_PHONE、SEND_SMS、READ_CONTACTS、ACCESS_FINE_LOCATIONなど)は、手動審査の前に自動で却下される
  • 有料アプリは、起動から10秒以内に権利の検証を終える

マージ後のマニフェストは、サードパーティのライブラリが足した権限を含みます。aapt dump permissions <app>.apkで点検するよう勧められています。署名鍵は更新のたびに同じものが必要で、紛失すると新しいアプリとして登録し直すことになります。審査は通常1〜2週間が目安で、休暇期間や再提出、申請の集中で伸びる場合があります。

数値や要件はスキル本文の記述で、ストアの方針は更新されます。提出の直前はmetavr docs searchで最新のポリシーを引き直す運用が、hz-quest-verify-firstの趣旨にも合います。

実機の不具合調査 — ログとスクリーンショット

クラッシュや描画の不具合にはhz-vr-debugが使われます。入口のコマンドは4つです。

metavr device list          # 端末が見えているか
metavr app list             # 入っているアプリ
metavr log --level E -n 500 # エラーレベルのログ
metavr capture screenshot -o view.png

metavr logはadb logcatの短縮形で、--tag Unityのようにタグで絞れます。端末が一覧に出ないときは、ケーブル、Developer Mode、USBデバッグの承認を順に見直します。

つまずきやすい点

落とし穴

metavr CLIが未導入のままスキルだけが動く

プラグインを入れた直後でも、metavrがPATHに無いとスキル内のコマンドが失敗します。metavr --versionが通るかを最初に見ます。npx経由で使うなら、コマンドの先頭にnpx -yを付けます。

  • UnrealとネイティブOpenXRには専用スキルがない: 新規プロジェクトの作成を除き、hz-quest-verify-firstのドキュメント検索で補います
  • アップロードと審査提出は別物: CLIでstore dist uploadが通っても、Dashboardの「Submit for Review」までは完了しません
  • 2Dアプリは要件が一部異なる: 2DのAndroidアプリは、ストア要件が没入型VRの部分集合です。没入型のチェックをそのまま当てはめません
  • テレメトリの設定: metavr telemetryには、同意設定の確認と変更のためのコマンドがあります。社内利用では、状態をmetavr telemetry statusで見ておきます

まとめ

meta-vrプラグインは、手順書と実機操作のCLIを一組にしたものです。Questの開発では、プラグインの価値はhz-quest-verify-firstが記憶ではなく公式ドキュメントを引かせる点と、metavrで実機の確認まで同じ流れで回せる点にあります。入れる順序はCLI、プラグイン、実機で、CLAUDE.mdにビルド経路とパッケージIDを書いておくと、スキルの振り分けが安定します。

権限は、読み取り系だけを自動許可し、アンインストールやストアへのアップロードは確認を挟む構成が扱いやすい形です。ストア提出のCLIは配布までで、審査提出はDashboardで行うことを、チームの手順書にも明記しておくと取り違えを防げます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →