urp-postprocessing

URP の Volume フレームワークを使って、ポストプロセスエフェクトのセットアップ、設定、デバッグをユーザーに案内します。

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

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

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

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

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

eval に C# を渡す方法

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

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

以下のスニペットがファイル形式で書かれている場合（読みやすさのために using を含む場合や、プロジェクトに保存する目的の場合）は、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 つ以上ある Volume が存在する — Volume コンポーネントが有効で、profile（または sharedProfile）が null ではなく、1 つ以上の VolumeComponent のプロパティで overrideState = true になっている必要があります。

事前確認用スニペット

次を実行して、セットアップをプログラムで確認してください。

// `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. Volume のセットアップ

エフェクトは、ScriptableObject である VolumeProfile に VolumeComponent オーバーライドとして追加します。

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

Local Volume（任意。ただし優先されます）：トリガー用の Collider と Volume コンポーネントを持つ GameObject を作成し、isGlobal = false に設定します。プロパティは次のとおりです。

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

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 — グローバル Volume のセットアップ、カメラのポストプロセス、プロファイル変更のテンプレート

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

必須の using

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

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

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

5. よく使うレシピ

形式：エフェクトのプロパティ=value。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).