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

package/dist/spine-base.d.ts

@@ -3,34 +3,224 @@ import { Component } from '@eva/eva.js';
 import { ComponentChanged } from '@eva/eva.js';
 import { Container } from 'pixi.js';
 import { ContainerManager } from '@eva/plugin-renderer';
+import { GameObject } from '@eva/eva.js';
 import { Renderer } from '@eva/plugin-renderer';
 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;
+    /** 容器管理器引用（由 SpineSystem 设置） */
+    _containerManager: any;
+    /** 挂载到插槽的 GameObject 映射（GameObject -> { slot, wrapper }） */
+    private _slotGameObjects;
+    /** 等待容器就绪的 slot 挂载请求 */
+    _pendingSlotObjects: {
+        slot: number | string;
+        gameObject: GameObject;
+        options?: {
+            followAttachmentTimeline?: boolean;
+        };
+    }[];
+    /** 等待执行的动画操作队列 */
     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;
+    /**
+     * 将一个 GameObject 挂载到 Spine 的指定插槽上
+     *
+     * 挂载后 GameObject 会跟随骨骼运动。当 Spine 组件销毁时，
+     * 挂载的 GameObject 也会被自动销毁。
+     *
+     * @param slot - 插槽名称或索引
+     * @param gameObject - 要挂载的 GameObject
+     * @param options - 可选配置
+     * @param options.followAttachmentTimeline - 是否跟随插槽的附件时间线
+     */
+    addSlotObject(slot: number | string, gameObject: GameObject, options?: {
+        followAttachmentTimeline?: boolean;
+    }): void;
+    private _doAddSlotObject;
+    /**
+     * 递归同步 gameObject 及其子树的 transform 到对应的渲染容器
+     */
+    private _syncTransformTree;
+    /**
+     * 处理等待容器就绪的 slot 挂载请求（由 SpineSystem 每帧调用）
+     */
+    _flushPendingSlotObjects(): void;
+    /**
+     * 从插槽上移除挂载的 GameObject
+     *
+     * @param gameObject - 要移除的 GameObject
+     */
+    removeSlotObject(gameObject: GameObject): void;
+    /**
+     * 销毁所有挂载到插槽的 GameObject（内部使用）
+     */
+    _destroySlotGameObjects(): void;
 }
 
 export declare interface SpineParams {
@@ -40,16 +230,47 @@ 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>;
+    /** Spine 组件实例映射（游戏对象 ID -> Spine 组件） */
+    private _spineComponents;
+    /** 渲染系统引用 */
     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>;