@eva/plugin-renderer-lottie 2.0.1-beta.4 → 2.0.1-beta.40

package/dist/plugin-renderer-lottie.esm.js

@@ -1,6 +1,6 @@
 import { decorators, OBSERVER_TYPE, resource, Component } from '@eva/eva.js';
 import { Renderer } from '@eva/plugin-renderer';
-import { UPDATE_PRIORITY, Ticker, Container, Texture, Graphics, Matrix as Matrix$1, Sprite, Assets, Text, TextStyle } from 'pixi.js';
+import { Ticker, Container, Assets, Texture, Graphics, Text, Matrix as Matrix$1, Sprite, TextStyle } from 'pixi.js';
 import iOSVersion from 'ios-version';
 
 /*! *****************************************************************************
@@ -271,7 +271,7 @@ if (typeof Uint8ClampedArray === 'function' && typeof Float32Array === 'function
  * @param {*} len a
  * @return {*}
  */
-function createSizedArray$1(len) {
+function createSizedArray$2(len) {
   return new Array(len);
 }
 
@@ -501,7 +501,7 @@ var BezierFactory = {
  * @return {*}
  */
 function _double(arr) {
-  return arr.concat(createSizedArray$1(arr.length));
+  return arr.concat(createSizedArray$2(arr.length));
 }
 var pooling = {
   double: _double,
@@ -510,7 +510,7 @@ var pooling = {
 var PoolFactory = function PoolFactory(initialLength, _create, _release) {
   var _length = 0;
   var _maxLength = initialLength;
-  var pool = createSizedArray$1(_maxLength);
+  var pool = createSizedArray$2(_maxLength);
   var ob = {
     newElement: newElement,
     release: release,
@@ -790,7 +790,7 @@ function buildBezierData(pt1, pt2, pt3, pt4) {
     var bezierData = new BezierData(curveSegments);
     var len = pt3.length;
     for (var k = 0; k < curveSegments; k += 1) {
-      point = createSizedArray$1(len);
+      point = createSizedArray$2(len);
       var perc = k / (curveSegments - 1);
       ptDistance = 0;
       for (var i = 0; i < len; i += 1) {
@@ -2178,9 +2178,9 @@ var ShapePath = /*#__PURE__*/ (function () {
     this.c = false;
     this._length = 0;
     this._maxLength = 8;
-    this.v = createSizedArray$1(this._maxLength);
-    this.o = createSizedArray$1(this._maxLength);
-    this.i = createSizedArray$1(this._maxLength);
+    this.v = createSizedArray$2(this._maxLength);
+    this.o = createSizedArray$2(this._maxLength);
+    this.i = createSizedArray$2(this._maxLength);
   }
 
   /**
@@ -2224,9 +2224,9 @@ var ShapePath = /*#__PURE__*/ (function () {
     {
       key: 'doubleArrayLength',
       value: function doubleArrayLength() {
-        this.v = this.v.concat(createSizedArray$1(this._maxLength));
-        this.i = this.i.concat(createSizedArray$1(this._maxLength));
-        this.o = this.o.concat(createSizedArray$1(this._maxLength));
+        this.v = this.v.concat(createSizedArray$2(this._maxLength));
+        this.i = this.i.concat(createSizedArray$2(this._maxLength));
+        this.o = this.o.concat(createSizedArray$2(this._maxLength));
         this._maxLength *= 2;
       },
 
@@ -2395,7 +2395,7 @@ var ShapeCollection = /*#__PURE__*/ (function () {
     _classCallCheck(this, ShapeCollection);
     this._length = 0;
     this._maxLength = 4;
-    this.shapes = createSizedArray$1(this._maxLength);
+    this.shapes = createSizedArray$2(this._maxLength);
   }
 
   /**
@@ -2407,7 +2407,7 @@ var ShapeCollection = /*#__PURE__*/ (function () {
       key: 'addShape',
       value: function addShape(shapeData) {
         if (this._length === this._maxLength) {
-          this.shapes = this.shapes.concat(createSizedArray$1(this._maxLength));
+          this.shapes = this.shapes.concat(createSizedArray$2(this._maxLength));
           this._maxLength *= 2;
         }
         this.shapes[this._length] = shapeData;
@@ -2432,7 +2432,7 @@ var ShapeCollection = /*#__PURE__*/ (function () {
 
 var _length = 0;
 var _maxLength = 4;
-var pool = createSizedArray$1(_maxLength);
+var pool = createSizedArray$2(_maxLength);
 
 /**
  * a
@@ -3257,7 +3257,7 @@ var MaskFrames = /*#__PURE__*/ (function (_DynamicPropertyConta) {
     _this.propType = 'mask';
     _this.masksProperties = masksProperties || [];
     _this.initDynamicPropertyContainer(elem);
-    _this.viewData = createSizedArray$1(_this.masksProperties.length);
+    _this.viewData = createSizedArray$2(_this.masksProperties.length);
     var len = _this.masksProperties.length;
     var hasMasks = false;
     for (var i = 0; i < len; i++) {
@@ -5688,7 +5688,7 @@ var DashProperty = /*#__PURE__*/ (function (_DynamicPropertyConta) {
     _this = _callSuper(this, DashProperty);
     _this.elem = elem;
     _this.frameId = -1;
-    _this.dataProps = createSizedArray$1(data.length);
+    _this.dataProps = createSizedArray$2(data.length);
     // this.renderer = renderer;
     _this.k = false;
     // this.dashStr = '';
@@ -7413,7 +7413,7 @@ var TextAnimatorProperty = /*#__PURE__*/ (function (_DynamicPropertyConta) {
     _this._textData = textData;
     _this._renderType = renderType;
     _this.elem = elem;
-    _this._animatorsData = createSizedArray$1(_this._textData.a.length);
+    _this._animatorsData = createSizedArray$2(_this._textData.a.length);
     _this._pathData = {};
     _this._moreOptions = {
       alignment: {},
@@ -10208,7 +10208,6 @@ const Tween = {
 };
 
 ({
-  UPDATE_PRIORITY,
   animationTicker: Ticker.shared,
 });
 
@@ -10268,6 +10267,61 @@ class LottieGraphicsMask extends Graphics {
   }
 }
 
+const updateTransformByHierarchy = (container, transform, parent) => {
+  // const localMatrixA = new Matrix();
+
+  if (transform.p) {
+    container.x = transform.p.v[0];
+    container.y = transform.p.v[1];
+  } else {
+    container.x = transform.px.v;
+    container.y = transform.py.v;
+  }
+
+  container.pivot.x = transform.a.v[0];
+  container.pivot.y = transform.a.v[1];
+
+  container.scale.x = transform.s.v[0];
+  container.scale.y = transform.s.v[1];
+
+  if (transform.r) {
+    container.rotation = transform.r.v + transform.orientation;
+  } else if (transform.rz) {
+    container.rotation = transform.rz.v + transform.or.v[2];
+  }
+
+  // let x = transform.p ? transform.p.v[0] : transform.px.v;
+  // let y = transform.p ? transform.p.v[1] : transform.py.v;
+
+  // const rotation = transform.r
+  //   ? transform.r.v + transform.orientation
+  //   : transform.rz
+  //   ? transform.rz.v + transform.or.v[2]
+  //   : 0;
+
+  // localMatrixA.setTransform(
+  //   x,
+  //   y,
+  //   transform.a.v[0],
+  //   transform.a.v[1],
+  //   transform.s.v[0],
+  //   transform.s.v[1],
+  //   rotation,
+  //   0,
+  //   0
+  // );
+
+  // if (parent) {
+  //   const parentWorldTransform = parent.worldTransform.clone();
+  //   container.setFromMatrix(localMatrixA.append(parentWorldTransform));
+  // } else {
+  //   container.setFromMatrix(localMatrixA);
+  // }
+
+  const parentAlpha = parent ? parent.alpha : 1;
+  container.alpha = parentAlpha * transform.o.v;
+};
+
 /**
  * NullElement class
  * @class
@@ -10316,27 +10370,7 @@ class CompElement extends Container {
   }
 
   updateLottieTransform(transform) {
-    if (transform.p) {
-      this.x = transform.p.v[0];
-      this.y = transform.p.v[1];
-    } else {
-      this.x = transform.px.v;
-      this.y = transform.py.v;
-    }
-
-    this.pivot.x = transform.a.v[0];
-    this.pivot.y = transform.a.v[1];
-
-    this.scale.x = transform.s.v[0];
-    this.scale.y = transform.s.v[1];
-
-    if (transform.r) {
-      this.rotation = transform.r.v + transform.orientation;
-    } else if (transform.rz) {
-      this.rotation = transform.rz.v + transform.or.v[2];
-    }
-
-    this.alpha = transform.o.v;
+    updateTransformByHierarchy(this, transform, this.hierarchy);
   }
 
   /**
@@ -10511,27 +10545,7 @@ class ShapeElement extends Graphics {
    * @param {*} transform
    */
   updateLottieTransform(transform) {
-    if (transform.p) {
-      this.x = transform.p.v[0];
-      this.y = transform.p.v[1];
-    } else {
-      this.x = transform.px.v;
-      this.y = transform.py.v;
-    }
-
-    this.pivot.x = transform.a.v[0];
-    this.pivot.y = transform.a.v[1];
-
-    this.scale.x = transform.s.v[0];
-    this.scale.y = transform.s.v[1];
-
-    if (transform.r) {
-      this.rotation = transform.r.v + transform.orientation;
-    } else if (transform.rz) {
-      this.rotation = transform.rz.v + transform.or.v[2];
-    }
-
-    this.alpha = transform.o.v;
+    updateTransformByHierarchy(this, transform, this.hierarchy);
   }
 
   /**
@@ -10557,6 +10571,154 @@ function createSizedArray(len) {
   return Array.apply(null, { length: len });
 }
 
+/**
+ * NullElement class
+ * @class
+ * @private
+ */
+class TextElement extends Text {
+  /**
+   * ShapeElement constructor
+   */
+  constructor(lottieLayer) {
+    super();
+    this.label = lottieLayer.fullname;
+    this.lottieLayer = lottieLayer;
+    this.lottieLayer.lettersChangedFlag = true;
+    if (this.lottieLayer.masks) {
+      this.mask = new LottieGraphicsMask(this.lottieLayer.session.local, this.lottieLayer);
+      this.addChild(this.mask);
+    }
+
+    this.init();
+    this.buildNewText();
+    this.updateLottie = this.updateLottie.bind(this);
+    this.updateLottie(this.lottieLayer, true);
+    this.lottieLayer.on('updatelayer', this.updateLottie);
+    this.onRender = () => {
+      this.updateLottie(this.lottieLayer, true);
+    };
+  }
+
+  init() {
+    this._textSpans = [];
+    this._yOffset = 0;
+    this._fillColorAnim = false;
+    this._strokeColorAnim = false;
+    this._strokeWidthAnim = false;
+    this._stroke = false;
+    this._fill = false;
+    this._justifyOffset = 0;
+    this._currentRender = null;
+    this._renderType = 'canvas';
+    this._fillStyle = {};
+    this._values = {
+      fill: '#000000',
+      stroke: '#000000',
+      sWidth: 0,
+      fValue: '',
+    };
+  }
+
+  buildNewText() {
+    const documentData = this.lottieLayer.textProperty.currentData;
+    this.renderedLetters = createSizedArray(documentData.l ? documentData.l.length : 0);
+    let hasFill = false;
+    if (documentData.fc) {
+      hasFill = true;
+      this._values.fill = Tools.rgb2hex(
+        documentData.fc.map(item => {
+          return item > 1 ? item : item * 255;
+        }),
+        documentData.fc,
+      );
+    } else {
+      this._values.fill = '#000000';
+    }
+    this._fill = hasFill;
+    let hasStroke = false;
+    if (documentData.sc) {
+      hasStroke = true;
+      this._values.stroke = this.buildColor(documentData.sc);
+      this._values.sWidth = documentData.sw;
+    }
+    const fontManager = this.lottieLayer.global.fontManager;
+    this._stroke = hasStroke;
+    this._values.fontSize = documentData.finalSize;
+    this._values.fontFamily = fontManager.getFontByName(documentData.f).fFamily;
+    this._values.fontWeight = documentData.fWeight;
+    this._values.fontStyle = documentData.fStyle;
+    this._values.lineHeight = documentData.finalLineHeight;
+    this._text = documentData.t;
+
+    this.renderText();
+  }
+
+  async renderText() {
+    this.text = this._text;
+    if (this.style.fontFamily) {
+      await Assets.get(this.style.fontFamily);
+    }
+    this.style.fontFamily = this._values.fontFamily;
+    this.style.fontSize = this._values.fontSize;
+    this.style.fill = this._values.fill;
+    this.style.fontWeight = this._values.fontWeight;
+    this.style.fontStyle = this._values.fontStyle;
+    this.style.lineHeight = this._values.lineHeight;
+
+    this.anchor.x = 0.5;
+    this.anchor.y = 0.8;
+  }
+
+  /**
+   * update lottie information
+   * @param {*} lottieLayer lottie element object
+   * @param {boolean} forceUpdate forceUpdate
+   */
+  updateLottie(lottieLayer, _forceUpdate = false) {
+    let forceUpdate = true;
+    if (lottieLayer.transform && forceUpdate) {
+      this.updateLottieTransform(lottieLayer.transform);
+    }
+    if (lottieLayer.masks && forceUpdate) {
+      this.updateLottieMasks(lottieLayer.masks);
+    }
+    if (lottieLayer._mdf) {
+      this.renderText();
+    }
+    this.visible = lottieLayer.isInRange;
+    this._onUpdate();
+  }
+
+  /**
+   * a
+   * @param {*} parent a
+   */
+  setTransformHierarchy(parent) {
+    this.hierarchy = parent;
+  }
+
+  /**
+   * a
+   * @param {*} transform
+   */
+  updateLottieTransform(transform) {
+    updateTransformByHierarchy(this, transform, this.hierarchy);
+  }
+
+  /**
+   * a
+   * @param {*} masks a
+   */
+  updateLottieMasks(masks) {
+    this.mask.updateMasks(masks);
+  }
+}
+
+function createSizedArray$1(len) {
+  return Array.apply(null, { length: len });
+}
+
 class MatrixHelper extends Matrix$1 {
   reset() {
     // 重置为单位矩阵
@@ -10630,7 +10792,7 @@ class MatrixHelper extends Matrix$1 {
  * @class
  * @private
  */
-class TextElement extends Graphics {
+class TextGlyphsElement extends Graphics {
   /**
    * ShapeElement constructor
    */
@@ -10676,15 +10838,14 @@ class TextElement extends Graphics {
 
   buildNewText() {
     const documentData = this.lottieLayer.textProperty.currentData;
-    this.renderedLetters = createSizedArray(documentData.l ? documentData.l.length : 0);
+    this.renderedLetters = createSizedArray$1(documentData.l ? documentData.l.length : 0);
     let hasFill = false;
     if (documentData.fc) {
       hasFill = true;
       this._values.fill = Tools.rgb2hex(
-        // documentData.fc.map((item) => {
-        //   console.log(item)
-        //   return item > 1 ? item : item * 255
-        // }),
+        documentData.fc.map(item => {
+          return item > 1 ? item : item * 255;
+        }),
         documentData.fc,
       );
     } else {
@@ -10741,8 +10902,7 @@ class TextElement extends Graphics {
       shapes = shapeData.shapes ? shapeData.shapes[0].it : [];
       jLen = shapes.length;
       matrixHelper.scale(documentData.finalSize / 100, documentData.finalSize / 100);
-      commands = createSizedArray(jLen - 1);
-      window.$commands.push(commands);
+      commands = createSizedArray$1(jLen - 1);
       let commandsCounter = 0;
       for (j = 0; j < jLen; j += 1) {
         if (shapes[j].ty === 'sh') {
@@ -10957,27 +11117,7 @@ class TextElement extends Graphics {
    * @param {*} transform
    */
   updateLottieTransform(transform) {
-    if (transform.p) {
-      this.x = transform.p.v[0];
-      this.y = transform.p.v[1];
-    } else {
-      this.x = transform.px.v;
-      this.y = transform.py.v;
-    }
-
-    this.pivot.x = transform.a.v[0];
-    this.pivot.y = transform.a.v[1];
-
-    this.scale.x = transform.s.v[0];
-    this.scale.y = transform.s.v[1];
-
-    if (transform.r) {
-      this.rotation = transform.r.v + transform.orientation;
-    } else if (transform.rz) {
-      this.rotation = transform.rz.v + transform.or.v[2];
-    }
-
-    this.alpha = transform.o.v;
+    updateTransformByHierarchy(this, transform, this.hierarchy);
   }
 
   /**
@@ -11043,27 +11183,7 @@ class SolidElement extends Graphics {
    * @param {*} transform
    */
   updateLottieTransform(transform) {
-    if (transform.p) {
-      this.x = transform.p.v[0];
-      this.y = transform.p.v[1];
-    } else {
-      this.x = transform.px.v;
-      this.y = transform.py.v;
-    }
-
-    this.pivot.x = transform.a.v[0];
-    this.pivot.y = transform.a.v[1];
-
-    this.scale.x = transform.s.v[0];
-    this.scale.y = transform.s.v[1];
-
-    if (transform.r) {
-      this.rotation = transform.r.v + transform.orientation;
-    } else if (transform.rz) {
-      this.rotation = transform.rz.v + transform.or.v[2];
-    }
-
-    this.alpha = transform.o.v;
+    updateTransformByHierarchy(this, transform, this.hierarchy);
   }
 
   /**
@@ -11138,27 +11258,7 @@ class SpriteElement extends Sprite {
    * @param {*} transform
    */
   updateLottieTransform(transform) {
-    if (transform.p) {
-      this.x = transform.p.v[0];
-      this.y = transform.p.v[1];
-    } else {
-      this.x = transform.px.v;
-      this.y = transform.py.v;
-    }
-
-    this.pivot.x = transform.a.v[0];
-    this.pivot.y = transform.a.v[1];
-
-    this.scale.x = transform.s.v[0];
-    this.scale.y = transform.s.v[1];
-
-    if (transform.r) {
-      this.rotation = transform.r.v + transform.orientation;
-    } else if (transform.rz) {
-      this.rotation = transform.rz.v + transform.or.v[2];
-    }
-
-    this.alpha = transform.o.v;
+    updateTransformByHierarchy(this, transform, this.hierarchy);
   }
 
   /**
@@ -11377,6 +11477,29 @@ function loadJson(path) {
   return new LoadJson(path);
 }
 
+const getLayerBySubstituteId = (lottieFile, substituteId) => {
+  const { substituteIds } = lottieFile || {};
+  if (!substituteIds || Object.keys(substituteIds).length === 0) return null;
+  let layer;
+  // 在复合图层内部
+  if (substituteId && substituteId.indexOf('_') === -1) {
+    const outerIndex = Number(substituteId);
+    if (!Number.isNaN(outerIndex)) {
+      layer = lottieFile?.layers?.[outerIndex];
+    }
+  } else if (substituteId) {
+    // 在顶层图层
+    const substituteIdArr = substituteId.split('_');
+    const outerIndex = Number(substituteIdArr[0]);
+    const innerIndex = Number(substituteIdArr[1]);
+    if (!Number.isNaN(outerIndex) && !Number.isNaN(innerIndex)) {
+      const asset = lottieFile.assets[outerIndex];
+      layer = asset?.layers?.[innerIndex];
+    }
+  }
+  return layer;
+};
+
 /**
  * an animation group, store and compute frame information, one lottie animate one AnimationGroup
  * @class
@@ -11405,6 +11528,7 @@ class AnimationGroup extends Eventer {
    * @param {boolean} [options.depthTest=true] enable depth test for 3d layer
    * @param {boolean} [options.maskComp=false] add mask for each comp
    * @param {string} [options.prefix=''] assets url prefix, look like link path
+   * @param {boolean} [options.replaceData=''] assets url prefix, look like link path
    */
   constructor(options) {
     super();
@@ -11635,7 +11759,14 @@ class AnimationGroup extends Eventer {
 
     if (options.keyframes) {
       if (!this._prefix && options.keyframes.prefix) this._prefix = options.keyframes.prefix;
-      this._setupDate(options.keyframes);
+      if (!options.replaceData) {
+        this._setupDate(options.keyframes);
+      } else {
+        this._response = options.keyframes;
+        if (this._replaceData) {
+          this._setupReplaceData();
+        }
+      }
     } else if (options.path) {
       let prefix = '';
       if (options.path.lastIndexOf('\\') !== -1) {
@@ -11647,7 +11778,14 @@ class AnimationGroup extends Eventer {
 
       this.jsonLoader = loadJson(options.path);
       this.jsonLoader.once('success', response => {
-        this._setupDate(response);
+        if (!options.replaceData) {
+          this._setupDate(response);
+        } else {
+          this._response = response;
+          if (this._replaceData) {
+            this._setupReplaceData();
+          }
+        }
       });
       this.jsonLoader.once('error', error => {
         this.emit('error', error);
@@ -11655,6 +11793,43 @@ class AnimationGroup extends Eventer {
     }
   }
 
+  replaceData(data) {
+    this._replaceData = data;
+    this._setupReplaceData();
+  }
+
+  _setupReplaceData() {
+    if (this._response && this._replaceData) {
+      if (this._response.substituteIds) {
+        const revertSubstituteIds = {};
+        for (const key in this._response.substituteIds) {
+          const value = this._response.substituteIds[key];
+          revertSubstituteIds[value] = key;
+        }
+
+        for (const name in this._replaceData) {
+          const data = this._replaceData[name];
+
+          const layer = getLayerBySubstituteId(this._response, revertSubstituteIds[name]);
+          if (!layer) continue;
+          // 更新图片图层或文本图层的内容
+          const { ty } = layer;
+          if (ty === 2) {
+            const asset = lottieFile.assets.find(item => item.id === layer.refId);
+            if (asset) {
+              asset.p = data;
+            }
+          } else if (ty === 5) {
+            if (layer?.t?.d?.k?.[0]?.s?.t) {
+              layer.t.d.k[0].s.t = data;
+            }
+          }
+        }
+      }
+      this._setupDate(this._response);
+    }
+  }
+
   /**
    * 安装动画数据
    * @private
@@ -11785,8 +11960,20 @@ class AnimationGroup extends Eventer {
         st,
       },
     };
-    session.fontManager.addChars(data.chars);
+    session.fontManager.addChars(data.chars || []);
     session.fontManager.addFonts(data.fonts, document.body);
+    if (data.fonts?.list?.length) {
+      const fonts = data.fonts.list
+        .map(item => ({
+          alias: item.fFamily,
+          src: item.fPath,
+          data: { family: item.fFamily },
+        }))
+        .filter(item => item.src);
+      Assets.load(fonts).catch(e => {
+        console.error(e);
+      });
+    }
 
     this._buildElements(session);
 
@@ -12022,7 +12209,10 @@ class AnimationGroup extends Eventer {
       //   texture,
       // });
     } else {
-      lottieLayer.display = new SpriteElement(lottieLayer, { asset, texture });
+      lottieLayer.display = new SpriteElement(lottieLayer, {
+        asset,
+        texture,
+      });
     }
     return lottieLayer;
   }
@@ -12065,7 +12255,13 @@ class AnimationGroup extends Eventer {
   _extraText(layer, session) {
     layer.global = session;
     const lottieLayer = new TextLottieLayer(layer, session);
-    lottieLayer.display = new TextElement(lottieLayer);
+    const usesGlyphs = !!session.fontManager.chars?.length;
+    if (usesGlyphs) {
+      lottieLayer.display = new TextGlyphsElement(lottieLayer);
+    } else {
+      lottieLayer.display = new TextElement(lottieLayer);
+    }
+
     return lottieLayer;
   }
 
@@ -12300,10 +12496,11 @@ class AnimationGroup extends Eventer {
    */
   update(snippetCache, firstFrame = false) {
     if (!this.living || !this.isDisplayLoaded || (this.isPaused && !firstFrame)) return;
-
-    const isEnd = this._updateTime(snippetCache);
-
-    const correctedFrameNum = this.beginFrame + this.frameNum;
+    let isEnd = this._updateTime(snippetCache);
+    const correctedFrameNum = this.direction === 1 ? this.beginFrame + this.frameNum : this.frameNum;
+    if (this.direction === -1 && correctedFrameNum <= this.beginFrame) {
+      isEnd = true;
+    }
     this.root.updateFrame(correctedFrameNum);
 
     const np = correctedFrameNum >> 0;
@@ -12405,6 +12602,7 @@ class AnimationGroup extends Eventer {
    * @param {boolean} [options.alternate=false] alternate direction every round
    * @param {number} [options.wait=0] need wait how much millisecond to start
    * @param {number} [options.delay=0] need delay how much millisecond to begin, effect every loop round
+   * @param {number} [options.direction=1] need direction
    * @return {this}
    */
   playSegment(name, options = {}) {
@@ -12428,6 +12626,11 @@ class AnimationGroup extends Eventer {
     if (Tools.isBoolean(options.alternate)) this.alternate = options.alternate;
     if (Tools.isNumber(options.wait)) this.wait = options.wait;
     if (Tools.isNumber(options.delay)) this.delay = options.delay;
+    if (Tools.isNumber(options.direction)) {
+      this.direction = options.direction;
+    } else {
+      this.direction = 1;
+    }
 
     this.replay();
     return this;
@@ -12533,9 +12736,15 @@ class AnimationGroup extends Eventer {
     this._repeatsCut = this.repeats;
     this._delayCut = this.delay;
     this.living = true;
-    this.frameNum = 0;
+    // 根据播放方向设置初始帧位置
+    if (this.direction === -1) {
+      // 倒着播放从duration开始
+      this.frameNum = this.duration;
+    } else {
+      // 正常播放从0开始
+      this.frameNum = 0;
+    }
     this.duration = Math.floor(this.endFrame - this.beginFrame);
-    this.direction = 1;
     return this;
   }
 
@@ -12904,6 +13113,12 @@ let LottieSystem = class LottieSystem extends Renderer {
             'update',
         ];
     }
+    /**
+     * System 初始化用，可以配置参数，游戏未开始
+     *
+     * System init, set params, game is not begain
+     * @param param init params
+     */
     init() {
         this.renderSystem = this.game.getSystem('Renderer');
         this.app = this.renderSystem.application;
@@ -12921,16 +13136,17 @@ let LottieSystem = class LottieSystem extends Renderer {
         });
     }
     add(changed) {
+        var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             this.manager = new AnimationManager(this.app);
             const component = changed.component;
             const container = this.renderSystem.containerManager.getContainer(changed.gameObject.id);
             if (!container)
                 return;
-            const _a = component.options, { resource: rn } = _a, otherOpts = __rest(_a, ["resource"]);
+            const _c = component.options, { resource: rn } = _c, otherOpts = __rest(_c, ["resource"]);
             const res = yield resource.getResource(rn);
             const data = res.data;
-            const url = res.src.json.url;
+            const url = ((_b = (_a = res.src) === null || _a === void 0 ? void 0 : _a.json) === null || _b === void 0 ? void 0 : _b.url) || '';
             const json = Object.assign({}, (data.json || {}));
             const assets = json.assets || [];
             assets.forEach(item => {
@@ -12939,6 +13155,9 @@ let LottieSystem = class LottieSystem extends Renderer {
             });
             const anim = this.manager.parseAnimation(Object.assign({ keyframes: json, prefix: this.getDir(url) }, otherOpts));
             component.anim = anim;
+            if (component._replaceData) {
+                anim.replaceData(component._replaceData);
+            }
             container.addChildAt(anim.group, 0);
             this.managerLife.forEach(eventName => {
                 anim.on(eventName, e => component.emit(eventName, e));
@@ -12948,6 +13167,8 @@ let LottieSystem = class LottieSystem extends Renderer {
         });
     }
     getDir(url) {
+        if (!url)
+            return url;
         return new URL('./', url).href;
     }
     remove(changed) {
@@ -12968,12 +13189,78 @@ LottieSystem = __decorate([
 ], LottieSystem);
 var LottieSystem$1 = LottieSystem;
 
+/**
+ * Lottie 动画组件
+ *
+ * Lottie 组件用于播放 Adobe After Effects 导出的 Lottie 动画文件。
+ * Lottie 是一种基于 JSON 的动画格式，可以实现复杂的矢量动画效果，
+ * 文件体积小、性能高，适用于图标动画、loading 动画、复杂 UI 动效等场景。
+ *
+ * 主要功能：
+ * - 播放 Lottie JSON 动画
+ * - 支持动画片段播放和循环
+ * - 支持插槽（slot）动态替换内容
+ * - 支持帧事件监听
+ * - 支持交互热区绑定
+ * - 支持动态替换动画数据
+ *
+ * @example
+ * ```typescript
+ * // 基础用法
+ * const animation = new GameObject('animation');
+ * animation.addComponent(new Lottie({
+ *   resource: 'loadingAnimation', // Lottie JSON 资源
+ *   autoStart: true
+ * }));
+ *
+ * // 播放指定片段
+ * const lottie = animation.getComponent('Lottie');
+ * lottie.play([0, 60], { repeats: -1 }); // 播放 0-60 帧，无限循环
+ *
+ * // 动态替换插槽内容
+ * lottie.play([0, 120], {
+ *   slot: [{
+ *     name: 'avatar',
+ *     type: 'IMAGE',
+ *     value: 'user-avatar.png',
+ *     style: { width: 100, height: 100 }
+ *   }, {
+ *     name: 'username',
+ *     type: 'TEXT',
+ *     value: '玩家名称',
+ *     style: { fontSize: 24 }
+ *   }]
+ * });
+ *
+ * // 监听特定帧事件
+ * lottie.on('@30', () => {
+ *   console.log('到达第 30 帧');
+ * });
+ *
+ * // 绑定点击热区
+ * lottie.onTap('buttonLayer', () => {
+ *   console.log('按钮被点击');
+ * });
+ * ```
+ */
 class Lottie extends Component {
+    /**
+     * 构造 Lottie 组件
+     * @param options - Lottie 配置选项
+     * @param options.resource - Lottie JSON 资源名称
+     * @param options.autoStart - 是否自动开始播放
+     */
     constructor(options) {
         super();
+        /** 待替换的数据 */
+        this._replaceData = null;
+        /** 资源加载状态 */
         this.loadStatus = false;
+        /** 首次播放回调 */
         this.firstPlay = null;
+        /** 前一次的插槽内容 */
         this.prevSlot = {};
+        /** 当前的插槽内容 */
         this.currentSlot = {};
         this.options = Object.assign({ autoStart: false }, options);
         this.on('success', () => {
@@ -13024,6 +13311,14 @@ class Lottie extends Component {
         });
         this.anim.playSegment(this.playParamsHandle(params), expandOpts);
     }
+    replaceData(data) {
+        if (data) {
+            if (this.anim)
+                this.anim.replaceData(data);
+            else
+                this._replaceData = data;
+        }
+    }
     playParamsHandle(params) {
         let p = [].concat(params);
         const { keyframes } = this.anim;
@@ -13050,6 +13345,7 @@ class Lottie extends Component {
         });
     }
 }
+/** 组件名称 */
 Lottie.componentName = 'Lottie';
 
 resource.registerResourceType('LOTTIE');