# 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:

```markdown
# 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.