CubeLand 资产规范

本规范适用于 CubeLand 自有内容及已迁入资产。保留现有 CubeLand 玩法、全部关卡数据、首页与外围框架，以及 PixelFlow 原生炮台、弹体、暂存区、背景和关内 UI 表现。

目录职责

目录	职责
Assets/SGame/CubeLand/Runtime/{Gameplay,Levels,Presentation}	玩法、关卡契约与显示实现
Assets/SGame/CubeLand/Editor/LevelPreview	Tools → 关卡编辑 编辑器与预览
Assets/SGame/CubeLand/Art/Gameplay/{Meshes,Textures,Shaders}	Board 与机关通过稳定 Addressables 地址预载的共享资产；编辑器复用同一份
Assets/SGame/CubeLand/Art/Gameplay/PixelFlow	炮台、弹体、环境、暂存槽及受击/碎裂特效的 Addressables Prefab 入口和按逻辑色 ID 读取的预载材质
Assets/SGame/CubeLand/Art/PixelFlow	PixelFlow 通过 GUID 引用的依赖，按类型归档
Assets/SGame/CubeLand/Art/AutoAtlas	自动图集流程管理的生成结果；与手工图集分开
Assets/SGame/CubeLand/Data/Levels	Addressables 关卡 JSON 与实际索引；清理美术时不改变内容
Assets/SGame/CubeLand	自有游戏根；Runtime/App 管理首页、存档和流程，Runtime/Integration 连接核心玩法，Features 集中活动内容
SDK、第三方插件原目录	保留包的目录、许可证、编辑器及反射加载约定

Art/PixelFlow 按 Fonts、Models、Animations、Materials、Textures、Prefabs、Shaders、VFX、UI 分类；需要细分时使用 Shooters、Projectiles、Trails、Environment。不再嵌套来源项目的 NativeSource/... 目录。来源信息写入美术入口文档，源资产名与内部结构保留。公共资产放在共同父级，私有依赖跟随其功能分类。

不创建只有目录的空骨架，不把同一资源分别复制给运行与预览，不为整理目录新增运行资源目录系统或 catalog。

加载契约

自有运行资源统一使用现有 Addressables 设置。游戏资源不放在 Resources 或 StreamingAssets。SDK 必须的 Resources 设置及原生插件配置遵守供应商机制。

• Data/Levels：887 个 JSON 按 CubeLand/Levels/{相对文件名，含扩展名} 注册；索引和关卡分组独立，关卡按单文件打包。LevelRepository 异步读取 TextAsset 并释放句柄，保留队列、循环和 JSON 内容。
• Art/Gameplay：以 CubeLand/Art/{相对路径，无扩展名} 注册，标签 CubeLand.Art。进关前异步预载，表现层只读取已加载缓存，地图退出时释放租约；不在 Update 内同步加载。
• PixelFlow Prefab 的间接依赖保留普通 Art/PixelFlow，无需为每个依赖单独注册。自有默认字体另以 CubeLand/Art/Fonts/Default 注册。
• 构建信息与预热变体地址为 CubeLand/App/BuildInfo、CubeLand/App/ShaderVariants；首页、UI、配置继续使用现有 AddressableResourceManager。
• 编辑器通过同一地址规则定位真实资产，保存和另存为后自动同步自有组；构建入口显式调用 CubeLandAddressables.SyncAll()。

Addressables 的四个自有组为 CubeLand.Art、CubeLand.Catalogs、CubeLand.Levels、CubeLand.App。同步只维护这些组，保留旧 UI 自定义别名和其他组。迁移资产仍需同时更新动态路径、UIWindow 地址、目录入口和生成器输出；只保留 GUID 不足以覆盖路径绑定。

文件身份与原生表现

移动 Unity 资产必须连同 .meta，保留 GUID 与子资产 fileID。目录合并前检查同名冲突；按计划清理空目录及成对目录 meta。不得为解决冲突生成新 GUID 或批量重建 meta。

保持 PixelFlow Prefab 的内部 TRS、骨骼、材质、贴图、字体、描边、动画与光照参数。保留 CubeLand JSON 色 ID、机关数据和 Core 命中/弹量/队列逻辑。源项目 PixelFlow、AntHaul 与原解包项目保持只读；不得通过修改源文件解决目标工程问题。

第三方代码保留包的名称与许可证。自有新资产使用清晰、可搜索的名称和类型目录，遵循现有语义；禁止仅为风格统一大批改名现有动态地址。

清理与无损压缩

删除以已确认加载根的真实 Editor 依赖闭包为依据，并复核全工程保留入边、序列化 GUID、字符串路径、动态名称与 Addressables 文件夹入口。互相引用但不再使用的一组资源须作为完整子图审核。裸文件名相同可能只是关卡 ID，不等于资源键相同。

仓库文件可使用 PNG 无损重压缩：像素、尺寸、色彩类型、位深、透明度必须一致；保留 ICC/sRGB、gAMA、cHRM 等颜色语义及其他原有非图像数据 chunk，不通过剥离 metadata 改变色彩解释。校验解码像素和语义 chunk 后方可替换。仓库文件瘦身不改变贴图尺寸、压缩平台格式、导入器、动画或网格精度。打包时的平台压缩按下述统一规则处理。

操作与回归证据

操作前记录目标工程、Git 基线、干净/并发修改状态、资产与 meta 哈希、真实 Editor 依赖图、运行根与动态地址。按精确计划移动或删除，避免整个目录的猜测性清空。

操作后检查实际 diff、Core/关卡哈希、Addressables 注册与标签、缺失 GUID、重复 GUID、配对 meta、残留字符串路径、Addressables 入口，以及保留根的依赖回归。PixelFlow 表现根资产和其未优化依赖的内容应保持一致；PNG 压缩用像素及语义等价证据。

脚本编译、Editor 导入、Play Mode、构建与设备表现分别报告。静态依赖通过不能宣称视觉、运行或设备验收；源文件减少的 MiB 不能宣称安装包或运行内存减少。报告分别列明仓库文件体积变化、Resources 收敛范围及尚未执行的构建/运行验证。

编辑器入口

Tools → 资产 → 检查规范 的实现位于 Assets/SGame/CubeLand/Editor/AssetAudit/CubeLandAssetAudit.cs，使用独立编辑器程序集。它只检查资产规范；关卡数据编辑仍使用 Tools → 关卡编辑。工具栏的关卡编辑按钮调用同一现有菜单，不建立第二套关卡入口。

打包纹理设置

仓库 PNG 的无损重压缩只减少源文件；移动端构建使用 Unity 导入产物与 SpriteAtlas，包体和显存优化由 AtlasCompressionTool 的统一平台规则负责。ASTC 是有损 GPU 压缩，不能称为无损。

统一配置及实现位于 Assets/SGame/CubeLand/Editor/Build/AtlasCompressionTool.cs。保留手工图集分组，自动图集按下节生成；统一参考 Hole 的 Android/iOS 规则：

类型	Android / iOS
已有图集的源 Sprite	RGBA32，避免先压缩源图再压缩图集
最终 SpriteAtlas	ASTC 5×5，quality 50
普通颜色贴图有效最大边 ≤512	ASTC 5×5，quality 50
普通颜色贴图有效最大边 >512 且 ≤1024	ASTC 6×6，quality 50
普通颜色贴图有效最大边 >1024	ASTC 8×8，quality 50

有效最大边按各平台独立计算，为原图最大边与当前有效 MaxSize 的较小值。已有更大 ASTC 块的普通贴图保持原设置；其他贴图只改平台 override、format、quality，启用 override 时延续原有效 MaxSize。图集同样保留有效 MaxSize、Packing、分组和引用。

范围为 Assets/SGame（包含 CubeLand 子目录），排除 Editor。保留线性数据、特殊贴图类型、法线、遮罩、调色板/查找表、HDR 与独立字体贴图的现有设置；TMP 内嵌字库不参与。不得整份套用 TextureImporter Preset，以免改变类型、sRGB、Alpha、Mip、Wrap、Read/Write、Sprite Border/Pivot 或切片。SDK/插件和其他平台配置保持各自约定。

• Tools → 资产 → 预览打包纹理设置：只读扫描，报告写 Library/CubeLand/texture-build-preview.json，不改资产或 meta。
• Assets → 工具 → 自动处理图集和孤儿纹理压缩：应用同一规则，按需重导入已改变的 Importer，报告写 Library/CubeLand/texture-build-apply.json。不会全局 SaveAssets。
• JenkinsBuild.ChangeSymbol → BuildBase.ChangeSymbol：调用 AutoAtlasAnalyzer.RunForBuildPipeline(3, 1024)，先同步自动图集再应用统一纹理规则。
• BuildBase.BuildBundle 在 BuildPipeline.BuildPlayer 前运行相同图集流程；覆盖直接调用 Build/BuildTest 的路径。
• JenkinsBuild.ProcessAtlasCompression 和既有 Spine 独立入口继续可用，Spine 复用相同规则。

应用设置会持久修改对应 meta；构建流程不自动回滚。只读预览不执行导入；实际应用、图集打包与完整 Player 构建分别验收。

自动图集打包

Tools → 资产 → 自动图集打包 与 JenkinsBuild.ProcessAutoAtlases() 复用 AutoAtlasAnalyzer。打包准备和直接构建入口调用 RunForBuildPipeline(3, 1024)；独立预执行使用相同入口，不调用签名、SDK 配置或 Player 构建。

ProjectSettings/EditorSettings.asset 已配置与 Hole 相同的 SpriteAtlasV2Build（仅构建启用），并纳入版本管理。执行时保证当前 Editor 进程使用 V2；已有 V2 模式保留。只读分析不改变开关。工具不通过全局保存持久化其他脏资产。

流程先扫描 Assets/SGame（包含 CubeLand 子目录，避免重叠扫描） 的 Prefab 中 Image、SpriteRenderer、SpriteMask 与 Selectable 状态 Sprite。按相同 Prefab 引用集合分组：单张组保留独立；独占组独立成图集；共享组至少 3 张独立成图集，小共享组合并 Common；Common/Icon 按直接所属目录归类，覆盖按路径动态加载的图标。原图任一边大于 1024 的纹理保持独立。Editor、SDK/插件、Spine、NoAtlas、字体、线性数据、次级 Sprite 贴图及不兼容的滤波/Mip 配置不参与自动分组。源图和动态地址不移动。

已有手工图集优先拥有成员，自动分组不会重复收录。只在 Assets/SGame/CubeLand/Art/AutoAtlas 创建和同步标有 CubeLand.AutoAtlasAnalyzer/v1 的图集；其他目录和未标记图集不清理。有外部引用的已生成图集保留身份及成员。图集名含稳定分组签名，成员改变时保留路径对应的 GUID；内容和最终设置不变时不写回、不重导入。只读分析报告为 Library/CubeLand/auto-atlas-preview.json，实际执行报告为 Library/CubeLand/auto-atlas-apply.json。

新自动图集采用 Hole 的 padding 8、禁旋转、禁 Tight Packing、Alpha Dilation、Bilinear、sRGB、无 Mip、不可读和 Include in Build。MaxSize 沿用 Hole 的原始 Sprite 面积与 85% 填充估算，在 256～8192 中选择；它是每页上限，可能生成多页，不表示源图降分辨率。现有手工图集的 Packing、纹理语义、成员和尺寸保持原约定；自动和手工图集的移动平台压缩都交给统一规则。新增图集使用 Unity 原生 SpriteAtlasAsset API 写入，无全局 SaveAssets。

首次执行后应检查旧图集身份与成员、自动成员唯一归属、源图/Prefab/关卡与运行代码内容、实际导入和图集打包；再次执行应为零变更。Editor 图集打包不是完整移动端构建或设备画质验收。

程序集与目录边界

SGameAssembly.asmdef 保留在 SGame 根；公共 Core 与 App/Features 维持现有程序集，不在目录整理中拆分双向依赖。Gameplay、Levels、Presentation 继续独立，通用 Addressables 句柄作用域放在 CubeLand.Assets。Editor/Build 使用 Core.Editor asmref 保持原编译归属；SDK和Config固定目录保留。自动图集签名按迁移前路径规范化，保证目录迁移不重建原图集。