2d Pixel Perfect

Set up, diagnose, and fix pixel perfect 2D rendering in Unity projects.

⚠️ There Are Two Completely Separate Implementations

Pixel perfect rendering in Unity is not one system — it is two separate, incompatible implementations, one per render pipeline. Always detect the pipeline before writing or diagnosing any code.

Do not install `com.unity.2d.pixel-perfect` in a URP project.

→ Always call `DetectPipeline()` first (references/pipeline-detection.cs), then branch your setup, diagnostics, and fixes based on the result.

When NOT to use this skill

• HD 2D or high-resolution 2D games — pixel snapping and point filtering will make smooth art look wrong
• UI-only scenes — use Canvas Scaler instead
• HDRP projects — Pixel Perfect Camera is not supported

Critical Reminders

⚠️ Detect the render pipeline first — URP and Built-in use different Pixel Perfect Camera components that are not interchangeable. ⚠️ Filter Mode = Point is the #1 fix — bilinear filtering is Unity's default and is almost always the cause of blurry sprites. ⚠️ Anti-Aliasing must be disabled — in Quality Settings and on the camera. AA actively blurs pixel edges.

Key Principles

1. Pipeline Detection & Camera Component Selection

See the two-path comparison table at the top of this file. Assembly name note: the standalone Built-in package installs into a Runtime/ folder, but the asmdef "name" field is Unity.2D.PixelPerfect — no Runtime suffix. HDRP is unsupported — see the HDRP fallback section under Common Issues.

→ Code: `references/pipeline-detection.cs` — DetectPipeline(), GetPixelPerfectCameraType(), and migration mismatch check.

2. Diagnostic-First Approach

Always diagnose before making changes. Report findings, then fix only what is broken.

3. Work in the correct scope

Default to scene scope. Scan project-wide only when the user explicitly requests it.

Diagnostic Checklist

Sprite import settings:

• [ ] Filter Mode = Point (no filter) on all in-scope sprites
• [ ] Mip Maps = disabled
• [ ] Compression = None / Uncompressed
• [ ] PPU consistent across all sprites in scene
• [ ] Sprite pivots set to Custom / Pixels mode — a center pivot on an odd-dimension sprite (e.g. 15×15) lands at 7.5px, causing 0.5px misalignment

→ Code: `references/sprite-settings.cs` — GetImporter() and FixSpriteImportSettings().

Editor snap settings:

• [ ] Grid Size = 1 / assetsPPU on all axes (e.g. PPU 16 → 0.0625, PPU 100 → 0.01)
• [ ] Grid Snapping enabled in the Grid and Snap overlay
• [ ] To snap existing GameObjects: select them → Align Selected → All Axes

Camera setup:

• [ ] Camera projection = Orthographic
• [ ] Pixel Perfect Camera component present and correct type for pipeline
• [ ] allowHDR, allowMSAA, allowDynamicResolution all false
• [ ] Scene view shows two green bounding boxes on the camera gizmo — solid = visible area, dotted = reference resolution

→ Code: `references/camera-setup-urp.cs` — full URP camera + PP Camera configuration. → Code: `references/camera-setup-builtin.cs` — Built-in standalone configuration.

Project quality settings:

• [ ] Anti-Aliasing = 0 in Quality Settings
• [ ] Anisotropic Filtering = Disabled

API Reference

Full property/method tables, GridSnapping and CropFrame enum values, and recommended configurations: → `references/api-reference.md` — read this when writing or reviewing camera setup code.

Quick enum summary:

`GridSnapping`: None · PixelSnapping (standard) · UpscaleRenderTexture (authentic low-res; incompatible with post-processing and UI text)

`CropFrame`: None · Pillarbox · Letterbox · Windowbox (safest default) · StretchFill

Reference Resolution

Choose before building any assets. Never change after asset production starts.

320×180 is the safest general choice. For screens with no integer fit (e.g. 1366×768), use cropFrame = Windowbox to add black bars rather than stretching to a fractional scale.

Migration & Compatibility

URP project with the Built-in standalone component

Symptom: DetectPipeline() returns URP but camera has UnityEngine.U2D.PixelPerfectCamera. Symptoms are subtle because the standalone component has ENABLE_URP conditional code.

Fix:

1. Remove com.unity.2d.pixel-perfect from Package Manager
2. Remove UnityEngine.U2D.PixelPerfectCamera from each camera
3. Add UnityEngine.Rendering.Universal.PixelPerfectCamera
4. Reconfigure — booleans (pixelSnapping, upscaleRT, cropFrameX/Y) become enums (gridSnapping, cropFrame)

→ Detection code: `references/pipeline-detection.cs` (bottom of file).

Old URP namespace (pre-Unity 2022 / URP pre-13.x)

Symptom: Compiler errors referencing UnityEngine.Experimental.Rendering.Universal.

Fix: Replace using UnityEngine.Experimental.Rendering.Universal; with using UnityEngine.Rendering.Universal;. Update any assembly-qualified type strings. The [MovedFrom] attribute handles serialization automatically — components on GameObjects survive the upgrade.

Common Issues & Solutions

Blurry sprites

Fix: Set Filter Mode to Point on all in-scope sprites, disable Mip Maps, disable AA in Quality Settings. → Code: `references/sprite-settings.cs`

Tilemap gaps between tiles

Work through in order — workarounds like negative cell gap or PPU = 31.99 break when the camera moves.

Cinemachine conflict

Cause: Both Cinemachine and the Pixel Perfect Camera write to orthographic size every frame.

Fix: Add CinemachinePixelPerfect extension via the Add Extension dropdown on each Virtual Camera. Do not add it via AddComponent in code.

Known limitations:

• Camera blends between virtual cameras are not pixel-perfect during transitions
• UpscaleRenderTexture reduces valid pixel-perfect ortho sizes, which may cause framing to deviate
• Target Group + Framing Transposer causes visible choppiness (no fix available)

Post-processing blur with upscaleRT

Cause: Post-processing runs after the PP Camera upscales the render texture.

Simple fix: Disable upscaleRT. Post-processing then runs at native screen resolution.

Advanced fix (Unity 6 URP): Inject a ScriptableRendererFeature2D at RenderPassEvent2D.AfterRenderingPostProcessing. Use 2D-specific base classes — ScriptableRendererFeature (3D base class) is silently ignored in a URP 2D renderer.

UI text blurry with upscaleRT

Status: Known Unity bug, declined to fix (still present Unity 6, 2025).