migrate-birp-to-urp
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseClassify the request, inspect the current project state, choose the correct migration path, and validate the Built-in to URP migration outcome carefully.
对请求进行分类,检查当前项目状态,选择正确的迁移路径,并认真验证从 Built-in 到 URP 的迁移结果。
Mandatory Execution Reference
强制执行参考
For any actual migration or repair pass, read references/implementation-patterns.md before the first call that edits project settings, materials, post-processing, lighting, probes, or scenes. This is mandatory even for short prompts such as "migrate this project to URP" when rollback safety is already confirmed.
evalIf that resource cannot be loaded, use the embedded rules in this SKILL.md and lower your confidence: do not claim PPv2 conversion, lighting/probe refresh, or migration completion from intent or tool logs alone.
对于任何实际迁移或修复操作,在第一次会修改项目设置、材质、后处理、光照、探针或场景的 调用之前,必须阅读 references/implementation-patterns.md。即使是“将此项目迁移到 URP”这类简短提示,只要回滚安全性已经确认,也必须执行此要求。
eval如果无法加载该资源,请使用此 SKILL.md 中内嵌的规则并降低置信度:不要仅凭意图或工具日志就声称已完成 PPv2 转换、光照或探针刷新,或迁移已经完成。
Critical Default
关键默认行为
For simple requests like "migrate this Built-in project to URP" or "move this project to URP", start or resume the safe migration workflow rather than jumping straight to conversion.
A generic upgrade prompt must not require the user to mention every migration risk. Inspect and handle common Built-in dependencies such as PPv2, baked lighting/lightmaps, reflection probes, particle/fog/smoke materials, Quality levels, camera post-processing, and representative scene validation.
Default result is phase-based:
- Detect whether the project is Built-in, partially migrated, already URP, or HDRP.
- Classify the request as standard 3D URP, URP 2D, selected-material conversion, planning-only, or troubleshooting.
- Inspect migration risks before recommending changes: opaque materials, particle/VFX materials, custom shaders, post-processing, camera effects, baked lighting/lightmaps/reflection probes, Quality levels, and representative scenes.
- Stop before any pipeline-mutating work until the user confirms a rollback point such as a branch, backup, archive, or disposable copy. Pipeline-mutating work includes installing URP, assigning a URP asset in Graphics/Quality settings, running converters, and editing materials or scenes.
- Choose the next migration phase, execute that phase, save/re-query its outputs, and report its phase status.
- Treat custom shaders, , Surface Shaders,
GrabPass, replacement shaders, and package-owned shaders as scoped follow-up work, not automatic converter work.OnRenderImage - Validate representative scenes, Console output, camera rendering, lighting/baked GI state, materials, post-processing persistence, and quality-level assignments before declaring full migration success.
Default phases:
- Phase 0: Inspect and plan. Detect pipeline state, representative scenes, rollback safety, PPv2, material/shader risks, Quality levels, lighting/lightmap/probe state, and custom render code.
- Phase 1: URP setup and supported material conversion. Install/reuse URP, create/assign URP assets in Graphics/Quality, convert supported opaque and particle/effect materials, and verify no supported materials remain on Built-in shaders.
- Phase 2: Post-processing and camera migration. Create persistent URP Volume profiles, wire scene Volumes/camera post-processing, disable legacy PPv2 for URP validation, and classify unsupported PPv2 effects such as SSR.
- Phase 3: Lighting, lightmaps, and reflection probes. Resolve stale Built-in lighting state, configure URP lighting/probe settings, rebake/refresh when feasible, or clearly mark lighting/probes partial.
- Phase 4: Final validation and report. Save/reload/re-query project state, capture representative scenes, check Console, and report complete/incomplete/manual items.
One turn may complete multiple phases if the project is small and Unity remains stable, but do not force all phases into one response. Prefer an honest phase boundary over an over-claimed "complete" result.
Ask configuration questions only when the project state or user intent leaves a real decision unresolved. If the user says "do not modify files", stay in audit/planning mode and do not perform conversion or asset edits.
对于“迁移这个 Built-in 项目到 URP”或“把这个项目迁移到 URP”之类的简单请求,应启动或恢复安全的迁移工作流,而不是直接进入转换。
通用升级提示不应要求用户逐一列出所有迁移风险。应自动检查并处理常见的 Built-in 依赖项,例如 PPv2、烘焙光照或 Lightmap、反射探针、粒子、雾和烟雾材质、Quality 级别、相机后处理,以及代表性场景验证。
默认结果按阶段划分:
- 检测项目当前处于 Built-in、部分迁移、已经使用 URP,还是 HDRP 状态。
- 将请求分类为标准 3D URP、URP 2D、选定材质转换、仅制定计划,或故障排查。
- 在建议更改之前检查迁移风险:不透明材质、粒子或 VFX 材质、自定义 Shader、后处理、相机效果、烘焙光照或 Lightmap、反射探针、Quality 级别,以及代表性场景。
- 在用户确认回滚点(如分支、备份、归档或一次性副本)之前,停止执行任何会修改渲染管线的操作。此类操作包括安装 URP、在 Graphics 或 Quality 设置中指定 URP Asset、运行转换器,以及编辑材质或场景。
- 选择下一迁移阶段,执行该阶段,保存并重新查询其输出,然后报告该阶段的状态。
- 将自定义 Shader、、Surface Shaders、
GrabPass、替换 Shader 和包所有的 Shader 作为有范围的跟进工作处理,而不是自动交给转换器处理。OnRenderImage - 在声明完整迁移成功之前,验证代表性场景、Console 输出、相机渲染、光照或烘焙 GI 状态、材质、后处理持久化情况以及 Quality 级别分配。
默认阶段:
- Phase 0:检查并规划。检测管线状态、代表性场景、回滚安全性、PPv2、材质或 Shader 风险、Quality 级别、光照、Lightmap、探针状态以及自定义渲染代码。
- Phase 1:URP 设置和支持的材质转换。安装或复用 URP,在 Graphics 和 Quality 中创建并指定 URP Asset,转换支持的不透明材质及粒子或特效材质,并验证是否还有受支持的材质在使用 Built-in Shader。
- Phase 2:后处理和相机迁移。创建持久化的 URP Volume Profile,连接场景 Volume 与相机后处理,为 URP 验证禁用旧版 PPv2,并对 SSR 等不受支持的 PPv2 效果进行分类。
- Phase 3:光照、Lightmap 和反射探针。解决过期的 Built-in 光照状态,配置 URP 光照和探针设置,在可行时重新烘焙或刷新,否则明确标记光照或探针仅部分完成。
- Phase 4:最终验证和报告。保存、重新加载并重新查询项目状态,捕获代表性场景,检查 Console,并报告完整、未完成或需要手动处理的项目。
如果项目规模较小且 Unity 保持稳定,一轮操作可以完成多个阶段,但不要强行在一次响应中完成所有阶段。宁可诚实地划分阶段边界,也不要过度声称“complete”。
仅当项目状态或用户意图仍存在实际未决问题时,才询问配置问题。如果用户说“不要修改文件”,则保持审计或规划模式,不执行转换或资产编辑。
Generic Upgrade Contract
通用升级约定
When the user gives a generic migration request and permits changes, drive the next phase from the project state:
- Do not ask the user to enumerate known Built-in features before inspection. Discover them.
- If PPv2, baked lighting, reflection probes, particle/fog/smoke materials, or multiple Quality levels exist, include them in the migration automatically.
- Prefer phase completion over all-in-one completion. Each phase should save/re-query its own outputs and end with ,
Phase complete, orPhase partial.Blocked - If Unity compilation, package installation, domain reload, or a long lighting bake interrupts the pass, report the interruption as a phase boundary and resume from saved partial state in the next turn rather than starting over.
- Do not rely on the user writing a detailed checklist prompt to get correct behavior. The detailed checklist is for benchmarking or stress testing; normal user prompts should still trigger this phased contract.
- A generic migration request gives permission to inspect and plan, but it does not prove rollback safety. If no rollback point is confirmed, stop before package install or URP assignment and ask for confirmation. Do not leave the project in a magenta partial state just to reach the backup question.
- If rollback safety is already confirmed or the user says the project is a disposable copy, continue within the current phase without asking again for routine work.
- At the end of a phase, give a concise next-phase prompt or say what phase should run next. Ask for confirmation before the next phase only when it introduces a new costly or risky operation, such as a long lighting bake, deletion/cleanup of legacy assets, or a custom shader rewrite.
- If rollback safety was confirmed and ordinary work inside the active phase remains incomplete, do not ask "would you like me to continue?" Continue repairing that phase until its gate passes, a tool/domain-reload boundary interrupts execution, or a genuinely new risky decision appears.
当用户给出通用迁移请求并允许更改时,应根据项目状态推进下一阶段:
- 不要要求用户在检查前枚举所有已知的 Built-in 功能;应主动发现这些功能。
- 如果存在 PPv2、烘焙光照、反射探针、粒子、雾或烟雾材质,或者存在多个 Quality 级别,应自动将其纳入迁移。
- 优先确保阶段完成,而不是追求一次性全部完成。每个阶段都应保存并重新查询自己的输出,并以 、
Phase complete或Phase partial结束。Blocked - 如果 Unity 编译、包安装、域重载或长时间光照烘焙中断了操作,应将此次中断视为阶段边界,并在下一轮从已保存的部分状态继续,而不是从头开始。
- 不要依赖用户编写详细检查清单提示才能获得正确行为。详细清单用于基准测试或压力测试;普通用户提示也应触发这一分阶段约定。
- 通用迁移请求授权检查和规划,但不能证明回滚安全。如果没有确认回滚点,应在安装包或指定 URP 前停止,并请求用户确认。不要为了先询问备份问题而让项目处于洋红色的部分迁移状态。
- 如果已经确认回滚安全,或用户说明项目是一次性副本,则在当前阶段内继续执行,无需再次询问常规操作。
- 在阶段结束时,给出简洁的下一阶段提示,或说明接下来应运行哪个阶段。只有当下一阶段引入新的高成本或高风险操作时,例如长时间光照烘焙、删除或清理旧资产、自定义 Shader 重写,才需要征求确认。
- 如果已确认回滚安全,且当前阶段的常规工作仍未完成,不要询问“是否继续”。应持续修复该阶段,直到其关卡通过、工具或域重载边界中断执行,或者出现真正新的高风险决策。
Generic Migration Success Gate
通用迁移成功关卡
Before saying a generic migration is "successful", "complete", or "fully migrated", verify saved project state, not just tool logs:
- Graphics settings and every relevant Quality level point to the intended URP asset.
- The URP asset has a valid default renderer in saved state, and current Console output does not contain unresolved render-pipeline errors such as "Default Renderer is missing". If a renderer error appears after assignment, re-query the saved renderer list/default index, clear stale Console output when possible, trigger a fresh scene/camera validation, and continue repair instead of stopping at "URP setup complete".
- Supported Built-in materials, including particle/fog/smoke materials, have URP-compatible shaders or are explicitly listed as unresolved custom/package shader cases. Textured/colorized source materials must preserve their source maps/colors; a URP shader assignment with missing or all-white
_BaseMapis incomplete if the source_BaseColoror_MainTexhad content. Particle, fog, smoke, steam, decal, VFX, additive, and transparent effect materials should not be blindly forced to_Color; prefer URP particle/effect shaders such asUniversal Render Pipeline/Litwhen appropriate.Universal Render Pipeline/Particles/Unlit - If the source scene used PPv2, a saved URP exists with persistent non-null override components, the representative scene references it through a URP
VolumeProfile, and legacy PPv2 is disabled for URP visual validation. A saved profile withVolume,components: []component refs, or a scene that still only references the old{fileID: 0}is incomplete.PostProcessProfile - If the representative scene uses baked/mixed lighting, an Enlighten/realtime-GI Lighting Settings asset, a Lighting Data asset, lightmaps, light probes, or reflection probes, do not leave routine lighting/probe repair as manual follow-up during a generic full migration. Attempt URP-compatible Lighting Settings assignment, clear/rebake or resume a bake when needed, refresh reflection probes when feasible, then save/reload and verify the scene references the intended lighting state. Creating a asset and calling
.lightingplusLightmapping.lightingSettings = targetis not enough; mark/save the scene, reload/re-query, and compare the saved sceneAssetDatabase.SaveAssets()reference or asset GUID. If a long bake or tool interruption prevents this, call the migration partial and resume from that phase.m_LightingSettings - A representative scene has been opened or selected deliberately before migration validation; do not infer baked-lighting or PPv2 absence from a default/test scene. The scene has been captured or inspected after saving/reloading, and Console output has been checked for render-pipeline, shader, or renderer-feature errors.
- Final wording must match the gate result. Use "complete" only when every gate passes. Use "partial" when URP is set up but PPv2 Volume persistence, legacy PPv2 disablement, lighting bake/probe refresh, or saved-state validation remains. Do not start the final response with "successfully migrated" if any required gate is partial.
Complete-report checklist:
- If the old PPv2 profile contains active , the new URP profile must contain a saved
DepthOfFieldoverride or the final report must call it omitted/manual.DepthOfField - If the old PPv2 profile contains active , configure a URP SSAO renderer feature when feasible, or mark AO as manual/partial.
AmbientOcclusion - If the old PPv2 profile contains active , list SSR as unsupported/manual unless a URP renderer-feature/custom replacement was actually added and validated.
ScreenSpaceReflections - If the scene still serializes the old Lighting Settings GUID or a non-zero old , lighting is partial.
m_LightingDataAsset - If the scene has reflection probes and the URP asset still serializes or
m_ReflectionProbeBlending: 0, reflections are partial unless intentionally disabled and reported.m_ReflectionProbeBoxProjection: 0 - If any checklist item is false, do not use "complete", "fully migrated", or "fully functional on URP" in the final answer.
Unsupported features can remain manual, but name them precisely. Examples include PPv2 Screen Space Reflections needing a URP renderer-feature/custom/third-party replacement, complex custom shader ports, , replacement shaders, or package-owned rendering code. If any success-gate item fails, continue repairing when allowed or report a partial migration with incomplete items; do not present the project as fully migrated.
GrabPassRegression guard summary:
- Use the detailed Execution Regression Checklist for actual migration or repair work.
- Verify saved scene references before status claims: URP Volume/profile, Quality assignments, Lighting Settings/Data, URP asset/renderer, and reflection-probe settings.
- Preserve material source data from a pre-conversion snapshot, then restore ,
_BaseMap, texture scale/offsets, and relevant maps after shader changes._BaseColor - Validate representative visuals for PPv2, foliage, particles/effects, baked lighting, probes, and exposure before final wording.
- Report exact phase status. is allowed for a passed phase; project-level
Phase completeis allowed only when every success gate passes.complete
在声明通用迁移“successful”、“complete”或“fully migrated”之前,应验证已保存的项目状态,而不只是工具日志:
- Graphics 设置和每个相关 Quality 级别都指向预期的 URP Asset。
- URP Asset 在已保存状态下具有有效的默认 Renderer,且当前 Console 输出中不存在未解决的渲染管线错误,例如“Default Renderer is missing”。如果指定 Asset 后出现 Renderer 错误,应重新查询已保存的 Renderer 列表和默认索引,在可行时清空过期 Console 输出,触发新的场景或相机验证,并继续修复,而不是停在“URP setup complete”。
- 受支持的 Built-in 材质,包括粒子、雾和烟雾材质,应具有 URP 兼容 Shader,或者被明确列为未解决的自定义或包 Shader 情况。带纹理或着色的源材质必须保留其源贴图或颜色;如果源材质的 或
_MainTex有内容,而 URP Shader 分配后缺少_Color或_BaseMap全为白色,则属于不完整。粒子、雾、烟雾、蒸汽、Decal、VFX、加法混合和透明特效材质不应被盲目指定为_BaseColor;适用时应优先使用Universal Render Pipeline/Lit等 URP 粒子或特效 Shader。Universal Render Pipeline/Particles/Unlit - 如果源场景使用 PPv2,则应存在已保存的 URP ,其中包含持久化且非空的 Override 组件;代表性场景应通过 URP
VolumeProfile引用它,并且为了 URP 视觉验证,应禁用旧版 PPv2。如果已保存 Profile 的Volume为空、组件引用为components: [],或者场景仍然只引用旧的{fileID: 0},则迁移不完整。PostProcessProfile - 如果代表性场景使用烘焙或混合光照、Enlighten 或实时 GI Lighting Settings Asset、Lighting Data Asset、Lightmap、Light Probe 或 Reflection Probe,则在通用完整迁移中,不应将常规光照或探针修复留作手动跟进。尝试指定 URP 兼容 Lighting Settings,必要时清除并重新烘焙或继续烘焙,在可行时刷新反射探针,然后保存、重新加载并验证场景引用了预期的光照状态。仅创建 Asset 并调用
.lighting与Lightmapping.lightingSettings = target并不足够;应标记并保存场景,重新加载或重新查询,并比较已保存场景中的AssetDatabase.SaveAssets()引用或 Asset GUID。如果长时间烘焙或工具中断导致无法完成,应将迁移标记为 partial,并在之后从该阶段继续。m_LightingSettings - 迁移验证前,应有意打开或选定一个代表性场景;不要根据默认或测试场景推断不存在烘焙光照或 PPv2。场景应在保存和重新加载后被捕获或检查,并检查 Console 中是否存在渲染管线、Shader 或 Renderer Feature 错误。
- 最终措辞必须与关卡结果一致。只有每项关卡都通过时才能使用“complete”。如果 URP 已设置,但 PPv2 Volume 持久化、旧版 PPv2 禁用、光照烘焙或探针刷新、已保存状态验证仍未完成,则使用“partial”。如果任何必需关卡仅为 partial,不得以“successfully migrated”开头。
完整报告检查清单:
- 如果旧 PPv2 Profile 包含已启用的 ,新的 URP Profile 必须包含已保存的
DepthOfFieldOverride,或者最终报告必须将其标记为遗漏或需要手动处理。DepthOfField - 如果旧 PPv2 Profile 包含已启用的 ,应在可行时配置 URP SSAO Renderer Feature,或者将 AO 标记为需要手动处理或仅部分完成。
AmbientOcclusion - 如果旧 PPv2 Profile 包含已启用的 ,除非实际添加并验证了 URP Renderer Feature、自定义替代方案或第三方替代方案,否则应将 SSR 列为不受支持或需要手动处理。
ScreenSpaceReflections - 如果场景仍序列化旧的 Lighting Settings GUID 或非零的旧 ,则光照迁移为 partial。
m_LightingDataAsset - 如果场景包含 Reflection Probe,而 URP Asset 仍序列化 或
m_ReflectionProbeBlending: 0,则反射迁移为 partial,除非这些功能被有意禁用并已明确报告。m_ReflectionProbeBoxProjection: 0 - 如果任何检查项为 false,则不得在最终答复中使用“complete”、“fully migrated”或“fully functional on URP”。
不受支持的功能可以保留为手动处理项,但应准确列明。例如,PPv2 Screen Space Reflections 需要 URP Renderer Feature、自定义实现或第三方替代方案;复杂自定义 Shader 移植、、替换 Shader 或包所有的渲染代码也属于此类。如果任何成功关卡未通过,应在允许的情况下继续修复,或者报告迁移为 partial 并列出未完成项;不要将项目描述为已完整迁移。
GrabPass回归防护摘要:
- 实际迁移或修复工作应使用详细的 Execution Regression Checklist。
- 在声明状态前验证已保存的场景引用:URP Volume 或 Profile、Quality 分配、Lighting Settings 或 Data、URP Asset 或 Renderer,以及 Reflection Probe 设置。
- 从转换前快照中保留材质源数据,然后在 Shader 更改后恢复 、
_BaseMap、纹理缩放与偏移以及相关贴图。_BaseColor - 最终措辞前,验证 PPv2、植被、粒子或特效、烘焙光照、探针和曝光的代表性视觉效果。
- 准确报告阶段状态。阶段通过后可以使用 ;只有每项成功关卡均通过时,才能在项目级别使用 complete。
Phase complete
Execution path: running C# in the Editor
执行路径:在 Editor 中运行 C#
Every C# step in this skill runs inside a live Editor through the Unity CLI. The
skill owns getting you there — installing the CLI, confirming a connected Editor, adding the
project's package, telling a genuinely absent Editor apart from one stuck in
Safe Mode, and discovering the Editor's command catalog. Follow it first; don't re-derive any of
it here.
unity-clicom.unity.pipelineTwo things it can't know for you:
-
You needin particular, not just a reachable Editor. Confirm it appears in the catalog. Its presence depends on the Pipeline package version, not on the CLI, so a healthy install can still lack it — if it's missing, say so and stop.
eval -
On an Editor older than 6000.3, expect the Pipeline package not to work at all, and read the symptom correctly rather than retrying.uses
com.unity.pipelineandIPreprocessBuildWithContext, which Unity introduced in 6000.3; the package's own manifest declaresBuildCallbackContext, so it installs happily and then fails to compile. Measured: present in 6000.3 / 6000.4 / 6000.5, absent in 6000.0 / 6000.1 / 6000.2 and in the 2022 and 2023 lines. The symptom is misleading — the server never starts,"unity": "6000.0"shows no row and no error, and the real cause isunity statuson those two types in the Editor log. If you see that, tell the user the Editor is too old for the Pipeline package rather than debugging the CLI.CS0246This matters here more than in most skills: someone migrating a project off the Built-in pipeline is, by definition, often on an older Editor. -
A render-pipeline migration is not safely authorable blind. Assigning a URP asset, converting materials, and rebaking lighting all need a live Editor. An unreachable Editor is a stop, not a cue to hand-edit.
ProjectSettings/GraphicsSettings.asset
Run C# with . defaults to a 30 second
timeout, which matters here: installing URP triggers a package refresh and domain reload that will
outlast it. Treat that as a phase boundary rather than raising the timeout.
unity command eval --code '<snippet>'unity command此技能中的每个 C# 步骤都通过 Unity CLI 在实时 Editor 中运行。 skill 负责建立执行环境,包括安装 CLI、确认已连接的 Editor、添加项目的 包、区分真正缺失的 Editor 与卡在 Safe Mode 的 Editor,以及发现 Editor 的命令目录。应先遵循该 skill,不要在这里重新推导这些内容。
unity-clicom.unity.pipeline它无法替你确定的两件事:
-
你确实需要,而不只是连接到 Editor。确认命令目录中包含它。它是否存在取决于 Pipeline 包的版本,而不是 CLI;因此,即使 CLI 安装正常,也可能缺少
eval。如果缺少,应说明这一点并停止。eval -
对于早于 6000.3 的 Editor,应预期 Pipeline 包完全无法工作,并正确识别症状,而不是反复重试。使用
com.unity.pipeline和IPreprocessBuildWithContext,而 Unity 在 6000.3 中才引入这两个类型;该包自身的 Manifest 声明BuildCallbackContext,因此它可以成功安装,随后却编译失败。实测结果:6000.3、6000.4、6000.5 中存在;6000.0、6000.1、6000.2 以及 2022 和 2023 系列中不存在。该症状具有误导性——服务器不会启动,"unity": "6000.0"不显示任何行且没有错误,真正原因会出现在 Editor 日志中的unity status。如果看到此情况,应告知用户 Editor 对 Pipeline 包而言过旧,而不是排查 CLI。CS0246 -
渲染管线迁移无法在看不到项目的情况下安全编写。 指定 URP Asset、转换材质和重新烘焙光照都需要实时 Editor。Editor 无法连接时应停止,而不是直接手工编辑。
ProjectSettings/GraphicsSettings.asset
使用 运行 C#。 默认超时时间为 30 秒,这一点很重要:安装 URP 会触发包刷新和域重载,其耗时将超过该限制。将其视为阶段边界,而不是简单提高超时时间。
unity command eval --code '<snippet>'unity commandPassing C# to eval
eval向 eval
传递 C#
evaleval- No directives. The compiler reads
usingas a resource-disposal statement and rejects it (using UnityEngine;).CS0210 - Types must be fully qualified. A bare or
GraphicsSettingsdoes not resolve (Volume/CS0246), and a bareCS0103is ambiguous withObject(object).CS0104 - Extension methods are unavailable, because they resolve through . Two that this skill would otherwise reach for:
usingbecomescamera.GetUniversalAdditionalCameraData(), and LINQ calls must be written statically —camera.GetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>()rather thanSystem.Linq.Enumerable.FirstOrDefault(sequence, predicate).sequence.FirstOrDefault(predicate)
eval- 不能使用 指令。 编译器会将
using解释为资源释放语句,并拒绝它(using UnityEngine;)。CS0210 - 类型必须使用完全限定名称。 裸写的 或
GraphicsSettings无法解析(Volume或CS0246),而裸写的CS0103会与Object产生歧义(object)。CS0104 - 扩展方法不可用,因为它们依赖 解析。此技能原本会使用的两个扩展方法是:
using改为camera.GetUniversalAdditionalCameraData();LINQ 调用必须静态编写,例如camera.GetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>(),而不是System.Linq.Enumerable.FirstOrDefault(sequence, predicate)。sequence.FirstOrDefault(predicate)
Two execution modes — pick by the snippet's shape
两种执行模式——根据代码片段形态选择
The references carry both shapes, and they are not interchangeable:
- Statement-shaped (a bare sequence of statements, like the detection snippets above) — pass
straight to , fully qualified, with no
evallines.using - Class- or method-shaped (anything declaring a , a
classmethod, or astatic, such as the material-snapshot pattern) — these are project files, not[MenuItem]input. A class declaration cannot be flattened into a statement block. Save the snippet undereval, let Unity compile it, then invoke its entry point through a one-lineAssets/Editor/call. Keep theevaldirectives in that file; they are correct there.using
For a multi-step migration the script route is the more reliable one anyway: it survives the domain
reloads that URP installation and material conversion trigger, whereas a long payload does
not.
eval参考资料包含两种形态,它们不可互换:
- 语句形态:连续的普通语句,例如上面的检测代码片段。直接传给 ,使用完全限定名称,不包含任何
eval行。using - 类或方法形态:任何声明 、
class方法或static的代码,例如材质快照模式。这些是项目文件,不能作为[MenuItem]输入。类声明无法展平为语句块。应将代码保存到eval,让 Unity 编译,然后通过一行Assets/Editor/调用其入口点。该文件中保留eval指令是正确的。using
对于多步骤迁移,脚本方式通常也更可靠,因为它能够承受 URP 安装和材质转换触发的域重载,而较长的 载荷无法承受。
evalDetecting the active render pipeline
检测当前渲染管线
csharp
var rp = UnityEngine.Rendering.GraphicsSettings.defaultRenderPipeline;
var qrp = UnityEngine.QualitySettings.renderPipeline;
return $"graphics={(rp == null ? "NULL (Built-in)" : rp.GetType().Name + ":" + rp.name)}, "
+ $"activeQualityLevel={(qrp == null ? "inherits Graphics" : qrp.GetType().Name + ":" + qrp.name)}";A means URP; means HDRP; on both
means Built-in. Check the per-quality-level assignment too — a project can be switched in
Graphics settings while a Quality level still points at a different asset, or at none:
UniversalRenderPipelineAssetHDRenderPipelineAssetNULLcsharp
var names = UnityEngine.QualitySettings.names;
var rows = new System.Collections.Generic.List<string>();
for (int i = 0; i < names.Length; i++)
{
var a = UnityEngine.QualitySettings.GetRenderPipelineAssetAt(i);
rows.Add($"{i}:{names[i]}={(a == null ? "inherits Graphics" : a.name)}");
}
return string.Join(", ", rows);If is unavailable in the project's Unity version, read
instead rather than switching levels at runtime —
mutates project state.
GetRenderPipelineAssetAtProjectSettings/QualitySettings.assetSetQualityLevelcsharp
var rp = UnityEngine.Rendering.GraphicsSettings.defaultRenderPipeline;
var qrp = UnityEngine.QualitySettings.renderPipeline;
return $"graphics={(rp == null ? "NULL (Built-in)" : rp.GetType().Name + ":" + rp.name)}, "
+ $"activeQualityLevel={(qrp == null ? "inherits Graphics" : qrp.GetType().Name + ":" + qrp.name)}";UniversalRenderPipelineAssetHDRenderPipelineAssetNULLcsharp
var names = UnityEngine.QualitySettings.names;
var rows = new System.Collections.Generic.List<string>();
for (int i = 0; i < names.Length; i++)
{
var a = UnityEngine.QualitySettings.GetRenderPipelineAssetAt(i);
rows.Add($"{i}:{names[i]}={(a == null ? "inherits Graphics" : a.name)}");
}
return string.Join(", ", rows);如果项目使用的 Unity 版本不支持 ,应改为读取 ,而不是在运行时切换 Quality 级别,因为 会修改项目状态。
GetRenderPipelineAssetAtProjectSettings/QualitySettings.assetSetQualityLevel0. Pre-Flight: Pipeline Detection and Reference Loading
0. 预检:管线检测与参考加载
Before doing anything else, you must determine the active render pipeline and migration mode:
- Detect Pipeline: Run the render-pipeline detection snippet from the execution-path section above.
- If or
currentRenderPipelinereferences adefaultRenderPipelineAsset-> URP.UniversalRenderPipelineAsset - If no render pipeline asset is assigned -> Built-in.
- If it references an -> HDRP. Explain that this skill only covers Built-in to URP migration. Basic comparison advice is fine, but do not drive an HDRP migration with this skill.
HDRenderPipelineAsset
- If
- Load Base Reference: Read references/migration-workflow.md.
- Load Shader References When Relevant: If the request mentions materials, shaders, magenta materials, rendering errors, image effects, or custom rendering, also read:
- references/custom-shader-triage.md
- references/complex-shader-situations.md when inspection or project-file search finds advanced shader/effect patterns
- Load Quality Reference When Relevant: If the request mentions shadows, lighting, baked lighting, lightmaps, reflection probes, quality settings, visual mismatch, or performance after migration, also read references/quality-settings-map.md.
- Load Implementation Patterns When Executing: If the request permits actual migration changes, post-processing conversion, baked-lighting/probe repair, or resume from a partial migration, also read references/implementation-patterns.md.
- Classify the Request as one of:
- Full-project Built-in to URP migration
- Built-in 2D to URP 2D migration
- Selected material-only conversion
- Planning / explanation only
- Troubleshooting after a previous migration
- If the project is already on URP, switch to troubleshooting mode instead of re-running setup blindly.
- Proceed only after the pipeline and migration path are clear.
开始任何操作之前,必须先确定当前渲染管线和迁移模式:
- 检测管线: 运行执行路径章节中的渲染管线检测代码片段。
- 如果 或
currentRenderPipeline引用defaultRenderPipelineAsset,则使用 URP。UniversalRenderPipelineAsset - 如果没有指定 Render Pipeline Asset,则使用 Built-in。
- 如果引用 ,则使用 HDRP。说明此技能仅涵盖 Built-in 到 URP 的迁移。可以提供基本对比建议,但不要使用此技能驱动 HDRP 迁移。
HDRenderPipelineAsset
- 如果
- 加载基础参考: 阅读 references/migration-workflow.md。
- 相关时加载 Shader 参考: 如果请求涉及材质、Shader、洋红色材质、渲染错误、图像效果或自定义渲染,还应阅读:
- references/custom-shader-triage.md
- 检查或项目文件搜索发现高级 Shader 或特效模式时,阅读 references/complex-shader-situations.md
- 相关时加载 Quality 参考: 如果请求涉及阴影、光照、烘焙光照、Lightmap、Reflection Probe、Quality 设置、视觉差异或迁移后的性能问题,还应阅读 references/quality-settings-map.md。
- 执行时加载实现模式: 如果用户允许实际迁移更改、后处理转换、烘焙光照或探针修复,或者需要继续部分完成的迁移,还应阅读 references/implementation-patterns.md。
- 将请求分类为以下一种:
- 完整的 Built-in 到 URP 项目迁移
- Built-in 2D 到 URP 2D 迁移
- 仅转换选定材质
- 仅制定计划或解释
- 迁移后的故障排查
- 如果项目已经使用 URP, 应切换到故障排查模式,而不是盲目重新运行设置流程。
- 只有在管线和迁移路径明确后才继续。
1. Assess Current Migration State
1. 评估当前迁移状态
Before making any changes, inspect what already exists:
- Inspect pipeline state and assignment points:
- Run both render-pipeline detection snippets from the execution-path section above — the Graphics-settings one and the per-quality-level one.
- If the project has Quality levels, inspect which Render Pipeline Asset each level uses before assuming the project is fully switched.
- Inventory migration surfaces: Use with
evalor equivalent asset queries to inventory:UnityEditor.AssetDatabase.FindAssets- materials, including particle/VFX materials that often use built-in particle shaders
- vegetation materials, including grass, tree, terrain-detail, SpeedTree, billboard, leaf-card, cutout, and wind-driven foliage materials
- shaders
- scenes and important prefabs
- URP assets and renderer assets, if any
- post-processing profiles / volume profiles
- Lighting Settings assets, Lighting Data assets, lightmaps, light probes, reflection probes, and mixed/baked lights
- Scan for rendering risk markers: Use available project-file search, , or a short
AssetDatabase.FindAssetsfile scan to search the project for rendering-specific patterns such as:eval- ,
PostProcessLayer,PostProcessVolumeUnityEngine.Rendering.PostProcessing - ,
OnRenderImage(,RenderWithShaderSetReplacementShader - ,
#pragma surface,GrabPassCGPROGRAM - , custom shader include paths, or package shader namespaces
CommandBuffer - vegetation markers such as ,
Nature/,SpeedTree,TreeCreator,Grass,Foliage,_Cutoff,_AlphaClip, billboard, or wind keywords_Cull
- If PPv2 is installed but grep finds nothing, inspect open scenes and profile assets through Unity APIs by component/type. Scene YAML and serialized package references can be missed by text search.
- Determine project shape: Decide whether the project is primarily 3D, primarily 2D, or mixed.
- Report Findings: Summarize the current state before proposing conversion. Example:
- "The project is still on Built-in, has no URP asset assigned, contains PPv2 references, and includes several custom shaders using surface-shader syntax."
进行任何更改之前,检查已经存在的内容:
- 检查管线状态和分配位置: 运行执行路径章节中的 Graphics 设置检测代码片段和逐 Quality 级别检测代码片段。
- 如果项目存在 Quality 级别,应先检查每个级别使用的 Render Pipeline Asset,再假定项目已完整切换。
- 盘点迁移影响范围: 使用 配合
eval或等效资产查询来盘点:UnityEditor.AssetDatabase.FindAssets- 材质,包括经常使用 Built-in Particle Shader 的粒子或 VFX 材质
- 植被材质,包括草地、树木、地形细节、SpeedTree、Billboard、Leaf Card、Cutout 和风驱动植被材质
- Shader
- 场景和重要 Prefab
- 已存在的 URP Asset 和 Renderer Asset
- 后处理 Profile 或 Volume Profile
- Lighting Settings Asset、Lighting Data Asset、Lightmap、Light Probe、Reflection Probe,以及 Mixed 或 Baked Light
- 扫描渲染风险标记: 使用可用的项目文件搜索、或简短的
AssetDatabase.FindAssets文件扫描,在项目中查找以下渲染相关模式:eval- 、
PostProcessLayer、PostProcessVolumeUnityEngine.Rendering.PostProcessing - 、
OnRenderImage(、RenderWithShaderSetReplacementShader - 、
#pragma surface、GrabPassCGPROGRAM - 、自定义 Shader Include 路径或包 Shader 命名空间
CommandBuffer - 、
Nature/、SpeedTree、TreeCreator、Grass、Foliage、_Cutoff、_AlphaClip、Billboard 或风相关关键字等植被标记_Cull
- 如果已安装 PPv2 但 grep 没有找到任何内容, 应通过 Unity API 按组件或类型检查打开的场景和 Profile Asset。文本搜索可能遗漏 Scene YAML 和序列化的包引用。
- 确定项目形态: 判断项目主要属于 3D、主要属于 2D,还是混合类型。
- 报告发现: 在提出转换建议前总结当前状态。例如:“项目仍使用 Built-in,没有指定 URP Asset,包含 PPv2 引用,并使用了多个采用 Surface Shader 语法的自定义 Shader。”
2. Gather Requirements
2. 收集需求
Determine what the user actually wants. If the request is ambiguous, ask.
Use these defaults for common requests:
| User says | Default interpretation |
|---|---|
| "Upgrade this project to URP" | Full-project migration |
| "Move this 2D project to URP" | Built-in 2D to URP 2D migration |
| "Convert these materials" | Targeted material conversion |
| "My materials turned pink" | Post-migration shader/material troubleshooting |
| "Lighting looks wrong after URP" | Quality and visual parity troubleshooting |
| "Do not change anything yet" | Planning / audit only |
确定用户实际需要什么。如果请求存在歧义,应进行询问。
常见请求使用以下默认解释:
| 用户说 | 默认解释 |
|---|---|
| “将此项目升级到 URP” | 完整项目迁移 |
| “将这个 2D 项目迁移到 URP” | Built-in 2D 到 URP 2D 迁移 |
| “转换这些材质” | 定向材质转换 |
| “我的材质变成粉红色了” | 迁移后的 Shader 或材质故障排查 |
| “迁移到 URP 后光照看起来不对” | Quality 和视觉一致性故障排查 |
| “暂时不要做任何更改” | 仅制定计划或审计 |
Information to Gather
需要收集的信息
- Scope: full project, selected materials, or troubleshooting only
- Target renderer: standard URP or URP 2D
- Validation targets: which scenes, prefabs, or cameras matter most to the user
- Risk tolerance: whether limited manual follow-up is acceptable
- Rendering dependencies: custom shaders, Asset Store shaders, PPv2, baked lighting/lightmaps/probes, image effects, command buffers, replacement shaders, or multiple Quality levels
- Execution permission: planning only vs actual project changes
- 范围: 完整项目、选定材质,或仅进行故障排查。
- 目标 Renderer: 标准 URP 或 URP 2D。
- 验证目标: 用户最看重的场景、Prefab 或相机。
- 风险容忍度: 是否可以接受有限的手动跟进工作。
- 渲染依赖项: 自定义 Shader、Asset Store Shader、PPv2、烘焙光照或 Lightmap、探针、图像效果、Command Buffer、替换 Shader,或多个 Quality 级别。
- 执行权限: 仅制定计划,还是实际修改项目。
3. Safety Gate
3. 安全关卡
Before any pipeline-mutating step:
- Confirm rollback safety.
- NEVER install URP, assign a URP asset, run the Render Pipeline Converter, edit materials, or edit migration scene state before the user confirms a backup, branch, archive, disposable copy, or rollback point.
- If rollback safety is missing, do not partially switch the project to URP. Stop in planning mode and ask for the rollback confirmation first.
- Separate engine-upgrade risk from pipeline-upgrade risk.
- If the project is also moving to a new Unity version, recommend doing the engine upgrade first and the pipeline migration second. Do not treat both as a single blind operation.
- If rollback safety is confirmed, treat it as covering the whole migration pass. Do not ask again before each converter; proceed through setup, material conversion, PPv2 migration, lighting/probe work, save/reload verification, and final reporting unless a new risky decision appears.
- If the user already authorized a full disposable migration, do not ask for permission to continue after routine setup or recoverable errors. Continue with the next incomplete migration phase. Ask only when a new destructive cleanup decision appears, a package/domain reload stops execution, or repeated repair attempts hit the validation iteration limit.
- If the project is already partially migrated, identify whether rollback safety was previously confirmed. If yes, resume from the first incomplete item. If no, report the partial state and ask before making additional changes.
在任何会修改管线的步骤之前:
- 确认回滚安全。
- 在用户确认备份、分支、归档、一次性副本或回滚点之前,绝不能安装 URP、指定 URP Asset、运行 Render Pipeline Converter、编辑材质或编辑迁移场景状态。
- 如果缺少回滚安全性,不要将项目部分切换到 URP。应停在规划模式,并先请求用户确认回滚点。
- 区分引擎升级风险与管线升级风险。 如果项目同时要升级到新的 Unity 版本,建议先完成引擎升级,再执行管线迁移。不要把两者当作一次盲操作处理。
- 如果已经确认回滚安全, 应将其视为覆盖整个迁移过程。不要在每次运行转换器前再次询问;除非出现新的高风险决策,否则应继续完成设置、材质转换、PPv2 迁移、光照或探针工作、保存与重新加载验证以及最终报告。
- 如果用户已经授权对一次性项目执行完整迁移, 不要在常规设置或可恢复错误之后请求继续许可。应继续处理下一个未完成的迁移阶段。只有当出现新的破坏性清理决策、遇到包安装或域重载导致执行停止,或者重复修复达到验证迭代上限时,才需要询问。
- 如果项目已经部分迁移, 应确定之前是否已确认回滚安全。如果已确认,则从第一个未完成项继续。如果未确认,则报告部分状态,并在进一步更改前请求确认。
4. Choose the Migration Path
4. 选择迁移路径
Use the correct path for the project:
根据项目选择正确路径:
Path A: Standard 3D Built-in to URP
Path A:标准 3D Built-in 到 URP
- Use this for normal 3D Built-in projects moving to standard URP.
- 用于从标准 3D Built-in 项目迁移到标准 URP 的情况。
Path B: Built-in 2D to URP 2D
Path B:Built-in 2D 到 URP 2D
- Use this when the project is primarily 2D and the user expects URP 2D lighting or renderer behavior.
- Do not treat this as the same workflow as standard URP.
- 用于项目主要为 2D,且用户期望使用 URP 2D 光照或 Renderer 行为的情况。
- 不要将其视为与标准 URP 相同的工作流。
Path C: Targeted Material-Only Conversion
Path C:仅转换选定材质
- Use this only when the project is already on URP and the user wants selected materials converted.
- 仅当项目已经使用 URP,而用户希望转换选定材质时使用。
Path D: Troubleshooting an Existing Migration
Path D:排查现有迁移问题
- Use this when the project is already on URP or the migration has already been attempted.
- Prioritize the highest-impact breakages instead of re-running the entire migration blindly.
- 当项目已经使用 URP,或迁移已尝试执行时使用。
- 优先修复影响最大的问题,而不是盲目重新运行整个迁移。
5. URP Setup Workflow
5. URP 设置工作流
Follow this exact setup order:
- Ensure URP is installed.
- Installing URP can trigger package refresh, compilation, and domain reload. Treat this as a phase boundary.
- Do not spin-wait indefinitely inside an call on
eval. Request installation, then verify throughUnityEditor.PackageManager.Client.Add, package listing, or the presence of URP types/assets after Unity finishes refreshing.Packages/manifest.json - If the package install causes the call to time out or return nothing, resume in a fresh turn after Unity finishes compiling. Do not restart the whole migration or reinstall URP; inspect the partial state and continue from there.
eval
- Create the required URP asset and renderer asset if they do not already exist.
- Assign the URP asset in Graphics settings and in all relevant Quality levels.
- For 2D projects, create and assign the correct 2D Renderer asset before conversion.
- If a URP asset already exists, inspect and reuse it when appropriate instead of creating duplicates automatically.
- Do not continue until URP is actually the active render pipeline for the target configuration.
严格遵循以下设置顺序:
- 确保已安装 URP。
- 安装 URP 可能触发包刷新、编译和域重载。将其视为阶段边界。
- 不要在 的
UnityEditor.PackageManager.Client.Add调用中无限等待。应发起安装请求,然后在 Unity 完成刷新后通过eval、包列表或 URP 类型及资产的存在情况进行验证。Packages/manifest.json - 如果包安装导致 调用超时或没有返回内容,应在 Unity 完成编译后的新一轮中继续。不要重启整个迁移或重新安装 URP;应检查部分状态并继续。
eval
- 如果所需的 URP Asset 和 Renderer Asset 尚不存在,则创建它们。
- 在 Graphics 设置和所有相关 Quality 级别中指定 URP Asset。
- 对于 2D 项目, 应先创建并指定正确的 2D Renderer Asset,然后再进行转换。
- 如果已经存在 URP Asset, 应在适当情况下检查并复用,而不是自动创建重复 Asset。
- 在 URP 真正成为目标配置的有效渲染管线之前,不要继续。
6. Conversion Workflow
6. 转换工作流
For actual conversion work, follow references/migration-workflow.md.
-
Choose the correct Render Pipeline Converter path:
Built-in Render Pipeline to URPBuilt-in Render Pipeline 2D to URP 2D
-
Initialize converters and inspect the candidate changes before converting.
-
For standard Built-in to URP migration, prefer the applicable converters described in the reference:
Rendering SettingsMaterial UpgradeAnimation Clip ConverterRead-only Material ConverterPost-processing Stack v2 Converter
-
For selected-material conversion, use the targeted material conversion workflow instead of converting the whole project.
-
Review warnings and failures before converting.
-
Run the conversion only after the user confirms the project is safe to change.
-
Verify which shader each material actually landed on — do not assume the converter chose the 3D target.returns the 2D provider set alongside the 3D one, and both claim
MaterialUpgrader.FetchAllUpgradersForPipelineat equal priority, so on a 3D project a plainStandardmaterial can silently convert toStandardinstead ofUniversal Render Pipeline/2D/Mesh2D-Lit-Default. Nothing errors and the material does not go magenta, so this is invisible unless you read the shader name back — measured on 6000.5.8f1.Universal Render Pipeline/LitRead every converted material'safterwards and confirm it matches the intended target from the mapping table. If any landed on ashader.nameshader in a 3D project, restore those materials from the rollback point and convert them with a 3D-filtered upgrader list, or with the manual pattern in references/implementation-patterns.md.2D/ -
After conversion, verify the saved project state.
- Re-open or re-query representative assets instead of trusting command output alone.
- Save both assets and open scenes after scene-level edits. Changes to scene components, camera data, active lighting settings, reflection probes, and PPv2 enable states are not proven by alone.
AssetDatabase.SaveAssets() - Confirm the URP asset is assigned in Graphics and intended Quality levels.
- For Quality levels, validate by re-querying or by reading the saved
QualitySettings.GetRenderPipelineAssetAt(i)entries incustomRenderPipeline. If they remainProjectSettings/QualitySettings.asset, the Quality levels are not explicitly assigned.{fileID: 0} - Do not call a guessed quality API such as ; in Unity versions where that API is unavailable, switch to each target level with
QualitySettings.SetRenderPipelineAssetAt, setQualitySettings.SetQualityLevel(index), then restore the original level and verify the savedQualitySettings.renderPipeline = urpAssetvalues.customRenderPipeline - Confirm converted materials actually reference URP shaders.
- Confirm representative materials that had source albedo textures now have non-null values. This check must compare against a pre-conversion material snapshot; do not use post-conversion
_BaseMapas the source of truth._MainTex - Confirm particle/VFX materials no longer reference Built-in particle shader IDs or legacy shader names; use URP particle shaders such as where appropriate. If material names or paths include
Universal Render Pipeline/Particles/Unlit,Particle,Fog,Smoke,Steam,VFX, or similar effect terms, preserve transparent/additive behavior rather than defaulting them to URP Lit.Additive - Confirm vegetation materials preserve cutout/alpha clipping, render face intent, textures, tint, normals, and expected wind/billboard behavior. If grass/tree cards become solid or static because their specialized shader behavior was lost, material conversion is partial.
- If PPv2 conversion was attempted, confirm saved URP Volume profiles contain persistent non-null entries and the scene/camera wiring uses URP-compatible components.
components - If baked lighting exists, preserve the old Lighting Data and lightmaps as reference data, then verify whether they still produce acceptable URP visuals. If a new Lighting Settings asset is created, verify the saved scene actually references it after saving/reloading; the asset existing on disk is not enough. In an actual generic migration, attempt rebaking/refreshing when stale baked data or reflection probes affect parity; if that cannot finish in the current turn, report the migration as partial and resume from the lighting/probe phase later.
- Do not claim "refreshed reflection probes" from intent. Verify new or updated probe outputs, changed saved reflection-probe assets, or successful probe-render tool output. If the existing EXR files remain unchanged, say probes were preserved as reference or still need refresh.
- If any verification fails, report the item as incomplete/manual follow-up, not as migrated.
对于实际转换工作,请遵循 references/migration-workflow.md。
-
选择正确的 Render Pipeline Converter 路径:
Built-in Render Pipeline to URPBuilt-in Render Pipeline 2D to URP 2D
-
初始化转换器,并在转换前检查候选更改。
-
对于标准 Built-in 到 URP 迁移, 优先使用参考资料中适用的转换器:
Rendering SettingsMaterial UpgradeAnimation Clip ConverterRead-only Material ConverterPost-processing Stack v2 Converter
-
对于选定材质转换, 使用定向材质转换工作流,而不是转换整个项目。
-
转换前检查警告和失败项。
-
仅在用户确认项目可安全更改后运行转换。
-
验证每个材质实际落入的 Shader——不要假定转换器选择了 3D 目标。会同时返回 2D 和 3D Provider 集合,而两者都以相同优先级声明支持
MaterialUpgrader.FetchAllUpgradersForPipeline,因此在 3D 项目中,普通Standard材质可能悄悄转换为Standard,而不是Universal Render Pipeline/2D/Mesh2D-Lit-Default。不会产生任何错误,材质也不会变成洋红色;除非读取 Shader 名称,否则问题不可见——该情况已在 6000.5.8f1 上实测。Universal Render Pipeline/Lit转换后读取每个已转换材质的,确认其与映射表中的预期目标一致。如果 3D 项目中的任何材质落入shader.nameShader,应从回滚点恢复这些材质,然后使用经过 3D 筛选的 Upgrader 列表进行转换,或采用 references/implementation-patterns.md 中的手动模式。2D/ -
转换后,验证已保存的项目状态。
- 重新打开或重新查询代表性资产,而不是只依赖命令输出。
- 在完成场景级编辑后,保存资产和已打开的场景。本身无法证明场景组件、相机数据、活动光照设置、Reflection Probe 和 PPv2 启用状态等更改已经保存。
AssetDatabase.SaveAssets() - 确认 Graphics 设置和预期 Quality 级别均已指定 URP Asset。
- 对于 Quality 级别,使用 重新验证,或读取
QualitySettings.GetRenderPipelineAssetAt(i)中已保存的ProjectSettings/QualitySettings.asset条目。如果它们仍为customRenderPipeline,说明 Quality 级别没有显式指定 URP Asset。{fileID: 0} - 不要调用凭猜测的 Quality API,例如 ;在不支持该 API 的 Unity 版本中,应切换到每个目标级别,调用
QualitySettings.SetRenderPipelineAssetAt,设置QualitySettings.SetQualityLevel(index),然后恢复原始级别并验证已保存的QualitySettings.renderPipeline = urpAsset值。customRenderPipeline - 确认已转换材质确实引用 URP Shader。
- 确认源反照率贴图非空的代表性材质,现在具有非空 值。此检查必须与转换前的材质快照进行比较;不要将转换后的
_BaseMap作为源数据的依据。_MainTex - 确认粒子或 VFX 材质不再引用 Built-in Particle Shader ID 或旧版 Shader 名称;适用时应使用 等 URP Particle Shader。如果材质名称或路径包含
Universal Render Pipeline/Particles/Unlit、Particle、Fog、Smoke、Steam、VFX或类似特效术语,应保留透明或加法混合行为,而不是默认使用 URP Lit。Additive - 确认植被材质保留 Cutout 或 Alpha Clip、Render Face 意图、纹理、色调、法线以及预期的风或 Billboard 行为。如果草地或树木卡片变为实体或静态状态,说明其专用 Shader 行为丢失,材质转换仅为 partial。
- 如果尝试转换 PPv2,确认已保存的 URP 包含持久化且非空的
VolumeProfile条目,并且场景或相机的连接使用 URP 兼容组件。components - 如果存在烘焙光照,保留旧 Lighting Data 和 Lightmap 作为参考数据,然后验证它们是否仍能提供可接受的 URP 视觉效果。如果创建了新的 Lighting Settings Asset,应验证保存并重新加载后的场景确实引用了它;仅确认磁盘上存在 Asset 并不足够。在实际通用迁移中,如果过期烘焙数据或 Reflection Probe 影响视觉一致性,应尝试重新烘焙或刷新;如果当前轮次无法完成,则报告迁移为 partial,并在之后从光照或探针阶段继续。
- 不要仅凭意图声称“已刷新 Reflection Probe”。应验证新的或更新后的 Probe 输出、已保存的 Reflection Probe Asset 发生变化,或者 Probe 渲染工具成功输出。如果现有 EXR 文件保持不变,应说明 Probe 仅作为参考保留,或仍需刷新。
- 如果任何验证失败,应将该项报告为未完成或需要手动跟进,而不是报告为已迁移。
7. Shader and Material Triage
7. Shader 与材质分诊
When materials are magenta, shaders fail to compile, or visuals drift heavily, use references/custom-shader-triage.md first.
- Identify affected materials and shaders.
- Inspect the exact material shader assignments, not just scene symptoms.
- Read Console and Inspector errors before editing shader code.
- Classify the shader case:
- supported Built-in shaders that the converter should handle
- simple custom shaders that might be ported safely
- complex custom shaders that need a scoped migration plan
- foliage/vegetation shaders that require cutout, two-sided leaves, billboards, terrain detail rendering, or wind behavior
- package-owned or Asset Store shaders that may require maintainer documentation, scoped custom porting, or manual follow-up
- For complex shader situations, use references/complex-shader-situations.md.
- Prefer the smallest safe fix.
- Restore rendering on representative materials first.
- Validate the result before scaling the fix to more assets.
- Never bulk search-and-replace shader code across the whole project unless the mapping is explicit, tested, and scoped.
当材质呈洋红色、Shader 编译失败或视觉严重偏移时,首先使用 references/custom-shader-triage.md。
- 确定受影响的材质和 Shader。 检查确切的材质 Shader 分配,而不只是场景症状。
- 编辑 Shader 代码前,先阅读 Console 和 Inspector 错误。
- 对 Shader 情况分类:
- 转换器应处理的受支持 Built-in Shader
- 可以安全移植的简单自定义 Shader
- 需要有范围迁移计划的复杂自定义 Shader
- 需要 Cutout、双面叶片、Billboard、地形细节渲染或风行为的植被 Shader
- 需要维护者文档、有范围的自定义移植或手动跟进的包所有或 Asset Store Shader
- 对于复杂 Shader 情况, 使用 references/complex-shader-situations.md。
- 优先采用最小且安全的修复。 先恢复代表性材质的渲染,验证结果后再扩展到更多资产。
- 除非映射关系明确、经过测试且范围受限,否则绝不要在整个项目中批量搜索并替换 Shader 代码。
8. Post-Processing, Cameras, and Rendering-Effect Triage
8. 后处理、相机与渲染效果分诊
Built-in projects often rely on more than material conversion.
- If PPv2 is present, inspect the converter output and validate the resulting URP volumes, profiles, and camera behavior.
- Inventory existing ,
PostProcessVolume, and PPv2PostProcessLayerassets before conversion.PostProcessProfile - Prefer the URP when available instead of hand-building equivalent profiles from memory.
Post-processing Stack v2 Converter - After conversion, verify that saved URP assets contain persistent override components, not an empty
VolumeProfileprofile or danglingcomponents: []component references.{fileID: 0} - If creating a profile by script, only creates a component object; for persistent profile assets, also call
VolumeProfile.Add<T>(), mark the profile and component dirty, save assets, reload the asset, and count saved non-null components before reporting success. If the saved profile hasAssetDatabase.AddObjectToAsset(component, profile)component entries, recreate or repair the profile before claiming migration success.{fileID: 0} - Verify representative scenes contain the intended objects and that target cameras have
Volumewith post-processing enabled when required.UniversalAdditionalCameraData - If the source scene still only serializes a PPv2 reference and no URP
sharedProfilereferences the newVolume, PPv2 migration is incomplete even if a URP profile asset exists on disk.VolumeProfile - If an active URP references an empty profile, treat that as incomplete scene wiring, not as active post-processing. Repair the profile or report PPv2 as partial.
Volume - Check whether old /
PostProcessVolumecomponents remain. If they remain, explain whether they are intentionally retained, harmless legacy leftovers, or unresolved migration work.PostProcessLayer - If old PPv2 components are retained only as reference while a URP Volume is active, disable the old PPv2 component/layer for URP visual validation to avoid double post-processing. Do not delete it until parity is accepted or the user approves cleanup.
- Do not remove PPv2 packages, components, or profiles as a cleanup step until a verified URP replacement exists or the user accepts that those effects will be dropped/manual follow-up.
- During an actual migration, do not leave common PPv2 parity as a vague manual task if the source profile is available. Create persistent URP overrides for common mappable effects such as Bloom, Color Adjustments/Tonemapping, Vignette, and Depth of Field, then verify the saved profile has non-null components.
- It is acceptable to mark unsupported or non-equivalent effects as manual follow-up, such as PPv2 Screen Space Reflections or Ambient Occlusion that should become a renderer feature / SSAO setup instead of a direct Volume override.
- If URP Volume overrides cannot be created reliably, document the PPv2 effects and their URP equivalents instead of claiming they were migrated.
- Inventory existing
- Do not treat transient tool success as post-processing success.
- A command log that says "Added Bloom" is not enough. Re-read the saved asset or inspect the scene after saving/reloading.
VolumeProfile - If the saved profile is empty, say the PPv2 setup was documented or partially prepared, not migrated.
- A command log that says "Added Bloom" is not enough. Re-read the saved
- If grep finds , treat it as a custom full-screen effect case.
OnRenderImage- In URP, custom full-screen effects should move toward , a Renderer Feature, or URP custom post-processing instead of staying on the Built-in image-effect path.
ScriptableRenderPass
- In URP, custom full-screen effects should move toward
- If grep finds or
RenderWithShader, treat it as a replacement-shader case.SetReplacementShader- These effects often need a deliberate URP renderer-feature or custom-pass strategy.
- If an effect depends on scene color, depth, or normals, verify the URP-compatible path rather than assuming the Built-in approach still applies.
- If custom cameras were stacking effects in Built-in, validate camera output explicitly after migration instead of assuming parity.
- For advanced shader/effect troubleshooting questions, provide concrete replacement patterns.
- For , mention
GrabPass/ Scene Color, the required URP asset setting, and the limitation that transparent ordering can differ from Built-in._CameraOpaqueTexture - For , mention
OnRenderImageplusScriptableRendererFeature. When showing a Unity 6-style template, use the reference pattern with a temporaryScriptableRenderPassandRTHandle.Blitter.BlitCameraTexture - Never recommend or other source-to-source blits as the main
Blitter.BlitCameraTexture(cmd, source, source, material, pass)replacement. If you are not going to show the safer temporary-target pattern, omit the code sample and explain the architecture instead.OnRenderImage - For Surface Shaders, state that has no direct URP equivalent and choose Shader Graph or a URP HLSL vertex/fragment rewrite based on effect complexity.
#pragma surface - Do not stop at "rewrite it"; give the user a practical first porting step and a validation target.
- For
Built-in 项目通常不仅依赖材质转换。
- 如果存在 PPv2, 检查转换器输出并验证生成的 URP Volume、Profile 和相机行为。
- 转换前盘点现有 、
PostProcessVolume和 PPv2PostProcessLayer资产。PostProcessProfile - 可用时优先使用 URP ,而不是凭记忆手工构建等效 Profile。
Post-processing Stack v2 Converter - 转换后,验证已保存的 URP 资产包含持久化 Override 组件,而不是空白的
VolumeProfileProfile 或悬空的components: []组件引用。{fileID: 0} - 如果通过脚本创建 Profile,只会创建组件对象;对于持久化 Profile 资产,还应调用
VolumeProfile.Add<T>(),标记 Profile 和组件为 Dirty,保存资产,重新加载资产,并在报告成功前统计已保存的非空组件。如果已保存 Profile 中存在AssetDatabase.AddObjectToAsset(component, profile)组件条目,应重新创建或修复 Profile,然后再声明迁移成功。{fileID: 0} - 验证代表性场景包含预期的 对象,并且目标相机在需要时具有启用后处理的
Volume。UniversalAdditionalCameraData - 如果源场景仍只序列化 PPv2 引用,且没有 URP
sharedProfile引用新的Volume,则即使磁盘上存在 URP Profile Asset,PPv2 迁移仍不完整。VolumeProfile - 如果活动 URP 引用空 Profile,应将其视为不完整的场景连接,而不是有效后处理。修复 Profile,或将 PPv2 报告为 partial。
Volume - 检查旧 或
PostProcessVolume组件是否仍然存在。如果仍存在,应解释它们是有意保留、无害的遗留项,还是未解决的迁移工作。PostProcessLayer - 如果旧 PPv2 组件仅作为参考保留,同时活动 URP Volume 已启用,应禁用旧 PPv2 组件或 Layer,以避免 URP 视觉验证时重复应用后处理。在视觉一致性得到接受或用户批准清理之前,不要删除它们。
- 在实际迁移中,不要将 PPv2 包、组件或 Profile 的移除作为清理步骤,除非已经验证存在 URP 替代方案,或者用户接受丢弃这些效果并将其作为手动跟进项。
- 实际迁移期间,如果源 Profile 可用,不要将常见 PPv2 视觉一致性工作留为含糊的手动任务。为 Bloom、Color Adjustments 或 Tonemapping、Vignette 和 Depth of Field 等常见且可映射的效果创建持久化 URP Override,然后验证已保存 Profile 包含非空组件。
- 可以将不受支持或不等效的效果标记为需要手动跟进,例如 PPv2 Screen Space Reflections 或 Ambient Occlusion;这些应转换为 Renderer Feature 或 SSAO 设置,而不是直接使用 Volume Override。
- 如果无法可靠创建 URP Volume Override,应记录 PPv2 效果及其 URP 等效项,而不是声称它们已经迁移。
- 转换前盘点现有
- 不要将临时工具成功视为后处理成功。 “Added Bloom”之类的命令日志并不充分。应重新读取已保存的 资产,或在保存并重新加载后检查场景。
VolumeProfile- 如果已保存 Profile 为空,应说明 PPv2 设置已记录或仅部分准备完成,而不是已迁移。
- 如果 grep 找到 , 将其视为自定义全屏效果情况。
OnRenderImage- 在 URP 中,自定义全屏效果应转向 、Renderer Feature 或 URP 自定义后处理,而不是继续使用 Built-in Image Effect 路径。
ScriptableRenderPass
- 在 URP 中,自定义全屏效果应转向
- 如果 grep 找到 或
RenderWithShader, 将其视为替换 Shader 情况。SetReplacementShader- 这些效果通常需要有意识地设计 URP Renderer Feature 或自定义 Pass 策略。
- 如果效果依赖 Scene Color、Depth 或 Normal, 应验证 URP 兼容路径,而不是假定 Built-in 方法仍然适用。
- 如果自定义相机在 Built-in 中叠加了多种效果, 迁移后应明确验证相机输出,而不是假定视觉一致性。
- 对于高级 Shader 或效果故障排查问题,应提供具体的替代模式。
- 对于 ,提及
GrabPass或 Scene Color、所需的 URP Asset 设置,以及透明排序可能与 Built-in 不同这一限制。_CameraOpaqueTexture - 对于 ,提及
OnRenderImage与ScriptableRendererFeature。展示 Unity 6 风格模板时,使用参考资料中的模式,配合临时ScriptableRenderPass和RTHandle。Blitter.BlitCameraTexture - 绝不能将 或其他 source 到 source 的 Blit 作为
Blitter.BlitCameraTexture(cmd, source, source, material, pass)的主要替代方案。如果不准备展示更安全的临时目标模式,则应省略代码示例并改为解释架构。OnRenderImage - 对于 Surface Shaders,说明 没有直接的 URP 等效项,并根据效果复杂度选择 Shader Graph 或 URP HLSL Vertex/Fragment 重写。
#pragma surface - 不要止步于“需要重写”;应向用户提供实用的首个移植步骤和验证目标。
- 对于
9. Quality, Lighting, and Visual Parity Review
9. Quality、光照与视觉一致性审查
Use references/quality-settings-map.md when the user mentions visual mismatch, shadows, performance, or quality settings.
- Review Graphics settings and each active Quality level.
- If a Quality level has no custom URP asset, state whether that level intentionally falls back to Graphics settings or still needs explicit assignment.
- Do not claim all quality levels are migrated unless each relevant level has been inspected.
- If using serialized project settings, the saved field is commonly ; writing a guessed field such as
customRenderPipelineis not enough unless the saved asset proves the assignment.renderPipelineAsset - If assigning through script, use the same pattern as URP's Render Settings converter: cache , call
QualitySettings.GetQualityLevel()for each target level, assignQualitySettings.SetQualityLevel(index), then restore the original quality level and verify on disk.QualitySettings.renderPipeline = urpAsset
- Check URP asset settings that commonly affect parity:
- shadows
- shadow distance and cascades
- MSAA
- render scale
- HDR, opaque texture, and depth texture settings when effects depend on them
- Do not promise identical lighting automatically.
- Built-in and URP can differ in light falloff, baked GI appearance, shadow tuning, reflection probe response, tonemapping, exposure, and post-processing behavior.
- For baked lighting scenes, treat existing lightmaps and Lighting Data as reference material, not guaranteed-final URP output.
- Inventory , scene
Lightmapping.lightingSettings, baked/mixed lights, light probes, reflection probes, and any existingLightmapSettings.LightingDataAsset - Preserve baked data until the user has a visual reference or rollback point, but do not keep stale Built-in lightmaps active as the final URP lighting solution if they blow out or distort the scene.
- If the scene looks blown out, too dark, or mismatched, first isolate post-processing/exposure by disabling legacy PPv2 during URP validation, then review URP Volume exposure/tonemapping/bloom before changing lights.
- If clearing baked data makes the scene stop being blown out, identify the old lightmaps/Lighting Data as stale or incompatible active data. Then rebake under URP with the final URP asset, renderer, Volume, and Quality settings instead of tuning lights against the stale bake.
- If creating or assigning URP-compatible , mark the lighting settings and active scene dirty, save the scene, reload or re-query, and verify the saved scene references the intended
LightingSettingsasset..lightingalone does not save the scene'sAssetDatabase.SaveAssets()reference. Do not report "Baked GI enabled" if the saved scene still points at an Enlighten/realtime-GI settings asset.Lightmapping.lightingSettings - When visual parity is part of the request and old / reflection-probe EXRs remain from the Built-in bake, treat them as reference data until rebaked/refreshed under URP. Do not claim visual parity is preserved from old bake data alone.
LightingData.asset - Recommend clearing/rebaking lighting and refreshing reflection probes when visual parity matters. Do not claim baked lighting was successfully migrated unless a representative scene has been visually checked after URP setup, and preferably after a URP bake.
- Inventory
- For 2D lighting projects, ensure sprites and tilemaps use URP-compatible lit materials where required.
- For performance regressions, inspect whether the issue is coming from:
- heavier URP asset settings
- post-processing
- extra shadow cost
- custom shader ports or non-batched shaders
- When changing URP asset settings, re-read the saved asset or query the property after saving before reporting values such as MSAA, additional-light limits, HDR, depth texture, or opaque texture.
当用户提到视觉差异、阴影、性能或 Quality 设置时,使用 references/quality-settings-map.md。
- 审查 Graphics 设置和每个活动 Quality 级别。
- 如果某个 Quality 级别没有自定义 URP Asset,应说明该级别是有意回退到 Graphics 设置,还是仍需显式指定。
- 除非已检查每个相关级别,否则不要声称所有 Quality 级别均已迁移。
- 如果使用序列化项目设置,常见保存字段为 ;仅写入凭猜测的
customRenderPipeline并不足够,除非已保存 Asset 能证明分配成功。renderPipelineAsset - 如果通过脚本分配,应采用与 URP Render Settings Converter 相同的模式:缓存 ,对每个目标级别调用
QualitySettings.GetQualityLevel(),指定QualitySettings.SetQualityLevel(index),然后恢复原始 Quality 级别并在磁盘上验证。QualitySettings.renderPipeline = urpAsset
- 检查影响视觉一致性的常见 URP Asset 设置:
- 阴影
- 阴影距离和级联
- MSAA
- Render Scale
- 当效果依赖这些设置时,检查 HDR、Opaque Texture 和 Depth Texture 设置
- 不要自动承诺完全相同的光照。 Built-in 与 URP 在光照衰减、烘焙 GI 表现、阴影调优、Reflection Probe 响应、Tonemapping、曝光和后处理行为方面可能存在差异。
- 对于烘焙光照场景, 将现有 Lightmap 和 Lighting Data 视为参考数据,而不是保证最终的 URP 输出。
- 盘点 、场景
Lightmapping.lightingSettings、Baked 或 Mixed Light、Light Probe、Reflection Probe,以及所有现有LightmapSettings。LightingDataAsset - 在拥有视觉参考或回滚点之前保留烘焙数据,但如果旧 Lightmap 导致 URP 场景过曝或失真,不要继续将过期 Built-in Lightmap 作为最终 URP 光照方案。
- 如果场景过曝、过暗或不匹配,应先禁用旧版 PPv2 以隔离后处理或曝光问题,再检查 URP Volume 的曝光、Tonemapping 和 Bloom,然后再更改灯光。
- 如果清除烘焙数据后场景不再过曝,应将旧 Lightmap 和 Lighting Data 识别为过期或不兼容的活动数据。随后应使用最终的 URP Asset、Renderer、Volume 和 Quality 设置在 URP 下重新烘焙,而不是针对过期烘焙数据调整灯光。
- 如果创建或指定 URP 兼容 ,应将 Lighting Settings 和活动场景标记为 Dirty,保存场景,重新加载或重新查询,并验证已保存场景引用了预期的
LightingSettingsAsset。仅调用.lighting不会保存场景中的AssetDatabase.SaveAssets()引用。如果已保存场景仍指向 Enlighten 或实时 GI Settings Asset,不要报告“已启用 Baked GI”。Lightmapping.lightingSettings - 当视觉一致性属于请求范围,且旧 或 Reflection Probe EXR 仍来自 Built-in 烘焙时,应将其作为参考数据保留,直到在 URP 下重新烘焙或刷新。不要仅凭旧烘焙数据声称视觉一致性已保留。
LightingData.asset - 当视觉一致性很重要时,建议清除并重新烘焙光照,并刷新 Reflection Probe。除非代表性场景在 URP 设置后,最好在 URP 烘焙后进行了视觉检查,否则不要声称烘焙光照已成功迁移。
- 盘点
- 对于 2D 光照项目, 确保 Sprite 和 Tilemap 在需要时使用 URP 兼容 Lit 材质。
- 对于性能回退, 检查问题是否来自:
- 更重的 URP Asset 设置
- 后处理
- 额外的 Shadow 成本
- 自定义 Shader 移植后失去批处理兼容性或引入额外 Pass
- 更改 URP Asset 设置后, 应重新读取已保存 Asset,或在保存后查询属性,然后再报告 MSAA、附加灯光限制、HDR、Depth Texture 或 Opaque Texture 等数值。
10. Validation
10. 验证
After setup, conversion, or troubleshooting, validate the result:
- Capture the scene: Capture the Scene View or a specific camera on a representative scene — see references/capturing-the-editor.md.
- Evaluate the result:
- no magenta materials unless unresolved custom shader blockers remain
- main lighting and shadows behave as expected
- baked GI/lightmaps, light probes, and reflection probes are acceptable or explicitly marked for rebake/refresh
- cameras render expected content
- post-processing or fullscreen effects still behave correctly
- sprites, tilemaps, or 2D lights work when relevant
- Verify persistent project data, not only visual output.
- Inspect saved URP assets, renderer assets, scene references, material shader GUIDs/names, Quality settings, and Volume profiles.
- Confirm the representative scene, not a default/test scene, was opened or otherwise inspected before concluding that baked lighting, PPv2, or reflection probes are absent.
- For material migration, include particle/VFX materials in the verification. Remaining built-in particle shader IDs or legacy particle shader names mean material migration is incomplete.
- For PPv2 migrations, saved URP assets must contain the expected override components before reporting them as migrated.
VolumeProfile - If a tool log reports mapped post-processing but the saved profile reloads with , override the tool log and report the migration as failed/incomplete.
components: [] - For baked-lighting scenes, inspect Lighting Settings, Lighting Data/lightmap references, light probes, and reflection probes. Compilation success does not prove baked lighting parity. If old lightmaps cause overexposure, clear active baked data and rebake under URP before judging parity. After assigning new lighting settings, verify the saved scene reference, not only the existence of the new asset.
.lighting - If old remains assigned and reflection-probe EXRs were not regenerated or explicitly accepted after visual inspection, classify lighting/probes as preserved or partial rather than refreshed.
LightingData.asset
- Check Console output with for shader, render pipeline, or renderer-feature errors.
Unity.GetConsoleLogs - Fix the highest-impact issue first, then validate again.
- Repeat for at most 3 iterations before reporting remaining blockers or asking the user how they want to proceed.
完成设置、转换或故障排查后,验证结果:
- 捕获场景: 捕获 Scene View 或代表性场景中的特定相机——参见 references/capturing-the-editor.md。
- 评估结果:
- 除尚未解决的自定义 Shader 阻塞项外,不应出现洋红色材质
- 主要光照和阴影行为符合预期
- 烘焙 GI 或 Lightmap、Light Probe 和 Reflection Probe 可接受,或者明确标记为需要重新烘焙或刷新
- 相机渲染出预期内容
- 后处理或全屏效果仍然正确工作
- 相关时,Sprite、Tilemap 或 2D Light 正常工作
- 验证持久化项目数据,而不只是视觉输出。 检查已保存的 URP Asset、Renderer Asset、场景引用、材质 Shader GUID 或名称、Quality 设置和 Volume Profile。
- 确认已检查代表性场景,而不是默认或测试场景,再得出不存在烘焙光照、PPv2 或 Reflection Probe 的结论。
- 对于材质迁移,验证中应包含粒子或 VFX 材质。如果仍存在 Built-in Particle Shader ID 或旧版 Particle Shader 名称,则材质迁移不完整。
- 对于 PPv2 迁移,在报告已迁移前,已保存的 URP 资产必须包含预期的 Override 组件。
VolumeProfile - 如果工具日志报告已映射后处理,但保存后的 Profile 重新加载时仍为 ,应以工具日志为准,并将迁移报告为失败或未完成。
components: [] - 对于烘焙光照场景,检查 Lighting Settings、Lighting Data 或 Lightmap 引用、Light Probe 和 Reflection Probe。编译成功不能证明烘焙光照的一致性。如果旧 Lightmap 导致过曝,应在判断视觉一致性之前清除活动烘焙数据并在 URP 下重新烘焙。指定新 Lighting Settings 后,应验证已保存的场景引用,而不只是确认存在新的 Asset。
.lighting - 如果旧 仍被指定,且 Reflection Probe EXR 未重新生成或未在视觉检查后明确接受,应将光照或探针归类为已保留或 partial,而不是已刷新。
LightingData.asset
- 使用 检查 Console 输出中的 Shader、渲染管线或 Renderer Feature 错误。
Unity.GetConsoleLogs - 优先修复影响最大的问题, 然后再次验证。
- 最多重复 3 次, 之后报告剩余阻塞项,或询问用户希望如何继续。
11. Troubleshooting Decision Tree
11. 故障排查决策树
If the user reports a migration problem, follow this diagnostic flow:
如果用户报告迁移问题,请遵循以下诊断流程:
Project still behaves like Built-in after "migration"
“迁移”后项目行为仍像 Built-in
- Check whether a URP asset is assigned in Graphics settings.
- Check whether the relevant Quality levels also point to a URP asset.
- Verify that the active render pipeline is actually URP before troubleshooting anything else.
- 检查 Graphics 设置中是否指定了 URP Asset。
- 检查相关 Quality 级别是否也指向 URP Asset。
- 在排查其他问题前,验证活动渲染管线确实是 URP。
Migration stopped after installing URP
迁移在安装 URP 后停止
- Treat this as a package-refresh/domain-reload boundary, not a failed full migration by itself.
- Re-check and package state. If URP is installed, do not reinstall it.
Packages/manifest.json - Inspect for partial assets such as URP assets, renderer assets, converted materials, empty Volume profiles, and scene component changes.
- If URP is installed/assigned but Built-in materials still dominate or the scene is magenta, material conversion is the immediate next incomplete item. Do not call URP setup complete and stop there if rollback safety has already been confirmed.
- Continue from the first incomplete verification item: Graphics/Quality assignment, renderer asset validity, material conversion, PPv2-to-URP Volume migration, baked-lighting rebake, then final validation.
- If the previous chat/export has no final response, report it as incomplete evidence and continue in a fresh chat/turn.
- 应将其视为包刷新或域重载边界,而不是单凭这一点判定完整迁移失败。
- 重新检查 和包状态。如果 URP 已安装,不要重新安装。
Packages/manifest.json - 检查部分资产,例如 URP Asset、Renderer Asset、已转换材质、空 Volume Profile 和场景组件更改。
- 如果 URP 已安装或指定,但 Built-in 材质仍占多数,或者场景呈洋红色,则材质转换是下一个需要完成的直接项目。回滚安全已经确认时,不要声明 URP 设置完成并就此停止。
- 从第一个未完成的验证项继续:Graphics 或 Quality 分配、Renderer Asset 有效性、材质转换、PPv2 到 URP Volume 迁移、烘焙光照重新烘焙,然后进行最终验证。
- 如果之前的聊天或导出内容没有最终响应,应将其报告为证据不完整,并在新的聊天或轮次中继续。
Materials are magenta / bright pink
材质呈洋红色或亮粉色
- Check Console and Inspector for shader errors.
- Confirm whether the material uses a supported Built-in shader, a custom shader, or a package-owned shader.
- If it is a supported Built-in shader, review the converter path or targeted material conversion first.
- If the project is already on URP and many supported Built-in materials remain, treat this as incomplete material conversion, not as final visual parity work.
- If it is a custom or package shader, move into references/custom-shader-triage.md and, when needed, references/complex-shader-situations.md.
- 检查 Console 和 Inspector 中的 Shader 错误。
- 确认材质使用的是受支持的 Built-in Shader、自定义 Shader,还是包所有的 Shader。
- 如果是受支持的 Built-in Shader,应先检查转换器路径或定向材质转换。
- 如果项目已经使用 URP,且大量受支持的 Built-in 材质仍然存在,则应将其视为材质转换未完成,而不是最终视觉一致性工作。
- 如果是自定义或包 Shader,应进入 references/custom-shader-triage.md;必要时再进入 references/complex-shader-situations.md。
Scene is much darker, brighter, or just "wrong"
场景明显更暗、更亮或“看起来不对”
- Compare Scene View and Game View captures.
- Check for double post-processing first: retained PPv2 /
PostProcessVolumeplus an active URPPostProcessLayercan overexpose or otherwise distort validation captures.Volume - Review shadows, ambient/environment lighting, tone mapping, skybox, exposure, bloom, and post-processing.
- Inspect baked lighting state: Lighting Settings, Lighting Data asset, lightmap references, mixed/baked lights, light probes, and reflection probes.
- Review quality-level assignments and URP asset settings before rewriting content.
- If clearing baked data fixes severe overexposure, treat the old lightmaps as stale active data: keep them only as reference/rollback evidence, then rebake under URP.
- If the scene depends on baked lighting, recommend a URP rebake and reflection-probe refresh before claiming visual parity.
- Remember that Built-in and URP light falloff can differ; treat that as a tuning task, not proof that conversion failed.
- 比较 Scene View 和 Game View 捕获结果。
- 首先检查重复后处理:保留的 PPv2 或
PostProcessVolume与活动 URPPostProcessLayer同时存在,可能导致过曝或以其他方式扭曲验证捕获结果。Volume - 检查阴影、环境光、Tonemapping、Skybox、曝光、Bloom 和后处理。
- 检查烘焙光照状态:Lighting Settings、Lighting Data Asset、Lightmap 引用、Mixed 或 Baked Light、Light Probe 和 Reflection Probe。
- 在重写内容之前,检查 Quality 级别分配和 URP Asset 设置。
- 如果清除烘焙数据可以解决严重过曝,应将旧 Lightmap 视为过期的活动数据:仅将其作为参考和回滚证据保留,然后在 URP 下重新烘焙。
- 如果场景依赖烘焙光照,在声明视觉一致性之前,建议在 URP 下重新烘焙并刷新 Reflection Probe。
- 记住 Built-in 与 URP 的光照衰减可能不同;应将其视为调优工作,而不是转换失败的证据。
Post-processing or fullscreen effects disappeared
后处理或全屏效果消失
- Check whether PPv2 was converted and whether the target camera and volume setup are still valid.
- Inspect saved URP assets. Empty profiles mean PPv2 effects were not actually migrated.
VolumeProfile - Check whether old /
PostProcessVolumecomponents remain active in scenes.PostProcessLayer - Search for , custom blit code, or replacement-shader camera effects.
OnRenderImage - Port the effect using a URP-compatible approach rather than trying to preserve the Built-in callback path unchanged.
- 检查 PPv2 是否已转换,以及目标相机和 Volume 设置是否仍然有效。
- 检查已保存的 URP 资产。空 Profile 意味着 PPv2 效果实际上没有迁移。
VolumeProfile - 检查旧 或
PostProcessVolume组件是否仍在场景中活动。PostProcessLayer - 搜索 、自定义 Blit 代码或替换 Shader 相机效果。
OnRenderImage - 使用 URP 兼容方式移植效果,而不是试图保持原有 Built-in 回调路径不变。
Transparent / refraction / distortion effects broke
透明、折射或扭曲效果失效
- Inspect whether the shader relied on or a similar Built-in screen-copy workflow.
GrabPass - If so, use references/complex-shader-situations.md and choose a Scene Color / Renderer Feature / custom-pass approach.
- 检查 Shader 是否依赖 或类似的 Built-in Screen Copy 工作流。
GrabPass - 如果是,则使用 references/complex-shader-situations.md,并选择 Scene Color、Renderer Feature 或自定义 Pass 方案。
2D lights are not affecting sprites
2D Light 无法影响 Sprite
- Confirm the project is actually using the 2D Renderer.
- Confirm existing sprite materials were upgraded to URP-compatible lit materials where needed.
- Do not assume dragged-in new sprites prove old project materials are correct.
- 确认项目确实在使用 2D Renderer。
- 确认现有 Sprite 材质在需要时已升级为 URP 兼容 Lit 材质。
- 不要因为拖入的新 Sprite 正常,就认为旧项目材质也正确。
Performance regressed after migration
迁移后性能回退
- Review render scale, shadows, additional lights, MSAA, post-processing, opaque/depth textures, and other URP asset settings.
- Check whether custom shader ports lost batching compatibility or introduced extra passes.
- Tune settings before assuming the only answer is a rollback.
- 检查 Render Scale、阴影、附加灯光、MSAA、后处理、Opaque 或 Depth Texture,以及其他 URP Asset 设置。
- 检查自定义 Shader 移植是否失去了批处理兼容性,或引入了额外 Pass。
- 在假设需要回滚前,先调整设置。
Custom shader compiles but visuals are still wrong
自定义 Shader 可以编译,但视觉仍然错误
- Determine whether the issue is simple parameter drift or a structural incompatibility.
- If the shader came from a surface shader, , replacement-shader workflow, or custom lighting path, treat it as a complex migration case.
GrabPass - Validate one representative material before rolling the approach out project-wide.
- 确定问题是简单参数漂移,还是结构性不兼容。
- 如果 Shader 来自 Surface Shader、、替换 Shader 工作流或自定义光照路径,应将其视为复杂迁移情况。
GrabPass - 在将方案扩展到整个项目之前,先验证一个代表性材质。
12. Core Guardrails
12. 核心防护规则
- Detect the active render pipeline first; for HDRP, explain the mismatch and offer only basic comparison guidance.
- Do not mutate the project before rollback safety is confirmed; instead stop in planning mode before URP install, asset assignment, converters, material edits, or scene edits.
- Do not treat tool logs or created assets as proof; instead save/reload/re-query Graphics, Quality, materials, Volumes, lighting, probes, Console, and representative scenes before status claims.
- Do not collapse partial phases into project-level completion; instead report ,
Phase complete, andPartial migrationbased on the success gate.Manual follow-up - Do not bulk-rewrite fragile rendering code; instead use scoped mappings for custom shaders, ,
GrabPass, replacement shaders, package-owned render code, and unsupported PPv2 effects.OnRenderImage
- 首先检测活动渲染管线;如果发现 HDRP,应说明不匹配情况,并仅提供基本对比指导。
- 在确认回滚安全之前,不要修改项目;应在安装 URP、指定 Asset、运行转换器、编辑材质或场景之前停在规划模式。
- 不要将工具日志或已创建资产视为证明;应在声明状态前保存、重新加载并重新查询 Graphics、Quality、材质、Volume、光照、探针、Console 和代表性场景。
- 不要将部分完成的阶段合并为项目级完成;应根据成功关卡报告 、
Phase complete和Partial migration。Manual follow-up - 不要批量重写脆弱的渲染代码;对于自定义 Shader、、
GrabPass、替换 Shader、包所有的渲染代码和不受支持的 PPv2 效果,应使用范围明确的映射关系。OnRenderImage
13. Reporting Back
13. 反馈报告
Summarize:
- which migration path was used
- whether the project is still Built-in, partially migrated, or fully on URP
- which converters ran
- what was fixed automatically
- what still needs manual work
- which scenes, materials, or cameras were validated
- what remains risky, especially around complex shaders, package effects, and visual parity
- whether post-processing was fully migrated, partially prepared, or only documented for manual follow-up
- whether Quality levels are explicitly assigned or intentionally relying on Graphics settings fallback
- whether particle/VFX materials were converted or still need URP particle-shader follow-up
- whether baked lighting/lightmaps/reflection probes were preserved as reference, verified visually, rebaked/refreshed, or left as manual follow-up
- whether exposure, tonemapping, ambient fill, and camera/Volume post-processing wiring were visually balanced or still remain partial
Use completion language conservatively. If the report contains any , , , , or unsupported-feature item, state that specific completed phases passed and call the overall migration partial/manual. Do not pair a project-level "complete" claim with manual follow-up bullets.
PartialManual follow-upnot validatedmay still need总结:
- 使用了哪条迁移路径
- 项目仍使用 Built-in、处于部分迁移状态,还是已完整使用 URP
- 运行了哪些转换器
- 自动修复了哪些问题
- 哪些工作仍需手动处理
- 验证了哪些场景、材质或相机
- 仍有哪些风险,尤其是复杂 Shader、包效果和视觉一致性方面
- 后处理是已完整迁移、仅部分准备,还是仅记录为手动跟进项
- Quality 级别是显式指定,还是有意依赖 Graphics 设置回退
- 粒子或 VFX 材质是否已转换,还是仍需跟进 URP Particle Shader
- 烘焙光照、Lightmap 和 Reflection Probe 是作为参考保留、完成视觉验证、重新烘焙或刷新,还是留作手动跟进项
- 曝光、Tonemapping、环境补光以及相机或 Volume 的后处理连接是否已完成视觉平衡,或者仍为 partial
使用完成状态措辞时应保持谨慎。如果报告中包含 、、、 或不受支持的功能项,应明确说明哪些已完成阶段通过,并将整体迁移标记为 partial 或需要手动处理。不要在手动跟进项存在时同时作出项目级 complete 声明。
PartialManual follow-upnot validatedmay still needReferences
参考资料
- Migration Workflow
- Custom Shader Triage
- Complex Shader Situations
- Quality Settings Map
- Implementation Patterns
When this skill is activated, proactively read references/migration-workflow.md. If the request involves materials, shaders, magenta materials, custom rendering, or fullscreen effects, also read references/custom-shader-triage.md and references/complex-shader-situations.md. If the request involves visual mismatch, lighting, baked lighting, lightmaps, reflection probes, shadows, or performance after migration, also read references/quality-settings-map.md. If the user permits actual migration changes or asks to continue/repair a partial migration, also read references/implementation-patterns.md.
- Migration Workflow
- Custom Shader Triage
- Complex Shader Situations
- Quality Settings Map
- Implementation Patterns
激活此 skill 后,应主动阅读 references/migration-workflow.md。如果请求涉及材质、Shader、洋红色材质、自定义渲染或全屏效果,还应阅读 references/custom-shader-triage.md 和 references/complex-shader-situations.md。如果请求涉及视觉差异、光照、烘焙光照、Lightmap、Reflection Probe、阴影或迁移后的性能问题,还应阅读 references/quality-settings-map.md。如果用户允许实际迁移更改,或要求继续或修复部分完成的迁移,还应阅读 references/implementation-patterns.md。