Communitygithub.com

unity-technologies/migrate-birp-to-urp

规划、执行并排查将 Unity 项目从内置渲染管线 (BiRP/BIRP/Built-in RP) 迁移至通用渲染管线 (URP) 的相关问题。当用户要求升级、转换、切换或迁移项目、场景、材质或着色器到URP;修复URP后的粉色或洋红色材质;转换内置材质/着色器;将2D项目迁移到URP 2D;审查URP后的光照、质量、后处理、烘焙光照贴图或反射探针;或诊断渲染管线迁移后的视觉问题时使用。

migrate-birp-to-urp 是什么?

该技能用于安全地将 Unity 项目从内置渲染管线 (BiRP) 迁移到通用渲染管线 (URP)。它会根据项目状态自动选择合适的迁移路径,并分阶段执行,包括检测当前管线、安装 URP、转换材质、处理后处理、迁移光照和反射探针,以及最终验证。技能强调回滚安全,在修改任何管线设置前会要求用户确认备份点,并主动检测常见的迁移风险,如 PPv2、烘焙光照、自定义着色器等。它支持标准 3D URP、URP 2D 以及故障排除场景,并提供了详细的划分阶段流程,确保迁移过程可控且可恢复。主要适用于 Unity 编辑器环境与 AI 编码助手(如 Claude Code、Cursor),通过分析项目状态和自动执行转换脚本,协助用户完成复杂且易出错的管线升级任务。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/unity-technologies/skills/tree/main/skills/migrate-birp-to-urp

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

对请求进行分类,检查当前项目状态,选择正确的迁移路径,并仔细验证从内置渲染管线到 URP 的迁移结果。

强制执行参考

对于任何实际的迁移或修复操作,在对项目设置、材质、后处理、光照、探针或场景进行第一次 eval 调用之前,请先阅读 references/implementation-patterns.md。即使对于简短提示(例如“将此项目迁移到 URP”)且回滚安全性已确认,这也是强制性的。

如果无法加载该资源,请使用此 SKILL.md 中嵌入的规则并降低您的置信度:不要仅凭意图或工具日志就声称 PPv2 转换、光照/探针刷新或迁移完成。

关键默认行为

对于简单请求,例如“将此内置项目迁移到 URP”或“将此项目移动到 URP”,请启动或恢复安全的迁移工作流程,而不是直接跳转到转换。

通用的升级提示不应要求用户提及每个迁移风险。检查并处理常见的内置依赖项,例如 PPv2、烘焙光照/光照贴图、反射探针、粒子/雾/烟雾材质、质量级别、相机后处理以及代表性场景验证。

默认结果是基于阶段的:

  1. 检测项目是内置管线、部分迁移、已经是 URP 还是 HDRP。
  2. 将请求分类为标准 3D URP、URP 2D、选定材质转换、仅规划或故障排除。
  3. 在推荐更改之前检查迁移风险:不透明材质、粒子/VFX 材质、自定义着色器、后处理、相机效果、烘焙光照/光照贴图/反射探针、质量级别和代表性场景。
  4. 在用户确认回滚点(例如分支、备份、存档或一次性副本)之前,停止所有改变管线的操作。改变管线的操作包括:安装 URP、在图形/质量设置中分配 URP 资源、运行转换器以及编辑材质或场景。
  5. 选择下一个迁移阶段,执行该阶段,保存/重新查询其输出,并报告其阶段状态。
  6. 将自定义着色器、GrabPass、表面着色器、OnRenderImage、替换着色器和包拥有的着色器视为范围明确的后续工作,而不是自动转换器的工作。
  7. 在声明完全迁移成功之前,验证代表性场景、控制台输出、相机渲染、光照/烘焙全局光照状态、材质、后处理持久性和质量级别分配。

默认阶段:

  • 阶段 0:检查和规划。检测管线状态、代表性场景、回滚安全性、PPv2、材质/着色器风险、质量级别、光照/光照贴图/探针状态以及自定义渲染代码。
  • 阶段 1:URP 设置和支持的材质转换。安装/重用 URP,在图形/质量设置中创建/分配 URP 资源,转换支持的不透明和粒子/效果材质,并验证没有支持的材质仍在使用内置着色器。
  • 阶段 2:后处理和相机迁移。创建持久的 URP Volume 配置文件,连接场景 Volume/相机后处理,为 URP 验证禁用旧版 PPv2,并将不支持的 PPv2 效果(如 SSR)分类。
  • 阶段 3:光照、光照贴图和反射探针。解决陈旧的内置光照状态,配置 URP 光照/探针设置,在可行时重新烘焙/刷新,或明确标记光照/探针为部分完成。
  • 阶段 4:最终验证和报告。保存/重新加载/重新查询项目状态,捕获代表性场景,检查控制台,并报告已完成/未完成/需要手动处理的项目。

一次交互可能完成多个阶段,如果项目规模小且 Unity 保持稳定,但不要强制所有阶段在一个回复中完成。相较于过度声称“完成”的结果,更倾向于诚实的阶段边界。

仅当项目状态或用户意图留下一个真正的决策未解决时,才询问配置问题。如果用户说“不要修改文件”,则保持在审计/规划模式,不执行转换或资产编辑。

通用升级契约

当用户给出通用的迁移请求并允许更改时,根据项目状态驱动下一个阶段:

  1. 不要在检查之前要求用户列举已知的内置功能。自行发现它们。
  2. 如果存在 PPv2、烘焙光照、反射探针、粒子/雾/烟雾材质或多个质量级别,自动将其包含在迁移中。
  3. 倾向于阶段完成而非一次性完成。每个阶段应保存/重新查询其自己的输出,并以“阶段完成”、“阶段部分完成”或“已阻止”结束。
  4. 如果 Unity 编译、包安装、域重新加载或长时间的光照烘焙中断了操作,将中断报告为阶段边界,并在下一次交互中从保存的部分状态恢复,而不是从头开始。
  5. 不要依赖用户编写详细的清单提示来获得正确行为。详细的清单用于基准测试或压力测试;正常的用户提示仍应触发此阶段的契约。
  6. 通用的迁移请求允许检查和规划,但不证明回滚安全性。如果未确认回滚点,请在包安装或 URP 分配之前停止并要求确认。不要仅仅为了达到备份问题而将项目置于粉红色部分状态。
  7. 如果回滚安全性已确认,或者用户说该项目是一次性副本,则继续在当前阶段内进行,无需再次询问常规工作。
  8. 在阶段结束时,给出一个简洁的下阶段提示或说明接下来应该运行哪个阶段。仅当下一个阶段引入新的昂贵或风险操作时(例如长时间的光照烘焙、删除/清理旧版资产或自定义着色器重写),才在开始前要求确认。
  9. 如果回滚安全性已确认,并且活动阶段内的常规工作仍未完成,则不要询问“您希望我继续吗?”。继续修复该阶段,直到其检查点通过、工具/域重新加载边界中断执行或出现真正新的风险决策为止。

通用迁移成功检查点

在声明通用迁移“成功”、“完成”或“完全迁移”之前,请验证已保存的项目状态,而不仅仅是工具日志:

  1. 图形设置和每个相关的质量级别都指向预期的 URP 资源。
  2. URP 资源在已保存状态中具有有效的默认渲染器,并且当前控制台输出不包含未解决的渲染管线错误,例如“默认渲染器缺失”。如果在分配后出现渲染器错误,请重新查询已保存的渲染器列表/默认索引,尽可能清除旧的控制台输出,触发新的场景/相机验证,并继续修复,而不是停步于“URP 设置完成”。
  3. 支持的内置材质(包括粒子/雾/烟雾材质)具有 URP 兼容的着色器,或明确列为未解决的自定义/包着色器情况。带纹理/颜色的源材质必须保留其源贴图/颜色;如果源 _MainTex 或 _Color 有内容,则分配了缺少 _BaseMap 或全白 _BaseColor 的 URP 着色器是不完整的。不应盲目地将粒子、雾、烟雾、蒸汽、贴花、VFX、相加和透明效果材质强制转换为 Universal Render Pipeline/Lit;在适当时,更倾向于使用 URP 粒子/效果着色器,例如 Universal Render Pipeline/Particles/Unlit。
  4. 如果源场景使用了 PPv2,则已保存的 URP

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

unity-technologies/2d-pixel-perfect

Sets up, diagnoses, and fixes pixel perfect 2D rendering in Unity projects. Use when working on any retro-style or pixel art 2D game.

unity-technologies/audio-setup-mixers

Scans the scene and audio assets to appropriately route Audio Sources into existing Audio Mixer Groups, classifying each source by what it plays. Use when the user asks about cleaning up mixer assignments, routing audio through a mixer, or which group a sound belongs in. Creating mixers and groups, and setting volumes, are not automated — the skill inventories what exists and asks the user to add anything missing.

unity-technologies/build-live-game

Build and operate a live game using Unity Services. Use when the user needs to implement, connect, or debug backend-driven features — battle passes, achievements, player progression, cloud saves, leaderboards, matchmaking, virtual economies, server-authoritative logic, anti-cheat, player accounts and authentication, remote configuration, feature flags, A/B testing, analytics, or cloud resource deployment. Triggers on live-ops, live service, backend, server authority, cloud code, cloud save, remote config, player data, retention, monetization loop, season pass, ranking, multiplayer sessions, lobbies, or any Unity Services integration.

unity-technologies/generate-editor-search-query

Generates Unity Search / Quick Search queries and opens the Unity Search window for read-only Unity Editor asset or scene-object lookup requests. Always use when the user asks to find, search, show, locate, filter, look up, query, or list concrete assets or scene objects in the current project or scene, even if Unity Search is not named. Covers materials, textures, prefabs, scenes, scripts, shaders, GameObjects, components, Lights, Cameras, UI objects, labels, paths, references, selected or named assets, and asset types. Also use when the user explicitly mentions Unity Search, Quick Search, Search window, open Search, or asks what Unity Search query to use. Do not use for general project overview, project structure, folder-purpose summaries, gameplay/system explanations, how-to programming questions, web search, repository text search, build logs, package installation, menu or settings search, modifying results, or non-Unity filesystem search unless the user explicitly asks to use Unity Search.

unity-technologies/implement-in-app-purchases

Implement, configure, and debug Unity In-App Purchases (IAP) — store connection, product catalog, consumable/non-consumable/subscription purchases, two-step pending-confirm flow, receipt validation, entitlement checking, restore transactions, Apple extensions (promotional purchases, Ask-to-Buy, code redemption), and Google Play extensions (subscription upgrade/downgrade), D2C Capabilities(direct to customer), 3rd party payment provider (Stripe/Coda) via Unity IAP/Unity Cloud. Use when the user needs to add, modify, debug, or migrate from native Android/iOS billing, 3rd party packages(RevenueCat/Adapty/Essential Kit/Unipay supported) to IAP. Triggers on microtransactions (MTX), monetization, real-money purchases, store purchases, buying items, support D2C, purchase via Stripe/Coda, migrate from native billing(Google's BillingClient or Apple's StoreKit/SKPaymentQueue/SKProduct)/RevenueCat/Adapty/EssentialKit/Unipay.

unity-technologies/initialize-ai-navigation

Sets up and configures the Unity AI Navigation system — NavMesh surfaces, NavMesh agents, obstacles, links, modifiers, areas and costs. Use when creating walkable navigation meshes, adding pathfinding agents, setting up patrol routes, configuring obstacle avoidance and carving, connecting separate NavMeshes with links, coupling navigation with animation, or troubleshooting navigation issues.

unity-technologies/levelplay-unity-integration

Integrates the LevelPlay Mediation SDK via the Ads Mediation UPM package. Use when a developer asks about adding ads to a Unity game, implementing rewarded, interstitial, or banner ads, setting up ad mediation, configuring ad networks, installing or updating the Ads Mediation package, troubleshooting LevelPlay namespace errors, resolving Android gradle or iOS CocoaPods dependency issues for ads, configuring ATT or privacy settings for ad compliance, tracking impression-level revenue (ILRD), initializing the LevelPlay SDK, or setting up ad unit IDs. Also use when a developer wants to monetize their Unity game with ads, asks how to get started with LevelPlay, ads, or mediation, or needs help with any part of the LevelPlay integration workflow including platform-specific setup for iOS or Android. Also use when upgrading the LevelPlay or IronSource SDK version, migrating from deprecated IronSource.Agent APIs, or migrating a game from Unity Ads to LevelPlay.

unity-technologies/localization

Sets up and configures Unity Localization, including locales, String/Asset Tables, CJK font support, and Addressables workflows. Use when the user wants to add languages to a project, translate UI text, support Asian (CJK) languages with TMP fonts, or mentions i18n, l10n, multilingual support, or making a game support multiple languages.

unity-technologies/manage-sprite-atlas

Manage SpriteAtlas using prebuild pipeline with IPreprocessBuildWithReport (DEFAULT approach). Use it to configure master atlases, variant atlases, texture settings, packing settings, and platform-specific configurations. Use when the user asks about creating sprite atlases, optimizing sprites, configuring atlas settings, adding sprites to atlases, creating variant atlases, implementing automated atlas generation, or runtime sprite atlas access. Always use prebuild approach unless user explicitly requests manual authoring.

相关技能