# Integration Guide

## 安装与导入

```bash
moon add WangYF0829/moonpixelanimkit
```

在使用方 `moon.pkg` 中导入 `WangYF0829/moonpixelanimkit`，代码中通过 `@moonpixelanimkit` 调用公开 API。解析结果和校验报告都应先检查 `ok`，再进入运行时或导出流程。

## 推荐资源导出方式

在 Aseprite 中导出 sprite sheet JSON，并保留 `frameTags` 和 `slices`：

```bash
aseprite hero.aseprite --batch --sheet hero.png --data hero.json --format json-array --list-tags --list-slices
```

MoonPixelAnimKit 的 v1 输入重点是 `hero.json`。图片渲染交给 Canvas、Phaser 或其他运行时。

## Phaser 接入

1. 用 `parse_sprite_sheet_json` 解析 JSON。
2. 用 `validate_sprite_sheet` 检查资源问题。
3. 用 `export_runtime_manifest` 或 `export_phaser_animation_plan` 生成运行时数据。
4. 在 JS/Phaser 侧加载 `hero.png`，按 manifest 注册动画。

## Canvas 接入

1. 用 `build_canvas_draw_plan(sheet, scale=1)` 获取绘制命令。
2. 每个命令包含 source rect、destination rect 和 duration。
3. 渲染层使用自己的 `drawImage` 实现。

## CI 资源检查

项目可以在 CI 中加入一个小程序读取导出的 JSON 字符串，调用：

```moonbit
let report = @moonpixelanimkit.validate_sprite_sheet_json(json_text)
assert_true(report.ok)
```

这样可以在提交资源时提前发现重复帧名、非法 tag 范围、缺失碰撞盒等问题。

## 版本边界

`0.1.x` 关注 Aseprite 常见导出 JSON 和 `.ase/.aseprite` 元数据。compressed cel 像素解压、Tileset 像素流、图像处理和纹理打包不在支持范围内。解析器识别 compressed cel 并返回诊断，调用方不能把元数据解析成功等同于像素已解码。

项目使用纯 MoonBit 数据处理，不要求 Aseprite、Phaser 或 Canvas 作为运行依赖。Aseprite CLI 只用于资源作者生成 JSON 和图片，渲染器只消费导出计划。