From 07c3ed612910f3499508d06fd1ca31cf331f26cf Mon Sep 17 00:00:00 2001 From: Dan Crosby Date: Sun, 14 Jun 2026 13:55:14 -0700 Subject: [PATCH] Mark URP migration complete (#7225) --- docs/URP_MIGRATION_PLAN.md | 153 +++++++++++--------------- docs/URP_PROBE_PLAYBOOK.md | 8 +- docs/URP_SHADER_DEBT_INVENTORY.md | 33 +++--- docs/URP_THIRD_PARTY_ASSET_AUDIT.md | 20 ++-- docs/URP_VISUAL_BASELINE_CHECKLIST.md | 15 +-- 5 files changed, 109 insertions(+), 120 deletions(-) diff --git a/docs/URP_MIGRATION_PLAN.md b/docs/URP_MIGRATION_PLAN.md index fed17f8e1b..3f85112f9b 100644 --- a/docs/URP_MIGRATION_PLAN.md +++ b/docs/URP_MIGRATION_PLAN.md @@ -1,11 +1,12 @@ -# URP Migration Plan +# URP Migration Completion Notes -Last refreshed: 2026-06-13 +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 now runs on URP: +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`. @@ -14,32 +15,33 @@ Universal Render Pipeline (URP). Eagle0 now runs on URP: - Legacy Post Processing Stack v2 has been removed from `Packages/manifest.json`; keep verifying it stays out with the migration inventory. -The migration should stay visible as a compatibility project, not a cosmetic cleanup. -The remaining goal is to keep future rendering fixes small and well-baselined instead -of rediscovering URP-specific failures late in a Unity upgrade. +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. For follow-up rendering work, use the baseline checklist -and inventory tooling before changing shaders, materials, camera layering, or render -pipeline settings. +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. -The next useful work is hardening: +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 third-party beast/effect material compatibility covered by focused tests. +4. Keep the existing CI guardrails passing. 5. Treat future pipeline experiments as separate branches with explicit findings. -This keeps normal gameplay work moving while making rendering regressions easier to -localize. +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. -## What We Can Do Right Now +## Maintenance Workflow ### 1. Create Visual Baselines -Capture a small set of known-good views before any follow-up change to URP settings, +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. @@ -55,18 +57,15 @@ Minimum baseline scenes and states: | Shardok | Terrain, grid lines, labels/icons, bridges, fires, overlays, command buttons | | Scene transitions | Connection -> Eagle -> Shardok -> Eagle | -Immediate deliverable: keep the manual checklist and editor-only capture tool working -so each rendering PR can leave screenshots in an ignored directory. +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 +### 2. Refresh The Shader And Material Inventory When Needed -The inventory is useful because scene split, URP, and recent visual fixes changed the -project enough that we should regenerate it before significant rendering work. - -Immediate deliverable: a report containing: +The inventory is useful before significant rendering work. It reports: - all shaders under `Assets/` - all materials and the shader each material uses @@ -78,9 +77,6 @@ Immediate deliverable: a report containing: - `UnityUI.cginc` - tessellation -This report can be generated by an editor script or a small external scanner. The -important bit is making it repeatable so we can measure progress during migration. - 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. @@ -92,7 +88,7 @@ assets. `docs/URP_SHADER_DEBT_INVENTORY.md` records the current production-vs-package classification for remaining Built-in-style shader patterns. -Current inventory snapshot from June 13, 2026: +Current inventory snapshot: - Render pipeline settings are URP for both graphics default and active quality. - Post Processing Stack reference hits are still zero. @@ -107,8 +103,9 @@ Current inventory snapshot from June 13, 2026: - 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. Remaining shader - debt is package/third-party cleanup. + 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 @@ -116,25 +113,22 @@ The project no longer depends on `com.unity.postprocessing`. The old references limited to an unused Orc/Ogre sample scene profile and scene-template type metadata, not production scenes. -Immediate deliverable: keep the project free of Post Processing Stack v2 references -and use the inventory report to catch regressions. +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 -This is a good small PR because it either deletes a risky dependency now or precisely -scopes the later migration work. - ### 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. -Immediate deliverable: keep drought visuals free of `GrabPass` unless we intentionally -add a new URP-friendly effect. +Keep drought visuals free of `GrabPass` unless we intentionally add a new +URP-friendly effect. If stronger drought visuals are needed later, prefer: @@ -142,31 +136,23 @@ If stronger drought visuals are needed later, prefer: - a small particle/sprite effect around the sun icon - a URP renderer feature only if screen-space distortion is truly worth the complexity -### 5. Check Third-Party URP Paths +### 5. Leave Third-Party Shader Conversion Demand-Driven -The riskiest third-party shader set is Polytope Studio. The plan should not assume -hand conversion until we know whether vendor URP variants exist or whether a current -package update has already solved part of this. - -Immediate deliverable: for each paid/third-party visual package, 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 +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. -Prioritize: +If a future visible regression or inventory update makes third-party conversion +necessary, record: -- Polytope Studio lowpoly character/environment shaders -- GUI Pro Kit Fantasy RPG shaders -- Modern UI Pack -- RRFreelance Orc/Ogre shaders -- DungeonMonsters2D sprite/animation shaders +- 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 @@ -177,22 +163,21 @@ a template for future risky pipeline experiments, not as current migration guida 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. -## Current Known Risks +## Known Maintenance Risks | Risk | Why It Matters | Right-Now Action | |---|---|---| -| `UnityUI.cginc` usage | URP does not provide the same include path/semantics | Inventory exact shader uses; plan replacement clipping helpers | -| `GrabPass` | No direct URP equivalent | Drought shimmer is removed/deferred; Polytope water shaders are present but not currently production-referenced | -| Surface shaders | URP does not support Built-in surface shader generation | Inventory and convert or replace | -| Polytope Studio shaders | Human-type Eagle beast effects use Polytope character prefabs with Built-in surface shaders | Check vendor URP availability before hand conversion; prioritize character materials over unused environment shaders | -| Post Processing Stack v2 | Replaced by URP Volume system | Verify whether production scenes use it | -| Scene lighting | URP lighting/shadow settings differ from BiRP | Baseline and rebake only after shader work is stable | -| Render ordering | Recent Shardok fixes rely on careful labels/fire/bridge ordering | Include Shardok overlay cases in baseline | +| `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 URP switch. Future rendering work should be split by observable -behavior: +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. @@ -203,7 +188,7 @@ behavior: This keeps the project from accumulating another broad, hard-to-revert rendering PR. -## Long-Term Phases +## Completed Phases ### Phase 0: Preparation And Switch @@ -230,24 +215,20 @@ This keeps the project from accumulating another broad, hard-to-revert rendering 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, -and project-owned Eagle/Shardok shaders free of scanned Built-in-only patterns. +project-owned Eagle/Shardok shaders free of scanned Built-in-only patterns, key +Addressables labels covered, and major Eagle/Shardok visual wiring guarded. -Highest priority: - -- Eagle map particles, weather overlays, and province map interactions -- Shardok terrain, bridge, fire overlay, foreground UI/effects, labels/icons, and - action animations -- Beast visuals on Eagle and Shardok maps, especially compatibility-material paths -- Tutorial TextMeshPro sprite assets +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 rendering follow-up. +- 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 +### 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. @@ -256,22 +237,23 @@ Follow-up notes: - Avoid leaving screen-space effects until the end; they are likely to drive renderer feature requirements. -### Phase 4: Third-Party Shaders +### Phase 4: Third-Party Shaders Maintenance -- Upgrade packages where vendor URP shaders exist. -- Convert remaining PBR/toon/vegetation shaders manually. +- 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 +### Phase 5: Materials, Lighting, And Post Processing Maintenance -- Batch-update remaining materials. -- Replace Post Processing Stack v2 with URP Volumes if still needed. -- Rebake lighting for production scenes. -- Tune shadow and HDR settings. +- 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 +### Phase 6: Validation Maintenance -Required visual QA: +Required visual QA for future rendering changes: - Connection lobby - Eagle map and command flows @@ -292,10 +274,7 @@ Required visual QA: | 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 | Current remaining work | - -The biggest variable is still third-party shader conversion. Vendor URP packages or -asset deletion can shrink this significantly. +| QA/polish | Completed for the migration; repeat for future rendering changes | ## Key Reminders diff --git a/docs/URP_PROBE_PLAYBOOK.md b/docs/URP_PROBE_PLAYBOOK.md index 5d1bdf3bfc..33a852ea0f 100644 --- a/docs/URP_PROBE_PLAYBOOK.md +++ b/docs/URP_PROBE_PLAYBOOK.md @@ -1,11 +1,11 @@ # URP Probe Playbook -Last refreshed: 2026-06-12 +Last refreshed: 2026-06-14 This playbook is historical reference for the disposable URP probe described in -`docs/URP_MIGRATION_PLAN.md`. URP is now enabled on main; keep this as a template -for future risky render-pipeline experiments. A probe branch is not a production -branch and should not be merged as-is. +`docs/URP_MIGRATION_PLAN.md`. The URP migration is complete; keep this only as a +template for future risky render-pipeline experiments. A probe branch is not a +production branch and should not be merged as-is. ## Goals diff --git a/docs/URP_SHADER_DEBT_INVENTORY.md b/docs/URP_SHADER_DEBT_INVENTORY.md index 0687e882ea..b204ac1562 100644 --- a/docs/URP_SHADER_DEBT_INVENTORY.md +++ b/docs/URP_SHADER_DEBT_INVENTORY.md @@ -1,11 +1,11 @@ # URP Shader Debt Inventory -Last refreshed: 2026-06-13 +Last refreshed: 2026-06-14 This inventory classifies remaining Built-in Render Pipeline shader patterns after -the URP switch. The project is running URP, but some shader source files still use -Built-in-era helpers or features. That is shader debt, not evidence that the old -pipeline is active. +the completed URP switch. The project is running URP, but some package shader source +files still use Built-in-era helpers or features. That is package/vendor debt, not +evidence that the old pipeline is active and not an active migration blocker. ## Scan Method @@ -35,7 +35,7 @@ serialized assets under: This catches serialized production references. It does not prove runtime code never loads an asset by path, but it separates game-path shader debt from package/demo -noise well enough to prioritize follow-up PRs. +noise well enough to decide whether future rendering work is needed. ## Summary @@ -81,6 +81,10 @@ Windows Unity build after merge. - `WeatherEffectMaterialTests` keeps Eagle flood/blizzard prefabs wired to the shared URP province particle material and prevents shader-name fallbacks from returning to those runtime paths. +- `EpidemicEffectMaterialTests` keeps Eagle epidemic particles wired to the shared + clipped particle material. +- `EagleMapMaterialWiringTests` keeps Eagle map/weather controllers wired to the + project map materials and expected URP shaders. - `ProjectShaderPatternTests` fails if project-owned Eagle/Shardok shaders reintroduce the scanned Built-in-only patterns. - `RuntimeShaderFindUsageTests` fails if project-owned Eagle/Shardok runtime @@ -92,6 +96,10 @@ Windows Unity build after merge. circling-bird effect. - `FireworksEffectTests` keeps the fireworks prefab wired to the project-owned clipped particle shader and prevents shader-name fallback from returning. +- `TutorialSpriteAssetTests` keeps tutorial TMP sprite assets and the shared dialogue + panel instruction sprite asset renderable. +- `ProvinceActionAnimatorSpriteTests` keeps Eagle action animation sprite fields + assigned in the Eagle scene. - `PostProcessingStackRemovalTests` keeps legacy Post Processing Stack v2 package and runtime/project-setting references from returning. - `ProductionShaderReferenceTests` keeps shaders with Built-in-only patterns, and @@ -105,7 +113,7 @@ currently contains the scanned Built-in-era shader patterns. | Shader | Patterns | Production References | Recommended Action | |---|---|---|---| -| None | None | None | Continue with runtime visual QA and package/vendor checks. | +| None | None | None | No active migration work. Re-run inventory after future rendering changes. | ## Referenced Package Shader @@ -127,12 +135,11 @@ not as urgent game-path blockers. | TextMeshPro package shaders | TMP SDF/bitmap/surface shaders | `UnityCG.cginc`, `UnityUI.cginc`, `UNITY_MATRIX_`, surface shader variants | Prefer package updates. Avoid editing package shaders unless a concrete TMP visual regression exists. | | Clown.fat and TileableBridgePack | Toony shaders, bridge cutout shader | `#pragma surface`, `UnityCG.cginc`, `UNITY_MATRIX_` | Leave as low priority unless a production reference appears. | -## Suggested Follow-Up PR Order +## Maintenance Guidance -1. Run runtime visual QA for Eagle map particles, weather overlays, Shardok fire, - foreground UI/effect overlays, beast visuals, and tutorial TMP sprites. -2. Leave unreferenced third-party/package shaders alone until they have a visible - regression or production reference. +Runtime visual QA for the URP migration was completed during playtesting and known +regressions from that pass were fixed. Leave unreferenced third-party/package shaders +alone until they have a visible regression or production reference. -Each rendering follow-up PR should use `docs/URP_VISUAL_BASELINE_CHECKLIST.md` and include -the affected screenshots in an ignored local directory, not in git. +Future rendering PRs should use `docs/URP_VISUAL_BASELINE_CHECKLIST.md` and include +affected screenshots in an ignored local directory, not in git. diff --git a/docs/URP_THIRD_PARTY_ASSET_AUDIT.md b/docs/URP_THIRD_PARTY_ASSET_AUDIT.md index 80c531231f..17aa272b1a 100644 --- a/docs/URP_THIRD_PARTY_ASSET_AUDIT.md +++ b/docs/URP_THIRD_PARTY_ASSET_AUDIT.md @@ -1,9 +1,9 @@ # URP Third-Party Asset Audit -Last refreshed: 2026-06-13 +Last refreshed: 2026-06-14 -This audit scopes third-party visual packages for the URP migration. It is based on -a GUID reference scan from production Unity assets under: +This audit scopes third-party visual packages after the completed URP migration. It +is based on a GUID reference scan from production Unity assets under: - `Assets/Scenes` - `Assets/Eagle` @@ -18,7 +18,7 @@ a GUID reference scan from production Unity assets under: The scan maps GUIDs from each package folder, then finds production scenes, prefabs, materials, controllers, assets, and scripts that reference those GUIDs. It does not prove runtime code never loads assets by path, but it catches the -serialized references that matter most for a render-pipeline migration. +serialized references that matter most for future render-pipeline maintenance. ## Summary @@ -66,7 +66,7 @@ That shader uses Built-in surface shader generation and is not URP-ready as-is. At runtime, Eagle beast effects pass their renderers through `BeastMaterialCompatibility.ConfigureRenderer`, which replaces non-URP materials with URP/Lit materials and bakes Polytope palette textures when needed. Treat this -as a visual QA risk rather than an immediate hand-conversion target. +as covered by the compatibility path unless a future visual regression appears. Polytope environment and water shaders still exist in the project and include Built-in-only features such as `GrabPass`, `UnityCG.cginc`, surface shaders, and @@ -90,13 +90,15 @@ generation in the source assets: At runtime, the Eagle monster-effect path also uses `BeastMaterialCompatibility.ConfigureRenderer`, so these renderers should be -visually verified before replacing vendor materials. Convert or replace the source -materials only if the compatibility path leaves the Ogre effect pink, dark, or +left on the compatibility path unless the Ogre effect becomes pink, dark, or otherwise visibly broken. -## Recommended URP Order +## Maintenance Guidance -1. Keep the runtime beast-effect compatibility path covered by visual checks. +The URP migration is complete; do not convert third-party packages speculatively. + +1. Keep the runtime beast-effect compatibility path covered by existing tests and + future visual checks when beast rendering changes. 2. If compatibility leaves a beast pink, dark, or visibly broken, replace the affected materials with URP/Lit materials before touching unused demo-only shader packs. 3. Leave Polytope water/vegetation/environment conversion until a production diff --git a/docs/URP_VISUAL_BASELINE_CHECKLIST.md b/docs/URP_VISUAL_BASELINE_CHECKLIST.md index 949aee4c5a..89f6f77a15 100644 --- a/docs/URP_VISUAL_BASELINE_CHECKLIST.md +++ b/docs/URP_VISUAL_BASELINE_CHECKLIST.md @@ -1,9 +1,10 @@ # URP Visual Baseline Checklist -Use this checklist before any URP follow-up branch changes render-pipeline settings, -custom shaders, materials, lighting, camera layering, or render order. The goal is -not exhaustive gameplay QA; it is a stable set of visual states that can be compared -by eye after rendering changes. +Use this checklist before any future branch changes render-pipeline settings, custom +shaders, materials, lighting, camera layering, or render order. The URP migration is +complete; this checklist is now a maintenance tool. The goal is not exhaustive +gameplay QA, but a stable set of visual states that can be compared by eye after +rendering changes. Save screenshots under: @@ -47,7 +48,7 @@ write a timestamped Game view capture to that directory. ## Acceptance Notes -For each URP rendering follow-up, record: +For each rendering follow-up, record: - Unity version and branch name. - Screenshot directory. @@ -56,5 +57,5 @@ For each URP rendering follow-up, record: - Any render-order differences, especially Shardok overlays and Eagle beast effects. - Whether the difference is acceptable, needs shader work, or needs asset/material work. -Do not merge a URP rendering branch until the affected Connection, Eagle, Shardok, -or Settings baseline captures are visually acceptable. +Do not merge a rendering branch until the affected Connection, Eagle, Shardok, or +Settings baseline captures are visually acceptable.