@eva/plugin-renderer-sprite-animation 2.0.1-beta.3 → 2.0.1-beta.31

package/dist/EVA.plugin.renderer.spriteAnimation.js

@@ -155,6 +155,7 @@ var _EVA_IIFE_spriteAnimation = function (exports, eva_js, pluginRenderer, rende
       const texture = data.image instanceof pixi_js.Texture ? data.image : pixi_js.Texture.from(data.image);
       const frames = textureObj.frames || {};
       const animations = textureObj.animations || {};
+      const newAnimations = {};
       const newFrames = {};
       for (const key in frames) {
         const newKey = name + resourceKeySplit + key;
@@ -168,10 +169,12 @@ var _EVA_IIFE_spriteAnimation = function (exports, eva_js, pluginRenderer, rende
             spriteList.push(newSpriteName);
           }
         }
-        animations[key] = spriteList;
+        newAnimations[key] = spriteList;
       }
-      textureObj.frames = newFrames;
-      const spriteSheet = new pixi_js.Spritesheet(texture, textureObj);
+      const spriteSheet = new pixi_js.Spritesheet(texture, _extends(_extends({}, textureObj), {
+        frames: newFrames,
+        animations: newAnimations
+      }));
       spriteSheet.parse().then(() => {
         const {
           textures

package/dist/EVA.plugin.renderer.spriteAnimation.min.js

@@ -1 +1 @@
-function _extends(){return _extends=Object.assign?Object.assign.bind():function(e){for(var t=1;t<arguments.length;t++){var i=arguments[t];for(var n in i)({}).hasOwnProperty.call(i,n)&&(e[n]=i[n])}return e},_extends.apply(null,arguments)}globalThis.EVA=globalThis.EVA||{},globalThis.EVA.plugin=globalThis.EVA.plugin||{},globalThis.EVA.plugin.renderer=globalThis.EVA.plugin.renderer||{};var _EVA_IIFE_spriteAnimation=function(e,t,i,n,o){"use strict";function r(e,t,i,n){var o,r=arguments.length,s=r<3?t:null===n?n=Object.getOwnPropertyDescriptor(t,i):n;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)s=Reflect.decorate(e,t,i,n);else for(var a=e.length-1;a>=0;a--)(o=e[a])&&(s=(r<3?o(s):r>3?o(t,i,s):o(t,i))||s);return r>3&&s&&Object.defineProperty(t,i,s),s}function s(e,t,i,n){return new(i||(i=Promise))((function(o,r){function s(e){try{c(n.next(e))}catch(e){r(e)}}function a(e){try{c(n.throw(e))}catch(e){r(e)}}function c(e){var t;e.done?o(e.value):(t=e.value,t instanceof i?t:new i((function(e){e(t)}))).then(s,a)}c((n=n.apply(e,t||[])).next())}))}function a(e,t){return e.constructor.IDEProps||(e.constructor.IDEProps={}),e.constructor.IDEProps[t]||(e.constructor.IDEProps[t]={}),e.constructor.IDEProps[t]}function c(e){return function(t,i){var n=a(t,i);n.key=i,n.type=e}}class m extends t.Component{constructor(){super(...arguments),this.resource="",this.autoPlay=!0,this.speed=100,this.forwards=!1,this.waitPlay=!1,this.waitStop=!1,this.times=1/0,this.count=0,this.complete=!1}init(e){e&&_extends(this,e),this.on("loop",(()=>{++this.count>=this.times&&(this.forwards?this.gotoAndStop(this.totalFrames-1):this.animate.stop(),this.complete=!0,this.emit("complete"))}))}play(e=1/0){0!==e&&(this.times=e,this.animate?(this.complete&&this.gotoAndStop(0),this.animate.play(),this.count=0,this.complete=!1):this.waitPlay=!0)}stop(){this.animate?this.animate.stop():this.waitStop=!0}set animate(e){this._animate=e,this.waitPlay&&(this.waitPlay=!1,this.play(this.times)),this.waitStop&&(this.waitStop=!1,this.stop())}get animate(){return this._animate}gotoAndPlay(e){this.animate.gotoAndPlay(e)}gotoAndStop(e){this.animate.gotoAndStop(e)}get currentFrame(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.currentFrame}get totalFrames(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.totalFrames}}m.componentName="SpriteAnimation",r([c("string")],m.prototype,"resource",void 0),r([c("boolean")],m.prototype,"autoPlay",void 0),r([c("number"),function(e){return function(t,i){a(t,i).step=e}}(10)],m.prototype,"speed",void 0),r([c("boolean")],m.prototype,"forwards",void 0);const p="_s|r|c_";t.resource.registerInstance(t.RESOURCE_TYPE.SPRITE_ANIMATION,(({name:e,data:t})=>new Promise((i=>{const n=t.json.data,r=t.image instanceof o.Texture?t.image:o.Texture.from(t.image),s=n.frames||{},a=n.animations||{},c={};for(const t in s){c[e+p+t]=s[t]}for(const t in a){const i=[];if(a[t]&&a[t].length>=0)for(const n of a[t]){const t=e+p+n;i.push(t)}a[t]=i}n.frames=c;const m=new o.Spritesheet(r,n);m.parse().then((()=>{const{textures:e}=m,t=[];for(const i in e)t.push(e[i]);i(t)}))})))),t.resource.registerDestroy(t.RESOURCE_TYPE.SPRITE_ANIMATION,(({instance:e})=>{if(e)for(const t of e)t.destroy(!0)}));let d=class extends i.Renderer{constructor(){super(...arguments),this.name="SpriteAnimation",this.animates={},this.autoPlay={}}init(){this.renderSystem=this.game.getSystem(i.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(e){const{width:t,height:i}=e.transform.size;this.animates[e.id]&&(this.animates[e.id].animatedSprite.width=t,this.animates[e.id].animatedSprite.height=i)}componentChanged(e){return s(this,void 0,void 0,(function*(){const i=e.gameObject.id;if("SpriteAnimation"===e.componentName){const n=e.component;if(this.autoPlay[e.gameObject.id]=n.autoPlay,e.type===t.OBSERVER_TYPE.ADD){const o=this.increaseAsyncId(i),{instance:r}=yield t.resource.getResource(n.resource);if(!this.validateAsyncId(i,o))return;r||console.error(`GameObject:${e.gameObject.name}'s Img resource load error`),this.add({frames:r,id:e.gameObject.id,component:n})}else if(e.type===t.OBSERVER_TYPE.CHANGE)if(e.prop&&"speed"===e.prop.prop[0])this.animates[e.gameObject.id].speed=1e3/60/n.speed;else{const o=this.increaseAsyncId(i),{instance:r}=yield t.resource.getResource(n.resource);if(!this.validateAsyncId(i,o))return;r||console.error(`GameObject:${e.gameObject.name}'s Img resource load error`),this.change({frames:r,id:e.gameObject.id,component:n})}else e.type===t.OBSERVER_TYPE.REMOVE&&(this.increaseAsyncId(i),this.remove(e.gameObject.id))}}))}add({frames:e,id:t,component:i}){const o=new n.SpriteAnimation({frames:e});this.animates[t]=o,this.containerManager.getContainer(t).addChildAt(o.animatedSprite,0),o.animatedSprite.onComplete=()=>{i.emit("complete")},o.animatedSprite.onFrameChange=()=>{i.emit("frameChange")},o.animatedSprite.onLoop=()=>{i.emit("loop")},i.animate=this.animates[t],this.animates[t].speed=1e3/60/i.speed,this.autoPlay[t]&&o.animatedSprite.play()}change({frames:e,id:t,component:i}){this.remove(t,!0),this.add({frames:e,id:t,component:i})}remove(e,t){const i=this.animates[e];i&&(this.autoPlay[e]=i.animatedSprite.playing,this.containerManager.getContainer(e).removeChild(i.animatedSprite),i.animatedSprite.destroy(),delete this.animates[e],t||delete this.autoPlay[e])}};d.systemName="SpriteAnimation",d=r([t.decorators.componentObserver({SpriteAnimation:["speed","resource"]})],d);var h=d;return e.SpriteAnimation=m,e.SpriteAnimationSystem=h,Object.defineProperty(e,"__esModule",{value:!0}),e}({},EVA,EVA.plugin.renderer,EVA.rendererAdapter,PIXI);globalThis.EVA.plugin.renderer.spriteAnimation=globalThis.EVA.plugin.renderer.spriteAnimation||_EVA_IIFE_spriteAnimation;
+function _extends(){return _extends=Object.assign?Object.assign.bind():function(e){for(var t=1;t<arguments.length;t++){var i=arguments[t];for(var n in i)({}).hasOwnProperty.call(i,n)&&(e[n]=i[n])}return e},_extends.apply(null,arguments)}globalThis.EVA=globalThis.EVA||{},globalThis.EVA.plugin=globalThis.EVA.plugin||{},globalThis.EVA.plugin.renderer=globalThis.EVA.plugin.renderer||{};var _EVA_IIFE_spriteAnimation=function(e,t,i,n,o){"use strict";function r(e,t,i,n){var o,r=arguments.length,s=r<3?t:null===n?n=Object.getOwnPropertyDescriptor(t,i):n;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)s=Reflect.decorate(e,t,i,n);else for(var a=e.length-1;a>=0;a--)(o=e[a])&&(s=(r<3?o(s):r>3?o(t,i,s):o(t,i))||s);return r>3&&s&&Object.defineProperty(t,i,s),s}function s(e,t,i,n){return new(i||(i=Promise))((function(o,r){function s(e){try{c(n.next(e))}catch(e){r(e)}}function a(e){try{c(n.throw(e))}catch(e){r(e)}}function c(e){var t;e.done?o(e.value):(t=e.value,t instanceof i?t:new i((function(e){e(t)}))).then(s,a)}c((n=n.apply(e,t||[])).next())}))}function a(e,t){return e.constructor.IDEProps||(e.constructor.IDEProps={}),e.constructor.IDEProps[t]||(e.constructor.IDEProps[t]={}),e.constructor.IDEProps[t]}function c(e){return function(t,i){var n=a(t,i);n.key=i,n.type=e}}class m extends t.Component{constructor(){super(...arguments),this.resource="",this.autoPlay=!0,this.speed=100,this.forwards=!1,this.waitPlay=!1,this.waitStop=!1,this.times=1/0,this.count=0,this.complete=!1}init(e){e&&_extends(this,e),this.on("loop",(()=>{++this.count>=this.times&&(this.forwards?this.gotoAndStop(this.totalFrames-1):this.animate.stop(),this.complete=!0,this.emit("complete"))}))}play(e=1/0){0!==e&&(this.times=e,this.animate?(this.complete&&this.gotoAndStop(0),this.animate.play(),this.count=0,this.complete=!1):this.waitPlay=!0)}stop(){this.animate?this.animate.stop():this.waitStop=!0}set animate(e){this._animate=e,this.waitPlay&&(this.waitPlay=!1,this.play(this.times)),this.waitStop&&(this.waitStop=!1,this.stop())}get animate(){return this._animate}gotoAndPlay(e){this.animate.gotoAndPlay(e)}gotoAndStop(e){this.animate.gotoAndStop(e)}get currentFrame(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.currentFrame}get totalFrames(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.totalFrames}}m.componentName="SpriteAnimation",r([c("string")],m.prototype,"resource",void 0),r([c("boolean")],m.prototype,"autoPlay",void 0),r([c("number"),function(e){return function(t,i){a(t,i).step=e}}(10)],m.prototype,"speed",void 0),r([c("boolean")],m.prototype,"forwards",void 0);const p="_s|r|c_";t.resource.registerInstance(t.RESOURCE_TYPE.SPRITE_ANIMATION,(({name:e,data:t})=>new Promise((i=>{const n=t.json.data,r=t.image instanceof o.Texture?t.image:o.Texture.from(t.image),s=n.frames||{},a=n.animations||{},c={},m={};for(const t in s){m[e+p+t]=s[t]}for(const t in a){const i=[];if(a[t]&&a[t].length>=0)for(const n of a[t]){const t=e+p+n;i.push(t)}c[t]=i}const d=new o.Spritesheet(r,_extends(_extends({},n),{frames:m,animations:c}));d.parse().then((()=>{const{textures:e}=d,t=[];for(const i in e)t.push(e[i]);i(t)}))})))),t.resource.registerDestroy(t.RESOURCE_TYPE.SPRITE_ANIMATION,(({instance:e})=>{if(e)for(const t of e)t.destroy(!0)}));let d=class extends i.Renderer{constructor(){super(...arguments),this.name="SpriteAnimation",this.animates={},this.autoPlay={}}init(){this.renderSystem=this.game.getSystem(i.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(e){const{width:t,height:i}=e.transform.size;this.animates[e.id]&&(this.animates[e.id].animatedSprite.width=t,this.animates[e.id].animatedSprite.height=i)}componentChanged(e){return s(this,void 0,void 0,(function*(){const i=e.gameObject.id;if("SpriteAnimation"===e.componentName){const n=e.component;if(this.autoPlay[e.gameObject.id]=n.autoPlay,e.type===t.OBSERVER_TYPE.ADD){const o=this.increaseAsyncId(i),{instance:r}=yield t.resource.getResource(n.resource);if(!this.validateAsyncId(i,o))return;r||console.error(`GameObject:${e.gameObject.name}'s Img resource load error`),this.add({frames:r,id:e.gameObject.id,component:n})}else if(e.type===t.OBSERVER_TYPE.CHANGE)if(e.prop&&"speed"===e.prop.prop[0])this.animates[e.gameObject.id].speed=1e3/60/n.speed;else{const o=this.increaseAsyncId(i),{instance:r}=yield t.resource.getResource(n.resource);if(!this.validateAsyncId(i,o))return;r||console.error(`GameObject:${e.gameObject.name}'s Img resource load error`),this.change({frames:r,id:e.gameObject.id,component:n})}else e.type===t.OBSERVER_TYPE.REMOVE&&(this.increaseAsyncId(i),this.remove(e.gameObject.id))}}))}add({frames:e,id:t,component:i}){const o=new n.SpriteAnimation({frames:e});this.animates[t]=o,this.containerManager.getContainer(t).addChildAt(o.animatedSprite,0),o.animatedSprite.onComplete=()=>{i.emit("complete")},o.animatedSprite.onFrameChange=()=>{i.emit("frameChange")},o.animatedSprite.onLoop=()=>{i.emit("loop")},i.animate=this.animates[t],this.animates[t].speed=1e3/60/i.speed,this.autoPlay[t]&&o.animatedSprite.play()}change({frames:e,id:t,component:i}){this.remove(t,!0),this.add({frames:e,id:t,component:i})}remove(e,t){const i=this.animates[e];i&&(this.autoPlay[e]=i.animatedSprite.playing,this.containerManager.getContainer(e).removeChild(i.animatedSprite),i.animatedSprite.destroy(),delete this.animates[e],t||delete this.autoPlay[e])}};d.systemName="SpriteAnimation",d=r([t.decorators.componentObserver({SpriteAnimation:["speed","resource"]})],d);var h=d;return e.SpriteAnimation=m,e.SpriteAnimationSystem=h,Object.defineProperty(e,"__esModule",{value:!0}),e}({},EVA,EVA.plugin.renderer,EVA.rendererAdapter,PIXI);globalThis.EVA.plugin.renderer.spriteAnimation=globalThis.EVA.plugin.renderer.spriteAnimation||_EVA_IIFE_spriteAnimation;

package/dist/plugin-renderer-sprite-animation.cjs.js

@@ -39,19 +39,74 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+/**
+ * 精灵动画组件
+ *
+ * SpriteAnimation 组件用于播放帧动画（序列帧动画）。
+ * 通过快速切换精灵图集中的不同帧，实现动画效果，
+ * 适用于角色动作、特效、UI 动画等场景。
+ *
+ * 主要功能：
+ * - 支持自动播放和手动控制
+ * - 可配置播放速度和循环次数
+ * - 支持跳转到指定帧
+ * - 提供播放完成事件
+ * - 支持 forwards 模式（停在最后一帧）
+ *
+ * @example
+ * ```typescript
+ * // 基础用法 - 自动播放
+ * const character = new GameObject('character');
+ * character.addComponent(new SpriteAnimation({
+ *   resource: 'walkAnimation', // 帧动画资源
+ *   autoPlay: true,
+ *   speed: 100 // 播放速度（毫秒/帧）
+ * }));
+ *
+ * // 控制播放
+ * const anim = character.getComponent('SpriteAnimation');
+ * anim.play(3); // 播放 3 次
+ * anim.play(Infinity); // 无限循环
+ * anim.stop(); // 停止播放
+ * anim.gotoAndPlay(10); // 跳到第 10 帧并播放
+ * anim.gotoAndStop(0); // 跳到第 0 帧并停止
+ *
+ * // 监听播放完成
+ * anim.on('complete', () => {
+ *   console.log('动画播放完成');
+ * });
+ * ```
+ */
 class SpriteAnimation$2 extends eva_js.Component {
     constructor() {
         super(...arguments);
+        /** 帧动画资源名称 */
         this.resource = '';
+        /** 是否自动播放 */
         this.autoPlay = true;
+        /** 播放速度（毫秒/帧） */
         this.speed = 100;
+        /** 是否在最后一帧停止（forwards 模式） */
         this.forwards = false;
+        /** 等待播放标志（资源加载前调用 play） */
         this.waitPlay = false;
+        /** 等待停止标志 */
         this.waitStop = false;
+        /** 播放次数 */
         this.times = Infinity;
+        /** 当前已播放次数 */
         this.count = 0;
+        /** 是否播放完成 */
         this.complete = false;
     }
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.resource - 帧动画资源名称
+     * @param obj.autoPlay - 是否自动播放
+     * @param obj.speed - 播放速度
+     * @param obj.forwards - 是否停在最后一帧
+     */
     init(obj) {
         obj && Object.assign(this, obj);
         this.on('loop', () => {
@@ -121,6 +176,7 @@ class SpriteAnimation$2 extends eva_js.Component {
         return (_b = (_a = this.animate) === null || _a === void 0 ? void 0 : _a.animatedSprite) === null || _b === void 0 ? void 0 : _b.totalFrames;
     }
 }
+/** 组件名称 */
 SpriteAnimation$2.componentName = 'SpriteAnimation';
 __decorate([
     inspectorDecorator.type('string')
@@ -143,6 +199,7 @@ eva_js.resource.registerInstance(eva_js.RESOURCE_TYPE.SPRITE_ANIMATION, ({ name,
         const texture = data.image instanceof pixi_js.Texture ? data.image : pixi_js.Texture.from(data.image);
         const frames = textureObj.frames || {};
         const animations = textureObj.animations || {};
+        const newAnimations = {};
         const newFrames = {};
         for (const key in frames) {
             const newKey = name + resourceKeySplit + key;
@@ -156,10 +213,9 @@ eva_js.resource.registerInstance(eva_js.RESOURCE_TYPE.SPRITE_ANIMATION, ({ name,
                     spriteList.push(newSpriteName);
                 }
             }
-            animations[key] = spriteList;
+            newAnimations[key] = spriteList;
         }
-        textureObj.frames = newFrames;
-        const spriteSheet = new pixi_js.Spritesheet(texture, textureObj);
+        const spriteSheet = new pixi_js.Spritesheet(texture, Object.assign(Object.assign({}, textureObj), { frames: newFrames, animations: newAnimations }));
         spriteSheet.parse().then(() => {
             const { textures } = spriteSheet;
             const spriteFrames = [];

package/dist/plugin-renderer-sprite-animation.cjs.prod.js

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@eva/eva.js"),t=require("@eva/inspector-decorator"),i=require("@eva/plugin-renderer"),a=require("@eva/renderer-adapter"),n=require("pixi.js");
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@eva/eva.js"),t=require("@eva/inspector-decorator"),i=require("@eva/plugin-renderer"),a=require("@eva/renderer-adapter"),s=require("pixi.js");
 /*! *****************************************************************************
 Copyright (c) Microsoft Corporation. All rights reserved.
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
@@ -13,4 +13,4 @@ MERCHANTABLITY OR NON-INFRINGEMENT.
 See the Apache Version 2.0 License for specific language governing permissions
 and limitations under the License.
 ***************************************************************************** */
-function s(e,t,i,a){var n,s=arguments.length,o=s<3?t:null===a?a=Object.getOwnPropertyDescriptor(t,i):a;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)o=Reflect.decorate(e,t,i,a);else for(var r=e.length-1;r>=0;r--)(n=e[r])&&(o=(s<3?n(o):s>3?n(t,i,o):n(t,i))||o);return s>3&&o&&Object.defineProperty(t,i,o),o}class o extends e.Component{constructor(){super(...arguments),this.resource="",this.autoPlay=!0,this.speed=100,this.forwards=!1,this.waitPlay=!1,this.waitStop=!1,this.times=1/0,this.count=0,this.complete=!1}init(e){e&&Object.assign(this,e),this.on("loop",(()=>{++this.count>=this.times&&(this.forwards?this.gotoAndStop(this.totalFrames-1):this.animate.stop(),this.complete=!0,this.emit("complete"))}))}play(e=1/0){0!==e&&(this.times=e,this.animate?(this.complete&&this.gotoAndStop(0),this.animate.play(),this.count=0,this.complete=!1):this.waitPlay=!0)}stop(){this.animate?this.animate.stop():this.waitStop=!0}set animate(e){this._animate=e,this.waitPlay&&(this.waitPlay=!1,this.play(this.times)),this.waitStop&&(this.waitStop=!1,this.stop())}get animate(){return this._animate}gotoAndPlay(e){this.animate.gotoAndPlay(e)}gotoAndStop(e){this.animate.gotoAndStop(e)}get currentFrame(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.currentFrame}get totalFrames(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.totalFrames}}o.componentName="SpriteAnimation",s([t.type("string")],o.prototype,"resource",void 0),s([t.type("boolean")],o.prototype,"autoPlay",void 0),s([t.type("number"),t.step(10)],o.prototype,"speed",void 0),s([t.type("boolean")],o.prototype,"forwards",void 0);const r="_s|r|c_";e.resource.registerInstance(e.RESOURCE_TYPE.SPRITE_ANIMATION,(({name:e,data:t})=>new Promise((i=>{const a=t.json.data,s=t.image instanceof n.Texture?t.image:n.Texture.from(t.image),o=a.frames||{},m=a.animations||{},c={};for(const t in o){c[e+r+t]=o[t]}for(const t in m){const i=[];if(m[t]&&m[t].length>=0)for(const a of m[t]){const t=e+r+a;i.push(t)}m[t]=i}a.frames=c;const p=new n.Spritesheet(s,a);p.parse().then((()=>{const{textures:e}=p,t=[];for(const i in e)t.push(e[i]);i(t)}))})))),e.resource.registerDestroy(e.RESOURCE_TYPE.SPRITE_ANIMATION,(({instance:e})=>{if(e)for(const t of e)t.destroy(!0)}));let m=class extends i.Renderer{constructor(){super(...arguments),this.name="SpriteAnimation",this.animates={},this.autoPlay={}}init(){this.renderSystem=this.game.getSystem(i.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(e){const{width:t,height:i}=e.transform.size;this.animates[e.id]&&(this.animates[e.id].animatedSprite.width=t,this.animates[e.id].animatedSprite.height=i)}componentChanged(t){return i=this,a=void 0,s=function*(){const i=t.gameObject.id;if("SpriteAnimation"===t.componentName){const a=t.component;if(this.autoPlay[t.gameObject.id]=a.autoPlay,t.type===e.OBSERVER_TYPE.ADD){const n=this.increaseAsyncId(i),{instance:s}=yield e.resource.getResource(a.resource);if(!this.validateAsyncId(i,n))return;s||console.error(`GameObject:${t.gameObject.name}'s Img resource load error`),this.add({frames:s,id:t.gameObject.id,component:a})}else if(t.type===e.OBSERVER_TYPE.CHANGE)if(t.prop&&"speed"===t.prop.prop[0])this.animates[t.gameObject.id].speed=1e3/60/a.speed;else{const n=this.increaseAsyncId(i),{instance:s}=yield e.resource.getResource(a.resource);if(!this.validateAsyncId(i,n))return;s||console.error(`GameObject:${t.gameObject.name}'s Img resource load error`),this.change({frames:s,id:t.gameObject.id,component:a})}else t.type===e.OBSERVER_TYPE.REMOVE&&(this.increaseAsyncId(i),this.remove(t.gameObject.id))}},new((n=void 0)||(n=Promise))((function(e,t){function o(e){try{m(s.next(e))}catch(e){t(e)}}function r(e){try{m(s.throw(e))}catch(e){t(e)}}function m(t){t.done?e(t.value):new n((function(e){e(t.value)})).then(o,r)}m((s=s.apply(i,a||[])).next())}));var i,a,n,s}add({frames:e,id:t,component:i}){const n=new a.SpriteAnimation({frames:e});this.animates[t]=n,this.containerManager.getContainer(t).addChildAt(n.animatedSprite,0),n.animatedSprite.onComplete=()=>{i.emit("complete")},n.animatedSprite.onFrameChange=()=>{i.emit("frameChange")},n.animatedSprite.onLoop=()=>{i.emit("loop")},i.animate=this.animates[t],this.animates[t].speed=1e3/60/i.speed,this.autoPlay[t]&&n.animatedSprite.play()}change({frames:e,id:t,component:i}){this.remove(t,!0),this.add({frames:e,id:t,component:i})}remove(e,t){const i=this.animates[e];i&&(this.autoPlay[e]=i.animatedSprite.playing,this.containerManager.getContainer(e).removeChild(i.animatedSprite),i.animatedSprite.destroy(),delete this.animates[e],t||delete this.autoPlay[e])}};m.systemName="SpriteAnimation",m=s([e.decorators.componentObserver({SpriteAnimation:["speed","resource"]})],m);var c=m;exports.SpriteAnimation=o,exports.SpriteAnimationSystem=c;
+function n(e,t,i,a){var s,n=arguments.length,o=n<3?t:null===a?a=Object.getOwnPropertyDescriptor(t,i):a;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)o=Reflect.decorate(e,t,i,a);else for(var r=e.length-1;r>=0;r--)(s=e[r])&&(o=(n<3?s(o):n>3?s(t,i,o):s(t,i))||o);return n>3&&o&&Object.defineProperty(t,i,o),o}class o extends e.Component{constructor(){super(...arguments),this.resource="",this.autoPlay=!0,this.speed=100,this.forwards=!1,this.waitPlay=!1,this.waitStop=!1,this.times=1/0,this.count=0,this.complete=!1}init(e){e&&Object.assign(this,e),this.on("loop",(()=>{++this.count>=this.times&&(this.forwards?this.gotoAndStop(this.totalFrames-1):this.animate.stop(),this.complete=!0,this.emit("complete"))}))}play(e=1/0){0!==e&&(this.times=e,this.animate?(this.complete&&this.gotoAndStop(0),this.animate.play(),this.count=0,this.complete=!1):this.waitPlay=!0)}stop(){this.animate?this.animate.stop():this.waitStop=!0}set animate(e){this._animate=e,this.waitPlay&&(this.waitPlay=!1,this.play(this.times)),this.waitStop&&(this.waitStop=!1,this.stop())}get animate(){return this._animate}gotoAndPlay(e){this.animate.gotoAndPlay(e)}gotoAndStop(e){this.animate.gotoAndStop(e)}get currentFrame(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.currentFrame}get totalFrames(){var e,t;return null===(t=null===(e=this.animate)||void 0===e?void 0:e.animatedSprite)||void 0===t?void 0:t.totalFrames}}o.componentName="SpriteAnimation",n([t.type("string")],o.prototype,"resource",void 0),n([t.type("boolean")],o.prototype,"autoPlay",void 0),n([t.type("number"),t.step(10)],o.prototype,"speed",void 0),n([t.type("boolean")],o.prototype,"forwards",void 0);const r="_s|r|c_";e.resource.registerInstance(e.RESOURCE_TYPE.SPRITE_ANIMATION,(({name:e,data:t})=>new Promise((i=>{const a=t.json.data,n=t.image instanceof s.Texture?t.image:s.Texture.from(t.image),o=a.frames||{},m=a.animations||{},c={},p={};for(const t in o){p[e+r+t]=o[t]}for(const t in m){const i=[];if(m[t]&&m[t].length>=0)for(const a of m[t]){const t=e+r+a;i.push(t)}c[t]=i}const d=new s.Spritesheet(n,Object.assign(Object.assign({},a),{frames:p,animations:c}));d.parse().then((()=>{const{textures:e}=d,t=[];for(const i in e)t.push(e[i]);i(t)}))})))),e.resource.registerDestroy(e.RESOURCE_TYPE.SPRITE_ANIMATION,(({instance:e})=>{if(e)for(const t of e)t.destroy(!0)}));let m=class extends i.Renderer{constructor(){super(...arguments),this.name="SpriteAnimation",this.animates={},this.autoPlay={}}init(){this.renderSystem=this.game.getSystem(i.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(e){const{width:t,height:i}=e.transform.size;this.animates[e.id]&&(this.animates[e.id].animatedSprite.width=t,this.animates[e.id].animatedSprite.height=i)}componentChanged(t){return i=this,a=void 0,n=function*(){const i=t.gameObject.id;if("SpriteAnimation"===t.componentName){const a=t.component;if(this.autoPlay[t.gameObject.id]=a.autoPlay,t.type===e.OBSERVER_TYPE.ADD){const s=this.increaseAsyncId(i),{instance:n}=yield e.resource.getResource(a.resource);if(!this.validateAsyncId(i,s))return;n||console.error(`GameObject:${t.gameObject.name}'s Img resource load error`),this.add({frames:n,id:t.gameObject.id,component:a})}else if(t.type===e.OBSERVER_TYPE.CHANGE)if(t.prop&&"speed"===t.prop.prop[0])this.animates[t.gameObject.id].speed=1e3/60/a.speed;else{const s=this.increaseAsyncId(i),{instance:n}=yield e.resource.getResource(a.resource);if(!this.validateAsyncId(i,s))return;n||console.error(`GameObject:${t.gameObject.name}'s Img resource load error`),this.change({frames:n,id:t.gameObject.id,component:a})}else t.type===e.OBSERVER_TYPE.REMOVE&&(this.increaseAsyncId(i),this.remove(t.gameObject.id))}},new((s=void 0)||(s=Promise))((function(e,t){function o(e){try{m(n.next(e))}catch(e){t(e)}}function r(e){try{m(n.throw(e))}catch(e){t(e)}}function m(t){t.done?e(t.value):new s((function(e){e(t.value)})).then(o,r)}m((n=n.apply(i,a||[])).next())}));var i,a,s,n}add({frames:e,id:t,component:i}){const s=new a.SpriteAnimation({frames:e});this.animates[t]=s,this.containerManager.getContainer(t).addChildAt(s.animatedSprite,0),s.animatedSprite.onComplete=()=>{i.emit("complete")},s.animatedSprite.onFrameChange=()=>{i.emit("frameChange")},s.animatedSprite.onLoop=()=>{i.emit("loop")},i.animate=this.animates[t],this.animates[t].speed=1e3/60/i.speed,this.autoPlay[t]&&s.animatedSprite.play()}change({frames:e,id:t,component:i}){this.remove(t,!0),this.add({frames:e,id:t,component:i})}remove(e,t){const i=this.animates[e];i&&(this.autoPlay[e]=i.animatedSprite.playing,this.containerManager.getContainer(e).removeChild(i.animatedSprite),i.animatedSprite.destroy(),delete this.animates[e],t||delete this.autoPlay[e])}};m.systemName="SpriteAnimation",m=n([e.decorators.componentObserver({SpriteAnimation:["speed","resource"]})],m);var c=m;exports.SpriteAnimation=o,exports.SpriteAnimationSystem=c;

package/dist/plugin-renderer-sprite-animation.d.ts

@@ -7,18 +7,75 @@ import { RendererManager } from '@eva/plugin-renderer';
 import { RendererSystem } from '@eva/plugin-renderer';
 import { SpriteAnimation as SpriteAnimation_2 } from '@eva/renderer-adapter';
 
+/**
+ * 精灵动画组件
+ *
+ * SpriteAnimation 组件用于播放帧动画（序列帧动画）。
+ * 通过快速切换精灵图集中的不同帧，实现动画效果，
+ * 适用于角色动作、特效、UI 动画等场景。
+ *
+ * 主要功能：
+ * - 支持自动播放和手动控制
+ * - 可配置播放速度和循环次数
+ * - 支持跳转到指定帧
+ * - 提供播放完成事件
+ * - 支持 forwards 模式（停在最后一帧）
+ *
+ * @example
+ * ```typescript
+ * // 基础用法 - 自动播放
+ * const character = new GameObject('character');
+ * character.addComponent(new SpriteAnimation({
+ *   resource: 'walkAnimation', // 帧动画资源
+ *   autoPlay: true,
+ *   speed: 100 // 播放速度（毫秒/帧）
+ * }));
+ *
+ * // 控制播放
+ * const anim = character.getComponent('SpriteAnimation');
+ * anim.play(3); // 播放 3 次
+ * anim.play(Infinity); // 无限循环
+ * anim.stop(); // 停止播放
+ * anim.gotoAndPlay(10); // 跳到第 10 帧并播放
+ * anim.gotoAndStop(0); // 跳到第 0 帧并停止
+ *
+ * // 监听播放完成
+ * anim.on('complete', () => {
+ *   console.log('动画播放完成');
+ * });
+ * ```
+ */
 export declare class SpriteAnimation extends Component<SpriteAnimationParams> {
+    /** 组件名称 */
     static componentName: string;
+    /** 帧动画资源名称 */
     resource: string;
+    /** 是否自动播放 */
     autoPlay: boolean;
+    /** 播放速度（毫秒/帧） */
     speed: number;
+    /** 是否在最后一帧停止（forwards 模式） */
     forwards: boolean;
+    /** 动画引擎实例 */
     _animate: SpriteAnimation_2;
+    /** 等待播放标志（资源加载前调用 play） */
     private waitPlay;
+    /** 等待停止标志 */
     private waitStop;
+    /** 播放次数 */
     private times;
+    /** 当前已播放次数 */
     private count;
+    /** 是否播放完成 */
     private complete;
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.resource - 帧动画资源名称
+     * @param obj.autoPlay - 是否自动播放
+     * @param obj.speed - 播放速度
+     * @param obj.forwards - 是否停在最后一帧
+     */
     init(obj?: SpriteAnimationParams): void;
     play(times?: number): void;
     stop(): void;
@@ -34,6 +91,7 @@ export declare interface SpriteAnimationParams {
     resource: string;
     autoPlay?: boolean;
     speed?: number;
+    /** Stop at last frame */
     forwards?: boolean;
 }
 

package/dist/plugin-renderer-sprite-animation.esm.js

@@ -35,19 +35,74 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+/**
+ * 精灵动画组件
+ *
+ * SpriteAnimation 组件用于播放帧动画（序列帧动画）。
+ * 通过快速切换精灵图集中的不同帧，实现动画效果，
+ * 适用于角色动作、特效、UI 动画等场景。
+ *
+ * 主要功能：
+ * - 支持自动播放和手动控制
+ * - 可配置播放速度和循环次数
+ * - 支持跳转到指定帧
+ * - 提供播放完成事件
+ * - 支持 forwards 模式（停在最后一帧）
+ *
+ * @example
+ * ```typescript
+ * // 基础用法 - 自动播放
+ * const character = new GameObject('character');
+ * character.addComponent(new SpriteAnimation({
+ *   resource: 'walkAnimation', // 帧动画资源
+ *   autoPlay: true,
+ *   speed: 100 // 播放速度（毫秒/帧）
+ * }));
+ *
+ * // 控制播放
+ * const anim = character.getComponent('SpriteAnimation');
+ * anim.play(3); // 播放 3 次
+ * anim.play(Infinity); // 无限循环
+ * anim.stop(); // 停止播放
+ * anim.gotoAndPlay(10); // 跳到第 10 帧并播放
+ * anim.gotoAndStop(0); // 跳到第 0 帧并停止
+ *
+ * // 监听播放完成
+ * anim.on('complete', () => {
+ *   console.log('动画播放完成');
+ * });
+ * ```
+ */
 class SpriteAnimation$2 extends Component {
     constructor() {
         super(...arguments);
+        /** 帧动画资源名称 */
         this.resource = '';
+        /** 是否自动播放 */
         this.autoPlay = true;
+        /** 播放速度（毫秒/帧） */
         this.speed = 100;
+        /** 是否在最后一帧停止（forwards 模式） */
         this.forwards = false;
+        /** 等待播放标志（资源加载前调用 play） */
         this.waitPlay = false;
+        /** 等待停止标志 */
         this.waitStop = false;
+        /** 播放次数 */
         this.times = Infinity;
+        /** 当前已播放次数 */
         this.count = 0;
+        /** 是否播放完成 */
         this.complete = false;
     }
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.resource - 帧动画资源名称
+     * @param obj.autoPlay - 是否自动播放
+     * @param obj.speed - 播放速度
+     * @param obj.forwards - 是否停在最后一帧
+     */
     init(obj) {
         obj && Object.assign(this, obj);
         this.on('loop', () => {
@@ -117,6 +172,7 @@ class SpriteAnimation$2 extends Component {
         return (_b = (_a = this.animate) === null || _a === void 0 ? void 0 : _a.animatedSprite) === null || _b === void 0 ? void 0 : _b.totalFrames;
     }
 }
+/** 组件名称 */
 SpriteAnimation$2.componentName = 'SpriteAnimation';
 __decorate([
     type('string')
@@ -139,6 +195,7 @@ resource.registerInstance(RESOURCE_TYPE.SPRITE_ANIMATION, ({ name, data }) => {
         const texture = data.image instanceof Texture ? data.image : Texture.from(data.image);
         const frames = textureObj.frames || {};
         const animations = textureObj.animations || {};
+        const newAnimations = {};
         const newFrames = {};
         for (const key in frames) {
             const newKey = name + resourceKeySplit + key;
@@ -152,10 +209,9 @@ resource.registerInstance(RESOURCE_TYPE.SPRITE_ANIMATION, ({ name, data }) => {
                     spriteList.push(newSpriteName);
                 }
             }
-            animations[key] = spriteList;
+            newAnimations[key] = spriteList;
         }
-        textureObj.frames = newFrames;
-        const spriteSheet = new Spritesheet(texture, textureObj);
+        const spriteSheet = new Spritesheet(texture, Object.assign(Object.assign({}, textureObj), { frames: newFrames, animations: newAnimations }));
         spriteSheet.parse().then(() => {
             const { textures } = spriteSheet;
             const spriteFrames = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-renderer-sprite-animation",
-  "version": "2.0.1-beta.3",
+  "version": "2.0.1-beta.31",
   "description": "@eva/plugin-renderer-sprite-animation",
   "main": "index.js",
   "module": "dist/plugin-renderer-sprite-animation.esm.js",
@@ -19,9 +19,9 @@
   "homepage": "https://eva.js.org",
   "dependencies": {
     "@eva/inspector-decorator": "^0.0.5",
-    "@eva/plugin-renderer": "2.0.1-beta.3",
-    "@eva/renderer-adapter": "2.0.1-beta.3",
-    "@eva/eva.js": "2.0.1-beta.3",
+    "@eva/plugin-renderer": "2.0.1-beta.31",
+    "@eva/renderer-adapter": "2.0.1-beta.31",
+    "@eva/eva.js": "2.0.1-beta.31",
     "pixi.js": "^8.8.1"
   }
 }