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.