mcpField
M
migrate-birp-to-urp

migrate-birp-to-urp

github.com/unity-technologies開発1.2k3.5k 回インストール1 日前に更新
リポジトリ

migrate-birp-to-urp について

Unity の Built-in から URP への移行を計画、実行、検証するスキルです。プロジェクトの依存関係と保存状態を段階的に確認し、パイプラインを変更する前にロールバック手段の確認を求めます。

主な機能

  1. 01パイプラインの状態と移行内容を分類
  2. 02マテリアル、シェーダー、ライティング、エフェクトを調査
  3. 03変更前にロールバック手段を確認
  4. 04段階的に移行し保存状態を検証
  5. 05代表シーンを確認して状況を報告

活用シーン

  1. 01Built-in から URP への移行を計画
  2. 02移行途中の Unity プロジェクトを監査
  3. 03対応マテリアルやカメラエフェクトを変換
  4. 04移行状況と未解決項目を確認

インストール

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

$npx skills add https://github.com/unity-technologies/skills --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 への移行結果を慎重に検証してください。

必須の実行リファレンス

実際に移行または修復を行う場合は、プロジェクト設定、マテリアル、ポストプロセス、ライティング、プローブ、シーンを編集する最初の 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 と報告できるのは、すべての成功条件を満たした場合のみです。

実行手順：エディターで C# を実行する

このスキルのすべての C# ステップは、Unity CLI を通じて実行中のエディター内で行います。そこに到達するための手順は unity-cli スキルが担当します — CLI のインストール、接続済みエディターの確認、プロジェクトへの com.unity.pipeline パッケージの追加、エディターが本当に存在しない場合とセーフモードで停止している場合の見分け方、エディターのコマンドカタログの確認です。まずそちらに従い、ここで手順を再構築しないでください。

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

  • 到達可能なエディターがあるだけでは不十分で、特に eval が必要です。カタログにあることを確認してください。その有無は CLI ではなく Pipeline パッケージのバージョンによって決まるため、正常にインストールできていても使えない場合があります。見つからない場合は、その旨を伝えて中止してください。

  • 6000.3 より古いエディターでは、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 に行もエラーも表示されません。実際の原因は、エディターログに記録されるこの 2 つの型に対する CS0246 です。この現象が見られたら、CLI のデバッグではなく、エディターが古すぎて Pipeline パッケージに対応していないとユーザーに伝えてください。

    この点は、ほとんどのスキルよりも重要です。 Built-in パイプラインからプロジェクトを移行する人は、定義上、古いエディターを使っていることがよくあります。

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

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

eval に C# を渡す

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

複数段階の移行では、スクリプトを使う方法のほうが確実です。URP のインストールやマテリアル変換で発生するドメインリロードにも対応できますが、長い 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 設定用と、品質レベルごとのものです。
    • プロジェクトに Quality レベルがある場合、プロジェクト全体が切り替わっていると決めつける前に、各レベルで使用されている Render Pipeline Asset を確認します。
  2. 移行対象を洗い出します： eval と UnityEditor.AssetDatabase.FindAssets、または同等のアセットクエリを使用して、以下を洗い出します：
    • マテリアル。組み込みパーティクルシェーダーをよく使用するパーティクル／VFX マテリアルも含めます
    • 植生マテリアル。草、木、地形詳細、SpeedTree、ビルボード、葉カード、カットアウト、風で揺れる葉のマテリアルも含めます
    • シェーダー
    • シーンと重要なプレハブ
    • URP アセットとレンダラーアセット（存在する場合）
    • ポストプロセッシングプロファイル／ボリュームプロファイル
    • Lighting Settings アセット、Lighting Data アセット、ライトマップ、ライトプローブ、リフレクションプローブ、Mixed／Baked ライト
  3. レンダリングに関するリスクの兆候を検索します： 使用可能なプロジェクトファイル検索、AssetDatabase.FindAssets、または短い 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 の参照があり、surface shader 構文を使用するカスタムシェーダーが複数含まれています。」

2. 要件を確認する

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

一般的な依頼には、以下をデフォルトとして使用します：

ユーザーの発言デフォルトの解釈
「このプロジェクトを URP にアップグレードして」プロジェクト全体の移行
「この 2D プロジェクトを URP に移行して」Built-in 2D から URP 2D への移行
「これらのマテリアルを変換して」対象を絞ったマテリアル変換
「マテリアルがピンクになった」移行後のシェーダー／マテリアルのトラブルシューティング
「URP にしたらライティングがおかしくなった」品質と見た目の同等性に関するトラブルシューティング
「まだ何も変更しないで」計画／監査のみ
確認する情報
  • 範囲： プロジェクト全体、選択したマテリアルのみ、またはトラブルシューティングのみ
  • 対象のレンダラー： 標準 URP または URP 2D
  • 検証対象： ユーザーにとって特に重要なシーン、プレハブ、カメラ
  • リスク許容度： 一部の手動対応が許容されるかどうか
  • レンダリングの依存関係： カスタムシェーダー、Asset Store のシェーダー、PPv2、ベイク済みライティング／ライトマップ／プローブ、イメージエフェクト、コマンドバッファ、置換シェーダー、または複数の Quality レベル
  • 実行の許可： 計画のみか、実際のプロジェクト変更も行うか

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 のインストールにより、パッケージの更新、コンパイル、ドメインの再読み込みが発生する場合があります。フェーズの境界として扱ってください。
    • UnityEditor.PackageManager.Client.Add を実行する eval 呼び出し内で、いつまでも待機し続けてはいけません。インストールを要求してから、Unity の更新が完了した後に Packages/manifest.json、パッケージ一覧、または URP の型やアセットの存在を確認してください。
    • パッケージのインストールによって 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 対応