# SpineViewer（Eagle 插件）

一个 **完全离线** 的 Eagle 格式扩展插件，用于在 Eagle 中直接预览由 Spine 导出的骨骼动画。

插件只接管「骨骼数据」和「纹理图集数据」类型的预览：
- 骨骼数据：`skel`、`skel.bytes`、`json`
- 纹理图集数据：`atlas`、`atlas.txt`

普通图片（`png/jpg/jpeg/webp`）仍由 Eagle 原生预览，插件不接管。

支持的 Spine 版本：**3.6 / 3.7 / 3.8 / 4.0 / 4.1 / 4.2 / 4.3**。

> 关键特性：无需网络、不走 CDN。所有 Spine 官方运行时代码都已拷贝到插件本地 `lib/` 目录，不含 git 子模块。

---

## 目录结构

```
SpineViewer/
├─ manifest.json              # 插件清单（预览扩展注册）
├─ logo.png                   # 插件图标
├─ assets/
│  └─ spine-badge.png         # 缩略图右下角使用的 Spine 官方 badge
├─ thumbnail/
│  └─ spine.js                # 缩略图生成（渲染骨骼首帧并交由 Eagle 缓存）
├─ viewer/
│  └─ spine.html              # 预览页面（动画播放 / 动画/皮肤切换 / 速度 / 缩放适配）
├─ js/
│  ├─ spine-utils.js          # 资源匹配、版本检测工具
│  └─ spine-render.js         # 纯 Node 渲染模块（缩略图用）
├─ lib/                       # 各版本 Spine 官方运行时（已拷贝到本地）
│  ├─ 3.6/ spine-canvas.js
│  ├─ 3.7/ spine-canvas.js
│  ├─ 3.8/ spine-canvas.js
│  ├─ 4.0/ spine-canvas.js
│  ├─ 4.1/ spine-canvas.js
│  ├─ 4.2/ spine-canvas.js
│  └─ 4.3/ spine-canvas.js
├─ LICENSES/                  # 第三方运行时及依赖的再分发许可证
└─ node_modules/              # 可选：@napi-rs/canvas（用于高质量缩略图渲染）
```

---

## 工作原理

1. **跨文件夹资源配对**：Eagle 会把导入的每个文件拆分成独立的元数据文件夹（`images/<id>.info/`，内含资产文件与 `metadata.json`），因此配套文件可能不在同一目录。插件会：
   - 定位到所选文件的 item 文件夹；
   - 扫描其**同级的所有 item 文件夹**，根据文件名（忽略 `-pro`、`-ess`、`-pma` 等常见后缀）自动关联出配套的 **骨骼文件** + **atlas** + **贴图**；
   - 从 atlas 中解析它引用的贴图页面，再到库中定位实际贴图文件。
2. **版本检测**：读取骨骼数据里的版本号（`.json` 读 `skeleton.spine`，`.skel` 读二进制头部），自动选择匹配的本地运行时。
3. **预览**：查看器通过 Node `fs` 直接读取分离在各 item 文件夹中的骨骼/atlas/贴图文件（无需网络、无 CORS），用 `spine-canvas` 渲染器在 `<canvas>` 上实时播放动画，并支持：
   - 动画列表切换
   - 皮肤切换
   - 播放 / 暂停（空格）
   - 循环开关
   - 播放速度调节
   - 预乘 Alpha（PMA）贴图渲染开关
   - 时间轴拖动、动画时长、秒刻度与关键帧标记
   - 零时长动画按单帧静态姿势预览
   - 自动适配并居中
   - 将当前帧设为自定义缩略图，并通知 Eagle 立即刷新列表缓存
4. **缩略图**：使用 `@napi-rs/canvas` 在 Node 中跨 item 文件夹读取资源并渲染骨骼首帧。自动生成和预览器中手动点击“生成缩略图”都会在右下角添加 Spine 官方 badge，便于识别数据文件。导入时会等待同批文件写入稳定，再按入库批次配对，避免复用旧库里的同名资源。处理器写入 PNG 工作图，最终缩略图缓存格式由 Eagle 决定，可能是体积更小的 WebP。
   - 同一前缀的 `atlas/json/skel` 共用资源发现和渲染任务，完成后主动补刷这一组的全部数据条目。
   - JSON 只在存在 Spine 官方导出的 `skeleton.spine` 版本字段时才按骨骼数据处理；普通 JSON、JSONC 和仅含 `bones` / `slots` 同名字段的数据会立即生成中性文件缩略图，不进入全库资源扫描或补刷队列。
   - 暂时缺少骨骼、atlas 或贴图时，前台最多短暂等待约半秒便显示回退图；后台采用逐步降频的方式观察约两分钟。链路补齐且文件稳定后自动生成 WebP 并通知 Eagle 刷新；更晚补拖的文件会通过新的导入回调重新触发识别。
   - 分批拖入时优先在同一个 Eagle 文件夹内补齐；大型文件夹导入会共享短时文件索引，避免每个条目重复扫描整个库。

---

## 使用说明

- 将 Spine 导出的一整套文件（`.skel`/`.json` + `.atlas` + `.png` 等）放在**同一个文件夹**并导入 Eagle。
- 点击其中任何一个文件即可预览动画；点击配套的贴图或 atlas 也会自动找到整套资源。

---

## 关于新版/旧版二进制

- **3.8 / 4.x** 的 `.skel` / `.skel.bytes` 二进制文件完整支持。
- **3.6 / 3.7** 的官方 JS 运行时 **不包含二进制解析器**，且其二进制格式与 3.8 不兼容。因此这两版的 `.skel` / `.skel.bytes` 无法由官方 JS 运行时直接加载。同批存在 **JSON** 时，插件会用 JSON 为 `atlas/json/skel` 三个条目生成相同的骨骼缩略图；没有 JSON 时则显示实际 atlas 贴图预览。

---

## 可选依赖说明

`@napi-rs/canvas` 仅用于缩略图的高质量渲染。它并非必需：
- 若保留 `node_modules/`（当前平台原生二进制），缩略图会渲染骨骼形象。
- 若删除 `node_modules/`，插件仍可正常预览动画，缩略图会显示一条纯 JS 占位图。

如需在多个平台分发，请安装对应平台的 `@napi-rs/canvas` 原生二进制。

---

## 分享与打包

### 分享源码

仓库中的 `node_modules/` 被 `.gitignore` 忽略是正常的。接收者克隆源码后，需要在插件目录执行：

```bash
npm ci --omit=dev
```

`@napi-rs/canvas` 会按当前操作系统和 CPU 下载预编译的 N-API 二进制，正常情况下不需要编译，也不需要安装 Rust/C++ 工具链。安装完成后，再从 Eagle 插件面板加载或打包插件。

### 分享可直接安装的插件

1. 在准备出包的目标系统上执行 `npm ci --omit=dev`。
2. 确认插件目录中保留了 `node_modules/`。否则骨骼动画仍可预览，但自动缩略图只能使用占位图。
3. 在 Eagle 中打开插件面板（快捷键 `P`），右键此插件并选择“打包插件”。
4. 把生成的 `.eagleplugin` 文件发给对方。对方直接安装，不需要再执行 npm，也不需要编译。

当前工作目录安装的是 **macOS Apple 芯片（darwin-arm64）** 的 Canvas 原生二进制。它不能直接作为 Windows 或 Intel Mac 的完整缩略图版本分发。建议分别在以下目标环境执行安装、测试和打包：

- macOS Apple 芯片
- macOS Intel
- Windows x64

如果每个安装包只携带一个平台的原生二进制，出包时还应把 `manifest.json` 的 `platform` / `arch` 改为对应的 `mac` + `arm`、`mac` + `x64` 或 `win` + `x64`。只有安装包确实包含并测试过所有目标平台的原生二进制时，才保留当前的 `all` + `all`。

### 出包文件检查

完整功能包至少应包含：

- `manifest.json`、`logo.png`
- `viewer/`、`thumbnail/`、`js/`、`lib/`、`assets/`
- `LICENSES/`
- `package.json`、`package-lock.json`
- 与目标平台匹配的 `node_modules/`

无需放入发布包的开发文件包括 `.git/`、日志、`.DS_Store`、`debug*.js`、`test-*.js`、`SpineViewer.code-workspace`，以及未在 `manifest.json` 中使用的 ICNS 测试文件。