hz-unity-sdk-upgrade

Meta XR Unity SDK のアップグレード

根拠に基づいた移行としてプロジェクトをアップグレードします。パッケージの解決とクリーンなコンパイルはチェックポイントであり、アプリが引き続き動作することの証明ではありません。

検証済みの最短経路を優先します。時間に限りのあるセッションでは、パッケージとプロバイダーの切り替えを完了し、重複する SDK コードを削除し、既知のすべての生成元と利用側を移行してから、任意のクリーンアップやより広範なプラットフォーム検証に進む前にクリーンなコンパイルを達成してください。既知のレガシー利用側やベンダー提供の SDK ファイルが残っている間は、残りの時間を使ってコンパイルが通るプロジェクト設定の調整に費やさないでください。

Unreal、ネイティブ Android、Spatial SDK、WebXR、Immersive Web SDK（IWSDK）、およびクロスプラットフォーム全般のアップグレードには、 hz-api-upgradeを使用してください。

必須のワークフロー

1. Unity アップグレード手順書を読みます。Unity のバージョン、レンダーパイプライン、XR プロバイダー、Meta パッケージ、ベンダー同梱の Assets/Oculus コンテンツ、アセンブリ定義、影響を受けるシーン／プレハブを対象に、範囲を限定した浅い棚卸しを行います。巨大なシリアライズ済みアセットをすべて読み込んだり、完全な GUID マップを作成したりせず、パスとレガシーシンボルを記録します。影響を受けるプロデューサー、コンシューマー、シリアライズ済みアセット、設定、テストをまとめたチェックリストを 1 つ作成し、調査を繰り返したり、重複する棚卸しタスクを開始したりせず、それを更新していきます。
2. パッケージまたは SDK ファミリーのマーカーから、ソースとターゲットの SDK バージョンを特定します。Meta XR パッケージのバージョン、マネージド OVRPlugin API を通じて報告されるバンドル済みネイティブ OVRPlugin のバージョン、Unity エディターのバージョン、XR プロバイダーは、それぞれ独立した要素として扱い、相互に推定してはいけません。いずれかの SDK バージョンが曖昧な場合は、根拠を報告し、その値が推定値であることを明記します。
3. 置き換えを選ぶ前に、metavr で最新のドキュメントを検索します。まず全範囲を対象にしたクエリを 1 件、使用中で影響の大きい各要素を対象にしたクエリを 1 件ずつ実行し、その後、最も関連性の高い信頼できる検索結果を取得します。中間リリースが重要であることがパッケージのメタデータまたは変更履歴から分かった場合に限り、公開済みリリースを個別に検索します。次の移行スライスに関連する公式ガイドと正確なターゲット API のシグネチャを確認したら、そのスライスを実装します。隣接する API の調査を続けず、新たなエラーや未解決のチェックリスト項目が生じた場合にのみ、検索を再開します。
4. 検索結果が見つからない、または関連性がない場合は、ドキュメントのカバレッジ不足として扱います。クエリと結果をアップグレードレポートに記録し、記憶を頼りに不足を補ったり、metavr が返していないガイダンスを見つけたと主張したりしてはいけません。
5. アプリケーションコードより先に、パッケージの構成を更新します。重複したベンダー同梱 SDK コンテンツを削除し、関連する Meta パッケージと、必要なブリッジ／アダプターパッケージをターゲットリリースと互換性のある状態に保ち、XR プロバイダーを意図的に更新し、アセンブリ定義の参照を解決します。パッケージ宣言とシリアライズ済みのローダー／プロバイダー設定の両方を検証します。OpenXR パッケージをインストールしても、そのローダーが有効になるわけではありません。このスライス内で必要なプロジェクトセットアップツールを実行し、完了を待ってから、ベンダー同梱 SDK コードを再スキャンします。インポートやセットアップの自動化によってファイルが再作成される可能性があるためです。パッケージソースの調査や、シーンとプレハブの詳細な移行に進む前に、変更後の最初のコンパイルを実行し、次に何を調査するかはその診断結果に基づいて判断します。
6. パッケージ／プロバイダーのスライスの後と、まとまりのある各移行スライスの後に、以下の重要なコンパイルループを実行します。コンパイルに失敗している状態で、無関係な移行作業をまとめて進めてはいけません。
7. プロデューサーとコンシューマーを一緒に移行します。任意のクリーンアップやプラットフォームのチェックに進む前に、具体的なコンシューマーファイルを列挙し、それぞれを移行済みとして記録します。.cs の呼び出し箇所だけでなく、シーン、プレハブ、シリアライズ済みフィールド、カスタムローダー、エディターツール、テストも検索します。コンパイルを通すためだけに、影響を受けるコンシューマーを削除したり、移行を省略したりしてはいけません。
8. プロジェクトで OVRSceneManager、OVRSceneRoom、OVRSceneAnchor、またはカスタム Scene API ローダーを使用している場合は、編集前にMRUK 移行のベストプラクティスを読み、最終コンパイルの前にその完了チェックリストを実行します。
9. Unity のメジャーバージョン、XR プロバイダー、または Input System の変更を伴う場合は、別個の移行要素として扱います。ビルドターゲットごとのシリアライズ済みプロバイダー設定、必要な OpenXR 機能グループとインタラクションプロファイル、Active Input Handling、Unity.InputSystem アセンブリ参照、Android エントリーポイント、権限、Addressables／Localization、レンダーパイプライン設定、色空間、該当する場合は Android の最小 SDK バージョンを確認します。バージョンに依存する詳細は、最新のドキュメントとインストール済みパッケージの API で検証します。
10. 検証は、パッケージの解決、スクリプトのコンパイル、編集／プレイモードのテスト、Android ビルド、ヘッドセットでの権限、シーン読み込み、入力、レンダリング、ライフサイクルの動作確認の順に段階的に行います。コンパイルには、既に開いているプロジェクトのエディターを安全に操作できる場合、インストール済みでドキュメント化された Unity エディター制御 CLI またはブリッジを優先します。それ以外の場合は、同じプロジェクトが他の場所で開かれていないことを確認した後に限り、対応する Unity エディターをバッチモードで使用します。同じプロジェクトで 2 つ目のエディターを起動したり、無関係な Unity プロセスを終了したりしてはいけません。正確なコマンドと結果をアップグレードレポートに残します。
11. 要求された検証段階がすべて合格するか、未合格または未検証として、阻害要因となっている段階、根拠、具体的な次のコマンドを明記するまで完了としてはいけません。

重要なコンパイル実行ループ

コンパイルはタスクの最後に行う検証ではなく、作業を止めて対応するフィードバックループとして扱ってください。

1. 編集を始める前に、環境が対応している場合は最新のベースラインコンパイルを実行し、既存のエラーを記録します。
2. パッケージと XR プロバイダーのチェックリストを完了し、パッケージの解決とインポートが終わるのを待ってから、すぐにコンパイルします。新たに発生したパッケージ、アセンブリ、API のエラーは、別のサブシステムを移行する前にすべて修正するか、変更を元に戻します。
3. 振る舞いのまとまりを一つ、最初から最後まで移行します。Scene API の移行であれば、プロデューサーと、洗い出したすべてのコンシューマーを対象にします。その後、もう一度コンパイルします。そのまとまりのシリアライズ済みアセットと設定をつなぎ直し、さらにもう一度コンパイルします。
4. 失敗した場合は、最初に対応すべきエラーを調べ、インストール済みの対象 API を確認するか、そのエラーを正確に検索して、最小限で一貫性のある修正を行い、再実行します。コンパイルが失敗している間は、関係のない作業を始めないでください。
5. 作業時間が限られている場合は、最後の約3分の1をコンパイルと修正のサイクルに充てます。Unity のパッケージインポートとドメインリロードには時間がかかるためです。この期間中の各操作は、編集、コンパイル、現在の最初のエラーの調査、または必要なプロデューサー／コンシューマー／パッケージの不変条件の確認など、既知の移行項目を直接解消するものに限ります。新たな洗い出し、重複するサブタスク、広範なドキュメント検索、任意のプロジェクト全体の修正、隣接 API の調査は始めないでください。最大実行時間が残り時間を超えるコマンドは実行しないでください。コンパイルが失敗したまま時間切れになった場合は、完了したと主張せず、コンパイルの失敗と残っているエラーを報告してください。
6. コード、パッケージ、またはシリアライズ済みファイルに最後に変更を加えた後、必ず新たにクリーンコンパイルを実行してください。それ以前に成功した結果では、その後の変更を検証できません。
7. コンパイルが非同期で実行される場合は、現在のタスクにとどまり、同じプロセスを終端結果が出るまで確認してください。リマインダーを設定したり、確認を先送りしたり、検証中に戻ったりしないでください。最新のログを読み、作業を続ける前に現在のエラーを修正してください。プロセスをアタッチしたままにできない環境では、コンパイルは未検証であり、完了していないと報告してください。

重要な完了判定

完了を報告する前に、次の項目を確認してください。

• 使用中の API に必要なブリッジ／アダプターパッケージも含め、パッケージの構成が正確であることを確認します。たとえば、Interaction SDK と OVR API を併用するプロジェクトでは、com.meta.xr.sdk.interaction.ovr が必要になる場合があります。意図した XR プロバイダーが存在して有効になっていること、旧プロバイダーへの置き換えが削除されているか設定解除されていること、重複して同梱された SDK コードがなくなっていることを確認します。
• ゲームコード、アセンブリ定義、シーン、プレハブ、プロジェクト設定を再確認し、影響を受ける旧プロデューサーとコンシューマーがすべて残っていないか調べます。
• 影響を受けるコンシューマースクリプトとその .meta GUID を維持し、既存の場所で移行します。依頼の範囲で明示的に維持される場合を除き、非推奨のコンシューマーがコンパイルできるだけでは未完了です。コードとシリアライズ済み参照を確認せず、未使用に見えるという理由だけで削除しないでください。
• Scene API が MRUK に移行された場合は、ローダーが AnchorLabels を読み取り、PlaneRect と VolumeBounds を処理し、MRUK の実行時作成時に SceneSettings を初期化することを確認します。カスタムローダーが分類をプレハブに割り当てる場合は、共通のプレハブ null チェックより前にグローバルメッシュ表現が選択されることと、GlobalMesh がアプリケーションの描画またはコリジョン用コンポーネントに渡されることを確認します。デバッグやエクスポーターのコードを含むすべてのコンシューマーが、移行後の仕様を使用していることも確認します。
• シリアライズ済みのプレハブのマッピングと MRUK／プロバイダー設定がつなぎ直されていることを確認します。C# のコンパイルだけでは、これらを検証できません。
• 報告では、パッケージの解決、スクリプトのコンパイル、プレーヤーのビルド、Horizon Link でのテスト、スタンドアロンデバイスでのテストを区別します。ある段階の証拠を、それより後の段階の証拠として扱わないでください。

ドキュメントコマンド

検索結果を保持するには、JSON 出力を使用します。

metavr docs search --category UNITY --format json "Meta XR Unity SDK release notes <source> <target>"
metavr docs search --category UNITY --format json "<deprecated symbol> migration"
metavr docs search --category UNITY --format json "<package name> <compiler or runtime error>"
metavr docs fetch --format json "<URL returned by search>"

metavr docs search はセマンティック検索であり、バージョン間の完全な差分ではありません。バージョンを指定した検索結果が不十分な場合は、パッケージ名とシンボル名で検索範囲を広げる必要があるということであり、破壊的変更の一覧を捏造してよいという意味ではありません。

metavr を利用できない場合、検索結果を捏造してはいけません。最新の公式 Developer Center ページと、インストール済みの対象パッケージの変更履歴、公開 API、サンプルを使用し、CLI によるライブ取得を実行していないことを明記してください。

ガードレール

• 同梱またはキャッシュされた破壊的変更の概要は手掛かりとして扱い、権威ある情報として扱わないでください。最新の公式ドキュメントとインストール済みの対象パッケージで確認してください。
• デフォルトで段階的なアップグレードを推奨しないでください。パッケージの制約と根拠に基づいて、一括移行か段階的な移行かを選択してください。
• プロジェクトのアセットを削除したり、シリアライズされたファイルを再生成したり、その利用箇所を特定する前にシーン全体を一括変更したりしないでください。
• 非推奨であることと削除済みであることを同一視しないでください。対象バージョンでのサポート状況と要求された範囲に基づいて、今すぐ移行すべきか判断してください。
• コンパイルだけを根拠に成功を報告しないでください。Unity のシリアライズ、Android の権限、デバイスでのみ実行されるパスで失敗することがあります。

参考資料

• Unity アップグレード手順書
• Scene API から MRUK への移行に関するベストプラクティス