hz-new-project-creation

新規プロジェクト作成スキル

ビルドパスを選択した後、Meta VR プロジェクトをゼロから作成し、設定します。このスキルでは、Meta VR ハードウェア向けに最適化された推奨設定を含む、ステップごとのセットアップ手順を説明します。

このスキルを使用するタイミング

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

• ビルドパスを選択した後、Meta Quest（Quest 2、Quest 3、Quest 3S、Quest Pro）および Meta VR Glasses を対象とする新しいプロジェクトを作成する
• Meta VR 向けに、適切なレンダリング設定、SDK バージョン、ビルドターゲットをプロジェクトに設定する
• 推奨アーキテクチャとフォルダー構成でプロジェクトテンプレートをセットアップする
• Standard Android、Meta Spatial SDK、Unity、Unreal Engine、または WebXR のいずれかを選択した後に、そのセットアップワークフローに従う

前提条件

Meta VR プロジェクトを作成する前に、プラットフォームにかかわらず、次の手順を完了してください。

1. Meta 開発者アカウントを作成する -- developer.meta.com で登録し、組織を作成します。
2. Meta VR デバイスを開発用にセットアップする -- スマートフォンの Meta Horizon アプリで、ヘッドセットの設定から開発者モードを有効にします。
3. USB デバッグを有効にする -- Meta VR デバイスを USB-C で接続し、ヘッドセットを装着して、「USB デバッグを許可」のプロンプトを承認します。
4. metavr をインストールする -- スタンドアロンの metavr CLI バイナリを PATH にインストールします（metavr-cli スキルを参照）。または、インストールせずに npx で必要に応じて実行します。

   metavr --version
   

   以下の例では metavr コマンドをそのまま使用しています。npm ディストリビューションを使用する場合は、先頭に npx -y を付けてください。

プロジェクトを開始する前に、デバイスの接続を確認してください。

metavr device list

選択したビルドパスから開始する

スキャフォールディングを行う前に hz-quest-verify-first を使用して、ビルドパスを特定してください。機能のチェックリストを基準に SDK を選択しないでください。複数のパスで似た Meta VR 機能を利用できますが、プロジェクト構成とランタイムモデルは異なります。

ビルドパス	選択する条件	セットアップの参考資料またはスキル
Standard Android	アプリの中心が、サイズ変更可能な 1 つの Horizon OS パネル内に表示する 2D UI であり、Jetpack Compose、Android Views、React Native、または Expo で実装する場合です。新しい 2D アプリではこれが既定です。Spatial SDK は不要です。	Standard Android プロジェクト。React Native または Expo には hz-react-native-expo を使用してください
Meta Spatial SDK	没入型シーン、3D エンティティ、環境制御、または 2D と 3D を組み合わせたコンテンツが必要なアプリの場合です。	Spatial SDK プロジェクト
Unity	C# で構築する没入型ゲームまたは体験の場合です。	Unity プロジェクト
Unreal Engine	C++ または Blueprints で構築する没入型プロジェクトの場合です。	Unreal プロジェクト
IWSDK / WebXR	ブラウザーで実行する、または Web アプリとして配信する Web ベースの体験の場合です。	Web プロジェクト

プラットフォームの選択後

ユーザーがプラットフォームを選択したら、詳細な手順に沿ってプロジェクトをセットアップするため、該当するリファレンスガイドを参照してください。

• Unity（Meta VR） -- プロジェクトを作成するには、必ず metavr_unity_setup MCP ツールを使用してください。Unity CLI を直接実行してはいけません。Package Manager／XR Plug-in Management の手順を手動で案内してはいけません。Unity プロジェクトのセットアップを参照してください。手動での代替手順は、MCP ツールを利用できない場合に限り、unity-project-manual.mdを参照してください。（注：このガイダンスは Meta VR の Unity プロジェクトにのみ適用されます。VR 以外の Unity プロジェクトでは、通常どおり Unity Hub を使用してください。）
• Unreal Engine -- Unreal プロジェクトのセットアップ
• 標準 Android -- 標準 Android プロジェクトのセットアップ。React Native または Expo で UI を実装する場合は、hz-react-native-expo を使用してください。
• Meta Spatial SDK -- Spatial SDK プロジェクトのセットアップ
• Web／IWSDK／WebXR -- Web プロジェクトのセットアップ

各リファレンスでは、次の内容を説明しています。

1. 必要なツールと SDK のバージョン
2. プロジェクトの作成手順
3. Meta VR 向けの推奨プロジェクト設定
4. ビルドとデプロイのワークフロー
5. テストと反復開発のワークフロー

注意点

Meta VR プロジェクトを新しくセットアップするときによくある落とし穴を紹介します。

• Android API レベルの不一致 -- 新しいイマーシブプロジェクトでは、最小 API を 32、ターゲット API を 34 に設定して開始してください。ストアで受け入れられる最小レベルについては hz-store-submit を、現在のターゲット範囲については hz-api-upgrade を確認してください。イマーシブアプリと 2D パネルアプリでは要件が異なります。API レベルを誤って設定すると、ビルドをインストールまたはアップロードできないことがあります。Unity の既定値はこれらの要件に合わない場合があるため、Player Settings > Other Settings と metavr docs search "target API" で必ず確認してください。
• ARM64 のみで、x86 は使用しない -- Meta VR デバイスは ARM64（aarch64）です。ビルドパイプラインが x86 をターゲットにしている場合や、x86 のネイティブライブラリを含んでいる場合、APK はインストールできますが、起動直後にクラッシュします。Unity では「Target Architectures」で ARM64 のみが選択されていることを確認してください。Android Studio では ABI フィルターを確認してください。
• Gradle のバージョン互換性 -- Meta の Android および Spatial SDK のサンプルでは、互換性のある Gradle、Android Gradle Plugin、Kotlin、KSP の各バージョンが固定されていることがよくあります。現在の公式テンプレートまたはサンプルからバージョン一式をまとめてコピーしてください。いずれかを個別にアップグレードすると、原因の特定が難しいビルドエラーが発生することがあります。
• Unity のバージョンは重要です -- すべての Unity バージョンが最新の Meta XR SDK と互換性があるわけではありません。サポートされている Unity のバージョン範囲は、Meta XR SDK のリリースノートで確認してください。サポート対象外の Unity バージョンを使用すると、原因の特定が難しい C# コンパイルエラーや、実行時の XR サブシステム不足のエラーが発生します。
• Vulkan と OpenGL ES -- Quest 3 は Vulkan に対応しており、最高のパフォーマンスを得るために Vulkan が推奨されています。Quest 2 も Vulkan に対応していますが、以前の一部の Meta XR SDK 機能には Vulkan 固有のバグがありました。Vulkan を使用した Quest 2 でレンダリングの乱れが見られる場合は、代替として OpenGL ES 3.0 を試し、バグを報告してください。
• Android マニフェストの権限不足 -- Meta VR 固有の機能（ハンドトラッキング、パススルー、シーン理解、アイトラッキング）には、マニフェストでの明示的な権限設定が必要です。適切な権限がないと、アプリからこれらの機能にアクセスできず、エラーも表示されません。SDK が自動で権限を追加することはありません。
• 初回ビルド前にパッケージ名を設定し忘れる -- デバイスに初めてインストールした後でパッケージ名を変更すると、データが失われたり、インストールに失敗したりすることがあります。初回のビルドとデプロイの前に、正しい com.company.appname パッケージ名を設定してください。
• Unreal Engine：OpenXR と OVRPlugin -- Unreal は Quest 向けに OpenXR バックエンドと従来の OVRPlugin バックエンドの両方をサポートしています。新しいプロジェクトでは OpenXR を使用してください。同じプロジェクト内でプラグインを併用すると、動作が不定になります。

セットアップ後によく行う作業

どのプラットフォームでも、プロジェクトの作成と設定が完了した後は、通常、次の作業が必要です。

Developer Dashboard へのアプリ登録

developer.meta.com でアプリのエントリーを作成し、App ID を取得します。権限チェック、マルチプレイヤー、実績、ストアへの提出など、プラットフォームの機能を利用するために必要です。

バージョン管理の設定

Git リポジトリを初期化し、選択したプラットフォームに合わせて .gitignore を設定します。

git init
# Use a platform-appropriate .gitignore (Unity, Unreal, Android, or Node.js)

最初のビルドとデプロイ

プロジェクトをビルドし、接続されている Meta VR デバイスにインストールします。

# After building, install the APK
metavr app install path/to/build.apk

# Launch the app
metavr app launch com.yourcompany.yourapp

# Monitor logs during first run
metavr adb logcat --follow --tag yourapp

パフォーマンスのベースライン

初回の実行に成功したら、アプリケーションがベースラインのパフォーマンス目標を満たしていることを確認します。

• フレームレート：最低 72 Hz（Quest 3 では 90 Hz または 120 Hz が推奨されます）
• フレームタイミング：スパイクのない安定したフレームタイム
• 熱状態：通常の使用中に熱スロットリングの警告が発生しないこと

参考資料

スキルの参考資料

• Unity プロジェクトのセットアップ -- metavr_unity_setup MCP ツールによる Unity プロジェクトのワンショットセットアップ
  • Unity の手動セットアップ（代替手順） -- ステップごとの手動設定。MCP ツールを利用できない場合にのみ必要です
• Unreal プロジェクトのセットアップ -- Unreal Engine プロジェクトの作成と設定をステップごとに解説します
• 標準 Android プロジェクトのセットアップ -- イマーシブ SDK を使わずに 2D Horizon OS パネルアプリを作成します
• Spatial SDK プロジェクトのセットアップ -- Meta Spatial SDK を使用してイマーシブまたはハイブリッド Android アプリを作成します
• Web プロジェクトのセットアップ -- IWSDK/WebXR プロジェクトの作成と設定をステップごとに解説します