152 lines
11 KiB
Markdown
152 lines
11 KiB
Markdown
# SpineViewer（Eagle 插件）
|
||
|
||
一个 **完全离线** 的 Eagle 格式扩展插件，用于在 Eagle 中直接预览由 Spine 导出的骨骼动画。
|
||
|
||
插件只接管「骨骼数据」和「纹理图集数据」类型的预览：
|
||
- 骨骼数据：`skel`、`skel.bytes`、`json`
|
||
- 纹理图集数据：`atlas`、`atlas.txt`
|
||
|
||
普通图片（`png/jpg/jpeg/webp`）仍由 Eagle 原生预览，插件不接管。
|
||
|
||
Eagle 按最后一段后缀分发格式扩展，因此插件同时注册 `txt` 和 `bytes`，再由查看器检查完整文件名。普通 JSON/TXT/BYTES 不会进入 Spine 预览。插件不注册导入缩略图处理器，导入阶段由 Eagle 自身处理。
|
||
|
||
支持的 Spine 版本：**3.4 / 3.5 / 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
|
||
├─ viewer/
|
||
│ └─ spine.html # 预览页面（动画播放 / 动画/皮肤切换 / 速度 / 缩放适配）
|
||
├─ js/
|
||
│ ├─ spine-utils.js # 资源匹配、版本检测工具
|
||
│ ├─ spine-legacy-binary.js # 3.4–3.7 二进制解析兼容层
|
||
│ └─ spine-render.js # Node 渲染辅助模块
|
||
├─ lib/ # 各版本 Spine 官方运行时（已拷贝到本地）
|
||
│ ├─ 3.4/ spine-canvas.js
|
||
│ ├─ 3.5/ spine-canvas.js
|
||
│ ├─ 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/ # 第三方运行时的再分发许可证
|
||
```
|
||
|
||
---
|
||
|
||
## 工作原理
|
||
|
||
1. **跨文件夹资源配对**：Eagle 会把导入的每个文件拆分成独立的元数据文件夹（`images/<id>.info/`，内含资产文件与 `metadata.json`），因此配套文件可能不在同一目录。插件会：
|
||
- 定位到所选文件的 item 文件夹；
|
||
- 涋描其**同级的所有 item 文件夹**，根据文件名（忽略 `-pro`、`-ess`、`-pma`、`-base`、`-atlas`、`-data`、`-mesh` 等常见尾缀，`-` 与 `_` 均可）自动关联出配套的 **骨骼文件** + **atlas** + **贴图**；尾缀表可在预览顶栏的“尾缀”下拉里追加自定义项；
|
||
- 从 atlas 中解析它引用的贴图页面，再到库中定位实际贴图文件。
|
||
2. **版本检测**：读取骨骼数据里的版本号（`.json` 读 `skeleton.spine`，`.skel` 读二进制头部），自动选择匹配的本地运行时。
|
||
3. **预览**：查看器通过 Node `fs` 直接读取分离在各 item 文件夹中的骨骼/atlas/贴图文件（无需网络、无 CORS），用 `spine-canvas` 渲染器在 `<canvas>` 上实时播放动画，并支持：
|
||
- 画布左上方自适应的浮动动画列表，动画较多时独立滚动，点击条目立即切换；没有动画数据时自动隐藏
|
||
- 皮肤切换
|
||
- 播放 / 暂停（空格）
|
||
- 循环开关
|
||
- 播放速度调节
|
||
- 预乘 Alpha（PMA）默认读取配套 `.atlas` / `.atlas.txt` 的 `pma:true/false`；用户手动切换后保存为该素材的显式覆盖值，重新打开时继续沿用
|
||
- 浮动时间轴支持拖动、动画时长、秒刻度与关键帧标记；顶部控制栏同样采用浮动布局
|
||
- 零时长动画按单帧静态姿势预览
|
||
- 自动适配并居中
|
||
- 用户可主动将当前帧设为当前素材的自定义缩略图；若已有自定义缩略图，替换前会明确确认
|
||
- 顶栏“尾缀”下拉列出内置尾缀（`pro` `ess` `pma` `base` `atlas` `data` `mesh`）与用户自定义尾缀；选择“＋ 添加尾缀…”可新增（仅字母、数字、`-`、`_`，最长 50 字符，上限由 `js/spine-utils.js` 的 `SUFFIX_MAX_LENGTH` 统一定义），选择自定义项可移除。配置保存在 Eagle userData 的 `SpineViewer/suffix-settings.json`，对全部素材与资源库生效，修改后自动重新加载以重新配对
|
||
4. **缩略图**：导入时不运行插件缩略图生成器，由 Eagle 自身处理。用户打开 Spine 预览后，仍可用原有按钮将当前帧设为**当前素材**的自定义缩略图。左侧的“为关联资源生成缩略图”会先列出已验证的同 stem `json / skel / skel.bytes / atlas / atlas.txt` 和 atlas 引用贴图；骨骼与 atlas 默认勾选，图片和已有自定义缩略图的素材默认不勾选；用户可主动勾选已有自定义缩略图的素材，确认后覆盖，原图无法由插件自动恢复。手动缩略图会添加 Spine badge 和导出版本号。
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
预览与手动缩略图使用 WebGL 绘制网格三角形，避免 Canvas 逐三角形裁切造成的细线接缝，覆盖全部九个运行时版本。贴图从原始文件直接解码到 GPU，避免 PMA 贴图经过 Canvas 中转导致低透明度颜色量化和光晕分层；支持逐顶点 RGB、Alpha 及运行时提供的双色染色。WebGL 不可用时回退到 Canvas，回退路径的染色能力有限。
|
||
|
||
“背景”开关默认关闭，使用实色背景；手动开启后绘制每格 50×50 世界单位的灰色方格，随骨骼视图一起移动和缩放。背景像素与骨骼在同一个帧缓冲中合成，支持正常、相加、相乘和滤色。手动缩略图跟随当前背景开关。4.3 等带 `-beta` 后缀的完整版本号也会显示在水印中。
|
||
|
||
加载骨骼时会先使用骨骼数据声明的默认皮肤；没有默认皮肤时使用皮肤列表中的第一个，并立即按 setup pose 重建槽位附件。手动切换皮肤也会执行同样的附件刷新，避免只有下拉框变化而画面为空。
|
||
|
||
Eagle 的公开素材 API 不提供任意自定义元数据字段。预乘设置保存在 Eagle 用户数据目录的 `SpineViewer/preview-settings/` 下，以素材库和素材 ID 区分；不修改 Eagle 的 `metadata.json`、标签或注释，也不会随素材导出到其他电脑。
|
||
|
||
Atlas 页面路径按不可信输入处理：插件拒绝绝对路径、`..`、盘符、UNC、URI 以及越出允许目录的符号链接；跨素材贴图只从当前 Eagle 素材库中已经枚举并验证的素材选择。导入阶段不由插件生成缩略图；手动批量操作只作用于明确列出并得到确认的当前资源组，已有自定义缩略图的素材默认不选中，只有用户明确勾选才会覆盖。诊断日志默认关闭；显式设置 `SPINEVIEWER_DEBUG_LOG=1` 时仅写系统临时目录。
|
||
|
||
- 将 Spine 导出的一整套文件（`.skel`/`.json` + `.atlas` + `.png` 等）放在**同一个文件夹**并导入 Eagle。
|
||
- 点击其中任何一个文件即可预览动画；点击配套的贴图或 atlas 也会自动找到整套资源。
|
||
|
||
---
|
||
|
||
## 关于新版/旧版二进制
|
||
|
||
- **3.5**：独立使用官方 3.5.51 运行时及对应二进制分支，支持 JSON、SKEL、SKEL.BYTES、ATLAS、ATLAS.TXT、预乘、动画、皮肤和缩略图。该版本没有裁剪附件。已对七组匹配的官方 JSON/SKEL 做姿势对比；Tank/Raptor 的不同导出批次分别做解析和渲染检查，详见 `lib/3.5/README.md`。
|
||
|
||
- **3.4**：使用官方 3.4.02 运行时与匹配的二进制解析分支，支持 JSON、SKEL、SKEL.BYTES、ATLAS、ATLAS.TXT，包含网格、变形、多皮肤、约束、时间轴、预乘及缩略图。3.4 本身没有裁剪附件。已验证九组官方 JSON/SKEL 示例；本地路径长度修正见 `lib/3.4/README.md`。
|
||
|
||
3.4 测试资源与回归命令（下载包括配套 PNG，可直接导入 Eagle）：
|
||
|
||
```sh
|
||
node tests/fetch-legacy-fixtures.js tests/.fixtures 3.4
|
||
node tests/legacy-binary.test.js tests/.fixtures 3.4
|
||
```
|
||
|
||
3.4 JSON 导出对数值采用截断，测试容许对应量化误差；Goblins 二进制还将三个端点相同的阶梯区间优化为线性，测试明确验证此差异。运行时保留二进制原始精度。
|
||
|
||
- **3.8 / 4.x** 的 `.skel` / `.skel.bytes` 二进制文件完整支持。
|
||
- **3.6 / 3.7**：插件已加入基于官方同版本 `spine-libgdx/SkeletonBinary.java` 移植的 JavaScript 解析兼容层，支持 `.skel` / `.skel.bytes`。无需同时导入 JSON；SKEL、atlas 和贴图齐全即可预览。
|
||
- 旧版数据始终使用匹配的 3.6 或 3.7 运行时，保留网格、权重、变形、约束、裁剪、绘制顺序和事件。3.7 的 IK 压缩/拉伸与音频事件字段单独解析。兼容层不需要编译或联网。
|
||
- 已验证官方 **3.6.32 / 3.7.90** 的七套示例；损坏、截断或版本不匹配的文件会报告解析错误。
|
||
|
||
### 旧版二进制回归测试
|
||
|
||
九个版本的完整普通 Alpha 示例可下载到本地（包括配套 Atlas 和 PNG，记录固定提交与文件校验值）：
|
||
|
||
```sh
|
||
node tests/fetch-official-examples.js
|
||
node tests/official-examples.test.js
|
||
node tests/legacy-binary.test.js tests/.fixtures 3.5
|
||
```
|
||
|
||
位置：`tests/.fixtures/`，按版本和示例分目录。每个示例可单独拖入 Eagle；不要把不同版本的同名文件混在同一个测试目录。3.5 官方 tag 的部分示例保留 beta 版本号，下载器不修改原始数据。
|
||
|
||
```sh
|
||
node tests/fetch-legacy-fixtures.js
|
||
node tests/legacy-binary.test.js
|
||
```
|
||
|
||
下载器从官方仓库固定提交获取两版 Spineboy、Goblins、Vine、Stretchyman、Tank、Coin、Raptor 的 JSON/SKEL/atlas。测试素材放在 `tests/.fixtures/`，不提交 Git，也不是插件运行依赖。测试不依赖原生 Canvas，比较附件、关键帧、不同皮肤与缩放下的动画姿势，并调用查看器渲染器检查几何数据。
|
||
|
||
官方 3.6 Raptor 的 JSON 与 SKEL 在一条 IK 曲线的阶梯插值位置上存在差异，测试明确记录该例外；解析器保留 SKEL 中的原始值。原始代码许可见 `LICENSES/Spine-Legacy-Binary-License.txt`。
|
||
|
||
---
|
||
|
||
## 分享与打包
|
||
|
||
### 分享源码
|
||
|
||
源码不依赖原生 Node 扩展；加载插件后即可使用预览和手动缩略图功能。
|
||
|
||
### 分享可直接安装的插件
|
||
|
||
1. 在 Eagle 中打开插件面板（快捷键 `P`），右键此插件并选择“打包插件”。
|
||
2. 把生成的 `.eagleplugin` 文件发给对方。安装包不含平台原生依赖，Windows 与 macOS 共用。
|
||
|
||
### 出包文件检查
|
||
|
||
完整功能包至少应包含：
|
||
|
||
- `manifest.json`、`logo.png`
|
||
- `viewer/`、`js/`、`lib/`、`assets/`
|
||
- `LICENSES/`
|
||
- `package.json`、`package-lock.json`
|
||
|
||
无需放入发布包的开发文件包括 `.git/`、日志、`.DS_Store`、`debug*.js`、`test-*.js`、`SpineViewer.code-workspace`，以及未在 `manifest.json` 中使用的 ICNS 测试文件。
|