@eva/spine-base 2.0.1-beta.26 → 2.0.1-beta.28

package/dist/spine-base.cjs.js

@@ -37,16 +37,80 @@ 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 eva_js.Component {
     constructor() {
         super(...arguments);
+        /** Spine 资源名称 */
         this.resource = '';
+        /** 动画缩放比例 */
         this.scale = 1;
+        /** 当前播放的动画名称 */
         this.animationName = '';
+        /** 是否自动播放动画 */
         this.autoPlay = true;
+        /** 是否保留资源（销毁时不释放） */
         this.keepResource = false;
+        /** 等待执行的动画操作队列 */
         this.waitExecuteInfos = [];
     }
+    /**
+     * 设置骨架实例
+     * 当骨架加载完成后自动执行等待队列中的动画操作
+     */
     set armature(val) {
         this._armature = val;
         if (!val)
@@ -65,17 +129,36 @@ class Spine extends eva_js.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;
@@ -85,6 +168,12 @@ class Spine extends eva_js.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,
                 });
@@ -100,6 +189,13 @@ class Spine extends eva_js.Component {
             console.log(e);
         }
     }
+    /**
+     * 停止指定轨道的动画
+     *
+     * 如果骨架尚未加载完成，停止操作将被加入等待队列。
+     *
+     * @param track - 动画轨道编号，默认为 0
+     */
     stop(track) {
         if (!this.armature) {
             this.waitExecuteInfos.push({
@@ -113,6 +209,16 @@ class Spine extends eva_js.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) {
@@ -128,12 +234,27 @@ class Spine extends eva_js.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) {
@@ -146,18 +267,41 @@ class Spine extends eva_js.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;
@@ -165,6 +309,7 @@ class Spine extends eva_js.Component {
         return this.armature.skeleton.findBone(boneName);
     }
 }
+/** 组件名称 */
 Spine.componentName = 'Spine';
 __decorate([
     inspectorDecorator.type('string')
@@ -227,17 +372,39 @@ function releaseSpineData(res, _imageSrc) {
 }
 
 const MaxRetryCount = 20;
+/**
+ * Spine 骨骼动画系统
+ *
+ * SpineSystem 负责管理所有 Spine 组件的骨架创建、动画更新和资源管理。
+ * 系统会监听 Spine 组件的变化，自动加载骨骼数据并创建动画实例，
+ * 并在每帧更新所有活跃的 Spine 动画。
+ *
+ * 主要功能：
+ * - 骨骼数据加载和缓存
+ * - 动画实例创建和销毁
+ * - 每帧动画状态更新
+ * - WebGL 上下文恢复处理
+ * - 资源重试机制
+ */
 let SpineSystem = class SpineSystem extends pluginRenderer.Renderer {
     constructor() {
         super(...arguments);
+        /** 骨架实例映射表（游戏对象 ID -> 骨架容器） */
         this.armatures = {};
     }
+    /**
+     * 初始化系统
+     * @param obj - 初始化参数
+     * @param obj.pixiSpine - PixiJS Spine 插件实例
+     */
     init({ pixiSpine }) {
         this.renderSystem = this.game.getSystem(pluginRenderer.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;
@@ -270,8 +437,14 @@ let SpineSystem = class SpineSystem extends pluginRenderer.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);
         }
         super.update();
@@ -312,6 +485,7 @@ let SpineSystem = class SpineSystem extends pluginRenderer.Renderer {
                 component.addHandler = setTimeout(() => {
                     if (!component.destroied) {
                         if (count === undefined) {
+                            // 最大重试次数
                             count = MaxRetryCount;
                         }
                         count--;
@@ -328,9 +502,11 @@ let SpineSystem = class SpineSystem extends pluginRenderer.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,
@@ -342,23 +518,30 @@ let SpineSystem = class SpineSystem extends pluginRenderer.Renderer {
                 armature.y = tran.size.height * tran.origin.y;
             }
             container.addChildAt(armature, 0);
+            /** 保证第一帧显示正常 */
             armature.update();
             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);
                 },
             });
@@ -393,6 +576,7 @@ let SpineSystem = class SpineSystem extends pluginRenderer.Renderer {
         });
     }
 };
+/** 系统名称 */
 SpineSystem.systemName = 'SpineSystem';
 SpineSystem = __decorate([
     eva_js.decorators.componentObserver({

package/dist/spine-base.d.ts

@@ -8,29 +8,172 @@ import { RendererManager } from '@eva/plugin-renderer';
 import { RendererSystem } from '@eva/plugin-renderer';
 import { UpdateParams } from '@eva/eva.js';
 
+/**
+ * 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：上半身动画
+ * ```
+ */
 export declare class Spine extends Component<SpineParams> {
+    /** 组件名称 */
     static componentName: string;
+    /** Spine 资源名称 */
     resource: string;
+    /** 动画缩放比例 */
     scale: number;
+    /** 当前播放的动画名称 */
     animationName: string;
+    /** 是否自动播放动画 */
     autoPlay: boolean;
+    /** 是否保留资源（销毁时不释放） */
     keepResource: boolean;
+    /** Spine 骨架实例（内部使用） */
     private _armature;
+    /** 等待执行的动画操作队列 */
     private waitExecuteInfos;
+    /**
+     * 设置骨架实例
+     * 当骨架加载完成后自动执行等待队列中的动画操作
+     */
     set armature(val: any);
+    /** 获取骨架实例 */
     get armature(): any;
+    /** 组件是否已销毁 */
     destroied: boolean;
+    /** 动画事件处理器 */
     addHandler: any;
+    /** 上一次使用的资源名称 */
     lastResource: string;
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.resource - Spine 资源名称
+     * @param obj.animationName - 默认动画名称
+     * @param obj.scale - 缩放比例
+     * @param obj.autoPlay - 是否自动播放
+     */
     init(obj?: SpineParams): void;
+    /** 组件销毁时调用 */
     onDestroy(): void;
+    /**
+     * 播放指定动画
+     *
+     * 如果骨架尚未加载完成，动画操作将被加入等待队列。
+     *
+     * @param name - 动画名称，不指定则使用 animationName 属性
+     * @param loopAnimation - 是否循环播放，默认跟随 autoPlay 属性
+     * @param track - 动画轨道编号，默认为 0
+     */
     play(name?: string, loopAnimation?: boolean, track?: number): void;
+    /**
+     * 停止指定轨道的动画
+     *
+     * 如果骨架尚未加载完成，停止操作将被加入等待队列。
+     *
+     * @param track - 动画轨道编号，默认为 0
+     */
     stop(track?: number): void;
+    /**
+     * 在当前动画之后添加新动画到队列
+     *
+     * 用于创建动画序列，当前动画播放完毕后自动播放下一个动画。
+     *
+     * @param name - 动画名称
+     * @param delay - 延迟时间（秒）
+     * @param loop - 是否循环播放
+     * @param track - 动画轨道编号，默认为 0
+     */
     addAnimation(name?: string, delay?: number, loop?: boolean, track?: number): void;
+    /**
+     * 设置两个动画之间的混合过渡时间
+     *
+     * 当从一个动画切换到另一个动画时，会在指定时间内进行平滑过渡。
+     *
+     * @param from - 起始动画名称
+     * @param to - 目标动画名称
+     * @param duration - 过渡时长（秒）
+     */
     setMix(from: string, to: string, duration: number): void;
+    /**
+     * 获取指定轨道当前播放的动画名称
+     *
+     * @param track - 动画轨道编号，默认为 0
+     * @returns 动画名称，如果未找到则返回 undefined
+     */
     getAnim(track?: number): any;
+    /**
+     * 设置默认的动画混合时间
+     *
+     * 当没有为特定动画对指定混合时间时，将使用此默认值。
+     *
+     * @param duration - 默认混合时长（秒）
+     */
     setDefaultMix(duration: number): void;
+    /**
+     * 替换指定插槽的附件
+     *
+     * 用于换装、武器切换等场景。
+     *
+     * @param slotName - 插槽名称
+     * @param attachmentName - 附件名称
+     */
     setAttachment(slotName: string, attachmentName: string): void;
+    /**
+     * 获取指定名称的骨骼
+     *
+     * 可用于直接操作骨骼的位置、旋转、缩放等属性。
+     *
+     * @param boneName - 骨骼名称
+     * @returns 骨骼对象，如果未找到则返回 undefined
+     */
     getBone(boneName: string): any;
 }
 
@@ -41,16 +184,45 @@ export declare interface SpineParams {
     autoPlay?: boolean;
 }
 
+/**
+ * Spine 骨骼动画系统
+ *
+ * SpineSystem 负责管理所有 Spine 组件的骨架创建、动画更新和资源管理。
+ * 系统会监听 Spine 组件的变化，自动加载骨骼数据并创建动画实例，
+ * 并在每帧更新所有活跃的 Spine 动画。
+ *
+ * 主要功能：
+ * - 骨骼数据加载和缓存
+ * - 动画实例创建和销毁
+ * - 每帧动画状态更新
+ * - WebGL 上下文恢复处理
+ * - 资源重试机制
+ */
 export declare class SpineSystem extends Renderer {
+    /** 系统名称 */
     static systemName: string;
+    /** 骨架实例映射表（游戏对象 ID -> 骨架容器） */
     armatures: Record<number, Container>;
+    /** 渲染系统引用 */
     renderSystem: RendererSystem;
+    /** 渲染器管理器 */
     rendererManager: RendererManager;
+    /** 容器管理器 */
     containerManager: ContainerManager;
+    /** PixiJS Spine 插件实例 */
     pixiSpine: any;
+    /**
+     * 初始化系统
+     * @param obj - 初始化参数
+     * @param obj.pixiSpine - PixiJS Spine 插件实例
+     */
     init({ pixiSpine }: {
         pixiSpine: any;
     }): void;
+    /**
+     * 每帧更新所有 Spine 动画
+     * @param e - 更新参数，包含帧间隔时间
+     */
     update(e: UpdateParams): void;
     componentChanged(changed: ComponentChanged): Promise<void>;
     add(changed: ComponentChanged, count?: number): Promise<void>;

package/dist/spine-base.esm.js

@@ -33,16 +33,80 @@ 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;
+        /** 等待执行的动画操作队列 */
         this.waitExecuteInfos = [];
     }
+    /**
+     * 设置骨架实例
+     * 当骨架加载完成后自动执行等待队列中的动画操作
+     */
     set armature(val) {
         this._armature = val;
         if (!val)
@@ -61,17 +125,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 +164,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 +185,13 @@ class Spine extends Component {
             console.log(e);
         }
     }
+    /**
+     * 停止指定轨道的动画
+     *
+     * 如果骨架尚未加载完成，停止操作将被加入等待队列。
+     *
+     * @param track - 动画轨道编号，默认为 0
+     */
     stop(track) {
         if (!this.armature) {
             this.waitExecuteInfos.push({
@@ -109,6 +205,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 +230,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,18 +263,41 @@ 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;
@@ -161,6 +305,7 @@ class Spine extends Component {
         return this.armature.skeleton.findBone(boneName);
     }
 }
+/** 组件名称 */
 Spine.componentName = 'Spine';
 __decorate([
     type('string')
@@ -223,17 +368,39 @@ 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 = {};
     }
+    /**
+     * 初始化系统
+     * @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;
@@ -266,8 +433,14 @@ 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);
         }
         super.update();
@@ -308,6 +481,7 @@ let SpineSystem = class SpineSystem extends Renderer {
                 component.addHandler = setTimeout(() => {
                     if (!component.destroied) {
                         if (count === undefined) {
+                            // 最大重试次数
                             count = MaxRetryCount;
                         }
                         count--;
@@ -324,9 +498,11 @@ 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,
@@ -338,23 +514,30 @@ let SpineSystem = class SpineSystem extends Renderer {
                 armature.y = tran.size.height * tran.origin.y;
             }
             container.addChildAt(armature, 0);
+            /** 保证第一帧显示正常 */
             armature.update();
             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);
                 },
             });
@@ -389,6 +572,7 @@ let SpineSystem = class SpineSystem extends Renderer {
         });
     }
 };
+/** 系统名称 */
 SpineSystem.systemName = 'SpineSystem';
 SpineSystem = __decorate([
     decorators.componentObserver({

package/package.json

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