@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/lib/types/registry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Per-agent skill provider registry.
+ *
+ * A bundle row lands in the harness's global scope layer, while an agent preset
+ * mounts its own skill provider in the agent's layer — and the nearest layer wins
+ * a duplicate name outright, regardless of rank. Registering from a bundle row
+ * alone therefore loses to whatever the preset already sees, and cannot vary by
+ * project. Registering through `agent.ctx` instead places this provider in that
+ * agent's layer: it wins the names it owns, and its catalog can depend on the
+ * project the agent is actually working in.
+ *
+ * This module keeps that bookkeeping: one shared reader and parse cache, one fact
+ * cache per working directory, and one registration per live agent. It also
+ * implements the provider itself, which re-reads the project facts whenever the
+ * harness asks for the catalog, so a changed editor version or package list
+ * invalidates the catalog instead of waiting for a restart.
+ *
+ * @module dsh-unity/lib/registry
+ */
+import type { DetectOptions, ProjectFacts } from './project.ts';
+import type { ReaderOptions, UnitySkillReader } from './skills.ts';
+import type { AgentLike, PluginContext, SessionLike, SkillProvider } from './harness.ts';
+/** How long detected project facts stay fresh before they are read again. */
+export declare const FACTS_TTL_MS = 2000;
+/** Settings the registry needs; the plugin entry point supplies them. */
+export interface RegistrySettings {
+    readonly skillDir: string;
+    readonly providerName: string;
+    readonly source: string;
+    readonly rank: number;
+    readonly exclude: ReadonlySet<string>;
+    readonly respectProjectRoots: boolean;
+    readonly injectContext: boolean;
+    readonly workspaceSkills: ReadonlySet<string>;
+    readonly gateByProject: boolean;
+    readonly enforceRequirements: boolean;
+    readonly parseCache: ReaderOptions['parseCache'];
+}
+/** Options for {@link createAgentRegistry}. */
+export interface RegistryOptions {
+    readonly ctx: PluginContext;
+    readonly settings: RegistrySettings;
+    readonly reader?: UnitySkillReader;
+    readonly detect?: (cwd: string) => Promise<ProjectFacts | undefined>;
+    readonly readProjectSkills?: (root: string) => Promise<Set<string>>;
+}
+/** The result of trying to register one agent. */
+export type RegistrationResult = 'registered' | 'unavailable' | 'skipped';
+/** The registry handed to the plugin entry point. */
+export interface AgentRegistry {
+    readonly reader: UnitySkillReader;
+    size(): number;
+    add(agent: AgentLike | undefined): Promise<RegistrationResult>;
+    remove(agent: AgentLike | undefined): void;
+    factsFor(cwd: string | undefined): Promise<ProjectFacts | undefined>;
+    projectSkillsFor(facts: ProjectFacts | undefined): Promise<Set<string>>;
+    invalidateAll(): void;
+    disposeAll(): void;
+}
+/**
+ * Create the registry that owns every per-agent registration.
+ *
+ * @param options - registry settings and injectable collaborators.
+ * @returns the registry.
+ */
+export declare function createAgentRegistry(options: RegistryOptions): AgentRegistry;
+/**
+ * Resolve an optional service from a context without requiring an injection.
+ *
+ * @param context - the context to read from, possibly an agent scope.
+ * @param name - service name.
+ * @returns the service, or `undefined` when unavailable.
+ */
+export declare function serviceOf<T>(context: {
+    get(name: string): unknown;
+} | undefined, name: string): T | undefined;
+/** Options passed to the real project detector. */
+export declare function resolveDetectOptions(ctx: PluginContext): DetectOptions;
+/**
+ * Build a single provider that resolves project facts from each lookup's `cwd`.
+ *
+ * Used as the fallback when a plugin context cannot reach `agent.ctx.skills`: the
+ * catalog still follows each lookup's working directory, but it registers in the
+ * global layer, where the nearest layer (the agent preset) wins a duplicate name.
+ * Context contribution stays agent-scoped, so a deployment on this path gets
+ * gating without the runtime-context line.
+ *
+ * @param options - settings and the registry whose caches are reused.
+ * @returns the provider to register globally.
+ */
+export declare function createGlobalProvider(options: {
+    settings: RegistrySettings;
+    registry: AgentRegistry;
+}): SkillProvider;
+/** Re-exported for callers that only need the session shape. */
+export type { SessionLike };

package/lib/types/requirements.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Unity version and UPM package requirement arithmetic.
+ *
+ * Skill frontmatter can state what the skill needs: `required_editor_version`
+ * (a range such as `>=6000.6`) and `required_packages` (a map of package id to
+ * range). The harness has no equivalent mechanism, so this module turns those
+ * declarations into a decision the plugin can act on: is the skill applicable to
+ * the project this agent is working in?
+ *
+ * Parsing is deliberately tolerant. A Unity editor version like `6000.3.14f1`
+ * becomes `[6000, 3, 14]` — the `f1` build suffix is information about the build
+ * channel, not ordering — while a package version keeps its prerelease tag.
+ * Anything unparseable is "unknown", and the caller treats unknown as *do not
+ * hide*: a declaration nobody can evaluate must not silently remove a skill.
+ *
+ * @module dsh-unity/lib/requirements
+ */
+import type { SkillRequirements } from './harness.ts';
+/** A version split into comparable numeric segments. */
+export interface ParsedVersion {
+    readonly segments: readonly number[];
+    readonly prerelease: string | undefined;
+}
+/**
+ * Parse a version string into comparable numeric segments.
+ *
+ * @param value - raw version such as `6000.3.14f1`, `17.5.0`, `1.2`.
+ * @returns the parsed version, or `undefined` when it is not a version.
+ */
+export declare function parseVersion(value: unknown): ParsedVersion | undefined;
+/** Compare two parsed versions, padding the shorter one with zeros. */
+export declare function compareVersions(left: ParsedVersion, right: ParsedVersion): number;
+/**
+ * Check a range against a version.
+ *
+ * @param rawRange - range text, for example `>=6000.6`.
+ * @param rawVersion - version text, for example `6000.3.14f1`.
+ * @returns `undefined` when either side cannot be parsed, so the caller can treat
+ *   the answer as unknown instead of hiding a skill.
+ */
+export declare function satisfiesRange(rawRange: unknown, rawVersion: unknown): boolean | undefined;
+/**
+ * Read the requirement declarations out of parsed skill frontmatter.
+ *
+ * @param data - parsed SKILL.md frontmatter.
+ * @returns the declared editor range and package ranges.
+ */
+export declare function readRequirements(data: Readonly<Record<string, unknown>>): SkillRequirements;
+/** Project facts that requirement checks depend on. */
+export interface RequirementFacts {
+    readonly editorVersion?: string;
+    readonly packages?: Map<string, string>;
+}
+/** The outcome of evaluating one skill's requirements. */
+export interface RequirementVerdict {
+    readonly applicable: boolean;
+    readonly unknown: boolean;
+    readonly reasons: readonly string[];
+}
+/**
+ * Evaluate requirements against project facts.
+ *
+ * @param requirements - declarations from {@link readRequirements}.
+ * @param facts - detected project facts; `undefined` means no project was detected.
+ * @returns the decision; `applicable` stays true when the answer is only unknown.
+ */
+export declare function evaluateRequirements(requirements: SkillRequirements, facts: RequirementFacts | undefined): RequirementVerdict;

package/lib/types/skills.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Discovery and loading for the packaged Unity skills.
+ *
+ * Each skill is a directory bundle `<skillDir>/<name>/SKILL.md`, the same shape
+ * the harness filesystem provider reads, so the tree needs no transformation.
+ * Discovery parses frontmatter into a catalog candidate and every load re-reads
+ * the file, matching the harness convention that a skill body has no separate
+ * cache.
+ *
+ * One parse cache is shared by every agent's provider: discovery runs per agent
+ * scope, but the files belong to this package, so one cache keyed by path plus
+ * modification time and size keeps N agents from re-parsing the same documents
+ * while still noticing an edit.
+ *
+ * @module dsh-unity/lib/skills
+ */
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions } from './harness.ts';
+import type { ParsedSkill } from './frontmatter.ts';
+/** Shared frontmatter cache keyed by file path. */
+export interface ParseCache {
+    read(file: string): Promise<ParsedSkill | undefined>;
+    clear(): void;
+}
+/** Options one reader is created with. */
+export interface ReaderOptions {
+    readonly skillDir: string;
+    readonly providerName: string;
+    readonly source: string;
+    readonly rank: number;
+    readonly exclude?: ReadonlySet<string>;
+    readonly parseCache?: ParseCache;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/** The reader the provider delegates to. */
+export interface UnitySkillReader {
+    readonly skillDir: string;
+    list(options?: SkillLookupOptions): Promise<SkillCandidate[]>;
+    load(candidate: SkillCandidate | undefined, options?: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+}
+/**
+ * Create a frontmatter cache keyed by path and file identity.
+ *
+ * @returns the cache.
+ */
+export declare function createParseCache(): ParseCache;
+/**
+ * Create a reader for one packaged skill directory.
+ *
+ * @param options - reader settings.
+ * @returns the reader.
+ */
+export declare function createUnitySkillReader(options: ReaderOptions): UnitySkillReader;

package/lib/types/watch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Live catalog refresh for the packaged skills.
+ *
+ * Editing a skill body already takes effect on the next load, because loading
+ * re-reads the file. Adding, removing, or changing the frontmatter of a skill is
+ * different: the registry caches the discovered catalog per scope and only
+ * refreshes when a provider asks it to. This watcher bridges the filesystem to
+ * that contract, so a skill edit shows up in the next step instead of forcing a
+ * restart.
+ *
+ * Watching is optional and never load-bearing: a platform or sandbox that cannot
+ * watch leaves the plugin fully functional with restart-time discovery.
+ *
+ * @module dsh-unity/lib/watch
+ */
+/** Options for {@link startSkillsWatcher}. */
+export interface WatcherOptions {
+    readonly dir: string;
+    readonly onChange: () => void;
+    readonly logger: {
+        warn(message: string): void;
+    };
+    readonly debounceMs?: number;
+}
+/**
+ * Start watching a skill directory for catalog-relevant changes.
+ *
+ * Only `SKILL.md` additions, removals, and edits matter: resource files below a
+ * skill are read on demand and do not change discovery.
+ *
+ * @param options - watcher options.
+ * @returns a disposer that stops the watcher.
+ */
+export declare function startSkillsWatcher(options: WatcherOptions): () => void;

package/lib/watch.js

@@ -0,0 +1,84 @@
+/**
+ * Live catalog refresh for the packaged skills.
+ *
+ * Editing a skill body already takes effect on the next load, because loading
+ * re-reads the file. Adding, removing, or changing the frontmatter of a skill is
+ * different: the registry caches the discovered catalog per scope and only
+ * refreshes when a provider asks it to. This watcher bridges the filesystem to
+ * that contract, so a skill edit shows up in the next step instead of forcing a
+ * restart.
+ *
+ * Watching is optional and never load-bearing: a platform or sandbox that cannot
+ * watch leaves the plugin fully functional with restart-time discovery.
+ *
+ * @module dsh-unity/lib/watch
+ */
+import { watch } from 'node:fs';
+/** Default coalescing window for filesystem bursts. */
+const DEFAULT_DEBOUNCE_MS = 200;
+/**
+ * Start watching a skill directory for catalog-relevant changes.
+ *
+ * Only `SKILL.md` additions, removals, and edits matter: resource files below a
+ * skill are read on demand and do not change discovery.
+ *
+ * @param options - watcher options.
+ * @returns a disposer that stops the watcher.
+ */
+export function startSkillsWatcher(options) {
+    const { dir, onChange, logger, debounceMs = DEFAULT_DEBOUNCE_MS } = options;
+    let timer;
+    let watcher;
+    let disposed = false;
+    const schedule = () => {
+        if (disposed)
+            return;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (disposed)
+                return;
+            try {
+                onChange();
+            }
+            catch (error) {
+                logger.warn(`unity skills: catalog refresh failed: ${String(error)}`);
+            }
+        }, debounceMs);
+        timer.unref?.();
+    };
+    try {
+        watcher = watch(dir, { recursive: true, persistent: false }, (_event, filename) => {
+            if (filename === null || filename === undefined) {
+                schedule();
+                return;
+            }
+            if (String(filename).endsWith('SKILL.md'))
+                schedule();
+        });
+    }
+    catch (error) {
+        logger.warn(`unity skills: cannot watch ${dir}, catalog changes need a restart: ${String(error)}`);
+        return () => { };
+    }
+    watcher.on('error', (error) => {
+        logger.warn(`unity skills: skill watcher stopped on ${dir}: ${String(error)}`);
+        dispose();
+    });
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        try {
+            watcher?.close();
+        }
+        catch {
+            // Closing an already-closed watcher is not an error worth surfacing.
+        }
+    }
+    return dispose;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Unity skills",
+    "description": "34 Unity game-development skills covering editor tooling, UI, 2D and physics, audio and performance, rendering, multiplayer, monetization, and builds. Each session sees the skills its Unity project supports: three workspace skills outside a project, then editor-version and package requirements applied inside one, with the project facts added to the runtime context."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Unity 技能",
+    "description": "覆盖 Unity 游戏开发的 34 个技能：编辑器工具、UI、2D 与物理、音频与性能、渲染、多人、变现与构建。按会话所在工程筛选：非 Unity 工程只保留 3 个起步技能，工程内按 Editor 版本与已装包隐藏不适用的，并把工程信息写进上下文。"
+  }
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@aqian0/dsh-unity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Unity game-development, monetization, and performance skills for DeepSeek Harness: 34 skills that load on demand, packaged as a DSH bundle.",
+  "keywords": [
+    "dsh-plugin",
+    "unity",
+    "gamedev",
+    "game-development"
+  ],
+  "license": "(MIT AND ISC AND LicenseRef-Unity-Companion-License)",
+  "author": "AQian",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AQian0/dsh-unity.git"
+  },
+  "homepage": "https://github.com/AQian0/dsh-unity#readme",
+  "bugs": {
+    "url": "https://github.com/AQian0/dsh-unity/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "skills/**",
+    "icon.svg",
+    "LICENSE.md",
+    "LICENSE-UNITY-COMPANION.md",
+    "NOTICE.md",
+    "CHANGELOG.md",
+    "README.md",
+    "docs/design.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\"",
+    "prepack": "npm run clean && npm run build",
+    "prepublishOnly": "npm run typecheck && npm test && npm run validate",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "validate": "node scripts/validate-skills.ts"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  },
+  "types": "lib/types/index.d.ts",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/2d-pixel-perfect/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: 2d-pixel-perfect
+description: Sets up, diagnoses, and fixes pixel perfect 2D rendering with PixelPerfectCamera in URP or Built-in. Use when a retro-style or pixel art 2D game looks blurry, jittery, or misaligned. Not for HD 2D or high-resolution art.
+---
+
+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.** 
+
+| | URP | Built-in |
+|---|---|---|
+| **Component** | `UnityEngine.Rendering.Universal.PixelPerfectCamera` | `UnityEngine.U2D.PixelPerfectCamera` |
+| **Package** | Built into URP — no extra install | `com.unity.2d.pixel-perfect` v6.0.0+ |
+| **API style** | Enums (`gridSnapping`, `cropFrame`) | Booleans (`pixelSnapping`, `upscaleRT`, `cropFrameX/Y`) |
+
+**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.
+
+| Reference resolution | 1080p | 1440p | 4K |
+|---|---|---|---|
+| 320 × 180 | 6× | 8× | 12× |
+| 480 × 270 | 4× | ~5.3× | 8× |
+| 640 × 360 | 3× | 4× | 6× |
+
+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.
+
+| # | Check | Fix |
+|---|---|---|
+| 1 | Sprite Atlas with Tight Packing off, Padding ≥ 4, Sprite Packer Mode enabled? | Enable Sprite Packer Mode in Editor settings; on the atlas set Padding ≥ 4 and turn Tight Packing off |
+| 2 | Mipmaps disabled on tileset textures and atlas? | Disable Generate Mip Maps |
+| 3 | AA = 0, MSAA off on camera? | Disable AA globally |
+| 4 | Compression = None? | RGBA 32-bit uncompressed |
+| 5 | All tile sprites have even pixel dimensions? | Odd dimensions cause 0.5px grid offset |
+| 6 | PPU = tile pixel width? (16×16 → PPU 16) | PPU mismatch leaves physical gaps |
+| 7 | Gaps only during camera movement after all above pass? | Use PP Camera pixel snapping; do not use `cellGap = -0.01f` |
+
+### 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).
+
+**Root causes**: (A) Canvas renders into the low-res buffer and is upscaled with the scene. (B) TMP's SDF gradient threshold is miscalibrated at low reference resolutions.
+
+**Fixes in order of reliability**:
+1. `Screen Space - Overlay` on Canvas — bypasses the camera, renders at native resolution
+2. Dedicated UI camera with no PP Camera component, `Screen Space - Camera` mode
+3. Unity 6 only: `Font Material → Debug Settings → Sharpness = 1` (mitigates B, not A)
+
+### Physics / render desync (micro-stutter)
+**Cause**: Physics runs at a fixed timestep; interpolated positions produce fractional values that snap to different pixels each frame.
+
+**Fix**:
+- Enable `Rigidbody2D.interpolation = RigidbodyInterpolation2D.Interpolate` on physics-driven sprites
+- Set `Time.fixedDeltaTime = 1f / 60f` to match target frame rate
+- Keep camera tracking in `LateUpdate`, not `FixedUpdate`
+
+### Non-integer scaling / pixel decimation
+**Cause**: Screen resolution is not a clean integer multiple of the reference resolution.
+
+**Fix**: Choose a reference resolution from the table above. Use `cropFrame = Windowbox` when no integer fit exists.
+
+### Missing URP 2D Renderer
+**Fix**:
+1. `Assets > Create > Rendering > URP 2D Renderer Data`
+2. Assign it to your URP Asset under Renderer List
+3. Requires `com.unity.render-pipelines.universal` 12.0+
+
+### HDRP fallback
+Pixel Perfect Camera is unsupported in HDRP.
+
+**Built-in / Unity 5.x**: Use `RenderTexture` + `Graphics.Blit` with `FilterMode.Point`.
+
+**Unity 6 URP**: Use `ScriptableRendererFeature2D` + `ScriptableRenderPass2D` injected at `RenderPassEvent2D.AfterRendering` with `AddRasterRenderPass`. Note: `OnRenderImage` and `Graphics.Blit` are incompatible with Unity 6's render graph.