mcpField
M
migrate-birp-to-urp

migrate-birp-to-urp

github.com/unity-technologies開発59956 回インストール4 日前に更新
リポジトリ

migrate-birp-to-urp について

Unity プロジェクトを Built-in から URP へ移行するための段階的なスキルです。プロジェクトのリスクを調べ、レンダーパイプラインを変更する前にロールバック地点を確認し、完了報告の前に保存状態と代表シーンを検証します。

主な機能

  1. 01パイプラインとプロジェクト状態の判定
  2. 02移行リスクの調査
  3. 03変更前のロールバック確認
  4. 04段階的な設定と変換
  5. 05保存状態とシーンの検証

活用シーン

  1. 01Built-in から URP への移行計画
  2. 02対応マテリアルの変換と URP 設定
  3. 03ポストプロセスとライティング移行の確認
  4. 04移行途中のプロジェクトの検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/unity-technologies/unity-agent-plugin --skill migrate-birp-to-urp

インストール後、Claude Code で/migrate-birp-to-urpを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

SECURITY.md
references/
capturing-the-editor.md
complex-shader-situations.md
custom-shader-triage.md
implementation-patterns.md
migration-workflow.md
quality-settings-map.md

詳細

リクエストを分類し、現在のプロジェクトの状態を確認して、適切な移行パスを選択し、Built-in から URP への移行結果を慎重に検証します。

必須の実行リファレンス

実際に移行または修復を行う場合、プロジェクト設定、マテリアル、ポストプロセス、ライティング、プローブ、シーンを編集する最初の script eval 呼び出しの前に、references/implementation-patterns.md を読んでください。ロールバックの安全性がすでに確認されている場合でも、「このプロジェクトを URP に移行して」のような短いプロンプトを含め、これは必須です。

このリソースを読み込めない場合は、この SKILL.md に埋め込まれたルールを使用し、確信度を下げてください。意図やツールのログだけを根拠に、PPv2 の変換、ライティング／プローブの更新、または移行の完了を主張してはいけません。

重要なデフォルト

「この Built-in プロジェクトを URP に移行して」や「このプロジェクトを URP に移して」のような単純なリクエストでは、変換に直行せず、安全な移行ワークフローを開始または再開してください。

一般的なアップグレードの依頼で、ユーザーにすべての移行リスクを個別に挙げてもらう必要はありません。PPv2、ベイク済みライティング／ライトマップ、リフレクションプローブ、パーティクル／フォグ／煙のマテリアル、Quality レベル、カメラのポストプロセス、代表的なシーンの検証など、Built-in によくある依存関係を調査して対処してください。

デフォルトの結果はフェーズごとに進めます。

  1. プロジェクトが Built-in、部分的に移行済み、すでに URP、または HDRP のいずれかを検出します。
  2. リクエストを、標準的な 3D URP、URP 2D、選択したマテリアルの変換、計画のみ、またはトラブルシューティングに分類します。
  3. 変更を推奨する前に移行リスクを調査します。不透明マテリアル、パーティクル／VFX マテリアル、カスタムシェーダー、ポストプロセス、カメラエフェクト、ベイク済みライティング／ライトマップ／リフレクションプローブ、Quality レベル、代表的なシーンを確認します。
  4. ブランチ、バックアップ、アーカイブ、使い捨てコピーなどのロールバックポイントをユーザーが確認するまで、レンダリングパイプラインを変更する作業に着手しません。レンダリングパイプラインを変更する作業には、URP のインストール、Graphics／Quality 設定での URP アセットの割り当て、コンバーターの実行、マテリアルまたはシーンの編集が含まれます。
  5. 次の移行フェーズを選択して実行し、その出力を保存して再クエリし、フェーズのステータスを報告します。
  6. カスタムシェーダー、GrabPass、Surface Shader、OnRenderImage、置換シェーダー、パッケージ所有のシェーダーは、自動コンバーターの対象ではなく、範囲を限定した後続作業として扱います。
  7. 移行の完了を宣言する前に、代表的なシーン、Console の出力、カメラのレンダリング、ライティング／ベイク済み GI の状態、マテリアル、ポストプロセスの保持状態、Quality レベルの割り当てを検証します。

デフォルトのフェーズ：

  • フェーズ 0：調査と計画。レンダリングパイプラインの状態、代表的なシーン、ロールバックの安全性、PPv2、マテリアル／シェーダーのリスク、Quality レベル、ライティング／ライトマップ／プローブの状態、カスタムレンダリングコードを検出します。
  • フェーズ 1：URP のセットアップとサポート対象マテリアルの変換。URP をインストールまたは再利用し、Graphics／Quality に URP アセットを作成／割り当て、サポート対象の不透明マテリアルとパーティクル／エフェクトマテリアルを変換し、サポート対象マテリアルに Built-in シェーダーが残っていないことを確認します。
  • フェーズ 2：ポストプロセスとカメラの移行。永続的な URP Volume プロファイルを作成し、シーンの Volume とカメラのポストプロセスを接続し、URP の検証中は旧 PPv2 を無効にし、SSR などサポート対象外の PPv2 エフェクトを分類します。
  • フェーズ 3：ライティング、ライトマップ、リフレクションプローブ。古い Built-in ライティング状態を解消し、URP のライティング／プローブ設定を構成し、可能であればベイクし直す／更新するか、ライティング／プローブが未完了であることを明記します。
  • フェーズ 4：最終検証と報告。プロジェクトの状態を保存／再読み込み／再クエリし、代表的なシーンをキャプチャして Console を確認し、完了項目／未完了項目／手動対応項目を報告します。

プロジェクトの規模が小さく Unity が安定している場合は、1 回のターンで複数のフェーズを完了してもかまいません。ただし、すべてのフェーズを 1 回の応答に無理に詰め込まないでください。「完了」を過大に主張するより、誠実にフェーズの区切りを示してください。

プロジェクトの状態やユーザーの意図から実際の判断事項が残っている場合に限り、設定に関する質問をしてください。ユーザーが「ファイルを変更しないで」と指定した場合は、監査／計画モードにとどまり、変換やアセットの編集を行わないでください。

汎用アップグレード契約

ユーザーから汎用的な移行依頼があり、変更が許可されている場合は、プロジェクトの状態に基づいて次のフェーズを進めます。

  1. 調査前に、既知の Built-in 機能をユーザーに列挙するよう求めないでください。機能は自分で調査します。
  2. PPv2、ベイク済みライティング、リフレクションプローブ、パーティクル／フォグ／煙のマテリアル、または複数の Quality レベルがある場合は、自動的に移行に含めます。
  3. すべてを一度に完了させるより、フェーズごとの完了を優先します。各フェーズでは、独自の出力を保存して再確認し、最後に Phase complete、Phase partial、または Blocked を出力します。
  4. Unity のコンパイル、パッケージのインストール、ドメインの再読み込み、または長時間のライティングベイクによって作業が中断された場合は、その中断をフェーズの境界として報告し、最初からやり直すのではなく、次のターンで保存済みの部分的な状態から再開します。
  5. 正しい動作を実現するために、ユーザーが詳細なチェックリストを含むプロンプトを書くことを前提にしないでください。詳細なチェックリストはベンチマークやストレステスト用です。通常のユーザープロンプトでも、この段階的な契約が適用されます。
  6. 汎用的な移行依頼によって、調査と計画は許可されますが、ロールバックの安全性が確認されたことにはなりません。ロールバックできることが確認できていない場合は、パッケージのインストールまたは URP の割り当てを行う前に中断し、確認を求めます。バックアップについて確認するためだけに、プロジェクトをマゼンタ色の不完全な状態のままにしないでください。
  7. ロールバックの安全性がすでに確認されている場合、またはユーザーがプロジェクトは破棄可能なコピーだと言っている場合は、通常の作業について再度確認せずに、現在のフェーズを続行します。
  8. フェーズの終了時に、次のフェーズを促す簡潔なプロンプトを提示するか、次に実行すべきフェーズを伝えます。長時間のライティングベイク、レガシーアセットの削除／クリーンアップ、カスタムシェーダーの書き換えなど、新たにコストの高い操作またはリスクのある操作が発生する場合に限り、次のフェーズに進む前に確認を求めます。
  9. ロールバックの安全性が確認されており、アクティブなフェーズ内の通常作業が未完了の場合、「続けてもよろしいですか？」と尋ねないでください。そのフェーズのゲートを通過するまで、ツールまたはドメインの再読み込みによって実行が中断されるまで、あるいは実際に新たなリスクのある判断が必要になるまで、修復を続けます。
汎用移行の成功ゲート

汎用的な移行が「成功」「完了」または「完全に移行済み」だと述べる前に、ツールのログだけではなく、保存されたプロジェクトの状態を検証します。

  1. Graphics 設定と、該当するすべての Quality レベルが、意図した URP アセットを参照していること。
  2. URP アセットに、保存された状態で有効なデフォルトレンダラーが設定されており、現在の Console 出力に「Default Renderer is missing」などの未解決のレンダーパイプラインエラーが含まれていないこと。割り当て後にレンダラーエラーが表示された場合は、保存済みのレンダラーリストとデフォルトインデックスを再取得し、可能であれば古い Console 出力をクリアしてから、新たにシーン／カメラの検証を実行し、「URP setup complete」の時点で止めずに修復を続けてください。
  3. パーティクル／フォグ／煙のマテリアルを含む、サポート対象の Built-in マテリアルに、URP 対応シェーダーが設定されているか、未解決のカスタム／パッケージシェーダーのケースとして明示的に記載されていること。テクスチャまたはカラーが設定されたソースマテリアルでは、元のマップ／カラーを維持してください。ソースの _MainTex または _Color に内容がある場合、_BaseMap が未設定、または _BaseColor がすべて白の URP シェーダー割り当ては不完全です。パーティクル、フォグ、煙、蒸気、デカール、VFX、加算、透過エフェクトのマテリアルに、無条件で Universal Render Pipeline/Lit を設定しないでください。適切な場合は、Universal Render Pipeline/Particles/Unlit などの URP パーティクル／エフェクトシェーダーを優先してください。
  4. ソースシーンで PPv2 を使用していた場合、保存済みの URP VolumeProfile に永続化された null 以外のオーバーライドコンポーネントがあり、代表シーンから URP Volume を通じて参照されており、URP のビジュアル検証ではレガシー PPv2 が無効になっていること。components: [] を含む保存済みプロファイル、{fileID: 0} のコンポーネント参照、または旧 PostProcessProfile のみを参照するシーンは不完全です。
  5. 代表シーンでベイク済み／混合ライティング、Enlighten／リアルタイム GI の Lighting Settings アセット、Lighting Data アセット、ライトマップ、ライトプローブ、またはリフレクションプローブを使用している場合、一般的な全面移行の際に、通常のライティング／プローブ修復を手作業の後続作業として残さないでください。URP 互換の Lighting Settings の割り当てを試み、必要に応じてクリアして再ベイクするか、ベイクを再開し、可能であればリフレクションプローブを更新してから、保存／再読み込みを行い、シーンが意図したライティング状態を参照していることを確認してください。.lighting アセットを作成し、Lightmapping.lightingSettings = target と AssetDatabase.SaveAssets() を呼び出すだけでは不十分です。シーンに変更を加えて保存し、再読み込み／再取得を行い、保存済みシーンの m_LightingSettings 参照またはアセット GUID を比較してください。長時間のベイクやツールの中断でこれを実行できない場合は、移行を「partial」とし、そのフェーズから再開してください。
  6. 移行の検証前に、代表シーンを意図的に開くか選択していること。デフォルト／テストシーンを根拠に、ベイク済みライティングや PPv2 が存在しないと推測しないでください。保存／再読み込み後のシーンをキャプチャまたは調査し、Console 出力にレンダーパイプライン、シェーダー、またはレンダラーフィーチャーのエラーがないか確認してください。
  7. 最終的な表現はゲートの結果と一致させてください。すべてのゲートに合格した場合に限り「complete」としてください。URP は設定済みでも、PPv2 Volume の永続化、レガシー PPv2 の無効化、ライティングベイク／プローブの更新、または保存状態の検証が残っている場合は「partial」としてください。必須ゲートが一部未完了の場合、最終回答を「successfully migrated」で始めないでください。

完了レポートのチェックリスト：

  • 古い PPv2 プロファイルに有効な DepthOfField が含まれている場合、新しい URP プロファイルに保存済みの DepthOfField オーバーライドを含めるか、最終レポートで省略または手動対応として記載してください。
  • 古い PPv2 プロファイルに有効な AmbientOcclusion が含まれている場合、可能であれば URP SSAO レンダラー機能を設定するか、AO を手動対応または部分対応として記載してください。
  • 古い PPv2 プロファイルに有効な ScreenSpaceReflections が含まれている場合、URP レンダラー機能またはカスタム置き換えを実際に追加して検証していない限り、SSR を非対応または手動対応として記載してください。
  • シーンに古い Lighting Settings GUID またはゼロ以外の古い m_LightingDataAsset がシリアライズされたままの場合、ライティングは部分対応です。
  • シーンにリフレクションプローブがあり、URP アセットに m_ReflectionProbeBlending: 0 または m_ReflectionProbeBoxProjection: 0 がシリアライズされたままの場合、意図的に無効にしてその旨を報告していない限り、反射は部分対応です。
  • チェックリストの項目が 1 つでも false の場合、最終回答で「完了」「完全に移行済み」「URP で完全に機能」と表現しないでください。

非対応機能は手動対応のままでもかまいませんが、具体的に記載してください。例として、URP レンダラー機能、カスタム置き換え、またはサードパーティ製の置き換えが必要な PPv2 の Screen Space Reflections、複雑なカスタムシェーダーの移植、GrabPass、置き換えシェーダー、パッケージが所有するレンダリングコードなどがあります。成功条件の項目が 1 つでも満たされない場合、許可されていれば修正を続けるか、未完了項目を記載して部分的な移行として報告してください。プロジェクトが完全に移行済みであるかのように提示しないでください。

回帰防止の概要：

  • 実際の移行または修復作業では、詳細な実行回帰チェックリストを使用してください。
  • 状態を報告する前に、保存済みのシーン参照を確認してください。対象は URP Volume／プロファイル、Quality の割り当て、Lighting Settings／Data、URP アセット／レンダラー、リフレクションプローブ設定です。
  • 変換前のスナップショットからマテリアルのソースデータを保持し、シェーダー変更後に _BaseMap、_BaseColor、テクスチャのスケール／オフセット、関連するマップを復元してください。
  • 最終的な表現を決める前に、PPv2、フォリッジ、パーティクル／エフェクト、ベイク済みライティング、プローブ、露出について、代表的なビジュアルを検証してください。
  • 各フェーズの状態を正確に報告してください。フェーズに合格した場合は Phase complete としてかまいませんが、プロジェクト全体を complete と報告できるのは、すべての成功条件を満たした場合のみです。

実行手順：Editor で C# を実行する

このスキルの C# の各ステップは、Unity CLI を介して起動した実行中の Editor 内で実行します。そこにたどり着くまでの手順は unity-cli スキルが担当します。CLI のインストール、Editor が接続されていることの確認、プロジェクトへの com.unity.pipeline パッケージの追加、Editor が本当に存在しない場合と Safe Mode で停止している場合の見分け方、Editor のコマンドカタログの確認を行います。まずこのスキルに従い、ここで手順を再導出しないでください。

このスキルで判断できないことが 2 つあります。

  • 接続可能な Editor があるだけでなく、特に script eval が必要です。 カタログに表示されることを確認してください。 これが使えるかどうかは CLI ではなく Pipeline パッケージのバージョンに依存するため、正常なインストールでも使えない場合があります。見つからない場合は、その旨を伝えて停止してください。

  • 6000.3 より古い Editor では、Pipeline パッケージがまったく動作しないと考えてください。 症状を正しく読み取り、再試行しないでください。com.unity.pipeline は IPreprocessBuildWithContext と BuildCallbackContext を使用します。これらは Unity 6000.3 で導入されたため、パッケージ独自のマニフェストでは "unity": "6000.0" と宣言されており、問題なくインストールされた後、コンパイルに失敗します。実測では、6000.3 / 6000.4 / 6000.5 には存在し、6000.0 / 6000.1 / 6000.2 と 2022 および 2023 系には存在しません。症状は誤解を招きます。サーバーは起動せず、unity status に行もエラーも表示されず、実際の原因は Editor ログに記録されたこれら 2 つの型の CS0246 です。これが見られた場合は、CLI のデバッグではなく、Editor が Pipeline パッケージには古すぎることをユーザーに伝えてください。

    これは多くのスキルよりも重要です。 Built-in パイプラインからプロジェクトを移行する人は、定義上、古い Editor を使用していることがよくあります。

  • レンダーパイプラインの移行を、Editor に接続せずに安全に作成することはできません。 URP アセットの割り当て、マテリアルの変換、ライティングの再ベイクには、いずれも実行中の Editor が必要です。Editor に接続できない場合は停止してください。ProjectSettings/GraphicsSettings.asset を手動編集する合図ではありません。

C# は unity command script eval --caller plugin --skill migrate-birp-to-urp --code '<snippet>' で実行します。unity command のデフォルトのタイムアウトは 30 秒です。ここでは URP のインストールによってパッケージの更新とドメインの再読み込みが発生し、タイムアウトを超えるため注意が必要です。タイムアウトを延長するのではなく、これをフェーズの境界として扱ってください。

script eval に C# を渡す

script eval がコンパイルするのはファイルではなくステートメントブロックです。これには 3 つの注意点があり、いずれも警告ではなくコンパイルエラーになります。

  • using ディレクティブは使えません。 コンパイラーは using UnityEngine; をリソース破棄ステートメントとして読み取り、拒否します（CS0210）。
  • 型は完全修飾名で指定する必要があります。 GraphicsSettings や Volume だけでは解決できず（CS0246 / CS0103）、Object だけでは object と曖昧になります（CS0104）。
  • 拡張メソッドは使用できません。 using を通じて解決されるためです。このスキルで通常使う 2 つの例を挙げます。camera.GetUniversalAdditionalCameraData() は camera.GetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>() とし、LINQ の呼び出しは sequence.FirstOrDefault(predicate) ではなく、 System.Linq.Enumerable.FirstOrDefault(sequence, predicate) のように静的に記述する必要があります。
2 つの実行モード — スニペットの形式に応じて選択してください

リファレンスには両方の形式が含まれており、互いに置き換えることはできません。

  • ステートメント形式（上記の検出スニペットのような、ステートメントだけの並び） — 完全修飾名を使い、using 行を含めずに、そのまま script eval に渡します。
  • クラスまたはメソッド形式（class、static メソッド、または [MenuItem] を宣言するもの。マテリアルのスナップショットパターンなど） — これらは プロジェクトファイルであり、script eval の入力ではありません。クラス宣言をステートメントブロックに平坦化することはできません。スニペットを Assets/Editor/ に保存し、Unity にコンパイルさせてから、1 行の script eval 呼び出しでエントリーポイントを実行します。using ディレクティブはそのファイルに残してください。そこでは正しい形式です。

複数手順にわたる移行では、スクリプトを使う方法のほうが確実です。URP のインストールやマテリアル変換で発生するドメインリロードにも耐えられますが、長い script eval のペイロードではそうはいきません。

アクティブなレンダーパイプラインの検出
var rp = UnityEngine.Rendering.GraphicsSettings.defaultRenderPipeline;
var qrp = UnityEngine.QualitySettings.renderPipeline;
return $"graphics={(rp == null ? "NULL (Built-in)" : rp.GetType().Name + ":" + rp.name)}, "
     + $"activeQualityLevel={(qrp == null ? "inherits Graphics" : qrp.GetType().Name + ":" + qrp.name)}";

UniversalRenderPipelineAsset は URP、HDRenderPipelineAsset は HDRP を意味し、両方が NULL の場合は Built-in です。品質レベルごとの割り当ても確認してください。Graphics 設定でプロジェクトを切り替えても、Quality レベルが別のアセット、またはアセットなしを参照していることがあります。

var names = UnityEngine.QualitySettings.names;
var rows = new System.Collections.Generic.List<string>();
for (int i = 0; i < names.Length; i++)
{
    var a = UnityEngine.QualitySettings.GetRenderPipelineAssetAt(i);
    rows.Add($"{i}:{names[i]}={(a == null ? "inherits Graphics" : a.name)}");
}
return string.Join(", ", rows);

プロジェクトの Unity バージョンで GetRenderPipelineAssetAt を利用できない場合は、実行時にレベルを切り替えるのではなく、ProjectSettings/QualitySettings.asset を読み取ってください。SetQualityLevel はプロジェクトの状態を変更します。

0. 事前確認：パイプラインの検出とリファレンスの読み込み

ほかの作業に着手する前に、アクティブなレンダーパイプラインと移行モードを必ず確認してください。

  1. パイプラインを検出する： 上記の実行方法のセクションにあるレンダーパイプライン検出スニペットを実行します。
    • currentRenderPipeline または defaultRenderPipelineAsset が UniversalRenderPipelineAsset を参照している場合 -> URP。
    • レンダーパイプラインアセットが割り当てられていない場合 -> Built-in。
    • HDRenderPipelineAsset を参照している場合 -> HDRP。このスキルの対象は Built-in から URP への移行のみであることを説明してください。基本的な比較の助言は構いませんが、このスキルを使って HDRP への移行を進めてはいけません。
  2. 基本リファレンスを読み込む： references/migration-workflow.md を読みます。
  3. 必要に応じてシェーダーのリファレンスを読み込む： リクエストでマテリアル、シェーダー、マゼンタ色のマテリアル、レンダリングエラー、イメージエフェクト、またはカスタムレンダリングに言及している場合は、以下も読みます。
  4. 必要に応じて品質設定のリファレンスを読み込む： リクエストでシャドウ、ライティング、ベイク済みライティング、ライトマップ、リフレクションプローブ、品質設定、移行後の見た目の不一致、またはパフォーマンスに言及している場合は、references/quality-settings-map.md も読みます。
  5. 実行時に実装パターンを読み込む： リクエストが実際の移行変更、ポストプロセッシング変換、ベイク済みライティング／プローブの修復、または部分移行からの再開を許可している場合は、references/implementation-patterns.md も読みます。
  6. リクエストを次のいずれかに分類します：
    • プロジェクト全体の Built-in から URP への移行
    • Built-in 2D から URP 2D への移行
    • 選択したマテリアルのみの変換
    • 計画／説明のみ
    • 以前の移行後のトラブルシューティング
  7. プロジェクトがすでに URP を使用している場合は、 むやみにセットアップを再実行せず、トラブルシューティングモードに切り替えます。
  8. パイプラインと移行経路が明確になってから 作業を進めます。

1. 現在の移行状態を評価する

変更を加える前に、すでにあるものを確認してください。

  1. パイプラインの状態と割り当て箇所を確認する：
    • 上記の実行パスのセクションにあるレンダーパイプライン検出用スニペットを両方実行します。Graphics設定用と、品質レベルごとのものです。
    • プロジェクトに品質レベルがある場合、プロジェクト全体の切り替えが完了していると判断する前に、各レベルでどのレンダーパイプラインアセットが使用されているかを確認します。
  2. 移行対象を一覧にする： UnityEditor.AssetDatabase.FindAssets または同等のアセットクエリを使用して script eval を実行し、次の対象を一覧にします。
    • マテリアル。組み込みのパーティクルシェーダーを使用していることが多いパーティクル／VFX マテリアルも含みます
    • 植生マテリアル。草、木、地形ディテール、SpeedTree、ビルボード、リーフカード、切り抜き、風で揺れる葉のマテリアルも含みます
    • シェーダー
    • シーンと重要なプレハブ
    • URP アセットとレンダラーアセット（存在する場合）
    • ポストプロセッシングプロファイル／ボリュームプロファイル
    • ライティング設定アセット、ライティングデータアセット、ライトマップ、ライトプローブ、反射プローブ、混合／ベイク済みライト
  3. レンダリング上のリスク要因を検索する： 利用可能なプロジェクトファイル検索、AssetDatabase.FindAssets、または短い script eval のファイルスキャンを使い、次のようなレンダリング固有のパターンをプロジェクト内で検索します。
    • PostProcessLayer、PostProcessVolume、UnityEngine.Rendering.PostProcessing
    • OnRenderImage(、RenderWithShader、SetReplacementShader
    • #pragma surface、GrabPass、CGPROGRAM
    • CommandBuffer、カスタムシェーダーのインクルードパス、パッケージのシェーダー名前空間
    • 植生を示す文字列。Nature/、SpeedTree、TreeCreator、Grass、Foliage、_Cutoff、_AlphaClip、_Cull、ビルボード、風のキーワードなど
  4. PPv2 がインストールされているのに grep で何も見つからない場合は、 Unity API を使い、コンポーネント／型ごとに開いているシーンとプロファイルアセットを確認します。シーンの YAML やシリアライズされたパッケージ参照は、テキスト検索で見つからない場合があります。
  5. プロジェクトの構成を判断する： プロジェクトが主に 3D、主に 2D、または混在のいずれかを判断します。
  6. 調査結果を報告する： 移行方法を提案する前に、現在の状態を要約します。例：
    • 「プロジェクトはまだ Built-in を使用しており、URP アセットは割り当てられていません。PPv2 への参照があり、サーフェスシェーダー構文を使用するカスタムシェーダーがいくつか含まれています。」

2. 要件を確認する

ユーザーが実際に何を求めているのかを確認します。依頼が曖昧な場合は質問してください。

一般的な依頼には、次のデフォルトの解釈を使用します。

ユーザーの発言デフォルトの解釈
"Upgrade this project to URP"プロジェクト全体の移行
"Move this 2D project to URP"Built-in 2D から URP 2D への移行
"Convert these materials"対象を絞ったマテリアル変換
"My materials turned pink"移行後のシェーダー／マテリアルのトラブルシューティング
"Lighting looks wrong after URP"品質と見た目の一致に関するトラブルシューティング
"Do not change anything yet"計画／監査のみ
確認する情報
  • 範囲： プロジェクト全体、選択したマテリアルのみ、またはトラブルシューティングのみ
  • 対象レンダラー： 標準 URP または URP 2D
  • 検証対象： ユーザーにとって重要なシーン、プレハブ、カメラ
  • 許容できるリスク： 限定的な手作業でのフォローアップが許容されるか
  • レンダリング関連の依存関係： カスタムシェーダー、Asset Store のシェーダー、PPv2、ベイク済みライティング／ライトマップ／プローブ、イメージエフェクト、コマンドバッファー、置換シェーダー、複数の品質レベル
  • 実行許可： 計画のみか、実際にプロジェクトを変更するか

3. 安全ゲート

パイプラインを変更する手順の前に、必ず次のことを行ってください。

  1. ロールバックの安全性を確認します。
    • ユーザーがバックアップ、ブランチ、アーカイブ、破棄可能なコピー、またはロールバックポイントを確認するまでは、URP のインストール、URP アセットの割り当て、Render Pipeline Converter の実行、マテリアルの編集、移行シーンの状態の編集を絶対に行わないでください。
    • ロールバックの安全性が確保されていない場合、プロジェクトの一部だけを URP に切り替えてはいけません。計画モードで作業を止め、まずロールバックの確認を求めてください。
  2. エンジンのアップグレードとパイプラインのアップグレードのリスクを切り分けます。
    • プロジェクトを新しい Unity バージョンにも移行する場合は、先にエンジンをアップグレードし、その後にパイプラインを移行することを推奨してください。両方をまとめて、確認なしに実行する操作として扱わないでください。
  3. ロールバックの安全性が確認された場合は、 移行作業全体がその確認の対象であるとみなします。新たにリスクのある判断が発生しない限り、各コンバーターの実行前に再度確認を求めず、セットアップ、マテリアル変換、PPv2 の移行、ライティング／プローブの作業、保存／再読み込みの検証、最終報告へと進めてください。
  4. ユーザーがすでに破棄可能な環境での完全な移行を許可している場合は、 通常のセットアップや復旧可能なエラーの後に、続行の許可を求めないでください。次の未完了の移行フェーズへ進んでください。新たに破壊的なクリーンアップの判断が発生した場合、パッケージ／ドメインの再読み込みによって実行が停止した場合、または修復を繰り返しても検証の反復上限に達した場合に限り、確認を求めてください。
  5. プロジェクトの移行がすでに一部完了している場合は、 以前にロールバックの安全性が確認されているかを特定してください。確認済みなら、最初の未完了項目から再開してください。未確認なら、一部移行済みの状態を報告し、追加の変更を行う前に確認を求めてください。

4. 移行パスを選択する

プロジェクトに適したパスを使用してください。

パス A：標準的な 3D Built-in から URP への移行
  • 通常の 3D Built-in プロジェクトを標準 URP に移行する場合に使用します。
パス B：Built-in 2D から URP 2D への移行
  • プロジェクトが主に 2D で、ユーザーが URP 2D のライティングまたはレンダラーの動作を想定している場合に使用します。
  • これは標準 URP と同じワークフローとして扱わないでください。
パス C：対象を絞ったマテリアルのみの変換
  • プロジェクトがすでに URP を使用していて、ユーザーが選択したマテリアルの変換を希望する場合に限り使用します。
パス D：既存の移行に関するトラブルシューティング
  • プロジェクトがすでに URP を使用している場合、または移行がすでに試行されている場合に使用します。
  • 移行全体を確認なしに再実行するのではなく、影響が最も大きい問題を優先してください。

5. URP のセットアップワークフロー

次の順序を厳守してセットアップしてください。

  1. URP がインストールされていることを確認します。
    • URP のインストールによって、パッケージの更新、コンパイル、ドメインの再読み込みが発生することがあります。これをフェーズの境界として扱ってください。
    • script eval 呼び出し内で UnityEditor.PackageManager.Client.Add の完了を無期限に待ち続けないでください。インストールを要求してから、Unity の更新完了後に Packages/manifest.json、パッケージ一覧、または URP の型／アセットの存在を確認してください。
    • パッケージのインストールによって script eval 呼び出しがタイムアウトするか、何も返さない場合は、Unity のコンパイル完了後、新しいターンで再開してください。移行全体を最初からやり直したり、URP を再インストールしたりせず、一部適用済みの状態を調べ、そこから続行してください。
  2. 必要な URP アセットとレンダラーアセットが存在しない場合は作成します。
  3. Graphics 設定および関連するすべての Quality レベルで、URP アセットを割り当てます。
  4. 2D プロジェクトの場合は、 変換の前に適切な 2D Renderer アセットを作成して割り当てます。
  5. URP アセットがすでに存在する場合は、 適切であれば重複を自動的に作成するのではなく、既存のアセットを確認して再利用します。
  6. 対象の構成で URP が実際にアクティブなレンダーパイプラインになるまでは、 作業を続行しないでください。

6. 変換ワークフロー

実際の変換作業では、references/migration-workflow.md に従ってください。

  1. 正しいレンダーパイプラインコンバーターのパスを選択します。
    • Built-in Render Pipeline to URP
    • Built-in Render Pipeline 2D to URP 2D
  2. 変換する前に、コンバーターを初期化して変更候補を確認します。
  3. Built-in から URP への標準的な移行では、リファレンスで説明されている該当するコンバーターを使用します。
    • Rendering Settings
    • Material Upgrade
    • Animation Clip Converter
    • Read-only Material Converter
    • Post-processing Stack v2 Converter
  4. 選択したマテリアルを変換する場合は、プロジェクト全体を変換するのではなく、対象を絞ったマテリアル変換ワークフローを使用します。
  5. 変換する前に、警告と失敗を確認します。
  6. プロジェクトに変更を加えても問題ないことをユーザーが確認した後にのみ、変換を実行します。
  7. 各マテリアルが実際にどのシェーダーに変換されたかを確認します。コンバーターが3D向けの変換先を選んだと決めつけてはいけません。MaterialUpgrader.FetchAllUpgradersForPipeline は、3D向けのプロバイダーセットに加えて2D向けのプロバイダーセットも返します。どちらも同じ優先度で Standard を対象とするため、3Dプロジェクトでも、通常の Standard マテリアルが Universal Render Pipeline/Lit ではなく Universal Render Pipeline/2D/Mesh2D-Lit-Default に気付かないまま変換されることがあります。エラーは発生せず、マテリアルもマゼンタ色にならないため、シェーダー名を読み戻さない限り見過ごされます。6000.5.8f1で確認しました。 変換されたすべてのマテリアルの shader.name を後で読み取り、マッピングテーブルで意図したターゲットと一致することを確認します。3D プロジェクトで 2D/ シェーダーに割り当てられたものがある場合は、それらのマテリアルをロールバックポイントから復元し、3D でフィルタリングしたアップグレーダーリスト、または references/implementation-patterns.md の手動パターンを使用して変換します。
  8. 変換後、保存されたプロジェクトの状態を検証します。
    • コマンドの出力だけを信頼せず、代表的なアセットを再度開くか再クエリします。
    • シーンレベルの編集後は、アセットと開いているシーンの両方を保存します。シーンコンポーネント、カメラデータ、アクティブなライティング設定、リフレクションプローブ、PPv2 の有効状態への変更は、AssetDatabase.SaveAssets() だけでは証明されません。
    • Graphics と意図した Quality レベルで URP アセットが割り当てられていることを確認します。
    • Quality レベルについては、QualitySettings.GetRenderPipelineAssetAt(i) を再クエリするか、ProjectSettings/QualitySettings.asset に保存された customRenderPipeline エントリを読み取って検証します。それらが {fileID: 0} のままである場合、Quality レベルは明示的に割り当てられていません。
    • QualitySettings.SetRenderPipelineAssetAt のような推測された品質 API を呼び出さないでください。その API が利用できない Unity バージョンでは、QualitySettings.SetQualityLevel(index) で各ターゲットレベルに切り替え、QualitySettings.renderPipeline = urpAsset を設定してから、元のレベルを復元し、保存された customRenderPipeline の値を検証します。
    • 変換されたマテリアルが実際に URP シェーダーを参照していることを確認します。
    • ソースのアルベドテクスチャを持っていた代表的なマテリアルが、現在 null ではない _BaseMap 値を持っていることを確認します。このチェックは変換前のマテリアルスナップショットと比較する必要があります。変換後の _MainTex を信頼できる情報源として使用しないでください。
    • パーティクル/VFX マテリアルが Built-in のパーティクルシェーダー ID やレガシーシェーダー名を参照しなくなっていることを確認します。適切な場合は Universal Render Pipeline/Particles/Unlit などの URP パーティクルシェーダーを使用します。マテリアル名やパスに Particle、Fog、Smoke、Steam、VFX、Additive、または同様のエフェクト用語が含まれる場合は、URP Lit にデフォルト設定するのではなく、透明/加算の挙動を維持します。
    • 植生マテリアルがカットアウト/アルファクリッピング、レンダーフェイスの意図、テクスチャ、ティント、ノーマル、および期待される風/ビルボードの挙動を維持していることを確認します。草/木のカードが、特殊なシェーダーの挙動を失ったために不透明または静的になっている場合、マテリアル変換は部分的です。
    • PPv2 変換を試みた場合は、保存された URP Volume プロファイルに永続的な null ではない components エントリが含まれ、シーン/カメラの配線が URP 互換コンポーネントを使用していることを確認します。
    • ベイク済みライティングが存在する場合は、古い Lighting Data とライトマップを参照データとして保持し、それらが依然として許容可能な URP の見た目を生成するかどうかを検証します。新しい Lighting Settings アセットが作成された場合は、保存/再読み込み後に保存されたシーンが実際にそれを参照していることを確認します。アセットがディスク上に存在するだけでは十分ではありません。実際の一般的な移行では、古いベイクデータやリフレクションプローブがパリティに影響する場合、再ベイク/リフレッシュを試みます。それが現在のターンで完了できない場合は、移行を部分的であると報告し、後でライティング/プローブのフェーズから再開します。
    • 意図から「リフレクションプローブをリフレッシュした」と主張しないでください。新規または更新されたプローブ出力、変更された保存済みリフレクションプローブアセット、またはプローブレンダーツールの正常な出力を検証します。既存の EXR ファイルが変更されていないままである場合は、プローブは参照として保持された、または依然としてリフレッシュが必要であると述べます。
    • いずれかの検証が失敗した場合は、その項目を移行済みとしてではなく、未完了/手動フォローアップとして報告します。

7. シェーダーとマテリアルのトリアージ

マテリアルがマゼンタ色になったり、シェーダーのコンパイルに失敗したり、見た目が大きく崩れたりした場合は、まず references/custom-shader-triage.md を参照してください。

  1. 影響を受けているマテリアルとシェーダーを特定します。
    • シーンに現れている症状だけでなく、該当するマテリアルのシェーダー割り当てを正確に確認してください。
  2. シェーダーコードを編集する前に、Console と Inspector のエラーを確認します。
  3. シェーダーのケースを分類します。
    • コンバーターで処理できる、サポート対象の Built-in シェーダー
    • 安全に移植できる可能性のあるシンプルなカスタムシェーダー
    • 範囲を絞った移行計画が必要な複雑なカスタムシェーダー
    • カットアウト、両面表示の葉、ビルボード、地形の詳細描画、または風の挙動が必要な葉や植生用シェーダー
    • メンテナーのドキュメント、範囲を絞ったカスタム移植、または手作業での追加対応が必要になる可能性がある、パッケージ提供元または Asset Store のシェーダー
  4. 複雑なシェーダーの状況には、 references/complex-shader-situations.md を参照してください。
  5. 安全性を確保できる最小限の修正を優先します。
    • まず代表的なマテリアルのレンダリングを復元します。
    • 修正を他のアセットにも広げる前に、結果を検証します。
  6. 対応関係が明示され、テスト済みで、対象範囲が限定されていない限り、プロジェクト全体でシェーダーコードを一括検索・置換しないでください。

8. ポストプロセス、カメラ、レンダリングエフェクトのトリアージ

Built-in プロジェクトでは、マテリアルの変換だけでは不十分なことがよくあります。

  1. **PPv2 が存在する場合は、**コンバーターの出力を調べ、変換後の URP のボリューム、プロファイル、カメラの動作を検証してください。
    • 変換前に、既存の PostProcessVolume、PostProcessLayer、PPv2 の PostProcessProfile アセットを一覧にしてください。
    • 利用できる場合は、記憶を頼りに同等のプロファイルを手作業で作成するのではなく、URP の Post-processing Stack v2 Converter を優先してください。
    • 変換後、保存された URP の VolumeProfile アセットに永続化されたオーバーライドコンポーネントが含まれていることを確認してください。components: [] の空のプロファイルや、参照先のない {fileID: 0} のコンポーネント参照があってはいけません。
    • スクリプトでプロファイルを作成する場合、VolumeProfile.Add<T>() が作成するのはコンポーネントオブジェクトだけです。永続化するプロファイルアセットにするには、AssetDatabase.AddObjectToAsset(component, profile) も呼び出し、プロファイルとコンポーネントを変更済みとしてマークし、アセットを保存してから再読み込みし、保存された null ではないコンポーネントの数を確認して、成功を報告してください。保存されたプロファイルに {fileID: 0} のコンポーネントエントリがある場合は、移行が成功したと主張する前に、プロファイルを作り直すか修復してください。
    • 代表的なシーンに意図した Volume オブジェクトが含まれていることと、必要に応じて対象カメラにポストプロセッシングが有効な UniversalAdditionalCameraData があることを確認してください。
    • 移行元のシーンに PPv2 の sharedProfile 参照しかシリアライズされておらず、新しい VolumeProfile を参照する URP の Volume がない場合、ディスク上に URP プロファイルアセットが存在していても、PPv2 の移行は未完了です。
    • アクティブな URP の Volume が空のプロファイルを参照している場合、これをポストプロセッシングが有効な状態としてではなく、シーンの設定が未完了の状態として扱ってください。プロファイルを修復するか、PPv2 の移行は一部のみ完了していると報告してください。
    • 古い PostProcessVolume／PostProcessLayer コンポーネントが残っているか確認してください。残っている場合は、意図的に保持しているのか、無害な旧コンポーネントなのか、未解決の移行作業なのかを説明してください。
    • 古い PPv2 コンポーネントを参照用としてのみ保持し、URP の Volume がアクティブになっている場合は、URP の表示を検証する際に二重のポストプロセッシングを避けるため、古い PPv2 コンポーネント／レイヤーを無効にしてください。表示の一致が確認されるか、ユーザーが削除を承認するまでは削除しないでください。
    • 検証済みの URP での置き換えが存在するか、ユーザーが効果を破棄する／手動で後続対応することを承認するまでは、クリーンアップの一環として PPv2 のパッケージ、コンポーネント、プロファイルを削除しないでください。
    • 実際に移行する際、移行元のプロファイルを利用できるのであれば、PPv2 の一般的な効果との表示の一致を曖昧な手動作業として残さないでください。Bloom、Color Adjustments／Tonemapping、Vignette、Depth of Field など、一般的にマッピング可能な効果について永続化された URP オーバーライドを作成し、保存されたプロファイルに null ではないコンポーネントがあることを確認してください。
    • PPv2 の Screen Space Reflections や、Volume オーバーライドに直接置き換えるのではなくレンダラーフィーチャー／SSAO の設定にするべき Ambient Occlusion など、サポートされていない効果や同等のものがない効果を手動で後続対応する項目として記録するのは問題ありません。
    • URP の Volume オーバーライドを確実に作成できない場合は、PPv2 の効果とそれに対応する URP の機能を記録し、移行済みとは主張しないでください。
  2. 一時的なツールの成功を、ポストプロセッシングの成功とみなさないでください。
    • 「Added Bloom」と表示するコマンドログだけでは不十分です。保存後に VolumeProfile アセットを再読み込みするか、シーンを調べてください。
    • 保存されたプロファイルが空の場合、PPv2 の設定は記録された、または部分的に準備されたと説明し、移行済みとはしないでください。
  3. **grep で OnRenderImage が見つかった場合は、**カスタム全画面効果として扱ってください。
    • URP では、カスタム全画面効果は Built-in のイメージエフェクト経路にとどめず、ScriptableRenderPass、Renderer Feature、または URP のカスタムポストプロセッシングに移行してください。
  4. **grep で RenderWithShader または SetReplacementShader が見つかった場合は、**置き換えシェーダーのケースとして扱ってください。
    • この種の効果では、意図的な URP のレンダラーフィーチャーまたはカスタムパスの方針が必要になることがよくあります。
  5. **効果がシーンカラー、深度、または法線に依存する場合は、**Built-in の方法がそのまま使えると決めつけず、URP で互換性のある経路を確認してください。
  6. **Built-in でカスタムカメラが効果を重ねていた場合は、**移行後に表示が一致すると決めつけず、カメラの出力を明示的に検証してください。
  7. **高度なシェーダー／効果のトラブルシューティングに関する質問には、**具体的な置き換えパターンを提示してください。
    • GrabPass については、_CameraOpaqueTexture／Scene Color、必要な URP アセット設定、透明オブジェクトの描画順が Built-in と異なる場合があるという制限に触れてください。
    • OnRenderImage については、ScriptableRendererFeature と ScriptableRenderPass に触れてください。Unity 6 スタイルのテンプレートを示す場合は、一時的な RTHandle と Blitter.BlitCameraTexture を使う参考パターンに従ってください。
    • Blitter.BlitCameraTexture(cmd, source, source, material, pass) や、ソースから同じソースへのその他の blit を、OnRenderImage の主な置き換え方法として推奨しないでください。より安全な一時ターゲットパターンを示さない場合は、コード例を省き、アーキテクチャを説明してください。
    • Surface Shader については、#pragma surface に URP で直接対応するものはないと述べ、効果の複雑さに応じて Shader Graph または URP HLSL の頂点／フラグメントへの書き換えを選んでください。
    • 「書き換えてください」という説明だけで終わらせず、実用的な最初の移植手順と検証すべき対象を示してください。

9. 品質、ライティング、ビジュアルの同等性に関するレビュー

ユーザーがビジュアルの不一致、シャドウ、パフォーマンス、または品質設定に言及した場合は、references/quality-settings-map.md を使用してください。

  1. Graphics 設定と、アクティブな各 Quality レベルを確認してください。
    • Quality レベルにカスタム URP アセットが設定されていない場合、そのレベルでは意図的に Graphics 設定にフォールバックするのか、それとも明示的な割り当てがまだ必要なのかを示してください。
    • 関連する各レベルを確認していない限り、すべての Quality レベルの移行が完了したと断言しないでください。
    • シリアライズされたプロジェクト設定を使用する場合、保存されるフィールドは通常 customRenderPipeline です。保存されたアセットで割り当てが確認できない限り、renderPipelineAsset のような推測したフィールドに書き込むだけでは不十分です。
    • スクリプトで割り当てる場合は、URP の Render Settings コンバーターと同じパターンを使用してください。QualitySettings.GetQualityLevel() の戻り値をキャッシュし、対象レベルごとに QualitySettings.SetQualityLevel(index) を呼び出して QualitySettings.renderPipeline = urpAsset を割り当てた後、元の Quality レベルに戻し、ディスク上で確認してください。
  2. 同等性に一般的に影響する URP アセットの設定を確認してください。
    • シャドウ
    • シャドウの描画距離とカスケード
    • MSAA
    • レンダースケール
    • エフェクトが依存する場合の HDR、Opaque Texture、Depth Texture の設定
  3. ライティングが自動的に同一になると約束しないでください。
    • Built-in と URP では、ライトの減衰、ベイクされた GI の見え方、シャドウの調整、Reflection Probe の反応、トーンマッピング、露出、ポストプロセッシングの動作が異なる場合があります。
  4. **ベイク済みライティングのシーンでは、**既存のライトマップと Lighting Data は参考資料として扱い、URP での最終出力が保証されるものとは見なさないでください。
    • Lightmapping.lightingSettings、シーンの LightmapSettings、ベイク済みライトと混合ライト、Light Probe、Reflection Probe、既存の LightingDataAsset を確認してください。
    • ユーザーがビジュアルの参考資料またはロールバック手段を得るまではベイク済みデータを保持してください。ただし、シーンが白飛びしたり歪んだりする場合は、古い Built-in のライトマップを最終的な URP ライティングソリューションとして有効にしたままにしないでください。
    • シーンが白飛びする、暗すぎる、または一致しない場合は、まず URP の検証中に従来の PPv2 を無効にして、ポストプロセッシングと露出の影響を切り分けてください。その後、ライトを変更する前に URP Volume の露出、トーンマッピング、ブルームを確認してください。
    • ベイク済みデータをクリアするとシーンの白飛びが解消する場合は、古いライトマップまたは Lighting Data が古い、あるいは互換性のない有効なデータであることを特定してください。その後、古いベイクに合わせてライトを調整するのではなく、最終的な URP アセット、Renderer、Volume、Quality 設定を使用して URP で再ベイクしてください。
    • URP 互換の LightingSettings を作成または割り当てる場合は、Lighting Settings とアクティブなシーンを変更済みとしてマークし、シーンを保存してから、再読み込みするか再クエリし、保存されたシーンが意図した .lighting アセットを参照していることを確認してください。AssetDatabase.SaveAssets() だけでは、シーンの Lightmapping.lightingSettings 参照は保存されません。保存されたシーンが引き続き Enlighten／リアルタイム GI の設定アセットを参照している場合、「ベイク済み GI が有効」と報告しないでください。
    • ビジュアルの同等性が依頼に含まれ、古い LightingData.asset や Reflection Probe の EXR が Built-in でのベイク時のまま残っている場合は、URP で再ベイクまたは更新するまで参考データとして扱ってください。古いベイクデータだけでビジュアルの同等性が保たれていると断言しないでください。
    • ビジュアルの同等性が重要な場合は、ライティングのクリアと再ベイク、および Reflection Probe の更新を推奨してください。URP のセットアップ後、代表的なシーンを目視で確認していない限り、また、できれば URP でベイクした後でない限り、ベイク済みライティングの移行が成功したと断言しないでください。
  5. **2D ライティングのプロジェクトでは、**必要に応じてスプライトとタイルマップが URP 互換の Lit マテリアルを使用していることを確認してください。
  6. **パフォーマンスが低下した場合は、**原因が次のどれに該当するか確認してください。
    • URP アセット設定の負荷増大
    • ポストプロセッシング
    • シャドウの追加コスト
    • カスタムシェーダーの移植、またはバッチ処理されないシェーダー
  7. **URP アセット設定を変更する場合は、**MSAA、追加ライトの上限、HDR、Depth Texture、Opaque Texture などの値を報告する前に、保存済みのアセットを再読み込みするか、保存後にプロパティを照会してください。

10. 検証

セットアップ、変換、またはトラブルシューティングの後に、結果を検証します。

  1. シーンをキャプチャします： 代表的なシーンで Scene View または特定のカメラをキャプチャします。詳しくはreferences/capturing-the-editor.mdを参照してください。
  2. 結果を評価します：
    • 未解決のカスタムシェーダーがブロッカーとして残っている場合を除き、マゼンタ色のマテリアルがないこと
    • メインのライティングとシャドウが想定どおりに動作すること
    • ベイク済み GI／ライトマップ、ライトプローブ、リフレクションプローブが適切であるか、再ベイク／更新が必要として明示的に記録されていること
    • カメラが想定されるコンテンツをレンダリングすること
    • ポストプロセッシングまたはフルスクリーンエフェクトが引き続き正しく動作すること
    • 該当する場合、スプライト、タイルマップ、または 2D ライトが動作すること
  3. 視覚的な出力だけでなく、永続化されたプロジェクトデータを確認します。
    • 保存済みの URP アセット、レンダラーアセット、シーン参照、マテリアルのシェーダー GUID／名前、Quality 設定、Volume プロファイルを調べます。
    • ベイク済みライティング、PPv2、またはリフレクションプローブが存在しないと結論付ける前に、デフォルト／テストシーンではなく代表的なシーンが開かれたか、別の方法で調査されたことを確認します。
    • マテリアルの移行では、パーティクル／VFX マテリアルも検証対象に含めます。組み込みパーティクルシェーダー ID またはレガシーパーティクルシェーダー名が残っている場合、マテリアルの移行は未完了です。
    • PPv2 の移行では、移行済みとして報告する前に、保存済み URP VolumeProfile アセットに想定されるオーバーライドコンポーネントが含まれていることを確認します。
    • ツールログでポストプロセッシングがマッピング済みと報告されていても、保存済みプロファイルを再読み込みしたときに components: [] となる場合は、ツールログではなく、移行は失敗／未完了として報告します。
    • ベイク済みライティングを使用するシーンでは、Lighting Settings、Lighting Data／ライトマップ参照、ライトプローブ、リフレクションプローブを調べます。コンパイルの成功は、ベイク済みライティングの同等性を証明するものではありません。古いライトマップによって露出過多になる場合は、有効なベイク済みデータを消去し、URP で再ベイクしてから同等性を判断します。新しいライティング設定を割り当てた後は、新しい .lighting アセットの存在だけでなく、保存済みシーンの参照を確認します。
    • 古い LightingData.asset が引き続き割り当てられており、リフレクションプローブの EXR が再生成されていない、または視覚的な確認後に明示的に許容されていない場合、ライティング／プローブは更新済みではなく、保持または部分的として分類します。
  4. Unity.GetConsoleLogs を使って Console の出力を確認し、シェーダー、レンダーパイプライン、またはレンダラーフィーチャーのエラーがないか調べます。
  5. **最も影響の大きい問題から修正し、**その後、再度検証します。
  6. **最大 3 回まで繰り返し、**残るブロッカーを報告するか、どのように進めたいかユーザーに確認します。

11. トラブルシューティングの判断フロー

ユーザーから移行の問題が報告された場合は、次の診断フローに従います。

「移行」後もプロジェクトが Built-in のように動作する
  1. Graphics 設定で URP アセットが割り当てられているか確認します。
  2. 該当する Quality レベルも URP アセットを参照しているか確認します。
  3. ほかのトラブルシューティングを行う前に、アクティブなレンダーパイプラインが実際に URP であることを確認します。
URP のインストール後に移行が停止した
  1. これ自体を移行全体の失敗と見なさず、パッケージの更新／ドメイン再読み込みの境界として扱います。
  2. Packages/manifest.json とパッケージの状態を再確認します。URP がインストール済みなら、再インストールしないでください。
  3. URP アセット、レンダラーアセット、変換済みマテリアル、空の Volume プロファイル、シーンコンポーネントの変更など、部分的に作成されたアセットを調べます。
  4. URP がインストール／割り当て済みでも、Built-in マテリアルが依然として大部分を占める、またはシーンがマゼンタ色の場合、次に優先して未完了項目を完了させるのはマテリアル変換です。ロールバックの安全性がすでに確認済みであれば、URP のセットアップを完了としてそこで止めないでください。
  5. 最初の未完了の検証項目から続けます。Graphics／Quality の割り当て、レンダラーアセットの妥当性、マテリアル変換、PPv2 から URP Volume への移行、ベイク済みライティングの再ベイク、最後の検証の順です。
  6. 前のチャット／エクスポートに最終応答がない場合は、証拠が不完全であると報告し、新しいチャット／ターンで続行します。
マテリアルがマゼンタ／明るいピンク色になっている
  1. Console と Inspector でシェーダーのエラーを確認します。
  2. マテリアルがサポート対象の Built-in シェーダー、カスタムシェーダー、またはパッケージ所有のシェーダーのいずれを使用しているか確認します。
  3. サポート対象の Built-in シェーダーの場合は、まずコンバーターの処理経路または対象を絞ったマテリアル変換を確認します。
  4. プロジェクトがすでに URP を使用しており、サポート対象の Built-in マテリアルが多数残っている場合は、最終的なビジュアルの一致を調整する作業ではなく、マテリアル変換が未完了だと判断します。
  5. カスタムシェーダーまたはパッケージシェーダーの場合は、references/custom-shader-triage.md を参照し、必要に応じて references/complex-shader-situations.md も確認します。
シーンが大幅に暗い、明るい、または「おかしい」
  1. Scene View と Game View のキャプチャを比較します。
  2. まずポストプロセスの二重適用を確認します。残っている PPv2 の PostProcessVolume／PostProcessLayer と、有効な URP Volume が共存すると、検証用キャプチャが露出過多になったり、その他の歪みが生じたりすることがあります。
  3. シャドウ、環境光／環境ライティング、トーンマッピング、スカイボックス、露出、ブルーム、ポストプロセスを確認します。
  4. ベイク済みライティングの状態を調べます。Lighting Settings、Lighting Data アセット、ライトマップの参照、Mixed／Baked ライト、ライトプローブ、リフレクションプローブを確認します。
  5. コンテンツを書き換える前に、品質レベルの割り当てと URP アセット設定を確認します。
  6. ベイク済みデータを消去して深刻な露出過多が解消する場合、古いライトマップは有効な古いデータだと判断します。参照／ロールバック用の証拠としてのみ保持し、その後 URP で再ベイクします。
  7. シーンがベイク済みライティングに依存している場合、ビジュアルが一致したと判断する前に、URP での再ベイクとリフレクションプローブの更新を推奨します。
  8. Built-in と URP ではライトの減衰が異なる場合があることを覚えておきます。これは調整作業として扱い、変換に失敗した証拠とはみなしません。
ポストプロセスまたはフルスクリーンエフェクトが消えた
  1. PPv2 が変換されているか、対象カメラと Volume の設定が引き続き有効か確認します。
  2. 保存済みの URP VolumeProfile アセットを調べます。プロファイルが空の場合、PPv2 のエフェクトは実際には移行されていません。
  3. 古い PostProcessVolume／PostProcessLayer コンポーネントがシーン内で引き続き有効か確認します。
  4. OnRenderImage、カスタム blit コード、または置換シェーダーによるカメラエフェクトを検索します。
  5. Built-in のコールバック経路をそのまま維持しようとせず、URP 対応の方法でエフェクトを移植します。
透明／屈折／歪みのエフェクトが壊れた
  1. シェーダーが GrabPass または同様の Built-in 画面コピー処理に依存していたか確認します。
  2. 依存していた場合は、references/complex-shader-situations.md を参照し、Scene Color／Renderer Feature／カスタムパスを使う方法を選択します。
2D ライトがスプライトに影響しない
  1. プロジェクトが実際に 2D Renderer を使用していることを確認します。
  2. 必要に応じて、既存のスプライトマテリアルが URP 対応の Lit マテリアルにアップグレードされていることを確認します。
  3. 新しいスプライトをドラッグして配置したことを、古いプロジェクトのマテリアルが正しい証拠だと決めつけないでください。
移行後にパフォーマンスが低下した
  1. レンダースケール、シャドウ、追加ライト、MSAA、ポストプロセス、不透明度／深度テクスチャ、その他の URP アセット設定を確認します。
  2. カスタムシェーダーの移植によりバッチングの互換性が失われたり、追加パスが導入されたりしていないか確認します。
  3. ロールバックしか解決策がないと決めつける前に、設定を調整します。
カスタムシェーダーはコンパイルできるが、見た目がまだおかしい
  1. 問題が単純なパラメーターのずれなのか、構造的な非互換性なのかを判断します。
  2. シェーダーが Surface Shader、GrabPass、置換シェーダーのワークフロー、またはカスタムライティング経路に由来する場合は、複雑な移行ケースとして扱います。
  3. プロジェクト全体に展開する前に、代表的なマテリアルを 1 つ検証します。

12. コアガードレール

  • まずアクティブなレンダーパイプラインを検出してください。HDRP の場合は不一致を説明し、基本的な比較方法のみを案内してください。
  • ロールバックの安全性を確認する前にプロジェクトを変更しないでください。URP のインストール、アセットの割り当て、コンバーターの実行、マテリアルの編集、シーンの編集を行う前に、計画モードで停止してください。
  • ツールのログや作成されたアセットを証拠として扱わないでください。ステータスを報告する前に、Graphics、Quality、マテリアル、Volume、ライティング、プローブ、Console、および代表的なシーンを保存、再読み込み、再照会してください。
  • 部分的なフェーズをプロジェクト全体の完了として扱わないでください。成功ゲートに基づいて、Phase complete、Partial migration、Manual follow-up を報告してください。
  • 壊れやすいレンダリングコードを一括で書き換えないでください。カスタムシェーダー、GrabPass、OnRenderImage、置換シェーダー、パッケージが所有するレンダリングコード、および未サポートの PPv2 エフェクトには、対象を絞ったマッピングを使用してください。

13. 結果の報告

以下を要約してください。

  • 使用した移行パス
  • プロジェクトが引き続き Built-in なのか、一部移行済みなのか、URP への移行が完了しているのか
  • 実行したコンバーター
  • 自動的に修正された内容
  • まだ手動作業が必要な内容
  • 検証したシーン、マテリアル、またはカメラ
  • 特に複雑なシェーダー、パッケージのエフェクト、見た目の同等性に関して残っているリスク
  • ポストプロセスの移行が完了したのか、一部準備済みなのか、手動での対応として記録しただけなのか
  • Quality レベルが明示的に割り当てられているのか、Graphics 設定へのフォールバックに意図的に依存しているのか
  • パーティクル／VFX マテリアルが変換済みなのか、URP パーティクルシェーダーへの対応がまだ必要なのか
  • ベイク済みライティング／ライトマップ／リフレクションプローブが参照用に保持されたのか、見た目が検証済みなのか、再ベイク／更新済みなのか、手動対応として残されているのか
  • 露出、トーンマッピング、環境光、およびカメラ／Volume のポストプロセス配線の見た目のバランスが取れているのか、まだ部分的な状態なのか

完了を示す表現は慎重に使用してください。報告に Partial、Manual follow-up、not validated、may still need、または未サポート機能に関する項目が含まれる場合は、完了した個別のフェーズが成功したことを示しつつ、移行全体は部分的または手動対応が必要であると明記してください。プロジェクト全体の「完了」という主張と、手動対応が必要な項目を併記しないでください。

参考資料

このスキルが有効になったら、事前に references/migration-workflow.md を読んでください。リクエストにマテリアル、シェーダー、マゼンタ色のマテリアル、カスタムレンダリング、またはフルスクリーンエフェクトが含まれる場合は、references/custom-shader-triage.md と references/complex-shader-situations.md も読んでください。リクエストに移行後の見た目の不一致、ライティング、ベイク済みライティング、ライトマップ、リフレクションプローブ、シャドウ、またはパフォーマンスが含まれる場合は、references/quality-settings-map.md も読んでください。ユーザーが実際の移行変更を許可している場合、または部分的な移行の続行や修復を依頼している場合は、references/implementation-patterns.md も読んでください。

コメント

Markdown 対応