unity-urp-migration
Migrate a Built-in project to URP, or fix a half-moved one: pink materials, PPv2, old shaders.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- unity-urp-migration
- description
- Migrate a Built-in project to URP, or fix a half-moved one: pink materials, PPv2, old shaders.
02 资源文件 13
- 参考文档reference/execution-and-report.md2.3 KB
- 参考文档reference/lighting-and-probes.md7.3 KB
- 参考文档reference/material-conversion.md7.0 KB
- 参考文档reference/migration-phases.md9.1 KB
- 参考文档reference/ppv2-to-volumes.md6.6 KB
- 参考文档reference/shader-migration.md9.2 KB
- 其他resources/Editor/LightingMigration.cs14.0 KB
- 其他resources/Editor/MaterialConverter.cs14.7 KB
- 其他resources/Editor/MigrationAudit.cs8.9 KB
- 其他resources/Editor/MigrationGate.cs7.3 KB
- 其他resources/Editor/PipelineAssignment.cs6.0 KB
- 其他resources/Editor/SceneCapture.cs4.4 KB
- 其他resources/Editor/VolumeMigration.cs11.9 KB
03 SKILL.md 正文
unity-urp-migration — five phases, each one read back before the next
Whether a migration is finished is a property of the saved project, not of the converter log. Four separate traps let this migration report success while the project still renders the old way, and each of them is invisible to every check except re-reading what was written. And nothing mutates — no package, no assignment, no material, no scene — until a rollback point has been confirmed out loud.
Symptom → where to look
| Symptom | Go to |
|---|---|
| "Migrate / upgrade this project to URP" | §1, starting at Phase 0 |
| "Everything went pink or magenta after switching to URP" | reference/material-conversion.md — incomplete material conversion |
| Not magenta, but white or untextured | reference/material-conversion.md — the snapshot and restore steps |
| "My Standard materials became 2D/Mesh2D-Lit-Default" | reference/material-conversion.md §trap |
| "The Render Pipeline Converter ran but it still looks Built-in" | §3 trap 1 — check Graphics settings and every quality tier; resolver in unity-render-urp → reference/resolve-active-pipeline.md |
Convert PPv2 / PostProcessVolume to a URP Volume; post-processing vanished |
reference/ppv2-to-volumes.md |
| Scene is blown out or far too dark | reference/ppv2-to-volumes.md (two stacks running) before reference/lighting-and-probes.md |
| Lightmaps look blown out after URP; probes look wrong | reference/lighting-and-probes.md |
GrabPass, OnRenderImage, a surface shader (#pragma surface), SetReplacementShader no longer work |
reference/shader-migration.md |
| "Which quality settings moved into the URP asset?" — shadow distance, MSAA, HDR | reference/migration-phases.md §quality map |
| The pass stopped right after the package installed | §1 — that is a phase boundary; resume, do not restart |
| A 2D project | §2, path B — a different renderer and a different upgrader set |
unity status shows no row and no error |
reference/execution-and-report.md §4, the floor trap |
| Before-and-after pictures wanted | resources/Editor/SceneCapture.cs |
1. The five phases
| Phase | Work | Gate | Scripts |
|---|---|---|---|
| 0 · Inspect | Pipeline at Graphics settings and at every tier; packages; risk grep; old post-processing found by component type; materials bucketed; lighting state | A report and a confirmed rollback point | resources/Editor/MigrationAudit.cs |
| 1 · Pipeline + materials | Install or reuse URP; asset and renderer; assign at Graphics and every tier; snapshot → convert → restore → verify | GetRenderPipelineAssetAt(i) right on every tier; every converted material's shader.name matches its mapped target; every material that had _MainTex has a non-null _BaseMap |
resources/Editor/PipelineAssignment.cs · resources/Editor/MaterialConverter.cs |
| 2 · Post-processing | Persisted VolumeProfile; scene Volume.sharedProfile; camera post-processing on; legacy components disabled |
After a reload, components are non-null; the saved scene references the profile; legacy components re-query as disabled with the scene saved clean | resources/Editor/VolumeMigration.cs |
| 3 · Lighting + probes | Identify a stale bake; scene references a URP .lighting; rebake or declare partial; probe settings on the asset |
Saved scene points at the .lighting; bake evidence or an explicit partial; m_ReflectionProbeBlending: 1 in the asset text |
resources/Editor/LightingMigration.cs |
| 4 · Validate + report | Save, reload, re-query; capture; console; wording | Every gate above passes | resources/Editor/MigrationGate.cs · resources/Editor/SceneCapture.cs |
Package installs, domain reloads and bakes are phase boundaries. When one interrupts the pass, resume from the first gate that did not pass — never from the beginning, because reinstalling a package and reconverting converted materials is how a migration loses an afternoon. The rollback confirmation covers the whole trip; ask again only when a genuinely new expensive or destructive step arrives.
Full phase detail, the converter table, the resume checklist and the quality-settings map:
reference/migration-phases.md.
2. Before the first mutation
Confirm the rollback point in words — a branch, a copy, a tag, or "this is a throwaway clone". Mutation starts at the package install, because a project with URP assigned and materials unconverted renders magenta, and that is not a state to leave someone in while asking about backups.
Engine upgrade first, pipeline second when the project is also moving Unity versions. Two migrations at once means every later symptom has two candidate causes.
Detect in two places, always. The project default is GraphicsSettings.defaultRenderPipeline;
the tiers are a loop over QualitySettings.names reading GetRenderPipelineAssetAt(i). A
project can be switched at one and not the other, and the one that is wrong is the one nobody
looked at.
There is no SetRenderPipelineAssetAt. Writing a tier means SetQualityLevel(i), then
QualitySettings.renderPipeline = asset, then restoring the original level. An invented setter
assigns nothing and reports nothing.
Detecting HDRP means stopping: explain that this is a different pipeline with different Volume components and different renderer plumbing, and that nothing here transfers.
Then pick the path: A standard 3D · B 2D, which needs the 2D renderer and the 2D upgrader container · C selected materials only, on a project already on URP · D troubleshooting an attempt that already happened · E plan only, changing nothing.
3. Four traps that make it look done
1 · Assigned at Graphics settings, not at the tiers. A tier reading {fileID: 0} inherits
the project default, which is legal — but say it is a choice rather than reporting "all tiers
migrated". A tier pointing at a different asset is worse: that is a second pipeline the
project ships with, and it renders on whichever platforms select that tier.
2 · Converted, not magenta, and wrong. Both the 2D and the 3D upgrader providers claim
Standard at equal priority, so a plain Standard material can land on a 2D shader in a 3D
project with nothing logged. Separately, changing a shader without a snapshot leaves _BaseMap
null and _BaseColor white while every property reads back cleanly. Read shader.name and
_BaseMap back after every conversion, whatever route ran.
3 · The empty profile asset. VolumeProfile.Add<T>(true) creates the override object but
does not make it a sub-asset. Without AssetDatabase.AddObjectToAsset the profile reloads as
components: [] or {fileID: 0} entries. And SaveAssets() writes the profile but not the
scene that references it — that needs MarkSceneDirty plus SaveScene.
4 · Lighting that is still Built-in. Old lightmaps and the lighting data asset are live
data, not history; they keep lighting the scene until something clears them.
Lightmapping.Clear() is not evidence until the scene is saved and re-read. "Probes refreshed"
needs a bake result, not an intention.
4–5. Execution path, report wording → reference/execution-and-report.md
§4 driving the passes through the CLI and a live Editor, and the floor trap where unity status
shows no row and no error; §5 matching the report's wording to the gate that passed.
Load what the situation needs
| The situation | Read |
|---|---|
| Running an actual migration, or resuming one | reference/migration-phases.md |
| Materials: magenta, white, 2D-shader hijack, particles, foliage | reference/material-conversion.md |
| The old post-processing stack, empty profiles, double post-processing | reference/ppv2-to-volumes.md |
| Lightmaps, a stale bake, reflection probes, exposure balance | reference/lighting-and-probes.md |
Custom shaders, GrabPass, OnRenderImage, replacement shaders |
reference/shader-migration.md |
Volume API, parameter defaults, types and ranges, overrideState, grade presets, the five-switch pre-flight |
unity-render-urp |
| Which pipeline is actually in force, including per-tier and per-platform | unity-render-urp → reference/resolve-active-pipeline.md |
| Porting a full-screen effect onto a project already on Render Graph; reviewing a renderer feature | unity-render-urp → reference/render-graph-review.md |
sharedProfile versus profile, and undo from eval |
unity-render-urp → reference/volume-templates.md |
| Reaching the Editor at all; installing CLI, editors, licences; the command catalog | unity-cli |
| Reading the command envelope; a confirm gate; screenshots and logs | unity-debug → reference/editor-control.md |
| "It got slower after the migration" — numbers across the change | unity-profiling |
| A 2D project's camera, upscaling and pipeline detection | unity-2d-pixel-perfect |
Discipline
- Read it back. Never trust a log. Every claim in a report comes from a file or an object reloaded after saving, not from the call that wrote it.
SaveAssetsis notSaveScene. Assets and scenes persist by different calls, and the half that was skipped reads correctly until the Editor closes.- Snapshot before changing a shader. Afterwards the source values are gone, and a repair written from post-conversion properties preserves the broken state.
- Read
shader.nameafter every conversion, converter or manual. It is the only check that catches a material that converted onto the wrong target. - Never claim a probe refresh from intent. Changed probe files or nothing.
- Package installs and bakes are boundaries. Resume from the first failed gate.
- Never edit materials or shaders under
Packages/orLibrary/PackageCache/. Local copy, or manual follow-up. - Grade custom shaders before porting any of them, and never bulk-replace shader source.
- Match the wording to the gate. "Complete" is a claim about saved state, not a summary of effort.
- Write captures to a temp path, not into
Assets/— a PNG in the project becomes an imported asset somebody has to clean up. - Never force an effect material to Lit. Particle, fog, smoke, additive and decal materials keep their blend mode or the effect is gone while every check says it converted.
Scope — what this skill does NOT do
| Not here | Go to |
|---|---|
| Post-processing that will not appear on a project already on URP | unity-render-urp |
| Volume parameters and grades, Render Graph review, the CLI, on-screen verification, frame-time cost, 2D upscaling | the handoff rows of the table above |
| Sprite import, atlases and tilemaps in their own right | unity-2d-sprites · unity-sprite-atlas · unity-tilemap |
Shading maths stays out. This skill decides how a shader should be ported and what evidence proves it landed; it does not decide what the shader should compute. HDRP stays out in both directions — neither migrating to it nor away from it.
04 同仓库更多 Skills
unity-web-release
Ship a WebGL/WebGPU build: shrink the download, Brotli server headers, Safari and iPhone memory.
unity-vivox
Vivox voice and text chat: channels, positional voice, mute and push-to-talk, mic permission.
unity-ui-ugui
Canvas UI (uGUI): CanvasScaler, RectTransform anchors, Layout Groups, ScrollView, UI built from C#.
unity-ui-toolkit
UI Toolkit (UXML, USS, UIDocument): flex layout, binding, custom elements, editor windows.
unity-ugs
Unity Gaming Services API: which package, init and sign-in order, Cloud Save, Cloud Code, Remote Config.
unity-tilemap
Tile Palettes for rect, hex and iso grids, rule tiles, autotiling from a terrain sheet.