CLI 图片与动画导出
将已保存的 .resprite 工程导出为单张 PNG、PNG 序列帧或规则图集。动画导出通过 manifest.json 描述图片和播放顺序。图片使用原画布尺寸、透明背景、零边距和 1 倍尺寸，空白帧也会保留。
本文的 resprite-cli 是命令简写。请先按平台使用指南设置实际调用路径：macOS / Linux AppDir 使用 "$cli"，Windows PowerShell 使用 & $cli，Linux AppImage 使用 "$cli" --cli。在终端中进入已保存 hero.resprite 的目录，再运行示例。CLI 使用独立选项，不读取编辑器导出偏好。每个示例使用不同的目标；首次执行时目标应不存在，父目录需预先创建。
导出单帧图片
resprite-cli export image hero.resprite --output hero-still.png --frame 0
成功后在工程旁生成 hero-still.png，合成可见图层并保留透明度。帧号从 0 开始。之后需要替换这张 PNG 时，在同一命令后加上 --overwrite。
导出序列帧
resprite-cli export frames hero.resprite --output hero-frames
成功后，hero-frames/manifest.json 记录帧与图片的对应关系，PNG 位于该目录下的 builds/ 中。每个源帧在每个图层导出单元中只输出一次；倒放或往返播放通过清单表达，不额外复制 PNG。
导出规则图集
resprite-cli export sheet hero.resprite --output hero-sheet --columns 8
成功后，在 hero-sheet/manifest.json 中读取图集图片路径及各帧区域。--columns 为每行列数，必须是正整数，默认 8；最后一行不足列数时保留透明空位。两个示例使用不同输出目录，可以分别尝试。
选择动画片段与拆分图层
先运行 resprite-cli inspect hero.resprite，在结果的 clips 数组中找到需要的片段，拷贝其 id，并替换下面的 CLIP_ID：
resprite-cli export sheet hero.resprite --output hero-clip --clip-id CLIP_ID --split-layers
--clip-id选择单个片段；不指定时导出整个时间轴。ID 来自inspect的clips[].id，同名片段也可准确区分。找不到指定 ID 时返回退出码 2。--split-layers拆分可见图层，沿用编辑器的分组拆分规则；设置为不拆分的组作为一个导出单元，隐藏图层不参与。不指定时合成全部可见图层。- 可以通过
--dry-run先查看实际拆分单元和输出计划，详见预演。
读取导出结果
典型目录如下；实际图片名称以清单为准：
hero-sheet/
manifest.json
builds/
<buildId>/
sprite.png
进程成功退出后，读取一次 manifest.json，按以下顺序加载动画：
- 选择
animations中的动画及其中一个tracks条目。 - 按该条目的
regions索引顺序，读取顶层regions中的帧区域。 - 用区域的
image索引找到images中的图片，将图片的path相对于manifest.json所在目录解析。 - 显示图片中的
x/y/width/height区域，持续durationMs毫秒，再播放下一个区域。拆分图层时，各轨道分别对应一个图层导出单元。
下面是一个无片段、单帧工程的清单摘录，仅展示读取关系；省略了版本、来源及校验字段，<buildId> 代表实际生成的目录名：
{
"images": [
{"path": "builds/<buildId>/sprite.png", "width": 16, "height": 16}
],
"regions": [
{"image": 0, "layerUnit": 0, "sourceFrame": 0, "frameId": "frame-1",
"x": 0, "y": 0, "width": 16, "height": 16,
"durationUnits": 1000, "durationMs": 100}
],
"tracks": [{"layerUnit": 0, "layerIds": null, "regions": [0]}],
"animations": [
{"id": null, "name": "timeline", "direction": "Forward",
"tracks": [{"layerUnit": 0, "regions": [0]}]}
]
}
本例帧率为 10 FPS：区域 0 从图片 0 的左上角取 16 × 16 像素，显示 100 毫秒。所有索引从 0 开始，区域坐标原点是图片左上角，单位为输出像素。
animations[].tracks[].regions 已按正放、倒放或往返方向展开，直接按顺序播放即可，不要再次应用 direction。durationMs 可以是小数，应累计精确时间，避免逐帧取整导致漂移。重复引用同一区域时，仍使用该区域时长。
更新与清理
首次导出时，输出目录必须不存在，父目录必须已存在。源工程应放在输出目录之外。更新上面已生成的图集可执行：
resprite-cli export sheet hero.resprite --output hero-sheet --columns 8 --overwrite
--overwrite 只更新本 CLI 创建且清单和当前图片均完整的目录，不能接管普通目录或修复损坏产物。清单包含校验信息，不支持手工修改；需要改变内容时重新导出。
更新会保留旧构建，以便已读取旧清单的程序继续加载。旧构建和中断后的残留不会自动清理，输出目录可能持续增长。始终按清单加载图片，不要扫描 builds 或推断文件名。
同一输出目录不能同时导出；遇到 output_busy / 退出码 4，应等待占用任务结束后重试。输出父目录中保留的 .resprite_cli_lock_<摘要> 是正常锁文件，存在并不表示任务仍在运行。所有 CLI 任务停止前，不要删除锁文件或清理相关目录；清理时还应确保没有程序在读取旧构建。
超时或强制结束后，可能已生成新产物但未返回成功报告，应按进程失败处理，核对清单和产物后再决定是否重试。渲染失败不会逐文件覆盖旧资源，但这不等于断电恢复保证。