urp-postprocessing

URP の Volume フレームワークを使用して、ポストプロセスエフェクトのセットアップ、設定、デバッグを支援します。

目標：セットアップ後に、コンソールエラーがゼロの状態で視覚的な結果が得られること。

0. 前提条件：C# を実行できる Editor

Volume プロファイル、VolumeParameter.overrideState、カメラのポストプロセスフラグは、Editor／ランタイムのオブジェクト状態です。以下の確認と編集はすべて、起動中の Editor 内で C# を実行します。

そこまでの準備は unity-cli スキルが担当します — CLI のインストール、接続済み Editor の確認、プロジェクトへの com.unity.pipeline パッケージの追加、Editor が本当に存在しない場合と Safe Mode で停止している場合の見分け方、Editor のコマンドカタログの確認です。まずそちらに従い、ここで同じ内容を調べ直さないでください。必要なのは特に script eval です。Editor に接続できるだけでは不十分です。script eval があるかどうかは CLI ではなく、Pipeline パッケージのバージョンによって決まります。見つからない場合は、その旨を伝えて停止してください。

接続済み Editor から script eval コマンドを使って C# を実行します。パラメーターの形式は unity command --format json で確認し、決めつけないでください。インライン形式は unity command script eval --caller plugin --skill urp-postprocessing --code '<snippet>' です。Pipeline のバージョンによっては、ファイル内のスニペットを実行する script eval_file も登録されています。script eval_file を使う前に、必ずカタログを確認してください。これは登録されていないことがよくあります。 unity command のタイムアウトは、デフォルトで 30 秒です。

C# を script eval に渡す

script eval がコンパイルするのはファイルではなくステートメントブロックです。そのため、コンパイルエラー（警告ではありません）が発生する原因が 2 つあります。

• using ディレクティブは使えません。 コンパイラーは using UnityEngine; をリソース破棄ステートメントとして読み取り、拒否します（CS0210）。
• 型名は完全修飾する必要があります。 AssetDatabase や Volume だけでは解決されません（CS0246／CS0103）。また、Object だけでは object と曖昧になります（CS0104）。

以下のスニペットが、読みやすさのため、またはプロジェクト内に保存するために、using を含むファイル形式で記述されている場合は、script eval に渡す前に型名を完全修飾してください。

0. 事前確認

エフェクトを設定する前に、すべての項目を確認してください。問題があれば、まず修正してください。

1. URP がアクティブなレンダーパイプラインであること — そうでない場合は、ユーザーに伝えて停止してください。
2. URP Asset で HDR が有効になっていること — トーンマッピングに必要です。Bloom は HDR で最も効果的に動作します。SDR でも動作しますが、threshold は 1 未満にする必要があります。
3. カメラでポストプロセスが有効になっていること — renderPostProcessing は true である必要があります（デフォルトは false）。カメラスタッキングでは、CameraRenderType.Base カメラ、またはスタック内の最後の Overlay カメラだけでポストプロセスを有効にしてください。また、Renderer の PostProcessData アセットが null でないことも確認してください。null の場合、ポストプロセスパスは存在しません。
4. Volume の GameObject レイヤーが、カメラの Volume Layer Mask に含まれていること — volumeLayerMask のデフォルトは、レイヤー 0 の「Default」のみです。Volume の GameObject.layer が含まれていない場合、カメラは Volume を無視します。
5. enabled = true で、有効な Profile と 1 つ以上の Override が設定された Volume が存在すること — Volume コンポーネントが有効で、null ではない profile（または sharedProfile）を持ち、1 つ以上の VolumeComponent のプロパティで overrideState = true になっている必要があります。

事前確認用スニペット

次を実行して、セットアップをプログラムで確認します。

// `script eval` compiles a statement block, not a file: no `using` directives are
// allowed, so every type is fully qualified.
var report = new System.Text.StringBuilder();

// 1. Check URP is active — a hard stop, so throw: it fails the eval loudly
var urpAsset = UnityEngine.Rendering.Universal.UniversalRenderPipeline.asset;
if (urpAsset == null)
    throw new System.Exception("URP is not the active render pipeline.");

// 2. Check HDR
if (!urpAsset.supportsHDR)
    report.AppendLine("Warning: HDR is disabled on the URP Asset. Tonemapping won't work; Bloom requires threshold < 1.");

// 3. Check camera post-processing
var cam = UnityEngine.Camera.main;
if (cam == null)
    throw new System.Exception("No Main Camera found.");
if (!cam.TryGetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>(out var camData))
    throw new System.Exception("Missing UniversalAdditionalCameraData on camera. Is URP active?");
if (!camData.renderPostProcessing)
    report.AppendLine("Warning: Post-processing is disabled on the camera. Enable via camData.renderPostProcessing = true.");

// 4. Check volume layer mask
var volumes = UnityEngine.Object.FindObjectsByType<UnityEngine.Rendering.Volume>(UnityEngine.FindObjectsSortMode.None);
foreach (var vol in volumes)
{
    if (!vol.enabled) { report.AppendLine($"Warning: Volume '{vol.name}' is disabled."); continue; }
    if ((camData.volumeLayerMask & (1 << vol.gameObject.layer)) == 0)
        report.AppendLine($"Warning: Volume '{vol.name}' on layer {vol.gameObject.layer} is not in camera's volumeLayerMask.");
    // 5. Check profile and overrides
    var profile = vol.sharedProfile;
    if (profile == null) { report.AppendLine($"Warning: Volume '{vol.name}' has no profile assigned."); continue; }
    if (profile.components.Count == 0)
        report.AppendLine($"Warning: Volume '{vol.name}' profile has no overrides.");
}

// Return the findings: logs land in the Editor console, the returned value comes back to you
return report.Length == 0 ? "Post-processing setup looks correct." : report.ToString();

1. ボリュームの設定

エフェクトは、VolumeProfile（ScriptableObject）のVolumeComponent オーバーライドとして追加します。

グローバルボリューム（最も一般的）：Volume コンポーネントを持つ GameObject で、isGlobal = true に設定し、profile を割り当てます。Volume のレイヤーが volumeLayerMask に含まれるすべてのカメラに影響します。

ローカルボリューム（任意。ただし、優先して適用されます）：トリガー用の Collider と Volume コンポーネントを持つ GameObject で、isGlobal = false に設定します。プロパティ：

• priority（float）— 値が大きいボリュームは、重なったときに値の小さいボリュームを上書きします。
• blendDistance（float）— ブレンドを開始する外側の距離（ワールド単位）です（0 = ブレンドなし。コライダーの境界で即座に切り替わります）。
• weight（float、0–1）— ボリューム全体の影響度を調整します。

2. ポストプロセスエフェクト

すべてのエフェクトは VolumeComponent のサブクラスであり、profile.Add<T>() を使って VolumeProfile にオーバーライドとして追加します。profile.Has<T>() または profile.TryGet<T>(out var t) で存在を確認します。削除するには profile.Remove<T>() を使います。

すべてのプロパティは VolumeParameter です。value を設定する前に、必ず overrideState = true を設定してください。そうしないと、Volume システムはその値を無視します。

特定のエフェクトを設定する場合は、完全な API リファレンスを確認してください：

• references/effect-reference.md — エフェクトごとのすべての VolumeComponent プロパティ（Bloom、Tonemapping、ColorAdjustments、DepthOfField、Vignette、MotionBlur、FilmGrain、ChromaticAberration、SplitToning、LensDistortion、WhiteBalance、PaniniProjection、LiftGammaGain、ShadowsMidtonesHighlights、ColorCurves、ChannelMixer）

コードテンプレート：

• references/code-templates.md — グローバルボリュームの設定、カメラのポストプロセス、プロファイルの変更に関するテンプレート

3. ハルシネーション防止ルール

必須の Using

これらは、プロジェクトに .cs ファイルを書き込む場合に適用されます。script eval に渡すスニペットには含められないため、代わりに型を完全修飾してください（上記「script eval への C# の渡し方」を参照）。

using UnityEngine.Rendering;           // Volume, VolumeProfile, VolumeComponent, VolumeParameter
using UnityEngine.Rendering.Universal;  // Bloom, Tonemapping, ColorAdjustments, UniversalRenderPipeline, etc.

誤り → 正しい API の対応

誤り	正しい API
PostProcessVolume	Volume（UnityEngine.Rendering から）
PostProcessLayer	UniversalAdditionalCameraData.renderPostProcessing（bool）
UnityEngine.Rendering.PostProcessing	UnityEngine.Rendering.Universal
profile.GetSetting<T>()	profile.TryGet<T>(out var t)（bool を返す）
profile.AddSettings<T>()	profile.Add<T>()（T を返す。すでに存在する場合は例外が発生するため、先に profile.Has<T>() で確認してください）
volume.sharedProfile（実行時に変更する場合）	volume.profile（アセットをインスタンスに自動複製します）
VolumeManager.instance.stack.GetComponent<T>()	volume.profile.TryGet<T>(out var t)

重要な事実

• 設定するすべての VolumeParameter で overrideState = true が必要です。Volume システムは overrideState が false のパラメーターを無視します。これはスクリプトで最もよくある間違いです。
• sharedProfile = アセットを直接返します（編集内容はディスクに保存されます）。profile = 必要に応じてインスタンスに自動複製します（実行時の編集に安全です）。volume.HasInstantiatedProfile() で確認してください。
• profile.Add<T>(bool overrides = false) — true を渡すと、追加したコンポーネントのすべてのパラメーターで overrideState が自動的に有効になります。

4. デバッグチェックリスト

後処理が機能しない場合は、次の順に確認してください。

1. cam.TryGetComponent<UniversalAdditionalCameraData>(out var data) が成功し、data.renderPostProcessing が true になっていますか？
2. シーンに profile（または sharedProfile）が割り当てられた Volume が存在しますか？
3. profile.Add<T>() でオーバーライドを追加し、設定する各プロパティの overrideState = true にしていますか？
4. Volume の GameObject.layer は、カメラの data.volumeLayerMask に含まれていますか？（デフォルトのマスクはレイヤー 0 の「Default」のみです。）
5. グローバルの場合は volume.isGlobal = true にしていますか？ ローカルの場合はカメラが Volume のトリガー Collider 内にありますか？
6. カメラの data.renderType は Overlay ではなく CameraRenderType.Base になっていますか？（Overlay カメラは Base カメラの出力に合成されます。）
7. UniversalRenderPipeline.asset.supportsHDR は true ですか？ Bloom と Tonemapping に必要です。
8. Game view で表示していますか？ Scene view には、ツールバーに個別の後処理切り替えがあります。

5. よく使うレシピ

形式：エフェクト プロパティ=値。Bloom の値は threshold/intensity/scatter の順です。

シネマティック（フィルム）： Tonemapping mode=ACES、ColorAdjustments contrast=15 saturation=-10、Bloom threshold=0.9 intensity=0.5 scatter=0.7、Vignette intensity=0.3 smoothness=0.4、FilmGrain type=Medium1 intensity=0.2

スタイライズド／鮮やか： Tonemapping mode=Neutral、ColorAdjustments saturation=20 contrast=10、Bloom threshold=0.8 intensity=1.5 scatter=0.6、SplitToning highlights=warm shadows=cool

ホラー／ダーク： ColorAdjustments postExposure=-0.5 saturation=-30 contrast=20、Vignette intensity=0.5 smoothness=0.3 color=dark-red、FilmGrain type=Large01 intensity=0.4、ChromaticAberration intensity=0.15

クリーン／モバイル： Tonemapping mode=Neutral、ColorAdjustments postExposure=0.2、Bloom threshold=1.0 intensity=0.3（控えめ）。モバイルでは FilmGrain、MotionBlur、DepthOfField を避けてください。

6. 最終確認

セットアップ後、ユーザーに次の内容を報告してください。

Post-Processing Setup Complete
- Volume: [Global/Local] on "[GameObject Name]"
- Profile: [Asset Path]
- Effects: [List with key property=value pairs]
- Camera: [Name] — renderPostProcessing=true, volumeLayerMask includes layer [N]

View results in Game view (not Scene view).
Undo all changes with Edit > Undo (Ctrl+Z).