# 网页粒子系统 · 阶段七 > 阶段定位：**Spine 4.2 骨架资源接入、统一场景变换与碰撞体路径跟随定版** > 完成日期：2026-08-29 > 工程目录：`/Users/tianmokeji/Desktop/SpineParticle` > 技术栈：Vue 3 + TypeScript + Pinia + PixiJS 7 + Spine Runtime 4.2 + Vite --- ## 一、阶段结论 阶段七完成了 Spine 骨架场景对象的第一版完整接入，并补齐了时间轴、场景变换和碰撞体路径跟随能力。Spine 资源现在可以离线加载、显示、选择动画、查看骨骼层级，并与粒子系统共同受统一的 30 FPS 时间轴控制。 本阶段主要完成： 1. 接入 Spine 官方 4.2 PixiJS 7 运行时并离线落盘； 2. 实现 Spine 骨架场景对象及独立属性面板； 3. 支持 JSON、SKEL、Atlas 和多张纹理资源加载； 4. 自动读取动画列表、动画时长和骨骼层级； 5. Spine 动画关闭自身循环，改由编辑器时间轴统一驱动； 6. 时间轴增加紫色 Spine 动画条和逐帧控制按钮； 7. 修复动画按浏览器刷新次数推进导致的播放过快问题； 8. 统一画布变换工具，使其作用于场景树当前选中的对象； 9. 为碰撞体和路径补充缩放变换； 10. 实现碰撞体沿路径移动、速度曲线和方向跟随； 11. 统一“路径”术语，移除重复的移动轨迹显示开关； 12. 完成旧场景字段补齐和热更新兼容处理。 --- ## 二、Spine 官方运行时接入 ### 2.1 运行时来源 项目使用 Spine 官方仓库中的 4.2 兼容版本： | 项目 | 内容 | |---|---| | 官方仓库 | `https://github.com/EsotericSoftware/spine-runtimes` | | 兼容分支 | `4.2` | | 固定提交 | `b81e5a58ed38704aee4f866f0e0ac672623ce914` | | `spine-core` | `4.2.119` | | `spine-pixi-v7` | `4.2.119` | | 渲染目标 | PixiJS 7 | 运行时代码放置在 `vendor/spine/`，通过 `file:` 依赖接入： ```text @esotericsoftware/spine-core -> vendor/spine/spine-core @esotericsoftware/spine-pixi-v7 -> vendor/spine/spine-pixi-v7 ``` 因此项目构建时不需要从 npm 在线下载 Spine 运行时代码。版本来源、提交号和许可提示记录在 `vendor/spine/SOURCE.md`，官方许可证保存在同目录中。 ### 2.2 代码拆分 Spine 功能没有继续堆叠到主面板和主画布文件中，而是拆分为： | 文件 | 职责 | |---|---| | `spineTypes.ts` | Spine 场景对象、动画和骨骼元数据类型 | | `spineAssetLoader.ts` | 读取骨架、Atlas 和纹理并生成 SkeletonData | | `spineAssetRegistry.ts` | 管理运行时资源和纹理释放 | | `SpineRuntimeLayer.ts` | 创建 Spine 显示对象并按编辑器帧同步动画 | | `SpineObjectPanel.vue` | 资源选择、属性、动画列表和层级树界面 | 这种拆分让主粒子系统逻辑与第三方骨架运行时保持边界，便于后续增加插槽、皮肤、混合和导出功能。 --- ## 三、Spine 场景对象 ### 3.1 创建与默认状态 点击场景对象模块中的 `＋骨架` 会创建一个 Spine 对象，并自动成为当前选中对象。 | 参数 | 默认值 | |---|---:| | 名称 | `SpineSkeleton1` | | 启用 | 开启 | | X / Y | 0 / 0 | | 旋转 | 0° | | Scale X / Y | 1 / 1 | | 开始时间 | 0 秒 | | 资源状态 | 未加载 | | 当前动画 | 无 | Spine 对象与粒子系统、碰撞体和路径统一显示在场景对象树中，支持选择和删除。删除对象时会同步释放已注册的 Spine 资源和纹理引用。 ### 3.2 支持的资源 加载一套 Spine 资源时需要选择： - 骨架数据：`.json` 或 `.skel`； - 图集描述：`.atlas`； - 纹理图片：`.png`、`.jpg`、`.jpeg`、`.webp`，允许多选； - 兼容文件选择器中的 `.wepb` 拼写。 加载器按 Atlas 页面的文件名匹配所选纹理。如果 Atlas 引用了未选择的纹理，会给出明确错误，不会创建不完整的骨架对象。 ### 3.3 测试资源 项目 `public/spine/` 中的 Spine 4.2 测试资源用于本阶段验证： - `bingo.json`； - `bingo.atlas`； - `bingo.png`； - `bingo_2.png`。 测试覆盖了 JSON 骨架、多纹理 Atlas、动画列表读取、画布渲染和骨骼层级展示。 --- ## 四、动画与骨骼层级 ### 4.1 动画列表 资源加载成功后，面板会从 SkeletonData 中读取全部动画： - 显示动画名称； - 显示真实动画时长，单位为秒； - 支持选择“无”或任意动画； - 默认选择资源中的第一个动画； - 切换动画后重新计算时间轴总长度并回到第 0 帧。 Spine 动画自身不循环播放。动画到达末尾后停留在末帧，是否重新从头播放由编辑器总时间轴的循环按钮决定。 ### 4.2 骨骼层级树 加载成功后同时读取骨骼名称、父级关系和深度，按层级显示为树结构。 层级树支持： - 点击父骨骼前的箭头折叠或展开子级； - “全部折叠”和“全部展开”； - 折叠父级后隐藏其全部后代； - 长层级树在固定高度区域内滚动。 该树当前用于查看资源结构，尚未提供骨骼选择、单骨骼变换或插槽编辑。 ### 4.3 Spine 资源显示设置 原属性面板中容易误解的“启用骨架显示”已改为系统设置中的“启用 Spine 资源显示”。 - 已加载包含动画的 Spine 资源时，可以全局显示或隐藏 Spine 资源； - 没有可用 Spine 动画时，该设置置灰； - 该开关只控制画布中的 Spine 资源，不影响编辑器自身的粒子拖尾骨骼、骨骼连线或蒙皮网格调试显示； - 对象自身的 `enabled` 状态仍会独立参与最终可见性判断。 --- ## 五、统一时间轴 ### 5.1 真实时间驱动 时间轴继续使用统一的 **30 FPS** 基准： ```text 1 秒 = 30 帧 当前动画时间 = 当前帧 / 30 - Spine 开始时间 ``` 修复前，Spine 动画会在浏览器每次刷新画面时前进一帧。高刷新率屏幕上动画会明显快于 Spine 编辑器中的同一动画。 现在使用实际经过时间累积，并按 `1/30` 秒的固定步长推进显示帧。浏览器刷新率只影响画面刷新平滑度，不再改变动画播放速度。 ### 5.2 Spine 紫色动画条 选择有效 Spine 动画后，时间轴新增紫色动画条： - 条带长度来自 Spine 动画的真实时长； - 长度不可拖动修改； - 整条可以左右拖动； - 左侧空白表示延迟播放时间； - 拖动以 1 帧为单位吸附； - 没有动画数据或当前动画为“无”时不显示。 Spine 动画、粒子系统和碰撞体路径移动共同参与总时间轴长度计算： ```text 总时长 = max( 粒子系统最晚消失时间, Spine 开始时间 + Spine 动画时长, 碰撞体路径移动时长 ) ``` ### 5.3 播放控制 时间轴控制区现在包括： | 控制 | 行为 | |---|---| | 播放 / 暂停 | 切换整体时间轴播放状态 | | 回到第一帧 | 跳转到第 0 帧 | | 前一帧 | 自动暂停并后退 1 帧 | | 后一帧 | 自动暂停并前进 1 帧 | | 移动到最后一帧 | 自动暂停并跳转到最后帧 | | 循环 | 控制整体时间轴到达末尾后的行为 | 这些操作统一影响粒子模拟、Spine 动画和碰撞体路径移动。 --- ## 六、场景对象变换统一 ### 6.1 当前选中对象 画布左上角的位移、旋转和缩放工具不再固定操作粒子系统，而是读取场景树中的当前选中对象。 支持的对象包括： - 粒子系统； - 碰撞体； - 路径； - Spine 骨架。 选择 Spine 对象后，变换工具只修改该 Spine 对象；选择碰撞体或路径后，同样只影响选中对象。 ### 6.2 缩放补齐 碰撞体新增 `scaleX`、`scaleY`，路径继续使用独立的 `scaleX`、`scaleY`。两类对象均可通过属性面板或画布缩放工具修改。 路径的位移、旋转和缩放会同时作用于： - 路径曲线显示； - 锚点和贝塞尔手柄； - 发射器路径采样； - 碰撞体路径跟随。 碰撞体缩放同时影响画布轮廓和实际粒子碰撞计算。 --- ## 七、碰撞体路径跟随 阶段六预留的“跟随路径移动”在本阶段完成运行时实现。 ### 7.1 默认参数 | 参数 | 默认值 | |---|---:| | 跟随路径移动 | 关闭 | | 目标路径 | 未选择 | | 移动时长 | 2 秒 | | 曲线模式 | 跟随导出 | | 移动进度曲线 | 0→1 线性 | | 方向沿路径 | 关闭 | 只有开启跟随并选择一条已启用且包含锚点的路径后，碰撞体才会开始移动。无效或已删除的目标路径不会改变碰撞体原始位置。 ### 7.2 移动计算 ```text 归一化时间 = clamp(当前时间 / 移动时长, 0, 1) 路径进度 = 移动进度曲线(归一化时间) 碰撞体位置 = 路径按长度采样(路径进度) ``` 路径采样会考虑路径对象自身的位移、旋转和缩放。每段三次贝塞尔曲线先离散采样并累计实际距离，再按总长度查找位置，减少不同曲线段参数长度不一致造成的明显速度变化。 面板提供三种曲线模式： - 跟随导出； - 线性； - 贝塞尔。 曲线编辑器横轴表示实时除以移动时长，纵轴表示路径进度。到达移动时长后，碰撞体停留在路径终点；编辑器时间轴循环时再从起点开始。 ### 7.3 方向沿路径 “方向沿路径”默认关闭： - 关闭时，碰撞体移动过程中保持自己的旋转值； - 开启时，根据路径当前位置前后采样点计算切线方向； - 碰撞体属性中的旋转值作为附加角度叠加，可继续微调朝向。 圆形碰撞体视觉上不容易观察旋转变化，矩形、椭圆和多边形更适合检查该功能。 ### 7.4 碰撞运行时 路径跟随不仅改变画布上的碰撞体预览位置，也会把同一份动态位置和旋转传给粒子碰撞检测。因此粒子会与移动中的碰撞体发生真实交互，物理、暂停和销毁三种响应保持有效。 运行时使用预览副本计算动态位置，不会持续覆盖碰撞体存储的基础 X、Y 和旋转值。关闭跟随后，碰撞体会恢复到属性面板中设置的基础变换。 路径对象本身始终在画布显示，因此移除了重复的“显示移动轨迹线”开关和额外轨迹覆盖层。 --- ## 八、术语与兼容性 ### 8.1 路径术语统一 用于贝塞尔对象和跟随功能的界面术语统一为“路径”： - 跟随路径移动； - 目标路径； - 路径进度； - 路径名称； - 闭合路径； - 路径颜色； - 发射器跟随路径。 发射器形状中的“轨道”仍表示粒子发射形状 `orbit`，不是场景路径对象，因此保留原名称。 ### 8.2 旧数据补齐 旧场景或热更新状态中的碰撞体可能缺少路径跟随字段。面板会即时补齐： - 目标路径； - 移动时长； - 曲线模式； - 移动进度曲线； - 方向沿路径。 曲线组件同时提供空值回退，避免旧数据加载或热更新瞬间因曲线为空导致界面渲染失败。 --- ## 九、验证结果 本阶段完成以下验证： - Spine 官方 4.2.119 本地运行时依赖和生产构建； - JSON、Atlas 和两张 PNG 测试资源加载； - 动画名称、真实时长和骨骼层级读取； - Spine 动画非循环播放及末帧保持； - 30 FPS 真实时间推进，不受浏览器刷新率影响； - 紫色 Spine 时间轴条长度和开始时间拖动； - 前一帧、后一帧和最后一帧自动暂停； - 骨骼层级单节点折叠和全部折叠； - Spine 资源全局显示开关和无动画时置灰； - 当前选中粒子、碰撞体、路径和 Spine 对象的画布变换； - 碰撞体和路径缩放与运行时表现同步； - 碰撞体目标路径、移动时长、进度曲线和方向开关； - 移动碰撞体参与实际粒子碰撞； - 路径术语统一及重复轨迹开关移除； - 旧碰撞体字段和曲线空值兼容； - 页面面板交互检查； - `npm run build` 生产构建通过； - `git diff --check` 通过。 构建仍有 Vite 对主产物体积超过 500 kB 的提示，不影响当前功能和构建结果，后续可通过按模块动态加载进一步优化。 --- ## 十、当前限制 1. Spine 资源通过本地文件选择器加载，刷新页面后需要重新选择，尚未纳入工程保存格式； 2. Spine 层级树当前只读，不能编辑骨骼、插槽、皮肤或约束； 3. Spine 动画尚未支持混合、播放速度、反向和多轨道叠加； 4. `.skel` 已接入官方二进制解析器，但本阶段主要使用 JSON 测试资源验证； 5. 碰撞体路径跟随当前为单次起点到终点，尚未提供往返或独立循环模式； 6. 自定义碰撞体仍使用规则多边形轮廓，尚未接入自由顶点编辑； 7. 场景对象和资源尚未形成完整的保存、导入和导出格式。 --- ## 十一、阶段八建议 1. 建立场景工程保存格式，持久化粒子、路径、碰撞体和 Spine 对象配置； 2. 将 Spine 资源复制到工程资源目录，支持刷新后自动恢复； 3. 增加 Spine 皮肤、插槽、混合时长和播放速度控制； 4. 为碰撞体路径跟随增加循环、往返、反向和结束行为； 5. 实现碰撞标签过滤和碰撞事件输出； 6. 实现自定义碰撞体自由顶点编辑； 7. 对 Spine 和曲线编辑器进行动态加载，降低主包体积； 8. 建立可复现的场景回归测试，覆盖统一时间轴和多对象组合。