在 Unity 6000.3+ 项目中自动创建/管理…

适用于 Unity 6000.3+ 项目，通过 IPreprocessBuildWithReport 预构建脚本自动生成/更新 SpriteAtlas V2，并配置内置数据或 Addressables 延迟绑定交付。

适用场景

解决思路

1. 写任何代码前，先阅读随附 resources/ 文件；任何图集工作先读 resources/authoringvsruntime.cs、references/common-errors.md。
2. 若走预构建生成（默认），先读 resources/spriteatlasprebuildgenerator.cs、resources/enablespritepacking.cs、resources/savespriteatlasasset.cs。
3. 若走 Addressables 延迟绑定，先读 resources/buildaddressablespostprocess.cs、resources/spriteatlaslatebinding.cs、resources/handlelatebinding.cs。
4. 若可能使用旧 API，先读 resources/deprecatedmethods.cs、resources/dontscriptspriteatlasineditor.cs、resources/dontpackinruntimebuilds.cs。
5. 若任务不在资源表中，浏览 resources/ 目录（共 38 个文件，含 custom packers、variants、platform settings、runtime access），不要凭记忆调 API。
6. 第一步扫描项目，查找包含标识符 `// [UNITY-SKILL:SPRITEATLAS]` 的已有 SpriteAtlas 脚本。
7. 若找到已有脚本，按给定格式告诉用户已找到的 Prebuild Generator、Addressables Builder、Runtime Loader 路径，并询问要如何处理。
8. 向用户提供选项：Option A 更新现有脚本（在现有路径重新生成，保留位置，更新到最新版，可能覆盖自定义修改）；Option B 用不同名称创建新脚本（与原脚本并存，需指定新名称/路径）；Option C 中止并保持现有不变。
9. 处理用户选择：若选 A，在现有路径重新生成，并将版本递增到 2.0.1+；若选 B，询问新脚本名（如 SpriteAtlasPrebuild_Custom.cs）后生成；若选 C，立即停止并告知未做更改。
10. 生成代码前询问交付机制：选 A 内置数据立即加载，还是选 B 通过 Addressables 延迟绑定按需加载。
11. 若选 Option A 内置数据：设置 includeInBuild=true，生成 1 个预构建生成脚本；适合核心 UI、主线玩法、始终需要的资源。
12. 若选 Option B Addressables：设置 includeInBuild=false，创建每个图集的 Addressables 条目，把 addressable 设置加入预构建步骤，必须构建 Addressables 内容作为构建步骤，并必须创建延迟绑定运行时加载脚本。
13. Addressables 交付必须生成全部三个脚本，不能只生成一两个：1) IPreprocessBuildWithReport 预构建脚本，生成图集并创建 Addressables 条目；2) IPostprocessBuildWithReport 构建 Addressables 内容 bundles；3) MonoBehaviour 延迟绑定运行时加载器，通过 SpriteAtlasManager 按需加载。
14. 启用 Sprite Packer 模式：使用 resources/enablespritepacking.cs 中的代码设置 EditorSettings.spritePackerMode 并配置导入器的打包设置。
15. 不要直接编辑 meta 文件。
16. 设置 Sprite Packer 模式后，读回 EditorSettings.spritePackerMode，确认不是 Disabled，并报告实际读到的值；如果无法读回，说明这一点，不要假设写入成功。
17. 默认且必须使用 IPreprocessBuildWithReport 在构建管线中自动生成或更新 SpriteAtlases，除非用户明确要求手动编写。
18. 不要创建带 [MenuItem] 属性的手动菜单脚本用于图集生成，除非用户明确要求；预构建方式不需要手动点击。
19. 只从项目的 Assets/ 文件夹添加精灵；绝不要从 Unity 内置资源、Packages 或外部位置添加精灵。
20. 在 V2 中严格区分上下文：编辑器授权用 SpriteAtlasAsset、SpriteAtlasImporter；编辑器打包预览可选 SpriteAtlasUtility.PackAtlases()；运行时用 SpriteAtlas、SpriteAtlasManager。
21. 禁止跨上下文用法：编辑器代码不要 new SpriteAtlas()；不要在编辑器用 AssetDatabase.LoadAssetAtPath<SpriteAtlas>(...)；不要在编辑器用 SpriteAtlasAsset.GetPackables()；不要在编辑器脚本修改 SpriteAtlas；变体应从 Master 运行时 SpriteAtlas 创建，而不是从原始 packable 对象（精灵/文件夹）创建。
22. 在 IPreprocessBuildWithReport.OnPreprocessBuild() 中实现核心 V2 工作流，而不是手动脚本。
23. 创建预构建脚本：在 Editor 文件夹创建 IPreprocessBuildWithReport 脚本，按交付选项定制。
24. 编辑 OnPreprocessBuild 方法，按项目精灵组织匹配一种或组合多种分类策略：按文件夹、按命名约定、按资产标签、按场景。
25. 按文件夹分类示例：调用 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")。
26. 按命名约定分类示例：调用 GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2")、GenerateAtlasByNaming("Assets/Art", "bg_", "Assets/Atlases/Backgrounds.spriteatlasv2")。
27. 在预构建中为不同分辨率生成 variant atlases（变体图集）。
28. 构建项目；图集会在构建期间自动生成/更新，无需手动菜单点击。Option A 图集包含进构建，运行时可立即使用；Option B 还会自动创建 addressable 条目、构建 Addressables 内容 bundle，并在运行时由延迟绑定加载器在精灵首次访问时自动加载图集。
29. 仅在用户明确要求手动控制或编辑器预览时使用高级手动授权模式，适合手工优化布局、自定义精灵排序、编辑器预览或用户明确要求。
30. 不要在这些情况下使用手动授权：用户只说创建 sprite atlas、优化 sprites、要求自动化工作流、未提到手动控制；这些应使用预构建。手动授权完整模式见 references/manual-authoring.md。
31. Key Requirement 1：生成代码前始终先检查包含 [UNITY-SKILL:SPRITEATLAS] 标识的已有脚本，并提示用户更新或新建。
32. Key Requirement 2：始终给生成的脚本打标签，在每个生成脚本顶部包含技能标识符，便于以后检测。
33. Key Requirement 3：生成代码前始终询问交付机制：Built-in data 还是 Addressables。
34. Key Requirement 4：始终启用 Sprite Packer 模式：在预构建脚本中设置 EditorSettings.spritePackerMode = SpritePackerMode.SpriteAtlasV2。
35. Key Requirement 5：始终使用预构建生成，把 IPreprocessBuildWithReport 作为默认图集创建方式。
36. Key Requirement 6：只从 Assets/ 文件夹添加精灵，绝不从 Packages、内置资源或外部位置添加。
37. Key Requirement 7：Addressables 交付时始终生成三个脚本：预构建图集生成器含 Addressables 设置、IPostprocessBuildWithReport 构建 Addressables 内容、扩展 SpriteAtlasManager 的延迟绑定运行时加载器脚本。
38. Key Requirement 8：正确设置 includeInBuild：内置数据为 true，Addressables 为 false。
39. Key Requirement 9：使用两步编辑器模式：用 SpriteAtlasAsset 创建 → 保存 → 导入 → 通过 SpriteAtlasImporter 配置 → SaveAndReimport()。
40. Key Requirement 10：编辑器代码中绝不要使用 SpriteAtlas，除非在已加载的运行时 atlas 上调用实例方法 SpriteAtlas.GetPackables()。
41. Key Requirement 11：变体引用 master：使用 SetMasterAtlas(SpriteAtlas)，其中运行时实例通过 AssetDatabase.LoadAssetAtPath<SpriteAtlas>() 加载。
42. Key Requirement 12：平台格式赋值直接使用 format = TextureImporterFormat.ASTC_6x6，无需强制转换。
43. Key Requirement 13：V2 图集使用文件扩展名 .spriteatlasv2，不是 .spriteatlas。
44. Key Requirement 14：SpriteAtlasUtility.PackAtlases() 是可选的，仅用于编辑器预览；构建时打包会自动进行。
45. 编辑器脚本命名空间使用：using UnityEditor; using UnityEditor.U2D; using UnityEngine; using UnityEngine.U2D;。
46. 运行时脚本命名空间使用：using UnityEngine; using UnityEngine.U2D;。
47. 详细参考：Addressables 交付见 references/addressables-delivery.md；手动授权见 references/manual-authoring.md；常见错误见 references/common-errors.md；API 参考见 references/api.md；自定义打包见 references/custom-packing.md；最佳实践见 references/best-practices.md。

适用边界 · 注意事项

• 不适用于 Unity 6000.3 之前的版本。
• 当用户明确要求手动编写、手工优化布局、精确精灵排列或编辑器预览时，不要使用默认预构建方法，改用手动授权。
• 当精灵来自 Unity 内置资源、Packages 或项目外部位置而非项目 Assets/ 文件夹时，不能使用本方法添加进图集。