eagle0/docs/URP_MIGRATION_PLAN.md

# URP Migration Completion Notes

Last refreshed: 2026-06-14

## Why This Matters

Unity is steering projects away from the Built-in Render Pipeline (BiRP) toward the
Universal Render Pipeline (URP). Eagle0 has completed the URP migration and now runs
on URP:

- `ProjectSettings/GraphicsSettings.asset` points at
  `Assets/Settings/URP/Eagle0URPPipeline.asset`.
- Every active quality level in `ProjectSettings/QualitySettings.asset` uses the
  same URP pipeline asset.
- Legacy Post Processing Stack v2 has been removed from `Packages/manifest.json`;
  keep verifying it stays out with the migration inventory.

The migration is no longer an active compatibility project. Keep this document as the
completion record and maintenance checklist for future Unity, URP, shader, material,
camera layering, or render-order changes.

## Current Recommendation

Keep URP enabled on main. Do not continue speculative URP cleanup. Use the baseline
checklist and inventory tooling only when a future change touches shaders, materials,
camera layering, render order, pipeline settings, or a visible rendering regression.

Maintenance rules:

1. Keep the visual baseline current for Connection, Eagle, Shardok, and Settings.
2. Refresh the shader/material inventory after meaningful asset or scene changes.
3. Remove or isolate unused rendering dependencies.
4. Keep the existing CI guardrails passing.
5. Treat future pipeline experiments as separate branches with explicit findings.

Known URP regressions found during playtesting have been fixed. Normal gameplay work
can proceed; future rendering PRs should be driven by observable regressions or
intentional rendering changes.

## Maintenance Workflow

### 1. Create Visual Baselines

Capture a small set of known-good views before any future change to URP settings,
custom shaders, render ordering, or third-party visual materials. These should be
reproducible enough that a human can compare screenshots after each rendering change.

Minimum baseline scenes and states:

| Area | Required View |
|---|---|
| Connection | Connect panel, stored account list, running games list |
| Eagle map | Normal province map with borders, faction highlights, selected province tooltip |
| Eagle weather | Drought/heat shimmer, flood, blizzard/rain overlays |
| Eagle beasts | Bird/animal/monster beast effects on map and notification panel |
| Eagle UI | Command panel, notifications, settings panel, generated text |
| Shardok | Terrain, grid lines, labels/icons, bridges, fires, overlays, command buttons |
| Scene transitions | Connection -> Eagle -> Shardok -> Eagle |

Keep the manual checklist and editor-only capture tool working so rendering PRs can
leave screenshots in an ignored directory.

Use `docs/URP_VISUAL_BASELINE_CHECKLIST.md` for the current manual baseline capture
set.

### 2. Refresh The Shader And Material Inventory When Needed

The inventory is useful before significant rendering work. It reports:

- all shaders under `Assets/`
- all materials and the shader each material uses
- all scenes/prefabs that reference custom shaders or Post Processing components
- all usages of Built-in-only shader features:
  - `GrabPass`
  - `#pragma surface`
  - `UnityCG.cginc`
  - `UnityUI.cginc`
  - tessellation

Run `Eagle0 > Rendering > Generate URP Migration Inventory` in the Unity editor to
generate the current report. The tool writes markdown and CSV files under Unity
`Temp/urp_migration/`, so running it should not dirty project assets.

The generated CSVs include both the full material list and production material
references, which helps separate game-path shader risk from unused package/demo
assets.

`docs/URP_SHADER_DEBT_INVENTORY.md` records the current production-vs-package
classification for remaining Built-in-style shader patterns.

Current inventory snapshot:

- Render pipeline settings are URP for both graphics default and active quality.
- Post Processing Stack reference hits are still zero.
- The all-material inventory is noisy: most material assets are `Standard`, and
  many Built-in-only shader hits are in third-party or package/demo assets.
- The production material-reference report is the better starting point for the
  probe. Current production shader references are concentrated in TextMeshPro,
  Eagle custom map/effect shaders, Shardok grid/fire materials, and a small number
  of standard-material beast assets.
- The project-owned Eagle and Shardok production custom shaders have been hardened
  for URP and passed Windows Unity builds after merge.
- Project-owned runtime-created Eagle/Shardok materials now use serialized shader or
  material references instead of project shader-name fallbacks.
- No project-owned production shader under `Assets/Eagle` or `Assets/Shardok`
  currently contains the scanned Built-in-era shader patterns.
- Package/third-party shader debt remains documented but is not on the production
  path unless a future inventory run finds new references.

### 3. Verify Legacy Post Processing Usage

The project no longer depends on `com.unity.postprocessing`. The old references were
limited to an unused Orc/Ogre sample scene profile and scene-template type metadata,
not production scenes.

Keep the project free of Post Processing Stack v2 references and use the inventory
report to catch regressions.

If references reappear:

- document the exact scene/camera/profile usage
- either remove the stale dependency or plan the equivalent URP Volume settings

### 4. Keep Drought Effects URP-Friendly

The old `Eagle/HeatShimmer` shader used a Built-in-style `GrabPass`, but shimmer was
already disabled in `DroughtEffect` because it did not work well with the UI Canvas.
Drought now intentionally uses the animated sun overlay as its current visual signal.

Keep drought visuals free of `GrabPass` unless we intentionally add a new
URP-friendly effect.

If stronger drought visuals are needed later, prefer:

- an animated transparent texture overlay clipped like the existing province particles
- a small particle/sprite effect around the sun icon
- a URP renderer feature only if screen-space distortion is truly worth the complexity

### 5. Leave Third-Party Shader Conversion Demand-Driven

The riskiest third-party shader set is Polytope Studio. Do not hand-convert package
shader sets speculatively.

`docs/URP_THIRD_PARTY_ASSET_AUDIT.md` records the current production GUID-reference
scan. The important result is that production assets use Polytope character prefabs
for Eagle beast effects, but the Polytope environment/water assets that still contain
`GrabPass` were not found on the production path.

If a future visible regression or inventory update makes third-party conversion
necessary, record:

- current installed version
- whether a URP-compatible version exists
- whether upgrading is license/account-accessible
- whether the package is still used in production scenes

### 6. Keep Probe Guidance For Future Pipeline Experiments

The original disposable probe has served its main purpose: URP is enabled on main and
the biggest visual regressions were fixed in focused PRs. Keep the probe playbook as
a template for future risky pipeline experiments, not as current migration guidance.

Use `docs/URP_PROBE_PLAYBOOK.md` when we need to measure a future Unity or render
pipeline change cheaply before committing to a mergeable branch.

## Known Maintenance Risks

| Risk | Why It Matters | Right-Now Action |
|---|---|---|
| `UnityUI.cginc` usage in package shaders | URP does not provide the same include path/semantics for hand-authored shaders | Leave package-managed TMP shaders alone unless a visible regression appears. |
| `GrabPass` in unused package shaders | No direct URP equivalent | Ignore until production starts referencing those assets. |
| Surface shaders in third-party packages | URP does not support Built-in surface shader generation | Covered by beast material compatibility on current production paths; convert only for a visible regression. |
| Post Processing Stack v2 | Replaced by URP Volume system | Keep package and runtime/project-setting references from returning. |
| Scene lighting | URP lighting/shadow settings differ from BiRP | Baseline and rebake only for visible regressions or intentional lighting work. |
| Render ordering | Shardok and Eagle overlays depend on careful layering | Include affected overlays in baseline whenever render order changes. |

## Follow-Up Strategy

Main now carries the completed URP switch. Future rendering work should be split by
observable behavior:

- **Compatibility fixes**: small PRs for specific pink/missing/dark assets.
- **Render ordering fixes**: small PRs for Shardok/Eagle layer order regressions.
- **Inventory/docs updates**: docs-only or editor-tool PRs that do not alter runtime
  visuals.
- **Pipeline experiments**: isolated branches using the probe playbook, with findings
  copied into a mergeable follow-up.

This keeps the project from accumulating another broad, hard-to-revert rendering PR.

## Completed Phases

### Phase 0: Preparation And Switch

- Visual baseline checklist/screenshots: complete, keep current
- Repeatable shader/material inventory: complete, keep current
- Post Processing Stack usage decision: complete, keep removed
- Drought visual decision: complete, use non-GrabPass visual signal
- Third-party URP availability check: documented
- Disposable URP probe findings: superseded by the merged URP switch
- CI guardrails for pipeline settings, runtime shader lookup, project shader
  patterns, and beast-material compatibility: complete

### Phase 1: Pipeline Setup

- Install/configure URP: complete
- Create URP Pipeline Asset and Renderer Asset: complete
- Configure forward rendering, shadows, HDR, and renderer features: complete enough
  for current gameplay paths
- Run Unity's Render Pipeline Converter: complete for the merged switch
- Keep a record of every auto-converted material: use the inventory/audit tools

### Phase 2: Runtime Visual QA And Cleanup

Project-owned custom shader conversion, shader-name fallback cleanup, and deletion
cleanup are complete. Current CI coverage keeps the URP pipeline assigned, required
runtime shader references serialized, required player-runtime-only shaders included,
project-owned Eagle/Shardok shaders free of scanned Built-in-only patterns, key
Addressables labels covered, and major Eagle/Shardok visual wiring guarded.

Runtime visual QA was completed during playtesting. Known regressions from that pass
were fixed before the migration was called done.

Follow-up notes:

- Use `docs/URP_VISUAL_BASELINE_CHECKLIST.md` for each future rendering follow-up.
- Keep screenshots in an ignored local directory, not in git.
- Treat package/third-party shader conversions as response work for visible
  regressions or new production references, not as speculative cleanup.

### Phase 3: GrabPass And Special Effects Maintenance

- Keep drought visuals on the current animated sun overlay unless a new URP-friendly
  effect is intentionally added.
- Reimplement or replace the Polytope `PT_Water_Shader` GrabPass shaders if they are
  ever become used by production assets.
- Avoid leaving screen-space effects until the end; they are likely to drive renderer
  feature requirements.

### Phase 4: Third-Party Shaders Maintenance

- Upgrade packages where vendor URP shaders exist and a production need appears.
- Convert remaining PBR/toon/vegetation shaders manually only for production
  references or visible regressions.
- Prefer replacement or deletion for unused demo-only assets.

### Phase 5: Materials, Lighting, And Post Processing Maintenance

- Batch-update materials only for production paths or visible regressions.
- Replace Post Processing Stack v2 with URP Volumes only if a production need returns.
- Rebake lighting for production scenes when scene lighting is intentionally changed.
- Tune shadow and HDR settings when visual QA or performance work justifies it.

### Phase 6: Validation Maintenance

Required visual QA for future rendering changes:

- Connection lobby
- Eagle map and command flows
- Eagle weather/beasts/notifications
- Shardok battle map overlays, unit text/icons, bridges, fires
- Scene transitions
- Mac and Windows builds
- Performance sanity check

## Rough Effort

| Work | Status |
|---|---|
| Preparation/probe | Complete |
| Pipeline setup | Complete |
| Core custom shaders | Complete |
| Runtime shader/build guardrails | Complete; project-owned runtime paths use serialized shader/material references |
| GrabPass/special effects | Deferred until a production reference or new effect need appears |
| Third-party shaders/materials | Covered by runtime compatibility and visual QA unless a visible regression appears |
| Lighting/post-processing | No current Post Processing Stack dependency; rebake/tune only for visible regressions |
| QA/polish | Completed for the migration; repeat for future rendering changes |

## Key Reminders

- URP is already enabled on main; keep follow-up work narrowly scoped.
- Project-owned shader-name fallbacks should stay out of runtime-created materials;
  use serialized shader/material references instead.
- `Shader.Find` remains acceptable for Unity/URP-provided shader names inside
  third-party compatibility shims, where there is no project asset to serialize.
- Do not hand-convert package shaders unless runtime visual QA exposes a concrete
  regression or a new production reference appears.
- Keep C# changes minimal; current rendering scripts mostly set material properties.
- Preserve recent Shardok render-order behavior while changing pipelines.
- Treat screenshots as migration tests; compilation alone is not meaningful here.