eagle0/docs/URP_PROBE_PLAYBOOK.md

URP Probe Playbook

Last refreshed: 2026-06-14

This playbook is historical reference for the disposable URP probe described in 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

• Use the already-installed URP package in an isolated branch.
• Create the minimum URP pipeline/renderer assets needed to enter Play Mode.
• Run Unity's Render Pipeline Converter.
• Record compile errors, pink materials, broken shaders, and visual regressions.
• Preserve findings in docs, then discard or reset the probe branch.

Branch Shape

Use two branches:

Branch	Purpose	Mergeable
codex/urp-probe	Disposable package/settings/material conversion experiment	No
codex/urp-probe-findings	Small docs-only summary copied from the probe	Yes

Do not open a PR from codex/urp-probe unless it is clearly marked draft and experimental. Prefer opening the PR from codex/urp-probe-findings.

Before Starting

1. Confirm origin/main is fresh.
2. Confirm the worktree is clean.
3. Capture or review the baseline checklist in docs/URP_VISUAL_BASELINE_CHECKLIST.md.
4. Generate a current inventory with Eagle0 > Rendering > Generate URP Migration Inventory.
5. Keep the inventory output under Unity Temp/urp_migration/; do not commit generated reports unless they are intentionally summarized.

Probe Steps

1. Create codex/urp-probe from origin/main.
2. Confirm com.unity.render-pipelines.universal is installed in Packages/manifest.json.
3. If testing new pipeline settings, create alternate URP Pipeline/Renderer assets under a clearly named temporary folder.
4. Assign the alternate URP pipeline asset in:
   • ProjectSettings/GraphicsSettings.asset
   • ProjectSettings/QualitySettings.asset
5. Run Unity's Render Pipeline Converter only if the experiment intentionally tests material conversion.
6. Enter Play Mode from Assets/Scenes/Main.unity.
7. Exercise the baseline views:
   • Connection lobby
   • Eagle map
   • Eagle weather and beast effects
   • Shardok terrain, grid, labels, bridges, fires, overlays
   • Connection -> Eagle -> Shardok -> Eagle transitions
8. Record the exact failure mode for every broken visual:
   • compile error
   • pink material
   • invisible mesh or sprite
   • wrong render order
   • lighting/shadow difference
   • input or scene-load regression

Expected High-Risk Areas

• Eagle map rendering:
  • province colors, borders, and ocean animation
  • weather overlays and province particles
  • beast effects on the map and in notifications
• Shardok map rendering:
  • terrain, bridges, fire overlays, and grid overlays
  • foreground UI/effect overlays
  • unit labels/icons over fires, bridges, and one-shot animations
• Third-party 3D materials:
  • Polytope Studio character prefabs used by Eagle human-type beast effects
  • RRFreelance Orc/Ogre materials used by OgreEffect
• Render ordering in Shardok:
  • unit text/icons versus fires
  • unit text/icons versus bridges
  • selection/command overlays versus labels

Findings Template

Copy this template into the mergeable findings branch after the probe:

# URP Probe Findings

Date:
Unity version:
URP package version:
Probe branch commit:

## Summary

- Entered Play Mode:
- Connection usable:
- Eagle usable:
- Shardok usable:
- Build attempted:

## Converter Results

- Materials converted:
- Materials left pink:
- Shader compile errors:

## Visual Regressions

| Area | Expected | Actual | Likely Cause | Next Action |
|---|---|---|---|---|

## Required Migration PRs

1.
2.
3.

## Notes

-

After The Probe

1. Copy findings into a docs-only branch.
2. Delete or abandon codex/urp-probe.
3. Do not merge probe-generated package/settings/material churn into main until the findings have been reviewed and broken visuals have owner PRs.