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. 交付机制（必需）
询问："您希望如何交付精灵图集？"
选项 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 的零值，因此任何没有人设置过它的项目都携带打包 Disabled，而在 Disabled 状态下创建的图集仍然可以导入、仍然作为资源显示、仍然看起来完成了，但永远无法打包。Unity 在 Inspector 中会这样说："Sprite Atlas packing is disabled"。工作流中的其他任何步骤都不会失败，因此以这种方式交付的图集会被视为成功。不要假设项目已配置好：请读取该值。
因此，不要认为 "我已经设置了" 就完成了。设置之后，再次读取 EditorSettings.spritePackerMode，确认它不是 Disabled，并报告您实际读取到的值。如果您无法读回，请说明，不要假设写入已生效。
不要直接编辑 meta 文件。
🚨 关键：默认方法为预构建生成
始终使用 IPreprocessBuildWithReport 在构建管道期间自动生成或更新 SpriteAtlas。 这是默认且必需的方法，除非用户明确要求手动创作。
❌ 不要创建手动菜单项脚本
除非明确要求，否则切勿创建带有 [MenuItem] 属性的图集生成脚本。 预构建方法消除了手动点击的需要。仅在以下情况下使用手动创作：经过手动优化的布局、特定的精灵排列或编辑器预览需求。请参阅 高级：手动创作。
🚨 关键：精灵源位置限制
仅添加项目 Assets 文件夹中的精灵。切勿添加来自 Unity 内建资源、包或外部位置的精灵。 Unity 内建资源无法打包到 SpriteAtlas 中，而包资源可能会引起导入/依赖问题。
关键的 V2 架构
| 上下文 | 组件 | 用途 | 允许的使用方式 |
|---|---|---|---|
| 编辑器 | SpriteAtlasAsset | 在编辑器资源中定义图集配置 | 创作、设置纹理/打包/平台设置 |
| 编辑器 | IPreprocessBuildWithReport | 在构建时自动生成 SpriteAtlasAsset | 构建前的默认方案 |
| 运行时 | SpriteAtlas | 在构建或使用 LoadByLocation（延迟绑定）时加载的运行时对象 | 仅用于访问 Sprite；不得在运行时创建 |
| 运行时 | UASSETBUNDLE/ADDRESSABLES | 包含图集用于按需加载 | 与包含 includeInBuild = false 的 SpriteAtlasAsset 一起使用 |