提交前发现图集错帧：为 JSON 与 PNG 增加结构验收

本文由 FrameSprite 作者工作流整理，AI 辅助编写，引用原始技术资料；构造案例不代表模型或引擎实测。

以有效与无效样本检查矩形范围、唯一帧键、动作引用和允许的打包特性，形成可运行交付检查。

简要答案

JSON 能解析只证明语法成立。交付检查还需验证真实纹理尺寸、有限整数坐标、正尺寸、矩形边界、唯一帧身份与动作引用。当前加载器不支持的旋转或多页特性应明确拒绝。为每个检查保留一个无效样本，命令失败时阻止交付，而非只输出警告继续发布。

适用范围

• 多个角色和动作批量交付，人工预览无法发现所有缺帧或越界矩形。

不适用范围

• 数据格式尚未声明，无法判断字段代表存储区域还是原始画布。

1. 声明导入器能力

写清支持固定网格或哪种 atlas 格式，是否支持旋转、裁边与多页。选择最小检查范围先覆盖实际交付，不应创建无法验证的万能转换器。

2. 验证尺寸与坐标

从真实图片取得宽高，坐标必须为有限整数，w/h 必须正数，x/y 不为负，x+w 和 y+h 不超过纹理。源尺寸与存储尺寸需按格式区分；旋转时不可机械把两者当同一矩形。

3. 检查身份与引用

对数组形式帧数据检测重复键，动作表必须只引用存在的帧。固定网格还应排除未用空格。常规 JSON.parse 不会保留重复对象键的全部记录，因此重复字段检测应在源层或明确数组结构进行。

4. 用失败样本证明检查有效

保留有效包、越界区域、缺帧引用和重复 ID 样本，检查退出码。再用帧灵实际导出通过结构验收后做视觉审查。结构正确不代表脚底、动作或透明边缘合格。

构造示例：128 像素纹理边界

纹理 128×128；有效区域 x=96,w=32，错误区域 x=100,w=32。

96+32=128 可接受；100+32=132 越界 4 像素，必须拒绝。

这里只证明几何检查，实际文件解码、格式兼容与动作效果另行验证。

最小交付失败条件

先检查越界，再检查画面是否好看

一张 256×128 图集，矩形 (240,0,16,32) 的右边界为 256，可以进入解码与预览检查；(244,0,16,32) 的右边界为 260，已经越界 4 像素，应立即失败。再检查坐标是否非负、宽高是否为正、帧名称是否唯一、动作引用是否存在。结构检查通过不代表顺序正确或动画连续，因此流水线还要保留逐帧预览和引擎导入验收。发布时让图片、JSON 和版本清单一起提交，避免运行时取得新图却继续使用旧坐标。

• 验收：几何边界
• 验收：帧引用
• 验收：版本一起发布

验证器不负责重新设计错误数据

发现越界后自动截短矩形，可能隐藏错帧并让动作尺寸变化；缺失帧自动用第零帧，也会把导出问题伪装成可用动画。检查应给出明确文件、帧键与原因，让制作端修复并重新导出。通过后保留验收记录与原始素材修订。

编辑与示例说明

本次补充由 AI 辅助整理，按公开原始技术资料核对。可下载的输入与预期结果是原创构造案例，不代表模型或引擎实测；实际项目应按步骤保留自己的验收记录。

常见问题

JSON.parse 成功代表可以导入吗？

不代表，还需字段、几何、引用与格式能力检查。

缺失帧可以自动补第一帧吗？

不应静默处理，否则掩盖交付错误。

结构验收能判断动作好不好吗？

不能，仍需游戏尺度下的视觉验收。

来源与补充材料

JSON.parse · MDN

TexturePacker command line parameters · CodeAndWeb

原文：https://cn.framesprite.com/guides/sprite-atlas-json-ci-structural-validation