Unity SpriteAtlas V2
提供在 Unity 專案中以程式碼編寫圖集的 編輯器安全 程序性知識。V2 強制嚴格區分編輯器創作與執行時期存取。
⚠️ 關鍵 V2 原則：
SpriteAtlas僅用於執行時期。SpriteAtlasAsset僅用於編輯器。切勿混淆使用情境。一律使用 V2。
🚨 關鍵：實作前的必要檢查與使用者輸入
在產生任何程式碼前，務必執行以下檢查並詢問這些問題：
撰寫程式碼前請先閱讀附帶資源（必要）
此技能在 resources/ 下附帶了可運作的 C# 程式碼，而圖集程式碼出錯幾乎都是因為沒有先閱讀這些資源就直接撰寫。請根據您選擇的路徑開啟檔案並先閱讀。
resources/ 總共包含 38 個檔案，涵蓋自訂打包器、變體、平台設定與執行時期存取。當您的工作不在上表列舉的範圍內時，請瀏覽該目錄，而不是自己發明一種方法。根據記憶中的 API 而不是閱讀這些資源來撰寫程式碼，是導致圖集匯入成功卻在執行時期毫無作用的最常見原因。
0. 檢查是否存在現有指令碼（必要的第一步）
在產生任何程式碼之前，掃描專案中是否存在由此技能產生的現有 SpriteAtlas 指令碼。
搜尋包含此識別碼的檔案：// [UNITY-SKILL:SPRITEATLAS]
如果找到現有指令碼，一律使用以下格式詢問使用者：
「我在您的專案中發現了現有的 SpriteAtlas 指令碼：
預建置產生器：
Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.csAddressables 建置器：
Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs執行時期載入器：
Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs您想怎麼處理？」
然後提供選項：
-
選項 A：更新現有指令碼（若需求變更，建議使用）
- 在現有路徑重新產生指令碼
- 保留檔案位置
- 更新至最新版本
- ⚠️ 可能會覆寫自訂修改
-
選項 B：以不同名稱建立新指令碼
- 與現有指令碼並存產生
- 允許多個圖集配置
- 原始指令碼保持不變
- 您需要指定新的名稱/路徑
-
選項 C：中止（保留現有檔案不變）
- 不產生程式碼
- 不變更專案
- 若您想保留現有設定，請選此項
使用者選擇處理方式：
- 如果選擇 A：在現有路徑重新產生，版本號增加至 2.0.1+
- 如果選擇 B：詢問新的指令碼名稱（例如 "SpriteAtlasPrebuild_Custom.cs"），然後產生
- 如果選擇 C：立即停止，告知使用者未進行任何變更
1. 傳遞機制（必要）
詢問：「您希望如何傳遞 Sprite 圖集？」
選項 A：內建資料（立即載入）
- 圖集包含在建置中並立即載入
- 設定
includeInBuild = true - 適用於：核心 UI、主要遊戲玩法用 Sprite、始終需要的資產
- 優點：簡單、無需額外套件、即時存取
- 缺點：增加初始建置大小、無法在不新建置的情況下更新
選項 B：透過 Addressables 延遲綁定（按需載入）
- 圖集不包含在建置中，透過 Addressables 按需載入
- 設定
includeInBuild = false - 為每個圖集建立 Addressables 條目
- 新增 Addressables 設定作為預建置步驟
- 🚨 必要：將建置 Addressables 內容作為建置步驟
- 🚨 必要：建立延遲綁定的執行時期載入器指令碼
- 適用於：DLC 內容、可選功能、大型資產、可下載內容
- 優點：更小的初始建置、可獨立更新、按需載入
- 缺點：需要 Addressables 套件、非同步載入、網路相依性
| 使用案例 | 推薦 |
|---|---|
| 總是可見的核心 UI Sprite | 選項 A：內建 |
| 教學或入門 Sprite | 選項 A：內建 |
| 特定關卡 Sprite（100+ 關卡） | 選項 B：Addressables |
| DLC 或季節性內容 | 選項 B：Addressables |
| 本地化 UI Sprite（多語言） | 選項 B：Addressables |
| 角色造型或裝飾品 | 選項 B：Addressables |
2. SpritePacker 模式（必要）
在建立圖集之前啟用 Sprite Packer 模式，然後讀取設定並確認它已生效。
使用 resources/enablespritepacking.cs 中的程式碼；它會設定 EditorSettings.spritePackerMode 並配置導入器的打包設定。
這是決定您產生的圖集是否真實有效的關鍵步驟。Disabled 是 SpritePackerMode 的零值，因此任何未設定此值的專案都處於打包已停用狀態。在已停用狀態下建立的圖集仍然可以導入、顯示為資產，看起來也像是完成了，但永遠無法進行打包。Unity 在檢視器中會顯示："Sprite Atlas packing is disabled"。工作流程中的其他步驟都不會失敗，因此以這種方式發佈的圖集看起來像是成功的。不要假設專案已經配置完畢：請讀取該值。
因此，不要將「我已設定」視為完成。設定後，請重新讀取 EditorSettings.spritePackerMode，確認它不是 Disabled，並回報您讀取到的實際值。如果您無法讀取，請說明情況，而不是假設寫入已成功。
請勿直接編輯 meta 檔案。
🚨 關鍵：預設方法為預建置生成
一律使用 IPreprocessBuildWithReport 在構建管線中自動產生或更新 SpriteAtlas。 這是預設且必要的方法，除非使用者明確要求手動創作。
❌ 不要建立手動選單項目指令碼
除非明確要求，否則切勿建立帶有 [MenuItem] 屬性的圖集生成指令碼。 預建置方法消除了手動點擊的需求。僅在以下情況使用手動創作：手動最佳化的佈局、特定的 Sprite 排列或編輯器預覽需求。請參閱進階：手動創作。
🚨 關鍵：Sprite 來源位置限制
僅從專案的 Assets 資料夾新增 Sprite。切勿從 Unity 內建資產、套件或外部位置新增 Sprite。 Unity 內建資產無法打包進 SpriteAtlas，而套件資產可能會導致導入/依賴問題。
關鍵 V2 架構
| 上下文 | 元件 | 用途 | 允許的使用方式 |
|---|