SpineViewer（Eagle 插件）
一个 完全离线 的 Eagle 格式扩展插件，用于在 Eagle 中直接预览由 Spine 导出的骨骼动画。
插件只接管「骨骼数据」和「纹理图集数据」类型的预览：
- 骨骼数据：
skel、skel.bytes、json - 纹理图集数据：
atlas、atlas.txt
普通图片（png/jpg/jpeg/webp）仍由 Eagle 原生预览，插件不接管。
Eagle 按最后一段后缀分发格式扩展，因此插件同时注册 txt 和 bytes，再检查完整文件名。导入复合后缀时，插件通过缩略图回调将 lili.atlas.txt 规范为 name: "lili"、ext: "atlas.txt"，skel.bytes 同理，磁盘文件名保持不变；同时生成匹配新名称的 WebP 缓存。这样可避开 Eagle 对 txt 强制显示文本卡片的逻辑。普通 TXT 保留文本内容、正常显示；普通 BYTES 显示文件说明，两者都不扫描资源库。修改注册后需要重新加载插件或重启 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
├─ thumbnail/
│ └─ spine.js # 缩略图生成（渲染骨骼首帧并交由 Eagle 缓存）
├─ 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/ # 第三方运行时及依赖的再分发许可证
└─ node_modules/ # 可选：@napi-rs/canvas（用于高质量缩略图渲染）
工作原理
- 跨文件夹资源配对：Eagle 会把导入的每个文件拆分成独立的元数据文件夹（
images/<id>.info/，内含资产文件与metadata.json），因此配套文件可能不在同一目录。插件会：- 定位到所选文件的 item 文件夹；
- 扫描其同级的所有 item 文件夹，根据文件名（忽略
-pro、-ess、-pma等常见后缀）自动关联出配套的 骨骼文件 + atlas + 贴图； - 从 atlas 中解析它引用的贴图页面，再到库中定位实际贴图文件。
- 版本检测：读取骨骼数据里的版本号（
.json读skeleton.spine，.skel读二进制头部），自动选择匹配的本地运行时。 - 预览：查看器通过 Node
fs直接读取分离在各 item 文件夹中的骨骼/atlas/贴图文件（无需网络、无 CORS），用spine-canvas渲染器在<canvas>上实时播放动画，并支持：- 动画列表切换
- 皮肤切换
- 播放 / 暂停（空格）
- 循环开关
- 播放速度调节
- 预乘 Alpha（PMA）默认读取配套
.atlas/.atlas.txt的pma:true/false；用户手动切换后保存为该素材的显式覆盖值，重新打开时继续沿用 - 时间轴拖动、动画时长、秒刻度与关键帧标记
- 零时长动画按单帧静态姿势预览
- 自动适配并居中
- 将当前帧设为自定义缩略图，并通知 Eagle 立即刷新列表缓存
- 缩略图：使用
@napi-rs/canvas在 Node 中跨 item 文件夹读取资源并渲染骨骼首帧。自动生成和预览器中手动点击“生成缩略图”都会在右下角添加 Spine 官方 badge，左下角添加完整导出版本号（例如3.4.02），便于识别数据文件。无法识别版本时不显示版本文字。导入时会等待同批文件写入稳定，再按入库批次配对，避免复用旧库里的同名资源。处理器写入 PNG 工作图，最终缩略图缓存格式由 Eagle 决定，可能是体积更小的 WebP。- 同一前缀的
atlas/json/skel共用资源发现和渲染任务，完成后主动补刷这一组的全部数据条目。 - JSON 只在存在 Spine 官方导出的
skeleton.spine版本字段时才按骨骼数据处理；普通 JSON、JSONC 和仅含bones/slots同名字段的数据会立即生成中性文件缩略图，不进入全库资源扫描或补刷队列。 - 暂时缺少骨骼、atlas 或贴图时，前台最多短暂等待约半秒便显示回退图；后台采用逐步降频的方式观察约两分钟。链路补齐且文件稳定后自动生成 WebP 并通知 Eagle 刷新；更晚补拖的文件会通过新的导入回调重新触发识别。
- 分批拖入时优先在同一个 Eagle 文件夹内补齐；大型文件夹导入会共享短时文件索引，避免每个条目重复扫描整个库。
- Eagle 在缩略图回调结束后会关闭执行窗口，因此补刷使用独立 Node 工作进程和临时文件队列，不依赖窗口内的定时器。每个素材库同时只有一个工作进程；确认资源稳定、素材已经入库后调用 Eagle API 补刷，失败会重试约两分钟，队列完成后退出。不会后台常驻。
- 同一前缀的
使用说明
预览与手动缩略图使用 WebGL 绘制网格三角形，避免 Canvas 逐三角形裁切造成的细线接缝，覆盖全部九个运行时版本。WebGL 不可用时回退到 Canvas。
“背景”开关默认开启，绘制每格 50×50 世界单位的灰色方格，随骨骼视图一起移动和缩放。背景像素与骨骼在同一个帧缓冲中合成，支持正常、相加、相乘和滤色；关闭方格后使用实色背景。手动缩略图跟随当前背景开关。4.3 等带 -beta 后缀的完整版本号也会显示在水印中。
加载骨骼时会先使用骨骼数据声明的默认皮肤；没有默认皮肤时使用皮肤列表中的第一个，并立即按 setup pose 重建槽位附件。手动切换皮肤也会执行同样的附件刷新，避免只有下拉框变化而画面为空。
Eagle 的公开素材 API 不提供任意自定义元数据字段。预乘设置保存在 Eagle 用户数据目录的 SpineViewer/preview-settings/ 下，以素材库和素材 ID 区分；不修改 Eagle 的 metadata.json、标签或注释，也不会随素材导出到其他电脑。
- 将 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）：
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，记录固定提交与文件校验值）：
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 版本号，下载器不修改原始数据。
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。
可选依赖说明
@napi-rs/canvas 仅用于缩略图的高质量渲染。它并非必需：
- 若保留
node_modules/（当前平台原生二进制），缩略图会渲染骨骼形象。 - 若删除
node_modules/，插件仍可正常预览动画，缩略图会显示一条纯 JS 占位图。
如需在多个平台分发，请安装对应平台的 @napi-rs/canvas 原生二进制。
分享与打包
分享源码
仓库中的 node_modules/ 被 .gitignore 忽略是正常的。接收者克隆源码后，需要在插件目录执行：
npm ci --omit=dev
@napi-rs/canvas 会按当前操作系统和 CPU 下载预编译的 N-API 二进制，正常情况下不需要编译，也不需要安装 Rust/C++ 工具链。安装完成后，再从 Eagle 插件面板加载或打包插件。
分享可直接安装的插件
- 在准备出包的目标系统上执行
npm ci --omit=dev。 - 确认插件目录中保留了
node_modules/。否则骨骼动画仍可预览，但自动缩略图只能使用占位图。 - 在 Eagle 中打开插件面板（快捷键
P），右键此插件并选择“打包插件”。 - 把生成的
.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.pngviewer/、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 测试文件。