@eva/spine-base 2.0.1-beta.9 → 2.0.1

package/dist/spine-base.esm.js

@@ -1,7 +1,7 @@
 import { Component, resource, OBSERVER_TYPE, decorators } from '@eva/eva.js';
 import { Renderer, RendererSystem } from '@eva/plugin-renderer';
+import { Container } from 'pixi.js';
 import { type } from '@eva/inspector-decorator';
-import { Assets } from 'pixi.js';
 
 /*! *****************************************************************************
 Copyright (c) Microsoft Corporation. All rights reserved.
@@ -34,15 +34,84 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+/**
+ * Spine 骨骼动画组件
+ *
+ * Spine 组件用于播放 Esoteric Software 的 Spine 骨骼动画。
+ * 支持骨骼动画播放控制、动画混合、附件替换等高级功能，
+ * 适用于角色动画、复杂特效等需要骨骼动画的场景。
+ *
+ * 主要功能：
+ * - 骨骼动画播放和控制
+ * - 动画轨道管理（多动画并行）
+ * - 动画混合过渡
+ * - 骨骼和附件访问
+ * - 支持 Spine 3.6 和 3.8 版本
+ *
+ * @example
+ * ```typescript
+ * // 创建 Spine 动画
+ * const character = new GameObject('character');
+ * const spine = new Spine({
+ *   resource: 'heroSpine', // Spine 资源
+ *   animationName: 'idle', // 默认动画
+ *   autoPlay: true, // 自动播放
+ *   scale: 0.5 // 缩放比例
+ * });
+ * character.addComponent(spine);
+ *
+ * // 播放动画
+ * spine.play('walk', true); // 循环播放 walk 动画
+ *
+ * // 停止动画
+ * spine.stop();
+ *
+ * // 动画混合
+ * spine.setMix('idle', 'walk', 0.3); // 设置过渡时间
+ * spine.play('walk');
+ *
+ * // 添加动画队列
+ * spine.play('attack', false); // 播放攻击动画
+ * spine.addAnimation('idle', 0, true); // 攻击完成后回到 idle
+ *
+ * // 替换附件（换装）
+ * spine.setAttachment('weapon', 'sword'); // 将武器槽替换为剑
+ *
+ * // 访问骨骼
+ * const headBone = spine.getBone('head');
+ * if (headBone) {
+ *   headBone.rotation = 15; // 旋转头部
+ * }
+ *
+ * // 多轨道动画
+ * spine.play('walk', true, 0); // 轨道0：身体动画
+ * spine.play('shoot', false, 1); // 轨道1：上半身动画
+ * ```
+ */
 class Spine extends Component {
     constructor() {
         super(...arguments);
+        /** Spine 资源名称 */
         this.resource = '';
+        /** 动画缩放比例 */
         this.scale = 1;
+        /** 当前播放的动画名称 */
         this.animationName = '';
+        /** 是否自动播放动画 */
         this.autoPlay = true;
+        /** 是否保留资源（销毁时不释放） */
+        this.keepResource = false;
+        /** 挂载到插槽的 GameObject 映射（GameObject -> { slot, wrapper }） */
+        this._slotGameObjects = new Map();
+        /** 等待容器就绪的 slot 挂载请求 */
+        this._pendingSlotObjects = [];
+        /** 等待执行的动画操作队列 */
         this.waitExecuteInfos = [];
     }
+    /**
+     * 设置骨架实例
+     * 当骨架加载完成后自动执行等待队列中的动画操作
+     */
     set armature(val) {
         this._armature = val;
         if (!val)
@@ -61,17 +130,36 @@ class Spine extends Component {
         }
         this.waitExecuteInfos = [];
     }
+    /** 获取骨架实例 */
     get armature() {
         return this._armature;
     }
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.resource - Spine 资源名称
+     * @param obj.animationName - 默认动画名称
+     * @param obj.scale - 缩放比例
+     * @param obj.autoPlay - 是否自动播放
+     */
     init(obj) {
         if (!obj)
             return;
         Object.assign(this, obj);
     }
+    /** 组件销毁时调用 */
     onDestroy() {
         this.destroied = true;
     }
+    /**
+     * 播放指定动画
+     *
+     * 如果骨架尚未加载完成，动画操作将被加入等待队列。
+     *
+     * @param name - 动画名称，不指定则使用 animationName 属性
+     * @param loopAnimation - 是否循环播放，默认跟随 autoPlay 属性
+     * @param track - 动画轨道编号，默认为 0
+     */
     play(name, loopAnimation, track) {
         try {
             const loop = loopAnimation !== null && loopAnimation !== void 0 ? loopAnimation : this.autoPlay;
@@ -81,6 +169,12 @@ class Spine extends Component {
                 this.waitExecuteInfos.push({
                     playType: true,
                     name,
+                    /**
+                     * 在 v1.2.2 之前，Spine 动画的 autoPlay 为 true，动画会循环播放 https://github.com/eva-engine/eva.js/pull/164/files#diff-46e9ae36c04e7a0abedc1e14fd9d1c4e81d8386e9bb851f85971ccdba8957804L131
+                     * 在 v1.2.2 之前，Spine 动画在每加载完( armature 设置之前)调用 play 是不生效的， 在 v1.2.2 [#164](https://github.com/eva-engine/eva.js/pull/164) 解决了这个问题
+                     * 解决了不生效的问题以后，加载完成之前调用 play 默认循环是false，导致 autoPlay 下本来循环动画不循环了，和之前表现不一致
+                     * 为了解决这个问题，在 autoPlay 的情况下，未加载完之前调用 play ，默认循环播放，除非设置不循环参数
+                     */
                     loop,
                     track,
                 });
@@ -96,6 +190,13 @@ class Spine extends Component {
             console.log(e);
         }
     }
+    /**
+     * 停止指定轨道的动画
+     *
+     * 如果骨架尚未加载完成，停止操作将被加入等待队列。
+     *
+     * @param track - 动画轨道编号，默认为 0
+     */
     stop(track) {
         if (!this.armature) {
             this.waitExecuteInfos.push({
@@ -109,6 +210,16 @@ class Spine extends Component {
         }
         this.armature.state.setEmptyAnimation(track, 0);
     }
+    /**
+     * 在当前动画之后添加新动画到队列
+     *
+     * 用于创建动画序列，当前动画播放完毕后自动播放下一个动画。
+     *
+     * @param name - 动画名称
+     * @param delay - 延迟时间（秒）
+     * @param loop - 是否循环播放
+     * @param track - 动画轨道编号，默认为 0
+     */
     addAnimation(name, delay, loop, track) {
         try {
             if (!this.armature) {
@@ -124,12 +235,27 @@ class Spine extends Component {
             console.log(e);
         }
     }
+    /**
+     * 设置两个动画之间的混合过渡时间
+     *
+     * 当从一个动画切换到另一个动画时，会在指定时间内进行平滑过渡。
+     *
+     * @param from - 起始动画名称
+     * @param to - 目标动画名称
+     * @param duration - 过渡时长（秒）
+     */
     setMix(from, to, duration) {
         if (!this.armature) ;
         else {
             this.armature.state.data.setMix(from, to, duration);
         }
     }
+    /**
+     * 获取指定轨道当前播放的动画名称
+     *
+     * @param track - 动画轨道编号，默认为 0
+     * @returns 动画名称，如果未找到则返回 undefined
+     */
     getAnim(track = 0) {
         try {
             if (!this.armature) {
@@ -142,25 +268,159 @@ class Spine extends Component {
             console.log(e);
         }
     }
+    /**
+     * 设置默认的动画混合时间
+     *
+     * 当没有为特定动画对指定混合时间时，将使用此默认值。
+     *
+     * @param duration - 默认混合时长（秒）
+     */
     setDefaultMix(duration) {
         if (!this.armature) ;
         else {
             this.armature.state.data.defaultMix = duration;
         }
     }
+    /**
+     * 替换指定插槽的附件
+     *
+     * 用于换装、武器切换等场景。
+     *
+     * @param slotName - 插槽名称
+     * @param attachmentName - 附件名称
+     */
     setAttachment(slotName, attachmentName) {
         if (!this.armature) {
             return;
         }
         this.armature.skeleton.setAttachment(slotName, attachmentName);
     }
+    /**
+     * 获取指定名称的骨骼
+     *
+     * 可用于直接操作骨骼的位置、旋转、缩放等属性。
+     *
+     * @param boneName - 骨骼名称
+     * @returns 骨骼对象，如果未找到则返回 undefined
+     */
     getBone(boneName) {
         if (!this.armature) {
             return;
         }
         return this.armature.skeleton.findBone(boneName);
     }
+    /**
+     * 将一个 GameObject 挂载到 Spine 的指定插槽上
+     *
+     * 挂载后 GameObject 会跟随骨骼运动。当 Spine 组件销毁时，
+     * 挂载的 GameObject 也会被自动销毁。
+     *
+     * @param slot - 插槽名称或索引
+     * @param gameObject - 要挂载的 GameObject
+     * @param options - 可选配置
+     * @param options.followAttachmentTimeline - 是否跟随插槽的附件时间线
+     */
+    addSlotObject(slot, gameObject, options) {
+        if (!this.armature) {
+            console.warn('Spine armature is not ready, cannot addSlotObject');
+            return;
+        }
+        if (!this._containerManager) {
+            console.warn('ContainerManager is not available');
+            return;
+        }
+        const container = this._containerManager.getContainer(gameObject.id);
+        if (!container) {
+            // 容器尚未就绪，加入 pending 队列，等待下一帧自动处理
+            this._pendingSlotObjects.push({ slot, gameObject, options });
+            return;
+        }
+        this._doAddSlotObject(slot, gameObject, container, options);
+    }
+    _doAddSlotObject(slot, gameObject, container, options) {
+        // 创建 wrapper 容器：Spine 骨骼矩阵作用在 wrapper 上，
+        // gameObject 的 container 作为子节点，其 transform 作为相对 slot 的局部偏移
+        const wrapper = new Container();
+        wrapper.addChild(container);
+        this.armature.addSlotObject(slot, wrapper, options);
+        this._slotGameObjects.set(gameObject, { slot, wrapper });
+        // slot object 可能不在 game.gameObjects 中，RendererSystem 不会自动同步 transform
+        // 手动同步 gameObject 及其子树的 transform 到 container
+        this._syncTransformTree(gameObject);
+    }
+    /**
+     * 递归同步 gameObject 及其子树的 transform 到对应的渲染容器
+     */
+    _syncTransformTree(gameObject) {
+        var _a;
+        if (!this._containerManager)
+            return;
+        this._containerManager.updateTransform({
+            name: gameObject.id,
+            transform: gameObject.transform,
+        });
+        if ((_a = gameObject.transform) === null || _a === void 0 ? void 0 : _a.children) {
+            for (const childTransform of gameObject.transform.children) {
+                if (childTransform.gameObject) {
+                    this._syncTransformTree(childTransform.gameObject);
+                }
+            }
+        }
+    }
+    /**
+     * 处理等待容器就绪的 slot 挂载请求（由 SpineSystem 每帧调用）
+     */
+    _flushPendingSlotObjects() {
+        if (this._pendingSlotObjects.length === 0)
+            return;
+        if (!this.armature || !this._containerManager)
+            return;
+        const still = [];
+        for (const pending of this._pendingSlotObjects) {
+            const container = this._containerManager.getContainer(pending.gameObject.id);
+            if (container) {
+                this._doAddSlotObject(pending.slot, pending.gameObject, container, pending.options);
+            }
+            else {
+                still.push(pending);
+            }
+        }
+        this._pendingSlotObjects = still;
+    }
+    /**
+     * 从插槽上移除挂载的 GameObject
+     *
+     * @param gameObject - 要移除的 GameObject
+     */
+    removeSlotObject(gameObject) {
+        // 从 pending 队列中移除
+        this._pendingSlotObjects = this._pendingSlotObjects.filter(p => p.gameObject !== gameObject);
+        const entry = this._slotGameObjects.get(gameObject);
+        if (entry && this.armature) {
+            this.armature.removeSlotObject(entry.wrapper);
+            entry.wrapper.destroy({ children: false });
+        }
+        this._slotGameObjects.delete(gameObject);
+    }
+    /**
+     * 销毁所有挂载到插槽的 GameObject（内部使用）
+     */
+    _destroySlotGameObjects() {
+        for (const [gameObject, entry] of this._slotGameObjects) {
+            if (!gameObject.destroyed) {
+                // 先从 spine 插槽移除 wrapper，避免 destroy 时重复操作
+                if (this.armature) {
+                    this.armature.removeSlotObject(entry.wrapper);
+                }
+                entry.wrapper.destroy({ children: false });
+                gameObject.destroy();
+            }
+        }
+        this._slotGameObjects.clear();
+        this._pendingSlotObjects = [];
+    }
 }
+/** 组件名称 */
 Spine.componentName = 'Spine';
 __decorate([
     type('string')
@@ -173,7 +433,10 @@ __decorate([
 ], Spine.prototype, "animationName", void 0);
 __decorate([
     type('boolean')
-], Spine.prototype, "autoPlay", void 0);
+], Spine.prototype, "autoPlay", void 0);
+__decorate([
+    type('boolean')
+], Spine.prototype, "keepResource", void 0);
 
 let dataMap = {};
 function createSpineData(name, data, scale, pixiSpine) {
@@ -213,14 +476,6 @@ function releaseSpineData(res, _imageSrc) {
     data.ref--;
     setTimeout(() => __awaiter(this, void 0, void 0, function* () {
         if (data.ref <= 0) {
-            yield Assets.unload([res.src.image.url, res.src.atlas.url, res.src.ske.url]);
-            const resolver = Assets.resolver;
-            delete resolver._assetMap[res.src.image.url];
-            delete resolver._assetMap[res.src.atlas.url];
-            delete resolver._assetMap[res.src.ske.url];
-            delete resolver._resolverHash[res.src.image.url];
-            delete resolver._resolverHash[res.src.atlas.url];
-            delete resolver._resolverHash[res.src.ske.url];
             resource.destroy(resourceName);
             delete dataMap[resourceName];
         }
@@ -228,17 +483,41 @@ function releaseSpineData(res, _imageSrc) {
 }
 
 const MaxRetryCount = 20;
+/**
+ * Spine 骨骼动画系统
+ *
+ * SpineSystem 负责管理所有 Spine 组件的骨架创建、动画更新和资源管理。
+ * 系统会监听 Spine 组件的变化，自动加载骨骼数据并创建动画实例，
+ * 并在每帧更新所有活跃的 Spine 动画。
+ *
+ * 主要功能：
+ * - 骨骼数据加载和缓存
+ * - 动画实例创建和销毁
+ * - 每帧动画状态更新
+ * - WebGL 上下文恢复处理
+ * - 资源重试机制
+ */
 let SpineSystem = class SpineSystem extends Renderer {
     constructor() {
         super(...arguments);
+        /** 骨架实例映射表（游戏对象 ID -> 骨架容器） */
         this.armatures = {};
+        /** Spine 组件实例映射（游戏对象 ID -> Spine 组件） */
+        this._spineComponents = {};
     }
+    /**
+     * 初始化系统
+     * @param obj - 初始化参数
+     * @param obj.pixiSpine - PixiJS Spine 插件实例
+     */
     init({ pixiSpine }) {
         this.renderSystem = this.game.getSystem(RendererSystem);
         this.renderSystem.rendererManager.register(this);
         this.pixiSpine = pixiSpine;
         this.game.canvas.addEventListener('webglcontextrestored', () => {
+            // 重建所有spine
             const objs = this.game.gameObjects;
+            // clearCache();
             let toAdd = [];
             for (let k in this.armatures) {
                 const id = +k;
@@ -271,10 +550,20 @@ let SpineSystem = class SpineSystem extends Renderer {
             }, 1000);
         }, false);
     }
+    /**
+     * 每帧更新所有 Spine 动画
+     * @param e - 更新参数，包含帧间隔时间
+     */
     update(e) {
         for (let key in this.armatures) {
+            // TODO: 类型
+            // @ts-ignore
             this.armatures[key].update(e.deltaTime * 0.001);
         }
+        // 处理等待容器就绪的 slot 挂载请求
+        for (let key in this._spineComponents) {
+            this._spineComponents[key]._flushPendingSlotObjects();
+        }
         super.update();
     }
     componentChanged(changed) {
@@ -297,7 +586,7 @@ let SpineSystem = class SpineSystem extends Renderer {
         });
     }
     add(changed, count) {
-        var _a, _b;
+        var _a, _b, _c;
         return __awaiter(this, void 0, void 0, function* () {
             const component = changed.component;
             clearTimeout(component.addHandler);
@@ -313,6 +602,7 @@ let SpineSystem = class SpineSystem extends Renderer {
                 component.addHandler = setTimeout(() => {
                     if (!component.destroied) {
                         if (count === undefined) {
+                            // 最大重试次数
                             count = MaxRetryCount;
                         }
                         count--;
@@ -329,37 +619,48 @@ let SpineSystem = class SpineSystem extends Renderer {
             this.remove(changed);
             const container = (_b = (_a = this.renderSystem) === null || _a === void 0 ? void 0 : _a.containerManager) === null || _b === void 0 ? void 0 : _b.getContainer(changed.gameObject.id);
             if (!container) {
+                // console.warn('添加spine的container不存在');
                 return;
             }
             component.lastResource = component.resource;
+            // @ts-ignore
             const armature = new this.pixiSpine.Spine({
                 skeletonData: spineData,
                 autoUpdate: false,
             });
             this.armatures[changed.gameObject.id] = armature;
+            this._spineComponents[changed.gameObject.id] = component;
             if (changed.gameObject && changed.gameObject.transform) {
                 const tran = changed.gameObject.transform;
                 armature.x = tran.size.width * tran.origin.x;
                 armature.y = tran.size.height * tran.origin.y;
             }
             container.addChildAt(armature, 0);
+            /** 保证第一帧显示正常 */
             armature.update();
+            component._containerManager = (_c = this.renderSystem) === null || _c === void 0 ? void 0 : _c.containerManager;
             component.armature = armature;
+            // @ts-ignore
             component.emit('loaded', { resource: component.resource });
             armature.state.addListener({
+                // @ts-ignore
                 start: (track, event) => {
                     component.emit('start', { track, name: track.animation.name });
                 },
+                // @ts-ignore
                 complete: (track, event) => {
                     component.emit('complete', { track, name: track.animation.name });
                 },
+                // @ts-ignore
                 interrupt: (track, event) => {
                     component.emit('interrupt', { track, name: track.animation.name });
                 },
-                end: (track, event) => {
+                end: (track, // @ts-ignore
+                event) => {
                     component.emit('end', { track, name: track.animation.name });
                 },
                 event: (track, event) => {
+                    // @ts-ignore
                     component.emit('event', track, event);
                 },
             });
@@ -381,17 +682,23 @@ let SpineSystem = class SpineSystem extends Renderer {
                 container.removeChild(armature);
             }
             if (component.armature) {
+                // 销毁所有挂载到插槽的 GameObject
+                component._destroySlotGameObjects();
                 component.armature.destroy({ children: true });
-                const res = yield resource.getResource(component.lastResource);
-                ((_d = (_c = res.data) === null || _c === void 0 ? void 0 : _c.image) === null || _d === void 0 ? void 0 : _d.src) || ((_f = (_e = res.data) === null || _e === void 0 ? void 0 : _e.image) === null || _f === void 0 ? void 0 : _f.label);
-                releaseSpineData(res);
+                if (!component.keepResource) {
+                    const res = yield resource.getResource(component.lastResource);
+                    ((_d = (_c = res.data) === null || _c === void 0 ? void 0 : _c.image) === null || _d === void 0 ? void 0 : _d.src) || ((_f = (_e = res.data) === null || _e === void 0 ? void 0 : _e.image) === null || _f === void 0 ? void 0 : _f.label);
+                    releaseSpineData(res);
+                }
             }
             component.armature = null;
             delete this.armatures[changed.gameObject.id];
+            delete this._spineComponents[changed.gameObject.id];
             if (changed.type === OBSERVER_TYPE.CHANGE) ;
         });
     }
 };
+/** 系统名称 */
 SpineSystem.systemName = 'SpineSystem';
 SpineSystem = __decorate([
     decorators.componentObserver({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/spine-base",
-  "version": "2.0.1-beta.9",
+  "version": "2.0.1",
   "description": "@eva/spine-base",
   "main": "index.js",
   "module": "dist/spine-base.esm.js",
@@ -18,9 +18,9 @@
   "license": "MIT",
   "homepage": "https://eva.js.org",
   "dependencies": {
-    "@eva/eva.js": "2.0.1-beta.9",
-    "@eva/plugin-renderer": "2.0.1-beta.9",
+    "@eva/eva.js": "2.0.1",
+    "@eva/plugin-renderer": "2.0.1",
     "@eva/inspector-decorator": "^0.0.5",
-    "pixi.js": "^8.8.1"
+    "pixi.js": "^8.17.0"
   }
 }