82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
# 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 # 插件图标
|
||
├─ thumbnail/
|
||
│ └─ spine.js # 缩略图生成（渲染骨骼首帧为 PNG）
|
||
├─ 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
|
||
└─ 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>` 上实时播放动画，并支持：
|
||
- 动画列表切换
|
||
- 皮肤切换
|
||
- 播放 / 暂停（空格）
|
||
- 循环开关
|
||
- 播放速度调节
|
||
- 自动适配并居中
|
||
4. **缩略图**：使用 `@napi-rs/canvas` 在 Node 中跨 item 文件夹读取资源并渲染骨骼首帧生成 PNG。若该依赖不可用，会自动回退为一条纯 JS 生成的占位 PNG。
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
- 将 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** 导出即可正常预览。
|
||
|
||
---
|
||
|
||
## 可选依赖说明
|
||
|
||
`@napi-rs/canvas` 仅用于缩略图的高质量渲染。它并非必需：
|
||
- 若保留 `node_modules/`（当前平台原生二进制），缩略图会渲染骨骼形象。
|
||
- 若删除 `node_modules/`，插件仍可正常预览动画，缩略图会显示一条纯 JS 占位图。
|
||
|
||
如需在多个平台分发，请安装对应平台的 `@napi-rs/canvas` 原生二进制。
|