2d-pixel-perfect

Unity プロジェクトで、2D のピクセルパーフェクトなレンダリングを設定、診断、修正します。

---

⚠ 完全に別個の実装が2つあります

Unity のピクセルパーフェクトなレンダリングは、単一のシステムではありません。レンダーパイプラインごとに、互換性のない別個の実装があります。コードを記述したり診断したりする前に、必ずパイプラインを検出してください。

	URP	Built-in
コンポーネント	UnityEngine.Rendering.Universal.PixelPerfectCamera	UnityEngine.U2D.PixelPerfectCamera
パッケージ	URP に組み込み済み。追加インストール不要	com.unity.2d.pixel-perfect v6.0.0+
API の形式	列挙型（gridSnapping、cropFrame）	ブール値（pixelSnapping、upscaleRT、cropFrameX/Y）

URP プロジェクトには com.unity.2d.pixel-perfect をインストールしないでください。

→ 必ず最初に DetectPipeline() を呼び出してください（references/pipeline-detection.cs）。その後、検出結果に応じてセットアップ、診断、修正を分岐してください。

---

このスキルを使用しない場合

• HD 2D ゲームや高解像度の 2D ゲーム — ピクセルスナップとポイントフィルタリングにより、滑らかなアートの見た目が損なわれます
• UI のみのシーン — 代わりに Canvas Scaler を使用してください
• HDRP プロジェクト — Pixel Perfect Camera はサポートされていません

---

重要な注意事項

⚠ まずレンダーパイプラインを検出してください — URP と Built-in では、互換性のない別々の Pixel Perfect Camera コンポーネントを使用します。 ⚠ 最もよくある修正は Filter Mode = Point です — Unity のデフォルトはバイリニアフィルタリングで、スプライトがぼやける原因のほとんどはこれです。 ⚠ アンチエイリアスは無効にしてください — Quality Settings とカメラの両方で無効にします。AA はピクセルのエッジを実際にぼかします。

主な原則

1. パイプラインの検出とカメラコンポーネントの選択

このファイル上部の2つのパスの比較表を参照してください。アセンブリ名に関する注意：スタンドアロンの Built-in パッケージは Runtime/ フォルダーにインストールされますが、asmdef の "name" フィールドは Unity.2D.PixelPerfect であり、Runtime サフィックスは付きません。HDRP はサポートされていません。Common Issues の HDRP フォールバックのセクションを参照してください。

→ コード：references/pipeline-detection.cs — DetectPipeline()、GetPixelPerfectCameraType()、および移行時の不一致チェック。

2. 診断を最優先するアプローチ

変更を加える前に、必ず診断してください。調査結果を報告し、壊れている箇所だけを修正してください。

3. 適切なスコープで作業する

デフォルトではシーンを対象にします。ユーザーが明示的に求めた場合に限り、プロジェクト全体をスキャンしてください。

---

診断チェックリスト

スプライトのインポート設定：

• 対象範囲内のすべてのスプライトで Filter Mode = Point (no filter)
• Mip Maps = 無効
• Compression = None / Uncompressed
• シーン内のすべてのスプライトで PPU が統一されている
• スプライトのピボットが Custom / Pixels モードに設定されている — 寸法が奇数のスプライト（例：15×15）で中央ピボットを使用すると、7.5px に配置され、0.5px のずれが発生します

→ コード：references/sprite-settings.cs — GetImporter() と FixSpriteImportSettings()。

エディターのスナップ設定：

• すべての軸で Grid Size = 1 / assetsPPU（例：PPU 16 → 0.0625、PPU 100 → 0.01）
• Grid and Snap オーバーレイで Grid Snapping が有効になっている
• 既存の GameObject をスナップするには、選択してから Align Selected → All Axes を実行します

カメラのセットアップ：

• カメラの投影方式 = Orthographic
• Pixel Perfect Camera コンポーネントがあり、パイプラインに適した型である
• allowHDR、allowMSAA、allowDynamicResolution がすべて false
• Scene ビューで、カメラのギズモに2つの緑色の境界ボックスが表示されている — 実線は表示領域、点線は参照解像度を示します

→ コード：references/camera-setup-urp.cs — URP カメラと PP Camera の完全な設定。 → コード：references/camera-setup-builtin.cs — Built-in のスタンドアロン設定。

プロジェクトの品質設定：

• Quality Settings で Anti-Aliasing = 0
• Anisotropic Filtering = Disabled

API リファレンス

プロパティ／メソッドの全テーブル、GridSnapping と CropFrame の列挙値、推奨設定については、次を参照してください。 → references/api-reference.md — カメラ設定コードを作成またはレビューするときにお読みください。

列挙値の簡単な概要：

GridSnapping：None · PixelSnapping（標準） · UpscaleRenderTexture（低解像度の画質を忠実に再現。ポストプロセスおよび UI テキストとは互換性がありません）

CropFrame：None · Pillarbox · Letterbox · Windowbox（最も安全なデフォルト） · StretchFill

---

参照解像度

アセットを作成する前に選択してください。アセットの制作を始めた後は、絶対に変更しないでください。

参照解像度	1080p	1440p	4K
320 × 180	6×	8×	12×
480 × 270	4×	~5.3×	8×
640 × 360	3×	4×	6×

320×180 は、汎用的な用途で最も安全な選択肢です。整数倍で表示できない画面（例：1366×768）では、分数スケールに引き伸ばすのではなく、cropFrame = Windowbox を使って黒帯を追加してください。

---

移行と互換性

組み込みのスタンドアロンコンポーネントを使用している URP プロジェクト

症状：DetectPipeline() は URP を返すものの、カメラには UnityEngine.U2D.PixelPerfectCamera が設定されています。スタンドアロンコンポーネントには ENABLE_URP の条件付きコードがあるため、症状はわかりにくいものです。

修正方法：

1. Package Manager から com.unity.2d.pixel-perfect を削除します
2. 各カメラから UnityEngine.U2D.PixelPerfectCamera を削除します
3. UnityEngine.Rendering.Universal.PixelPerfectCamera を追加します
4. 再設定します。ブール値（pixelSnapping、upscaleRT、cropFrameX/Y）は列挙値（gridSnapping、cropFrame）になります

→ 検出コード：references/pipeline-detection.cs（ファイル末尾）。

古い URP 名前空間（Unity 2022 より前／URP 13.x より前）

症状：UnityEngine.Experimental.Rendering.Universal を参照するコンパイラーエラーが発生します。

修正方法：using UnityEngine.Experimental.Rendering.Universal; を using UnityEngine.Rendering.Universal; に置き換えます。アセンブリ修飾型の文字列も更新してください。[MovedFrom] 属性がシリアライズを自動的に処理するため、GameObject 上のコンポーネントはアップグレード後も保持されます。

---

よくある問題と解決策

スプライトがぼやける

修正方法：対象となるすべてのスプライトの Filter Mode を Point に設定し、Mip Maps を無効にして、Quality Settings で AA を無効にします。 → コード：references/sprite-settings.cs

タイル間に Tilemap の隙間ができる

負のセル間隔や PPU = 31.99 などの回避策はカメラの移動時に問題が起きるため、以下を順番に確認してください。

#	確認項目	修正方法
1	Sprite Atlas で Tight Packing がオフ、Padding ≥ 4、Sprite Packer Mode が有効になっていますか？	Editor の設定で Sprite Packer Mode を有効にし、アトラスの Padding を ≥ 4 に設定して、Tight Packing をオフにします
2	タイルセットのテクスチャとアトラスで Mipmaps が無効になっていますか？	Generate Mip Maps を無効にします
3	AA = 0 で、カメラの MSAA がオフになっていますか？	AA をグローバルに無効にします
4	Compression = None になっていますか？	RGBA 32-bit uncompressed にします
5	すべてのタイルスプライトのピクセル寸法は偶数ですか？	奇数の寸法では 0.5px のグリッドずれが生じます
6	PPU = タイルのピクセル幅になっていますか？（16×16 → PPU 16）	PPU が一致しないと物理的な隙間ができます
7	上記をすべて確認しても、カメラの移動中だけ隙間ができますか？	PP Camera のピクセルスナップを使用します。cellGap = -0.01f は使用しないでください

Cinemachine との競合

原因：Cinemachine と Pixel Perfect Camera の両方が、毎フレーム orthographic size を書き換えています。

修正方法：各 Virtual Camera の Add Extension ドロップダウンから CinemachinePixelPerfect 拡張機能を追加します。コードで AddComponent を使って追加しないでください。

既知の制限：

• Virtual Camera 間のカメラブレンドは、遷移中にピクセルパーフェクトになりません
• UpscaleRenderTexture は有効なピクセルパーフェクトの ortho size を減らすため、フレーミングがずれることがあります
• Target Group と Framing Transposer の併用では目立つカクつきが発生します（解決策はありません）

upscaleRTによる後処理のぼやけ

原因：PP Cameraがレンダーテクスチャをアップスケールした後に、後処理が実行されます。

簡単な解決方法：upscaleRTを無効にします。後処理はネイティブの画面解像度で実行されるようになります。

高度な解決方法（Unity 6 URP）：RenderPassEvent2D.AfterRenderingPostProcessingでScriptableRendererFeature2Dを挿入します。2D専用の基底クラスを使用してください。3Dの基底クラスであるScriptableRendererFeatureは、URPの2Dレンダラーでは無視されます。

upscaleRT使用時にUIテキストがぼやける

状況：既知のUnityのバグです。修正は見送られており、2025年のUnity 6でも残っています。

根本原因：（A）Canvasが低解像度バッファーにレンダリングされ、シーンとともにアップスケールされます。（B）TMPのSDFグラデーションしきい値が、低い参照解像度では適切に調整されていません。

信頼性の高い順の解決方法：

1. CanvasをScreen Space - Overlayに設定します。カメラを介さず、ネイティブの解像度でレンダリングされます
2. PP Cameraコンポーネントを持たない専用UIカメラを使用し、Screen Space - Cameraモードに設定します
3. Unity 6のみ：Font Material → Debug Settings → Sharpness = 1（Bを緩和しますが、Aには効果がありません）

物理演算とレンダリングのずれ（マイクロスタッター）

原因：物理演算は固定タイムステップで実行されます。補間された位置は小数値になり、フレームごとに異なるピクセル位置へスナップされます。

解決方法：

• 物理演算で動くスプライトでは、Rigidbody2D.interpolation = RigidbodyInterpolation2D.Interpolateを有効にします
• Time.fixedDeltaTime = 1f / 60fを設定し、目標フレームレートに合わせます
• カメラの追従処理はFixedUpdateではなく、LateUpdateに設定します

非整数スケーリング／ピクセルの間引き

原因：画面解像度が参照解像度の整数倍になっていません。

解決方法：上の表から参照解像度を選びます。整数倍で画面に収まらない場合は、cropFrame = Windowboxを使用します。

URP 2D Rendererが見つからない

解決方法：

1. Assets > Create > Rendering > URP 2D Renderer Data
2. 作成したアセットを、URP AssetのRenderer Listに割り当てます
3. com.unity.render-pipelines.universal 12.0以降が必要です

HDRPのフォールバック

HDRPではPixel Perfect Cameraはサポートされていません。

Built-in／Unity 5.x：RenderTextureとGraphics.BlitをFilterMode.Pointとともに使用します。

Unity 6 URP：RenderPassEvent2D.AfterRenderingでAddRasterRenderPassを使用して、ScriptableRendererFeature2DとScriptableRenderPass2Dを挿入します。注：OnRenderImageとGraphics.Blitは、Unity 6のレンダーグラフと互換性がありません。