# API Reference

本页说明常用入口。由当前源码生成的完整公共类型与函数签名见根目录 `pkg.generated.mbti`；CI 使用 `moon info --target all` 检查接口快照是否与实现一致。

## JSON Parsing

`parse_sprite_sheet_json(input : String) -> PixelAnimParseResult`

解析 Aseprite 导出的 sprite sheet JSON。支持 `frames` 为数组或对象的两种常见导出形式。

`validate_sprite_sheet_json(input : String) -> ValidationReport`

解析并校验 JSON，适合 CLI 或资源流水线直接调用。

## Binary Parsing

`parse_aseprite_binary(bytes : Array[Int]) -> AseParseResult`

读取 `.ase/.aseprite` 文件头、帧头和常见 chunk 元数据。v1 的定位是结构检查与动画元数据提取，不进行 compressed cel 像素解压。

`validate_ase_file(file : AseFile) -> ValidationReport`

检查 canvas、帧数量、色深和 compressed cel 等二进制结构风险。

## Runtime

`build_animation_library(sheet : SpriteSheet) -> AnimationLibrary`

将 `frameTags` 转为可运行的 `AnimationClip` 集合；如果没有 tag，会生成 `all` fallback clip。

`AnimationPlayer::new(library, clip_name?)`

创建轻量播放器状态。

`AnimationPlayer::step(delta_ms)`

按毫秒推进当前 clip，并消费跨越多帧的完整时间增量；支持 once、repeat 和 pingpong。

`sample_clip_at(clip, elapsed_ms)`

按时间点采样某个 clip 当前帧，适合 deterministic test 或离线导出。

## Boxes

`build_frame_box_table(sheet : SpriteSheet) -> FrameBoxTable`

根据 `meta.slices` 构建帧级 box 表。slice 名称包含 `hit`、`hurt`、`collision`、`solid`、`origin` 时会自动分类。

`FrameBoxTable::for_frame(frame_index)`

获取某一帧的所有 box。

`has_required_box_kinds(table, require_hit?, require_hurt?, require_collision?)`

检查游戏项目常用 box 是否齐全。

## Export

`export_runtime_manifest(sheet : SpriteSheet) -> String`

导出 JSON manifest，包含 atlas、clips、frames、boxes。

`export_phaser_animation_plan(sheet : SpriteSheet) -> String`

导出 Phaser 3 动画创建计划，方便接入 Phaser 项目。

`build_canvas_draw_plan(sheet, scale?)`

生成 Canvas 绘制命令数组，适合教学、调试和 WebAssembly demo。

## Report

`asset_report_from_json(input, format?)`

输出 text/json 两种资源报告。

`ase_binary_report(bytes, format?)`

输出 `.ase/.aseprite` 结构报告。

## Analytics

`analyze_sprite_sheet(sheet) -> SpriteSheetStats`

统计 frame/tag/slice/layer 数量、atlas 面积、已使用面积、利用率、trimmed/rotated 帧数量和 duration 范围。

`build_sheet_timeline(sheet)`

生成全局帧时间轴。

`build_tag_timeline(sheet, tag_name)`

生成单个动画 tag 的时间轴。

`timeline_frame_at(entries, elapsed_ms, looped?)`

按毫秒采样时间轴。

`check_asset_policy(sheet, policy)`

按项目策略检查素材是否符合游戏运行要求，例如是否必须有 frameTags、是否必须有 hitbox/hurtbox/collision box、是否允许 rotated frame 等。

## Naming

`split_frame_name(name)`

将 `hero_run_12` 这类名称拆成 stem 与数字后缀。

`group_frame_names(sheet)`

按 stem 统计帧名序列。

`inspect_frame_name_groups(sheet)`

检查编号缺口和疑似单帧分组。

`naming_report_text(sheet)`

输出适合 CI 日志阅读的命名报告。

## Compatibility

`check_export_compatibility(sheet, options?)`

按 Phaser 3、Canvas 2D、runtime manifest 或严格游戏素材策略检查导出兼容性，覆盖 frameTags、slices、hitbox/hurtbox/collision box、rotated frame、atlas 尺寸和帧时长。

`validate_sprite_sheet_json_for_export(input, options?)`

把 JSON 解析、基础校验和导出兼容性检查合并为一个入口，适合资源构建流水线和 CI。

`recommended_aseprite_export_flags(options?)`

返回建议的 Aseprite CLI 导出参数，帮助项目固定 `--list-tags`、`--list-slices` 等关键开关。