manage-sprite-atlas

Unity SpriteAtlas V2

为 Unity 项目中的图集脚本编写提供编辑器安全的程序化知识。V2 强制严格区分编辑器创作与运行时访问。

⚠ V2 关键原则：SpriteAtlas 仅限运行时使用。SpriteAtlasAsset 仅限编辑器使用。绝不要混用上下文。始终使用 V2。

🚨 关键：实现前必须进行的检查和确认的用户输入

生成任何代码之前，始终先执行这些检查并提出这些问题：

编写代码前先阅读随附资源（必需）

此技能在 resources/ 中提供了可用的 C# 代码，而图集代码出错，几乎总是因为没有先阅读这些代码就开始编写。先打开与你选择的实现路径相关的文件，再编写代码。

选择的路径	首先阅读
任何图集相关工作	resources/authoringvsruntime.cs、references/common-errors.md
预构建生成（默认）	resources/spriteatlasprebuildgenerator.cs、resources/enablespritepacking.cs、resources/savespriteatlasasset.cs
选项 B：Addressables 延迟绑定	resources/buildaddressablespostprocess.cs、resources/spriteatlaslatebinding.cs、resources/handlelatebinding.cs
任何可能使用较旧 API 的情况	resources/deprecatedmethods.cs、resources/dontscriptspriteatlasineditor.cs、resources/dontpackinruntimebuilds.cs

resources/ 中共有 38 个文件，涵盖自定义打包器、变体、平台设置和运行时访问。如果你的任务不在上表中，请浏览该目录，而不是凭空设计方案。依赖记忆而不阅读这些 API，是导致图集导入顺利却在运行时毫无效果的最常见原因。

0. 检查现有脚本（必须首先执行）

生成任何代码之前，扫描项目，查找此技能生成的现有 SpriteAtlas 脚本。

搜索包含标识符 // [UNITY-SKILL:SPRITEATLAS] 的文件。

如果找到现有脚本，始终使用以下格式询问用户：

"我在你的项目中找到了现有的 SpriteAtlas 脚本：

预构建生成器：

• Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.cs

Addressables 构建器：

• Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs

运行时加载器：

• Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs

你希望如何处理？"

然后提供以下选项：

• 选项 A：更新现有脚本（需求发生变化时推荐）

  • 在现有路径重新生成脚本
  • 保留文件位置
  • 更新到最新版本
  • ⚠ 可能覆盖自定义修改

• 选项 B：使用不同名称创建新脚本

  • 在现有脚本旁生成新脚本
  • 支持多种图集配置
  • 原有脚本保持不变
  • 你需要指定新名称和路径

• 选项 C：中止（保持现有脚本不变）

  • 不生成代码
  • 不更改项目
  • 如果你想保留当前配置，请选择此选项

处理用户选择：

• 如果选择 A：在现有路径重新生成，将版本号递增至 2.0.1+
• 如果选择 B：询问新的脚本名称（例如“SpriteAtlasPrebuild_Custom.cs”），然后生成
• 如果选择 C：立即停止，并告知用户未进行任何更改

1. 交付机制（必需）

询问：“你希望如何交付精灵图集？”

选项 A：内置数据（立即加载）

• 图集包含在构建中并立即加载
• 设置 includeInBuild = true
• 适用于：核心 UI、主要游戏精灵、始终需要的资源
• 优点：简单，无需额外包，可立即访问
• 缺点：增加初始构建大小，无法在不重新构建的情况下更新

选项 B：通过 Addressables 延迟绑定（按需加载）

• 图集不包含在构建中，而是通过 Addressables 按需加载
• 设置 includeInBuild = false
• 为每个图集创建 Addressables 条目
• 将 Addressables 设置添加为预构建步骤
• 🚨 必需：将 Addressables 内容构建作为构建步骤
• 🚨 必需：创建延迟绑定运行时加载器脚本
• 适用于：DLC 内容、可选功能、大型资源、可下载内容
• 优点：初始构建更小，可独立更新，按需加载
• 缺点：需要 Addressables 包、异步加载、依赖网络

使用场景	推荐选项
始终可见的核心 UI 精灵	选项 A：内置
教程或引导精灵	选项 A：内置
特定关卡的精灵（100 个以上关卡）	选项 B：Addressables
DLC 或季节性内容	选项 B：Addressables
本地化 UI 精灵（多种语言）	选项 B：Addressables
角色皮肤或装饰物品	选项 B：Addressables

2. SpritePacker 模式（必需）

创建图集之前，请启用 Sprite Packer 模式，然后读回设置并确认已生效。 使用 resources/enablespritepacking.cs 中的代码；它会设置 EditorSettings.spritePackerMode 并配置导入器的打包设置。

这一步决定你生成的图集是否真正有效。Disabled 是 SpritePackerMode 的零值，因此任何尚未设置该值的项目都会保持打包禁用状态。在禁用状态下创建的图集仍会导入、仍会作为资源显示，也仍然看起来已经完成，但永远无法打包。Unity 会在检查器中明确提示："Sprite Atlas packing is disabled"（Sprite Atlas 打包已禁用）。工作流中的其他步骤都不会失败，因此以这种方式交付的图集看起来像是成功了。不要假设项目已经配置好：请读取该值。

因此，不要把“我设置了”当作完成。设置后，读回 EditorSettings.spritePackerMode，确认它不是 Disabled，并报告你实际读取到的值。如果无法读回，请如实说明，不要假设写入已生效。

不要直接编辑 meta 文件。

🚨 关键：默认采用预构建生成方式

始终使用 IPreprocessBuildWithReport 在构建流程中自动生成或更新 SpriteAtlases。 除非用户明确要求手动制作，否则这是默认且必需的方式。

❌ 不要创建手动菜单项脚本

除非用户明确要求，否则绝不要创建带有 [MenuItem] 特性的图集生成脚本。 预构建方式无需手动点击。仅在以下情况下使用手动制作方式：手动优化布局、指定精灵排列，或需要编辑器预览。请参阅高级：手动制作。

🚨 关键：精灵来源位置限制

只能添加来自项目 Assets 文件夹的精灵。绝不要添加来自 Unity 内置资源、包或外部位置的精灵。 Unity 内置资源无法打包到 SpriteAtlas 中，而包资源可能导致导入或依赖问题。

V2 架构关键要点

上下文	组件	用途	允许的用法
编辑器创作	SpriteAtlasAsset	添加/移除精灵和文件夹；存储元数据	✅ 仅限编辑器脚本
编辑器设置	SpriteAtlasImporter	配置纹理、打包和平台设置	✅ 仅限编辑器脚本
编辑器打包	SpriteAtlasUtility.PackAtlases()	可选的编辑器预览打包（不用于构建）	⚠ 仅用于预览；图集会在构建时自动打包
运行时	SpriteAtlas	查询已打包的精灵（只读）	✅ 仅限运行时脚本
运行时加载	SpriteAtlasManager	动态加载回调	✅ 仅限运行时脚本

禁止跨上下文使用（常见错误来源）

❌ 无效模式	✅ 正确模式
在编辑器代码中使用 new SpriteAtlas()	使用 SpriteAtlasAsset + SpriteAtlasImporter
在编辑器中使用 AssetDatabase.LoadAssetAtPath<SpriteAtlas>(...)	使用 SpriteAtlasAsset.Load(...)
在编辑器中使用 SpriteAtlasAsset.GetPackables()	使用 SpriteAtlas.GetPackables()
在编辑器脚本中修改 SpriteAtlas	修改 SpriteAtlasAsset → 重新导入 → 使用 SpriteAtlasImporter
从原始可打包对象（精灵/文件夹）创建变体	从 Master 运行时 SpriteAtlas 创建变体

切勿在编辑器代码中针对 SpriteAtlas 编写脚本——在 V2 中，它仅供运行时使用，GetPackables 除外。

V2 核心工作流（仅供参考——请改用 Prebuild）

🚨 重要：此工作流仅供参考。务必在 IPreprocessBuildWithReport.OnPreprocessBuild() 中实现此工作流，不要使用手动脚本。请参阅快速入门。

前提条件

• Unity 6000.3 或更高版本
• 基本了解 Unity 的资源导入管线
• 熟悉用于图集创作的编辑器脚本

快速入门：自动化 Prebuild 生成（默认方案）

概述

**这是创建 SpriteAtlases 的首选和默认方式。**实现 IPreprocessBuildWithReport，根据分类规则在每次构建前自动生成或更新 SpriteAtlases。无需手动点击菜单。

工作流步骤

步骤 1：询问用户选择交付方式

生成代码前，询问：“你希望如何交付精灵图集：(A) 内置数据，还是 (B) 通过 Addressables 延迟绑定？”

步骤 2：创建 Prebuild 脚本

在 Editor 文件夹中创建此脚本。根据用户选择的交付方式进行自定义：

选项 A：内置数据（立即加载）

内置数据（立即加载）

选项 B：通过 Addressables 延迟绑定（按需加载）

🚨 强制要求：用户选择 Addressables 时，必须生成以下全部三个脚本。切勿只生成其中一两个——Addressables 交付必须具备全部三个脚本才能正常工作。

必需脚本（以下三个全部必需）：

1. Prebuild 脚本（IPreprocessBuildWithReport）——生成图集并创建 Addressables 条目
2. 构建 Addressables 脚本（IPostprocessBuildWithReport）——构建 Addressables 内容包
3. 延迟绑定运行时加载器（MonoBehaviour）——处理运行时按需加载

完整实现请参阅 references/addressables-delivery.md。

完整工作流

User Request
    ↓
Step 0: Check for existing scripts with [UNITY-SKILL:SPRITEATLAS] identifier
    ↓
    ├─ Found existing scripts?
    │   ↓ YES
    │   Ask user: Update existing / Create new / Abort
    │   ↓
    │   Handle user choice
    │
    └─ NO existing scripts or user chose "Create new"
        ↓
        Ask "Built-in data or Addressables?"
        ↓
        ├─ Option A: Built-in
        │   ↓
        │   Generate 1 script: Prebuild generator (includeInBuild=true)
        │
        └─ Option B: Addressables
            ↓
            Generate 3 scripts:
              1. Prebuild: Generate atlases + create Addressables entries (includeInBuild=false)
              2. Postprocess: Build Addressables bundles
              3. Runtime: Late-binding loader component

步骤 3：自定义分类规则

编辑 OnPreprocessBuild 方法，以匹配项目的 Sprite 组织方式。选择一种或组合多种策略：

策略	适用场景	实现方式
基于文件夹	Sprite 按文件夹结构组织	GenerateAtlasByFolder("Assets/Art/UI", "Assets/Atlases/UI.spriteatlasv2")
命名约定	Sprite 遵循命名模式	GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2")
资源标签	Sprite 使用标签进行标记
基于场景	Sprite 用于特定场景	查询场景引用

步骤 4：构建项目

图集会在构建期间自动生成/更新。无需手动点击菜单。 这就是预构建作为默认方案的原因。

对于内置数据（选项 A）：

• 图集会包含在构建中
• 运行时可立即使用

对于 Addressables（选项 B）——还需要执行以下步骤：

你必须生成三个脚本（而不仅仅是一个）：

1. 预构建脚本（IPreprocessBuildWithReport）——生成图集并自动创建 Addressables 条目
2. 构建 Addressables 脚本（IPostprocessBuildWithReport）——构建 Addressables 内容包
3. 延迟绑定运行时加载器（MonoBehaviour）——通过 SpriteAtlasManager 按需加载

构建过程将会：

• 生成图集（预构建步骤）
• 自动创建 addressable 条目
• 构建 addressables 内容包（后处理步骤）
• 运行时：延迟绑定加载器会在首次访问 Sprite 时自动加载图集

常见分类模式

按文件夹结构：

GenerateAtlasByFolder("Assets/Art/UI/Buttons", "Assets/Atlases/UI_Buttons.spriteatlasv2");
GenerateAtlasByFolder("Assets/Art/UI/Icons", "Assets/Atlases/UI_Icons.spriteatlasv2");
GenerateAtlasByFolder("Assets/Art/Characters/Player", "Assets/Atlases/Player.spriteatlasv2");

按命名约定：

GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2");
GenerateAtlasByNaming("Assets/Art", "bg_", "Assets/Atlases/Backgrounds.spriteatlasv2");

预构建中的变体生成

为不同分辨率生成变体图集。

高级：手动创建（非默认方案——仅在明确要求时使用）

⚠ 警告：手动创建并非默认方案。仅当用户明确要求手动控制或在开发期间预览编辑器效果时，才使用这些模式。

🚨 默认方案：改用 IPreprocessBuildWithReport 进行预构建生成。请参阅快速入门。

仅在以下情况下适合手动创建：

• 需要精确定位的手动优化 Sprite 布局
• 自定义 Sprite 排序要求
• 在创作工作流中预览编辑器效果
• 用户明确要求

在以下情况下不要使用手动创建：

• 用户要求“创建 Sprite 图集”（使用预构建）
• 用户要求“优化 Sprite”（使用预构建）
• 用户要求自动化工作流（使用预构建）
• 未提及需要特定的手动控制

有关完整的手动创建模式，包括主图集创建、变体创建和运行时加载，请参阅 references/manual-authoring.md。

关键要求（仅适用于 V2）

1. 🚨 务必先检查是否已有脚本：生成代码前，先扫描带有 [UNITY-SKILL:SPRITEATLAS] 标识符的脚本，并询问用户是更新现有脚本还是新建脚本
2. 🚨 务必为生成的脚本添加标记：在每个生成的脚本顶部包含技能标识符，以便日后检测
3. 🚨 务必询问交付方式：生成代码前，询问用户“内置数据还是 Addressables？”
4. 🚨 务必启用 Sprite Packer 模式：在预构建脚本中设置 EditorSettings.spritePackerMode = SpritePackerMode.SpriteAtlasV2
5. 🚨 务必使用预构建生成方式：将 IPreprocessBuildWithReport 作为创建图集的默认方式
6. 🚨 仅添加 Assets/ 文件夹中的精灵：绝不要添加来自 Packages、内置资源或外部位置的精灵
7. 🚨 对于 Addressables 交付，务必生成三个脚本：
   • 带有 Addressables 设置的预构建图集生成器
   • 用于构建 Addressables 内容的 IPostprocessBuildWithReport
   • 延迟绑定运行时加载器脚本（扩展 SpriteAtlasManager）
8. 正确设置 includeInBuild：内置数据设为 true，Addressables 设为 false
9. 两步式编辑器模式：通过 SpriteAtlasAsset 创建 → 保存 → 导入 → 通过 SpriteAtlasImporter 配置 → SaveAndReimport()
10. 绝不要在编辑器代码中使用 SpriteAtlas——但已加载的运行时图集上的 SpriteAtlas.GetPackables() 实例方法除外
11. 变体引用主图集：使用 SetMasterAtlas(SpriteAtlas)，并通过 AssetDatabase.LoadAssetAtPath<SpriteAtlas>() 加载运行时实例
12. 平台格式赋值：直接使用 format = TextureImporterFormat.ASTC_6x6（不要强制转换）
13. 文件扩展名：V2 图集使用 .spriteatlasv2（不是 .spriteatlas）
14. SpriteAtlasUtility.PackAtlases() 为可选项：仅用于编辑器预览；构建时会自动打包

常见错误和无效模式请参阅 references/common-errors.md。

详细参考

• Addressables 交付：references/addressables-delivery.md - 使用 Addressables 的完整延迟绑定设置
• 手动创建：references/manual-authoring.md - 手动模式（不是默认方式，仅在用户明确要求时使用）
• 常见错误：references/common-errors.md - 无效模式和 API 修正
• API 参考：references/api.md - 完整的 V2 类文档
• 自定义打包：references/custom-packing.md - ScriptablePacker 实现
• 最佳实践：references/best-practices.md - 优化建议和常见陷阱

命名空间

编辑器脚本：

using UnityEditor;            // AssetImporter, AssetDatabase
using UnityEditor.U2D;        // SpriteAtlasAsset, SpriteAtlasImporter, SpriteAtlasUtility
using UnityEngine;            // Runtime types (e.g., TextureImporterFormat)
using UnityEngine.U2D;        // SpriteAtlas

运行时脚本：

using UnityEngine;            // Core Unity types
using UnityEngine.U2D;        // SpriteAtlas, SpriteAtlasManager