Communitygithub.com

unity-technologies/migrate-birp-to-urp

規劃、執行並排除 Unity 專案從 Built-in Render Pipeline (BiRP) 遷移至 Universal Render Pipeline (URP) 的疑難雜症。當使用者要求升級、轉換、切換或遷移專案、場景、材質或著色器至 URP、修復 URP 後的粉紅色或洋紅色材質、轉換 Built-in 材質/著色器、將 2D 專案移至 URP 2D、檢視 URP 後的燈光、品質、後製處理、烘焙光照貼圖或反射探針,或診斷渲染管線遷移後的視覺問題時使用。

migrate-birp-to-urp 是什麼?

這個技能專門處理 Unity 專案從 Built-in Render Pipeline (BiRP) 遷移至 Universal Render Pipeline (URP) 的完整工作流程。它會先分類請求、檢查專案狀態,然後根據不同情境選擇正確的遷移路徑,最後驗證遷移結果。此技能支援標準 3D URP、URP 2D、選擇性材質轉換、純規劃或疑難排解等模式。工作流程分為多個階段,包括:檢查與規劃 (偵測管線狀態、場景、材質/著色器風險)、URP 設定與材質轉換、後製處理與相機遷移、燈光與光照貼圖/反射探針處理,以及最終驗證與報告。此技能對於確保遷移過程安全且完整至關重要,它會自動偵測常見的 Built-in 相依項目 (如 PPv2、烘焙燈光、粒子材質),並要求確認回滾點 (如分支、備份) 才進行會修改管線的操作。最終,它會驗證圖形設定、URP 資源、材質正確性、燈光狀態等條件,以宣告遷移成功或完成。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

分類請求,檢查當前專案狀態,選擇正確的遷移路徑,並仔細驗證 Built-in 到 URP 的遷移結果。

強制執行參考

在進行任何實際的遷移或修復作業之前,請先閱讀 references/implementation-patterns.md 再進行第一個會編輯專案設定、材質、後製處理、燈光、探針或場景的 eval 呼叫。即使是在已確認回滾安全性的情況下,對於像是「將此專案遷移到 URP」這類簡短提示,也必須強制執行此步驟。

如果無法載入該資源,請使用此 SKILL.md 中的內嵌規則,並降低你的信心水準:不要僅根據意圖或工具日誌就聲稱已完成 PPv2 轉換、燈光/探針更新或遷移完成。

關鍵預設行為

對於像是「將此 Built-in 專案遷移到 URP」或「將此專案移至 URP」的簡單請求,請啟動或恢復安全的遷移工作流程,而不是直接跳到轉換步驟。

一個通用的升級提示不應要求使用者提及每一個遷移風險。請檢查並處理常見的 Built-in 相依項目,例如 PPv2、烘焙燈光/光照貼圖、反射探針、粒子/霧氣/煙霧材質、品質設定、相機後製處理,以及具代表性的場景驗證。

預設結果基於以下階段:

  1. 偵測專案是 Built-in、部分遷移、已為 URP 還是 HDRP。
  2. 將請求分類為標準 3D URP、URP 2D、選擇性材質轉換、純規劃或疑難排解。
  3. 在建議修改前檢查遷移風險:不透明材質、粒子/VFX 材質、自訂著色器、後製處理、相機特效、烘焙燈光/光照貼圖/反射探針、品質設定,以及具代表性的場景。
  4. 在使用者確認回滾點(例如分支、備份、存檔或可丟棄的副本)之前,停止所有會改變管線的工作。改變管線的工作包括安裝 URP、在圖形/品質設定中指定 URP 資源、執行轉換器,以及編輯材質或場景。
  5. 選擇下一個遷移階段、執行該階段、儲存/重新查詢其輸出,並報告其階段狀態。
  6. 將自訂著色器、GrabPass、表面著色器 (Surface Shader)、OnRenderImage、替換著色器 (replacement shader) 以及套件擁有的著色器視為有範圍的後續工作,而非自動轉換器的工作。
  7. 在宣告完整遷移成功之前,驗證代表性的場景、控制台輸出、相機渲染、燈光/烘焙全域照明 (GI) 狀態、材質、後製處理的持續性,以及品質設定指派。

預設階段:

  • 階段 0:檢查與規劃。偵測管線狀態、代表性場景、回滾安全性、PPv2、材質/著色器風險、品質設定、燈光/光照貼圖/探針狀態,以及自訂渲染程式碼。
  • 階段 1:URP 設定與支援的材質轉換。安裝/重複使用 URP、在圖形/品質設定中建立/指派 URP 資源、轉換支援的不透明與粒子/效果材質,並確認沒有支援的材質仍使用 Built-in 著色器。
  • 階段 2:後製處理與相機遷移。建立持久的 URP Volume 設定檔、連接場景 Volume / 相機後製處理、為 URP 驗證停用舊版 PPv2,並分類不支援的 PPv2 效果,例如 SSR。
  • 階段 3:燈光、光照貼圖與反射探針。解決過時的 Built-in 燈光狀態、設定 URP 燈光/探針設定、在可行時重新烘焙/更新,或明確標記燈光/探針為部分完成。
  • 階段 4:最終驗證與報告。儲存/重新載入/重新查詢專案狀態、擷取代表性場景、檢查控制台,並報告完整/不完整/需要手動處理的項目。

如果專案很小且 Unity 維持穩定,一個互動回合可能完成多個階段,但不要強求在一個回覆中完成所有階段。寧願誠實地標記階段邊界,也不要過度聲稱「完成」。

僅在專案狀態或使用者意圖確實存在未解決的決定時,才詢問設定問題。如果使用者說「不要修改檔案」,則停留在審計/規劃模式,不要執行轉換或資源編輯。

通用升級合約

當使用者提出通用的遷移請求並允許修改時,請根據專案狀態驅動下一個階段:

  1. 在檢查之前,不要要求使用者列舉已知的 Built-in 功能。請自行發現它們。
  2. 如果存在 PPv2、烘焙燈光、反射探針、粒子/霧氣/煙霧材質或多個品質設定,請自動將它們納入遷移範圍。
  3. 優先完成階段,而不是一次性全部完成。每個階段應儲存/重新查詢其自身的輸出,並以「Phase complete」、「Phase partial」或「Blocked」結束。
  4. 如果 Unity 編譯、套件安裝、領域重新載入或長時間的燈光烘焙中斷了操作,請將此中斷報告為一個階段邊界,並在下一個回合從已儲存的局部狀態繼續,而不是重新開始。
  5. 不要依賴使用者撰寫詳細的檢查清單提示來獲得正確的行為。詳細的檢查清單是為了基準測試或壓力測試;正常的使用者提示仍應觸發此階段性合約。
  6. 一個通用的遷移請求允許檢查和規劃,但它並不證明回滾安全性。如果沒有確認回滾點,請在套件安裝或 URP 指派之前停止,並要求確認。不要為了達到備份問題而讓專案處於洋紅色的部分狀態。
  7. 如果回滾安全性已確認,或者使用者說該專案是可丟棄的副本,則在當前階段內繼續進行,無需再為例行工作請求許可。
  8. 在階段結束時,提供一個簡潔的下一個階段提示,或說明接下來應該執行哪個階段。僅在引入新的昂貴或高風險操作時,才在執行下一個階段前請求使用者確認,例如長時間的燈光烘焙、刪除/清理舊版資源,或重寫自訂著色器。
  9. 如果回滾安全性已確認,且活躍階段內的例行工作仍未完成,則不要問「你想讓我繼續嗎?」。繼續修復該階段,直到其閘門通過、工具/領域重新載入邊界中斷執行,或出現一個真正新的高風險決策。

通用遷移成功閘門

在說一個通用遷移是「成功」、「完成」或「完全遷移」之前,請驗證已儲存的專案狀態,而不僅僅是工具日誌:

  1. 圖形設定和每個相關的品質設定都指向預期的 URP 資源。
  2. URP 資源在已儲存的狀態中有一個有效的預設渲染器,且當前控制台輸出中沒有未解決的渲染管線錯誤,例如「Default Renderer is missing」。如果在指派後出現渲染器錯誤,請重新查詢已儲存的渲染器清單/預設索引,盡可能清除過時的控制台輸出,觸發新的場景/相機驗證,並繼續修復,而不是在「URP 設定完成」時就停止。
  3. 支援的 Built-in 材質,包括粒子/霧氣/煙霧材質,具有 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.

相關技能