admin/eagle0
1
0
Fork 0
mirror of https://github.com/nolen777/eagle0.git synced 2026-07-28 21:35:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refresh URP migration plan (#7082)

Browse Source
This commit is contained in:
admin
2026-06-11 11:40:14 -07:00
committed by GitHub
parent b104038221
commit 63feec92f4
1 changed files with 249 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/URP_MIGRATION_PLAN.md
+249 -147
View File
@@ -1,173 +1,275 @@
# URP Migration Plan
## Why
Last refreshed: 2026-06-11
Unity is removing Built-In Render Pipeline (BiRP) support after Unity 6.7. We're currently on Unity 6.4. Each Unity minor version ships roughly quarterly, giving us a few release cycles before BiRP is dropped. This document lays out the migration plan.
## Why This Matters
## Strategy: Long-Lived Feature Branch
Unity is steering projects away from the Built-in Render Pipeline (BiRP) toward the
Universal Render Pipeline (URP). This project is still on BiRP:
All URP conversion work happens on a **long-lived `urp-migration` branch**. Main stays fully functional on BiRP throughout the migration.
- `ProjectSettings/GraphicsSettings.asset` has no custom render pipeline asset.
- Every quality level in `ProjectSettings/QualitySettings.asset` has no custom render
pipeline asset.
- `Packages/manifest.json` still includes `com.unity.postprocessing`, the legacy
Post Processing Stack v2 package.
- **Main branch**: Continues using BiRP. All gameplay, AI, and server development proceeds normally.
- **URP branch**: Accumulates rendering pipeline changes across all phases.
- **Regular rebasing**: Periodically rebase/merge `main` into the URP branch to stay current. Shader and material changes rarely conflict with gameplay code, so merge conflicts should be manageable.
- **Merge to main**: Only when everything renders correctly and visual QA passes.
That means we should treat URP as a compatibility project, not a cosmetic cleanup.
The goal is to migrate on our schedule, with visual baselines and small de-risking
PRs, instead of discovering late that a Unity upgrade turns the game pink.
This avoids the "everything is pink" problem of switching the pipeline on main before shaders are converted.
## Current Recommendation
## Current State
Do **not** switch main to URP yet.
| Category | Count | Notes |
The next useful work is preparation:
1. Build a reliable visual baseline for the current BiRP project.
2. Refresh the shader/material inventory with current scene-split assets.
3. Remove or isolate unused rendering dependencies.
4. Create a disposable URP probe branch to measure actual breakage.
5. Only then start a long-lived `urp-migration` branch.
This keeps normal gameplay work moving while making the eventual migration less
mysterious.
## What We Can Do Right Now
### 1. Create Visual Baselines
Before changing render pipelines, capture a small set of known-good views. These
should be reproducible enough that a human can compare screenshots after each URP
conversion step.
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 |
Immediate deliverable: a short manual test checklist, or an editor-only capture tool
that writes screenshots to an ignored directory. This should happen before any URP
settings change.
### 2. Refresh The Shader And Material Inventory
The old inventory is useful, but scene split and recent visual fixes changed the
project enough that we should regenerate it before migration work.
Immediate deliverable: a report containing:
- 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
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.
### 3. Verify Legacy Post Processing Usage
The project still depends on `com.unity.postprocessing: 3.5.4`. Current search results
show `PPP_Orc.asset` and scene template references, but not obvious production scene
usage.
Immediate deliverable: determine whether Post Processing Stack v2 is actually used
in production scenes.
If it is unused:
- remove `com.unity.postprocessing`
- remove unused profiles/resources/templates
- verify Unity opens cleanly
If it is used:
- document the exact scene/camera/profile usage
- 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. Decide What To Do With Heat Shimmer
`Eagle/HeatShimmer` uses a Built-in-style screen distortion approach, and `GrabPass`
does not translate directly to URP. Drought visuals should be triaged before the main
URP branch.
Immediate deliverable: decide one of:
- keep heat shimmer and reimplement it in URP
- replace it with a simpler URP-friendly drought effect
- remove/defer shimmer if the gameplay signal is already handled by other weather UI
This decision matters because it determines whether we need a custom URP renderer
feature early.
### 5. Check Third-Party URP Paths
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
Prioritize:
- Polytope Studio lowpoly character/environment shaders
- GUI Pro Kit Fantasy RPG shaders
- Modern UI Pack
- RRFreelance Orc/Ogre shaders
- DungeonMonsters2D sprite/animation shaders
### 6. Run A Disposable URP Probe
After the baseline and inventory exist, create a throwaway probe branch. This is not
the migration branch.
Probe goals:
- install URP
- create a minimal URP pipeline asset and renderer asset
- switch only the probe branch to URP
- run Unity's Render Pipeline Converter
- record what turns pink, what compiles, and what still renders
- throw away or reset the probe branch after documenting findings
The probe should answer unknowns cheaply. It should not try to produce a mergeable
game.
## Current Known Risks
| Risk | Why It Matters | Right-Now Action |
|---|---|---|
| Shaders | 47 | 7 custom Eagle, 1 hex mesh, 20 Polytope, 13 TextMesh Pro, 6 other third-party |
| Materials | 325 | Mix of Standard shader, custom, and third-party |
| ShaderGraph files | 4 | All TextMesh Pro (URP + HDRP variants already exist) |
| Scenes with baked lighting | 5 | Connection, Eagle, Shardok, Shared, Map Editor |
| Post-processing | 1 profile | PPP_Orc.asset (Post Processing Stack v2, FXAA/TAA, AO) |
| C# rendering scripts | 16 | Material/shader property manipulation only |
| Rendering path | Forward | Matches URP default |
| `ProvinceMapShader` | Core Eagle map rendering: province IDs, borders, ocean animation, faction highlighting, clipping | Audit inputs/properties and baseline screenshots |
| `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 | Decide heat shimmer/water strategy early |
| Surface shaders | URP does not support Built-in surface shader generation | Inventory and convert or replace |
| Polytope Studio shaders | Many character/environment materials may depend on Built-in lighting | Check vendor URP availability before hand conversion |
| 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 |
### Positive Findings
## Migration Strategy After Prep
- **No OnRenderImage, Graphics.Blit, CommandBuffer, or GL.\* usage** in C# code
- Forward rendering already in use (matches URP default)
- TextMesh Pro already has URP ShaderGraph variants in the project
- No custom render passes or ScriptableRenderFeatures
- Shader property manipulation (SetTexture, SetFloat, SetColor) is URP-compatible
Once the immediate prep work is complete, start a long-lived `urp-migration` branch.
Main should remain on BiRP until URP visual QA passes.
### Known Risk Areas
- **Main branch**: continues shipping BiRP while gameplay work proceeds.
- **URP branch**: accumulates pipeline, shader, material, lighting, and post-processing
changes.
- **Regular rebasing**: keep the URP branch current with main to avoid a painful final
integration.
- **Merge to main**: only after screenshots/manual QA show Connection, Eagle, and
Shardok are visually acceptable.
- **GrabPass shaders** (HeatShimmerShader, PT_Water_Shader) have no direct URP equivalent
- **ProvinceMapShader** is complex (province ID lookup, border rendering, ocean animation, faction highlighting, UI clipping)
- **Surface shaders** (`#pragma surface surf Standard`) must be rewritten as HLSL or ShaderGraph
- **Polytope Studio shaders** (20 shaders) have no vendor-provided URP variants
- **Post Processing Stack v2** must be replaced with URP's integrated Volume system
- **Tessellation** (PT_Water_Shader) is not natively supported in URP
This avoids the "everything is pink" problem of switching the pipeline before shaders
are converted.
## Shader Inventory
## Long-Term Phases
### Custom Eagle Shaders (7) -- HIGH PRIORITY
### Phase 0: Preparation
| Shader | Complexity | Key Issues |
|---|---|---|
| ProvinceMapShader | High | Province ID texture lookup, border rendering, ocean animation, faction highlighting, `UnityUI.cginc` dependency, stencil/clipping |
| ProvinceWeatherMapShader | Medium | Weather overlay rendering |
| ProvinceWeatherShader | Medium | Province weather effects |
| ProvinceParticleShader | Low | Custom particle rendering |
| HeatShimmerShader | High | **GrabPass** for screen distortion, province masking |
| ClipRectParticleUnlit | Low | UI-clipped particle shader |
| maskShader | Low | UI masking |
- Visual baseline checklist/screenshots
- Repeatable shader/material inventory
- Post Processing Stack usage decision
- Heat shimmer decision
- Third-party URP availability check
- Disposable URP probe findings
### Hex Mesh Shader (1) -- MODERATE PRIORITY
### Phase 1: Pipeline Setup
Uses `#pragma surface surf Standard` with GPU instancing. Straightforward conversion to URP Lit or ShaderGraph.
- Install/configure URP on the long-lived branch.
- Create URP Pipeline Asset and Renderer Asset.
- Configure forward rendering, shadows, HDR, and renderer features.
- Run Unity's Render Pipeline Converter.
- Keep a record of every auto-converted material.
### Third-Party Shaders (39)
### Phase 2: Core Custom Shaders
| Source | Count | Complexity | Notes |
Highest priority:
- `ProvinceMapShader`
- `ProvinceWeatherMapShader`
- `ProvinceWeatherShader`
- `ProvinceParticleShader`
- `ClipRectParticleUnlit`
- `maskShader`
- `Hex Mesh Shader`
Conversion notes:
- Replace Built-in includes such as `UnityCG.cginc`.
- Replace `UnityUI.cginc` clipping with URP-compatible code.
- Preserve stencil operations, render queues, texture lookups, and property names.
- Test map interactions, not just static rendering.
### Phase 3: GrabPass And Special Effects
- Reimplement or replace `HeatShimmerShader`.
- Reimplement or replace `PT_Water_Shader`.
- Avoid leaving screen-space effects until the end; they are likely to drive renderer
feature requirements.
### Phase 4: Third-Party Shaders
- Upgrade packages where vendor URP shaders exist.
- Convert remaining PBR/toon/vegetation shaders manually.
- Prefer replacement or deletion for unused demo-only assets.
### Phase 5: Materials, Lighting, And Post Processing
- 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.
### Phase 6: Validation
Required visual QA:
- 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 | Best Case | Realistic | Worst Case |
|---|---|---|---|
| Polytope Studio | 20 | Moderate-High | PBR, Toon, vegetation (custom lighting), water (**GrabPass + tessellation**). No vendor URP pack available. |
| TextMesh Pro | 13 | Low | URP ShaderGraph variants already exist in project |
| RRFreelance | 3 | Low | Standard surface shaders, direct conversion |
| Clown.fat | 2 | Moderate | Custom ToonRamp lighting model |
| GUI Pro Kit | 1 | Low | Hidden particle shader |
| Preparation/probe | 2-4 days | 1 week | 2 weeks |
| Core custom shaders | 1.5 weeks | 2-3 weeks | 4 weeks |
| GrabPass/special effects | 2-4 days | 1-2 weeks | 3 weeks |
| Third-party shaders/materials | 1.5 weeks | 2-3 weeks | 4 weeks |
| Lighting/post-processing | 3-5 days | 1-2 weeks | 2 weeks |
| QA/polish | 1 week | 2 weeks | 3 weeks |
| **Total** | **5-7 weeks** | **8-12 weeks** | **16+ weeks** |
### GrabPass Shaders (Require Special Handling)
GrabPass does not exist in URP. These must be reimplemented using `ScriptableRenderPass` + `Renderer Features` or Blit-based alternatives:
1. **HeatShimmerShader** -- Screen distortion effect (currently has a shimmer-disabled TODO, may be deprioritized)
2. **PT_Water_Shader** -- Water refraction/transparency (PT_Water_Shader_WebGl exists without GrabPass as a reference)
## Phased Approach
### Phase 1: Pipeline Setup + Auto-Conversion (Days 1-3)
- Install URP package
- Create URP Pipeline Asset and Renderer Asset
- Configure basic pipeline settings (forward rendering, shadow settings)
- Run Unity's **Render Pipeline Converter** (Edit > Rendering > Render Pipeline Converter)
- Auto-converts Standard shader materials and some built-in shaders
- Handles a significant portion of the 325 materials
- Will NOT touch custom shaders
- Create a test scene to validate basic rendering
- Migrate viewport clipping system (`RendererViewportClipper`, `ViewportClipper`, `PopupClipper`) to use URP-compatible global shader properties
### Phase 2: Custom Eagle Shaders (Weeks 1-3)
This is the critical path. Without these, the game is unplayable.
**Week 1-2: ProvinceMapShader**
- Convert from BiRP Cg/HLSL to URP HLSL
- Replace `UnityCG.cginc` includes with `Core.hlsl` / `Common.hlsl`
- Replace `UnityUI.cginc` with custom URP-compatible UI clipping
- Preserve province ID texture lookup, border rendering, ocean animation, faction highlighting
- Validate stencil operations and render queue ordering
**Week 2-3: Remaining Eagle shaders**
- ProvinceWeatherMapShader + ProvinceWeatherShader
- ProvinceParticleShader + ClipRectParticleUnlit
- maskShader
- Hex Mesh Shader (convert surface shader to URP Lit)
- HeatShimmerShader (reimplement without GrabPass, or defer if shimmer remains disabled)
### Phase 3: Third-Party Shaders (Weeks 4-6)
**Polytope Studio (20 shaders)**
- Convert PBR shaders (Armors, NPC, Weapons, Props, Rock) from surface shaders to URP Lit / ShaderGraph
- Convert Toon shaders to custom URP shader or ShaderGraph with custom lighting
- Convert vegetation shaders (custom `StandardCustom` lighting) to ShaderGraph
- PT_Water_Shader: Reimplement without GrabPass and tessellation (use PT_Water_Shader_WebGl as reference for non-GrabPass approach)
**Other third-party**
- Clown.fat ToonRamp shaders: Convert custom lighting model to ShaderGraph
- RRFreelance shaders: Direct Standard-to-URP-Lit conversion
- GUI Pro Kit particle shader: Convert to URP particle shader
### Phase 4: Materials, Lighting & Post-Processing (Weeks 7-8)
**Materials**
- Batch-update any remaining materials not handled by the auto-converter
- Verify all 325 materials render correctly
- Fix any visual differences from lighting model changes
**Lighting**
- Rebake lightmaps for all 5 scenes (Connection, Eagle, Shardok, Shared, Map Editor)
- Configure URP shadow cascade settings to match current quality levels
- Verify HDR rendering
**Post-Processing**
- Remove Post Processing Stack v2 dependency (`com.unity.postprocessing: 3.5.1`)
- Replace with URP integrated Volume system
- Recreate PPP_Orc effects (FXAA/TAA, Ambient Occlusion) using URP Volume overrides
### Phase 5: Testing & Validation (Weeks 9-11)
- Visual QA across all 6 scenes
- Verify beast/character rendering (vertex colors, animations)
- Verify weather effects (blizzard, drought, flood)
- Verify particle systems (fire & explosion effects, UI particles)
- Verify UI rendering (GUI Pro Kit, Modern UI Pack, TextMesh Pro)
- Performance profiling (URP has different performance characteristics)
- Test on target platforms
- Bug fixes and visual polish
## Effort Estimates
| Phase | Best Case | Realistic | Worst Case |
|---|---|---|---|
| 1. Pipeline Setup | 1-2 days | 2-3 days | 3-5 days |
| 2. Custom Eagle Shaders | 1.5 weeks | 2-3 weeks | 3-4 weeks |
| 3. Third-Party Shaders | 1.5 weeks | 2-3 weeks | 3-4 weeks |
| 4. Materials & Lighting | 3-5 days | 1-1.5 weeks | 2 weeks |
| 5. Testing & Validation | 1 week | 1.5-2 weeks | 2-3 weeks |
| **Total** | **6-8 weeks** | **8-12 weeks** | **12-16 weeks** |
The biggest variable is Polytope Studio shader conversion. If vendor URP packs become available, Phase 3 shrinks significantly.
The biggest variable is still third-party shader conversion. Vendor URP packages or
asset deletion can shrink this significantly.
## Key Reminders
- **Don't leave GrabPass rewrites and ProvinceMapShader for the end** -- they're the riskiest pieces and should be tackled early.
- The migration window (~1 year) is comfortable. Spreading the work across this window is fine, but front-load the hard shader work.
- C# code changes should be minimal -- the codebase avoids direct rendering API usage.
- `UnityUI.cginc` has no direct URP equivalent. Custom implementation will be needed for UI clipping in shaders.
- Do not switch main to URP as a first step.
- Do not leave `ProvinceMapShader`, `UnityUI.cginc`, or `GrabPass` work until the end.
- 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.