@galacean/effects-threejs 2.10.0-alpha.0 → 2.10.0-alpha.1

package/dist/index.js

@@ -3,7 +3,7 @@
  * Description: Galacean Effects runtime threejs plugin for the web
  * Author: Ant Group CO., Ltd.
  * Contributors: 燃然,飂兮,十弦,云垣,茂安,意绮
- * Version: v2.10.0-alpha.0
+ * Version: v2.10.0-alpha.1
  */
 
 'use strict';
@@ -726,6 +726,26 @@ function clamp$1(value, min, max) {
         array[offset] = this.x;
         array[offset + 1] = this.y;
     };
+    /**
+     * 计算向量相对于正 x 轴的角度（弧度）
+     * @returns 弧度值
+     */ _proto.angle = function angle() {
+        var angle = Math.atan2(-this.y, -this.x) + Math.PI;
+        return angle;
+    };
+    /**
+     * 绕指定中心点旋转向量
+     * @param center - 旋转中心
+     * @param angle - 旋转角度（弧度）
+     * @returns 旋转结果
+     */ _proto.rotateAround = function rotateAround(center, angle) {
+        var c = Math.cos(angle), s = Math.sin(angle);
+        var x = this.x - center.x;
+        var y = this.y - center.y;
+        this.x = x * c - y * s + center.x;
+        this.y = x * s + y * c + center.y;
+        return this;
+    };
     /**
      * 随机生成向量
      * @returns 向量
@@ -1279,6 +1299,25 @@ Vector2.ZERO = new Vector2(0.0, 0.0);
      */ _proto.applyProjectionMatrix = function applyProjectionMatrix(m, out) {
         return m.projectPoint(this, out);
     };
+    /**
+     * 从四维矩阵提取平移分量
+     * @param m - 四维矩阵
+     * @returns 向量
+     */ _proto.setFromMatrixPosition = function setFromMatrixPosition(m) {
+        var e = m.elements;
+        this.x = e[12];
+        this.y = e[13];
+        this.z = e[14];
+        return this;
+    };
+    /**
+     * 从四维矩阵提取指定列的三维分量
+     * @param m - 四维矩阵
+     * @param index - 列下标
+     * @returns 向量
+     */ _proto.setFromMatrixColumn = function setFromMatrixColumn(m, index) {
+        return this.setFromArray(m.elements, index * 4);
+    };
     /**
      * 通过标量数值创建向量
      * @param num - 数值
@@ -2919,17 +2958,27 @@ var PluginSystem = /*#__PURE__*/ function() {
     PluginSystem.getPlugins = function getPlugins() {
         return plugins;
     };
-    PluginSystem.initializeComposition = function initializeComposition(composition, scene) {
-        plugins.forEach(function(loader) {
-            return loader.onCompositionCreated(composition, scene);
+    PluginSystem.notifyCompositionCreated = function notifyCompositionCreated(composition, scene) {
+        plugins.forEach(function(plugin) {
+            return plugin.onCompositionCreated(composition, scene);
+        });
+    };
+    PluginSystem.notifyCompositionDestroy = function notifyCompositionDestroy(composition) {
+        plugins.forEach(function(plugin) {
+            return plugin.onCompositionDestroy(composition);
+        });
+    };
+    PluginSystem.notifyEngineCreated = function notifyEngineCreated(engine) {
+        plugins.forEach(function(plugin) {
+            return plugin.onEngineCreated(engine);
         });
     };
-    PluginSystem.destroyComposition = function destroyComposition(comp) {
-        plugins.forEach(function(loader) {
-            return loader.onCompositionDestroy(comp);
+    PluginSystem.notifyEngineDestroy = function notifyEngineDestroy(engine) {
+        plugins.forEach(function(plugin) {
+            return plugin.onEngineDestroy(engine);
         });
     };
-    PluginSystem.onAssetsLoadStart = function onAssetsLoadStart(scene, options) {
+    PluginSystem.notifyAssetsLoadStart = function notifyAssetsLoadStart(scene, options) {
         return _async_to_generator(function() {
             return __generator(this, function(_state) {
                 return [
@@ -2941,9 +2990,9 @@ var PluginSystem = /*#__PURE__*/ function() {
             });
         })();
     };
-    PluginSystem.onAssetsLoadFinish = function onAssetsLoadFinish(scene, options, engine) {
-        plugins.forEach(function(loader) {
-            return loader.onAssetsLoadFinish(scene, options, engine);
+    PluginSystem.notifyAssetsLoadFinish = function notifyAssetsLoadFinish(scene, options, engine) {
+        plugins.forEach(function(plugin) {
+            return plugin.onAssetsLoadFinish(scene, options, engine);
         });
     };
     return PluginSystem;
@@ -3009,6 +3058,18 @@ function getPluginUsageInfo(name) {
    * 合成销毁时触发。
    * @param composition - 合成对象
    */ _proto.onCompositionDestroy = function onCompositionDestroy(composition) {};
+    /**
+   * 引擎创建完成后触发。
+   * 适用于注册引擎级单例、建立以引擎为键的映射、绑定全局监听等场景。
+   * @param engine - 引擎实例
+   * @since 2.10.0
+   */ _proto.onEngineCreated = function onEngineCreated(engine) {};
+    /**
+   * 引擎销毁时触发。
+   * 适合解绑监听、释放引擎级资源或清理以引擎为键的映射。
+   * @param engine - 引擎实例
+   * @since 2.10.0
+   */ _proto.onEngineDestroy = function onEngineDestroy(engine) {};
     return Plugin;
 }();
 
@@ -4996,7 +5057,7 @@ var Animatable = /*#__PURE__*/ function() {
      * @param qb - 四元数
      * @param t - 插值比
      */ _proto.slerpQuaternions = function slerpQuaternions(qa, qb, t) {
-        this.copyFrom(qa).slerp(qb, t);
+        return this.copyFrom(qa).slerp(qb, t);
     };
     /**
      * 通过四元数旋转向量
@@ -7554,7 +7615,10 @@ function setSideMode(material, side) {
         material.cullFace = side === SideMode.BACK ? glContext.BACK : glContext.FRONT;
     }
 }
-function setMaskMode(material, maskMode) {
+/**
+ * @deprecated 2.10 起 runtime 内部已不再通过 `MaskMode` 设置模板测试参数。
+ * 仅为兼容旧版本对外导出的接口而保留，新代码请勿使用。
+ */ function setMaskMode(material, maskMode) {
     switch(maskMode){
         case undefined:
             material.stencilTest = false;
@@ -9439,6 +9503,13 @@ function isUniformStructArray(value) {
         translation.x = te[12];
         translation.y = te[13];
         translation.z = te[14];
+        scale.x = sx;
+        scale.y = sy;
+        scale.z = sz;
+        if (Math.abs(sx) < 1e-8 || Math.abs(sy) < 1e-8 || Math.abs(sz) < 1e-8) {
+            rotation.set(0, 0, 0, 1);
+            return this;
+        }
         // scale the rotation part
         var m = Matrix4.tempMat0;
         m.copyFrom(this);
@@ -9455,9 +9526,6 @@ function isUniformStructArray(value) {
         m.elements[9] *= invSZ;
         m.elements[10] *= invSZ;
         rotation.setFromRotationMatrix(m);
-        scale.x = sx;
-        scale.y = sy;
-        scale.z = sz;
         return this;
     };
     _proto.getTranslation = function getTranslation(translation) {
@@ -9468,6 +9536,45 @@ function isUniformStructArray(value) {
         var te = this.elements;
         return scale.set(Math.hypot(te[0], te[1], te[2]), Math.hypot(te[4], te[5], te[6]), Math.hypot(te[8], te[9], te[10]));
     };
+    /**
+     * 提取矩阵的旋转部分（去除缩放）
+     * @param m - 源矩阵
+     * @returns 矩阵
+     */ _proto.extractRotation = function extractRotation(m) {
+        var v = Matrix4.tempVec0;
+        var me = m.elements;
+        var te = this.elements;
+        var scaleX = 1 / v.set(me[0], me[1], me[2]).length();
+        var scaleY = 1 / v.set(me[4], me[5], me[6]).length();
+        var scaleZ = 1 / v.set(me[8], me[9], me[10]).length();
+        te[0] = me[0] * scaleX;
+        te[1] = me[1] * scaleX;
+        te[2] = me[2] * scaleX;
+        te[3] = 0;
+        te[4] = me[4] * scaleY;
+        te[5] = me[5] * scaleY;
+        te[6] = me[6] * scaleY;
+        te[7] = 0;
+        te[8] = me[8] * scaleZ;
+        te[9] = me[9] * scaleZ;
+        te[10] = me[10] * scaleZ;
+        te[11] = 0;
+        te[12] = 0;
+        te[13] = 0;
+        te[14] = 0;
+        te[15] = 1;
+        return this;
+    };
+    /**
+     * 设置矩阵的平移部分（不影响旋转和缩放）
+     * @param v - 平移向量
+     * @returns 矩阵
+     */ _proto.setPosition = function setPosition(v) {
+        this.elements[12] = v.x;
+        this.elements[13] = v.y;
+        this.elements[14] = v.z;
+        return this;
+    };
     /**
      * 获得矩阵分解的结果
      * @returns 分解的结果
@@ -10761,6 +10868,23 @@ Euler.tempMat0 = new Matrix4();
      */ _proto.equals = function equals(other) {
         return this.origin.equals(other.origin) && this.direction.equals(other.direction);
     };
+    /**
+     * 光线到平面的距离
+     * @param plane - 平面
+     * @returns 距离值，平行且不在平面上时返回 null，平行且在平面上时返回 0
+     */ _proto.distanceToPlane = function distanceToPlane(plane) {
+        var normal = plane.normal;
+        var denominator = normal.dot(this.direction);
+        if (denominator === 0) {
+            // 光线与平面平行
+            if (normal.dot(this.origin) + plane.distance === 0) {
+                return 0;
+            }
+            return null;
+        }
+        var t = -(this.origin.dot(normal) + plane.distance) / denominator;
+        return t >= 0 ? t : null;
+    };
     /**
      * 根据矩阵对光线进行变换
      * @param m - 变换矩阵
@@ -12621,65 +12745,70 @@ exports.MaterialRenderType = void 0;
     return new Material(engine, props);
 };
 
+// 8 位 stencil buffer 上限为 255；为反向蒙版的 INCR 预留 1 的递增余量，
+// 否则当正向蒙版填满到 255 时，反向 INCR 会饱和、无法排除任何像素。
+var MAX_MASK_REFERENCE_COUNT = 254;
 /**
  * @internal
  */ var MaskProcessor = /*#__PURE__*/ function() {
     function MaskProcessor() {
         this.alphaMaskEnabled = false;
         this.isMask = false;
-        this.inverted = false;
-        this.maskMode = exports.MaskMode.NONE;
         /**
    * 多个蒙版引用列表，支持正面和反面蒙版
    */ this.maskReferences = [];
         /**
    * 期望的 stencil 值（等于正向蒙版的数量）
    */ this.expectedStencilValue = 0;
-        this.prevStencilFunc = [
-            0,
-            0
-        ];
-        this.prevStencilOpZPass = [
-            0,
-            0
-        ];
-        this.prevStencilRef = [
-            0,
-            0
-        ];
-        this.prevStencilMask = [
-            0,
-            0
-        ];
         this.stencilClearAction = {
             stencilAction: exports.TextureLoadAction.clear
         };
     }
     var _proto = MaskProcessor.prototype;
     /**
-   * @deprecated
-   */ _proto.getRefValue = function getRefValue() {
-        return 1;
-    };
-    /**
-   * 设置蒙版选项（兼容旧版单蒙版 API）
+   * 设置蒙版选项。
+   *
+   * @param data.references - 蒙版引用列表。
+   *   传入空数组等价于无蒙版。
+   *   超过 254 个引用时，多余部分将被忽略并打印警告。
    */ _proto.setMaskOptions = function setMaskOptions(engine, data) {
-        var _data_isMask = data.isMask, isMask = _data_isMask === void 0 ? false : _data_isMask, _data_inverted = data.inverted, inverted = _data_inverted === void 0 ? false : _data_inverted, reference = data.reference, _data_alphaMaskEnabled = data.alphaMaskEnabled, alphaMaskEnabled = _data_alphaMaskEnabled === void 0 ? false : _data_alphaMaskEnabled;
+        var _data_isMask = data.isMask, isMask = _data_isMask === void 0 ? false : _data_isMask, _data_references = data.references, references = _data_references === void 0 ? [] : _data_references, _data_alphaMaskEnabled = data.alphaMaskEnabled, alphaMaskEnabled = _data_alphaMaskEnabled === void 0 ? false : _data_alphaMaskEnabled;
         this.alphaMaskEnabled = alphaMaskEnabled;
         this.isMask = isMask;
-        this.inverted = inverted;
         this.maskReferences = [];
-        if (isMask) {
-            this.maskMode = exports.MaskMode.MASK;
-        } else {
-            this.maskMode = inverted ? exports.MaskMode.REVERSE_OBSCURED : exports.MaskMode.OBSCURED;
-            var maskable = engine.findObject(reference);
-            if (maskable) {
-                this.maskReferences.push({
-                    maskable: maskable,
-                    inverted: inverted
-                });
+        if (isMask || references.length === 0) {
+            return;
+        }
+        var seen = new Map();
+        for(var _iterator = _create_for_of_iterator_helper_loose(references), _step; !(_step = _iterator()).done;){
+            var ref = _step.value;
+            var maskPath = ref.mask;
+            if (!maskPath) {
+                continue;
             }
+            var maskable = engine.findObject(maskPath);
+            if (!maskable) {
+                console.warn("Mask reference not found: " + JSON.stringify(maskPath) + ". Skipping.");
+                continue;
+            }
+            var _ref_inverted;
+            var inverted = (_ref_inverted = ref.inverted) != null ? _ref_inverted : false;
+            var existingInverted = seen.get(maskable);
+            if (existingInverted !== undefined) {
+                if (existingInverted !== inverted) {
+                    console.warn("Same maskable referenced with conflicting inverted flags; keeping the first occurrence.");
+                }
+                continue;
+            }
+            if (this.maskReferences.length >= MAX_MASK_REFERENCE_COUNT) {
+                console.warn("Maximum of " + MAX_MASK_REFERENCE_COUNT + " mask references exceeded. Additional masks will be ignored.");
+                break;
+            }
+            seen.set(maskable, inverted);
+            this.maskReferences.push({
+                maskable: maskable,
+                inverted: inverted
+            });
         }
     };
     /**
@@ -12692,8 +12821,8 @@ exports.MaterialRenderType = void 0;
             return ref.maskable === maskable;
         });
         if (!exists) {
-            if (this.maskReferences.length >= 255) {
-                console.warn("Maximum of 255 mask references exceeded. Additional masks will be ignored.");
+            if (this.maskReferences.length >= MAX_MASK_REFERENCE_COUNT) {
+                console.warn("Maximum of " + MAX_MASK_REFERENCE_COUNT + " mask references exceeded. Additional masks will be ignored.");
                 return;
             }
             this.maskReferences.push({
@@ -12719,6 +12848,11 @@ exports.MaterialRenderType = void 0;
         this.maskReferences = [];
     };
     /**
+   * 获取当前蒙版引用列表的浅拷贝。
+   */ _proto.getMaskReferences = function getMaskReferences() {
+        return this.maskReferences.slice();
+    };
+    /**
    * 绘制所有蒙版，被蒙版的元素调用。
    *
    * 使用递增 stencil 计数法实现任意数量蒙版的交集：
@@ -12726,12 +12860,17 @@ exports.MaterialRenderType = void 0;
    * 2. 反向蒙版渲染，将已通过所有正向蒙版的像素标记为无效
    * 3. 最终只有 stencil == 正向蒙版数量 的像素才通过测试
    *
-   * 最多支持 255 个蒙版引用（受 8 位 stencil buffer 限制）
+   * 最多支持 254 个蒙版引用（8 位 stencil buffer 上限 255，需为反向 INCR 预留 1）
    */ _proto.drawStencilMask = function drawStencilMask(renderer, maskedComponent) {
         var frameClipMasks = maskedComponent.frameClipMasks;
+        var addedFrameClipMasks = [];
         for(var _iterator = _create_for_of_iterator_helper_loose(frameClipMasks), _step; !(_step = _iterator()).done;){
             var frameClipMask = _step.value;
+            var referenceCount = this.maskReferences.length;
             this.addMaskReference(frameClipMask, false);
+            if (this.maskReferences.length > referenceCount) {
+                addedFrameClipMasks.push(frameClipMask);
+            }
         }
         if (this.maskReferences.length > 0) {
             renderer.clear(this.stencilClearAction);
@@ -12767,7 +12906,7 @@ exports.MaterialRenderType = void 0;
             var material = _step3.value;
             this.setupMaskedMaterial(material);
         }
-        for(var _iterator4 = _create_for_of_iterator_helper_loose(frameClipMasks), _step4; !(_step4 = _iterator4()).done;){
+        for(var _iterator4 = _create_for_of_iterator_helper_loose(addedFrameClipMasks), _step4; !(_step4 = _iterator4()).done;){
             var frameClipMask1 = _step4.value;
             this.removeMaskReference(frameClipMask1);
         }
@@ -12776,24 +12915,24 @@ exports.MaterialRenderType = void 0;
    *  绘制几何体蒙版，蒙版元素绘制时调用
    */ _proto.drawGeometryMask = function drawGeometryMask(renderer, geometry, worldMatrix, material, maskRef, subMeshIndex) {
         if (subMeshIndex === void 0) subMeshIndex = 0;
-        var previousColorMask = material.colorMask;
+        var prevColorMask = material.colorMask;
         var prevStencilTest = material.stencilTest;
-        this.copyStencilArrayValue(this.prevStencilFunc, material.stencilFunc);
-        this.copyStencilArrayValue(this.prevStencilOpZPass, material.stencilOpZPass);
-        this.copyStencilArrayValue(this.prevStencilRef, material.stencilRef);
-        this.copyStencilArrayValue(this.prevStencilMask, material.stencilMask);
-        // const prevStencilOpFail = material.stencilOpFail;
-        // const prevStencilOpZFail = material.stencilOpZFail;
+        var prevStencilFunc = material.stencilFunc;
+        var prevStencilOpFail = material.stencilOpFail;
+        var prevStencilOpZFail = material.stencilOpZFail;
+        var prevStencilOpZPass = material.stencilOpZPass;
+        var prevStencilRef = material.stencilRef;
+        var prevStencilMask = material.stencilMask;
         this.setupMaskMaterial(material, maskRef);
         renderer.drawGeometry(geometry, worldMatrix, material, subMeshIndex);
-        material.colorMask = previousColorMask;
+        material.colorMask = prevColorMask;
         material.stencilTest = prevStencilTest;
-        material.stencilFunc = this.prevStencilFunc;
-        material.stencilOpZPass = this.prevStencilOpZPass;
-        // material.stencilOpFail = prevStencilOpFail;
-        // material.stencilOpZFail = prevStencilOpZFail;
-        material.stencilRef = this.prevStencilRef;
-        material.stencilMask = this.prevStencilMask;
+        material.stencilFunc = prevStencilFunc;
+        material.stencilOpFail = prevStencilOpFail;
+        material.stencilOpZFail = prevStencilOpZFail;
+        material.stencilOpZPass = prevStencilOpZPass;
+        material.stencilRef = prevStencilRef;
+        material.stencilMask = prevStencilMask;
     };
     /**
    * 设置蒙版材质的 stencil 属性（写入蒙版）
@@ -12821,12 +12960,18 @@ exports.MaterialRenderType = void 0;
             0xFF
         ];
         // 通过时递增 stencil 值，不通过时保持不变
+        material.stencilOpFail = [
+            glContext.KEEP,
+            glContext.KEEP
+        ];
+        material.stencilOpZFail = [
+            glContext.KEEP,
+            glContext.KEEP
+        ];
         material.stencilOpZPass = [
             glContext.INCR,
             glContext.INCR
         ];
-        // material.stencilOpFail = [glContext.KEEP, glContext.KEEP];
-        // material.stencilOpZFail = [glContext.KEEP, glContext.KEEP];
         material.colorMask = false; // 不写入颜色
     };
     /**
@@ -12861,13 +13006,6 @@ exports.MaterialRenderType = void 0;
             material.stencilTest = false;
         }
     };
-    _proto.copyStencilArrayValue = function copyStencilArrayValue(target, source) {
-        if (!source) {
-            return;
-        }
-        target[0] = source[0];
-        target[1] = source[1];
-    };
     _create_class(MaskProcessor, [
         {
             key: "maskable",
@@ -12883,7 +13021,7 @@ exports.MaterialRenderType = void 0;
                 if (value) {
                     this.maskReferences.push({
                         maskable: value,
-                        inverted: this.maskMode === exports.MaskMode.REVERSE_OBSCURED
+                        inverted: false
                     });
                 }
             }
@@ -16668,19 +16806,15 @@ function buildBezierEasing(leftKeyframe, rightKeyframe) {
         y2 = numberToFix((p2.y - p0.y) / valueInterval, 5);
     }
     if (x1 < 0) {
-        console.error("Invalid bezier points, x1 < 0", p0, p1, p2, p3);
         x1 = 0;
     }
     if (x2 < 0) {
-        console.error("Invalid bezier points, x2 < 0", p0, p1, p2, p3);
         x2 = 0;
     }
     if (x1 > 1) {
-        console.error("Invalid bezier points, x1 >= 1", p0, p1, p2, p3);
         x1 = 1;
     }
     if (x2 > 1) {
-        console.error("Invalid bezier points, x2 >= 1", p0, p1, p2, p3);
         x2 = 1;
     }
     var str = ("bez_" + x1 + "_" + y1 + "_" + x2 + "_" + y2).replace(/\./g, "p");
@@ -16771,10 +16905,49 @@ function oldBezierKeyFramesToNew(props) {
     return keyframes;
 }
 
+/**
+ * 通用对象引用阶梯曲线（不插值）。对象引用不可插值，
+ * 按时间阶梯采样取 time ≤ t 的最近关键帧。
+ *
+ * 继承 ValueGetter 以复用 PropertyClipPlayable<T>；数值相关方法
+ * （toUniform/toData/getIntegrate*）保留基类 NOT_IMPLEMENT——对象引用 curve
+ * 不走 shader 通路。典型用例：T = Sprite（sprite 属性 K 帧切图）。
+ */ var ReferenceCurve = /*#__PURE__*/ function(ValueGetter) {
+    _inherits(ReferenceCurve, ValueGetter);
+    function ReferenceCurve() {
+        return ValueGetter.apply(this, arguments);
+    }
+    var _proto = ReferenceCurve.prototype;
+    _proto.onCreate = function onCreate(props) {
+        this.keyframes = props;
+    };
+    _proto.getValue = function getValue(time) {
+        var keys = this.keyframes;
+        if (keys.length === 0) {
+            return undefined;
+        }
+        // 阶梯采样：取 time ≤ t 的最大关键帧；t < 首帧取首帧。无插值。
+        var result = keys[0][1];
+        for(var i = 0; i < keys.length; i++){
+            if (keys[i][0] <= (time != null ? time : 0)) {
+                result = keys[i][1];
+            } else {
+                break;
+            }
+        }
+        return result;
+    };
+    return ReferenceCurve;
+}(ValueGetter);
+
 /**
  * Vector2 曲线
  * TODO: add spec
  */ var VECTOR3_CURVE = 27;
+/**
+ * 对象引用阶梯曲线（spec ValueType.REFERENCE_CURVE）。
+ * props 为 [[time, value], ...]，value 为已解析的对象引用实例。
+ */ var REFERENCE_CURVE = 28;
 var _obj$5;
 var map$1 = (_obj$5 = {}, _obj$5[ValueType.RANDOM] = function(props) {
     if (_instanceof1(props[0], Array)) {
@@ -16831,6 +17004,9 @@ var map$1 = (_obj$5 = {}, _obj$5[ValueType.RANDOM] = function(props) {
 }, // TODO: add spec
 _obj$5[VECTOR3_CURVE] = function(props) {
     return new Vector3Curve(props);
+}, // 对象引用阶梯曲线（不插值）：props.data 为 [time, value][]，value 已解析为 EffectsObject
+_obj$5[REFERENCE_CURVE] = function(props) {
+    return new ReferenceCurve(props);
 }, _obj$5);
 function createValueGetter(args) {
     if (!args || !isNaN(+args)) {
@@ -21893,16 +22069,26 @@ var canvasPool = new CanvasPool();
  * 单张字符 atlas 的边长(像素,scale 后的实际像素,非逻辑尺寸)。
  * 512×512 在 24px 字号下约可容纳 250+ 字形,常见 demo 文本足够
  */ var ATLAS_SIZE = 512;
+/**
+ * 字体度量探针字符串。带重音符的 É/Å 把墨水顶推到接近字体真实 ascent，
+ * 单字 'M' 只有 cap height(~0.7em) 太矮，会让 CJK / 带重音字顶部越过 cell 上界被裁
+ */ var METRICS_STRING = "|\xc9q\xc5";
+/** 字体度量基线符号 */ var BASELINE_SYMBOL = "M";
+/**
+ * 字形 cell 四周留白（逻辑像素）。ink 略超字体度量、或 italic 斜体越界时由它吸收，
+ * 保证 cell 采样矩形内不裁切字形
+ */ var GLYPH_PADDING = 4;
 /**
  * 一种字体（family + weight + style + size 唯一确定）对应一张 atlas。
  *
- * Skyline 风格 packer：行内堆字，行尾换行，行高 = (ascent+descent) * FONT_SCALE。
+ * Skyline 风格 packer：行内堆字，行尾换行，cell 高 = ceil((fontHeight + padding*2) * 1)，
+ * 所有字共用同一 cell 高与 baseline，实现同行 baseline 对齐。
  * atlas 满后 `ensureChar` 返回 null，调用方应跳过该字（不再扩页，v1 范围）。
  *
  * canvas 内容变更后需要 `uploadIfDirty` 重新上传到纹理 — 由调用方在使用纹理前主动触发，
  * 避免每加一字都 upload 一次造成的 GL 开销
  */ var GlyphAtlas = /*#__PURE__*/ function() {
-    function GlyphAtlas(engine, scaledFontString, ascent, descent) {
+    function GlyphAtlas(engine, scaledFontString, /** baseline 距 cell 顶距离（像素，scale 后，仅 ascent 部分，不含 padding） */ ascentPx, /** baseline 距 cell 底距离（像素，scale 后，仅 descent 部分） */ descentPx, fontStyle) {
         this.engine = engine;
         this.scaledFontString = scaledFontString;
         this.glyphs = new Map();
@@ -21923,11 +22109,14 @@ var canvasPool = new CanvasPool();
         ctx.font = scaledFontString;
         ctx.textBaseline = "alphabetic";
         ctx.fillStyle = "#ffffff";
-        this.ascent = ascent;
-        this.descent = descent;
-        this.lineHeight = ascent + descent;
-        this.ascentPx = Math.ceil(ascent * FONT_SCALE);
-        this.lineHeightPx = Math.ceil((ascent + descent) * FONT_SCALE);
+        this.paddingPx = GLYPH_PADDING * FONT_SCALE;
+        this.italicScale = fontStyle === "italic" ? 2 : 1;
+        // ascent/descent 由探针 '|ÉqÅM' 测得 actualBoundingBox（重音字已抬高 ink 顶），
+        // 两者内部保持浮点，仅 cell 高做一次外层 ceil — 与 padding 共同保证 cell 内不裁切
+        var fontHeightPx = ascentPx + descentPx;
+        this.baselinePx = this.paddingPx + ascentPx;
+        this.cellHPx = Math.ceil(fontHeightPx + this.paddingPx * 2);
+        this.lineHeight = this.cellHPx / FONT_SCALE;
         this.texture = Texture.create(engine, {
             sourceType: exports.TextureSourceType.image,
             image: this.canvas,
@@ -21956,10 +22145,12 @@ var canvasPool = new CanvasPool();
         ctx.font = this.scaledFontString;
         // measureText 用的是 scaledFontString，advance 已经是 scale 后的像素，不能再乘 FONT_SCALE
         var advancePx = ctx.measureText(char).width;
-        var cellW = Math.max(1, Math.ceil(advancePx));
-        var cellH = this.lineHeightPx;
+        // italic 放大 cell 宽防斜体越界；ceil 对齐像素网格避免相邻字采样重叠
+        var widthPx = Math.max(1, Math.ceil(advancePx * this.italicScale));
+        var paddedWidthPx = widthPx + this.paddingPx * 2;
+        var cellH = this.cellHPx;
         // 行尾换行
-        if (this.currentX + cellW > ATLAS_SIZE) {
+        if (this.currentX + paddedWidthPx > ATLAS_SIZE) {
             this.currentX = 0;
             this.currentY += cellH;
         }
@@ -21971,15 +22162,17 @@ var canvasPool = new CanvasPool();
         }
         var px = this.currentX;
         var py = this.currentY;
-        ctx.fillText(char, px, py + this.ascentPx);
-        this.currentX += cellW;
+        // baseline 落在 cell 顶部下方 paddingPx + ascentPx 处，四周 padding 吸收越界 ink
+        ctx.fillText(char, px + this.paddingPx, py + this.baselinePx);
+        this.currentX += paddedWidthPx;
         this.dirty = true;
         var info = {
             px: px,
             py: py,
-            pw: cellW,
+            pw: paddedWidthPx,
             ph: cellH,
-            width: cellW / FONT_SCALE
+            advance: advancePx / FONT_SCALE,
+            paddingLeft: this.paddingPx / FONT_SCALE
         };
         this.glyphs.set(char, info);
         return info;
@@ -22031,22 +22224,25 @@ var canvasPool = new CanvasPool();
         if (cached) {
             return cached;
         }
-        var fontString = fontStyle + " " + fontWeight + " " + fontSize + "px " + fontFamily;
         var scaledFontString = fontStyle + " " + fontWeight + " " + fontSize * FONT_SCALE + "px " + fontFamily;
-        // 用 'M' 探一次得到字体级 ascent/descent（整张 atlas 共享行高，各字 baseline 对齐）
+        // 探一次得到字体级 ascent/descent（整张 atlas 共享 cell 高与 baseline，各字对齐）。
+        // 直接在 scaledFontString 下测，得到的就是 scale 后像素，无需再乘 FONT_SCALE。
+        // 探针用 '|ÉqÅ' + 'M'：带重音符的 ÉÅ 把 ink 顶推到接近字体真实 ascent，
+        // 单字 'M' 只有 cap height(~0.7em) 太矮，CJK / 带重音字顶部会越过 cell 上界被裁。
+        // 取 actualBoundingBoxAscent/Descent 度量 ink 边界，跨平台语义稳定
         var probeCanvasAndContext = canvasPool.getCanvasAndContext(1, 1);
         var probeCtx = probeCanvasAndContext.context;
-        var ascent = fontSize * 0.8;
-        var descent = fontSize * 0.2;
+        var ascentPx = fontSize * 0.8 * FONT_SCALE;
+        var descentPx = fontSize * 0.2 * FONT_SCALE;
         try {
-            probeCtx.font = fontString;
-            var m = probeCtx.measureText("M");
-            ascent = m.actualBoundingBoxAscent || ascent;
-            descent = m.actualBoundingBoxDescent || descent;
+            probeCtx.font = scaledFontString;
+            var m = probeCtx.measureText(METRICS_STRING + BASELINE_SYMBOL);
+            ascentPx = m.actualBoundingBoxAscent || ascentPx;
+            descentPx = m.actualBoundingBoxDescent || descentPx;
         } finally{
             canvasPool.releaseCanvasAndContext(probeCanvasAndContext);
         }
-        var atlas = new GlyphAtlas(this.engine, scaledFontString, ascent, descent);
+        var atlas = new GlyphAtlas(this.engine, scaledFontString, ascentPx, descentPx, fontStyle);
         this.atlases.set(fontKey, atlas);
         return atlas;
     };
@@ -22450,8 +22646,8 @@ var Graphics = /*#__PURE__*/ function() {
    * `color` 作为乘色与白色字形 alpha 相乘，任意颜色都不会污染 atlas。
    *
    * 字体参数全部展开，避免调用方每帧创建临时 style 对象触发 GC
-   * @param x - 文本左下角 X 坐标
-   * @param y - 文本左下角 Y 坐标（对齐 baseline 上方 ascent 处）
+   * @param x - 文本左下角 X 坐标（首字 ink 起始处，含 padding 的 quad 会向左延伸）
+   * @param y - 文本左下角 Y 坐标（cell 底，含底部 padding；字形 ink 在其上方 padding+ascent 处）
    * @param text - 要绘制的文本内容，空串直接 return
    * @param fontSize - 字号（逻辑像素）
    * @param color - 乘色，默认白色，范围 0-1
@@ -22482,13 +22678,15 @@ var Graphics = /*#__PURE__*/ function() {
             var u1 = (info.px + info.pw) / ATLAS_SIZE;
             var v0 = 1 - (info.py + info.ph) / ATLAS_SIZE;
             var v1 = 1 - info.py / ATLAS_SIZE;
-            this.pushQuad(cursorX, y, info.width, lineHeight, color, {
+            // quad 宽与采样区都含四周 padding（cell 留白透明）；但光标只按 advance 前进，
+            // quad 起点左偏 paddingLeft 使字形 ink 落在 cursorX — padding 区重叠无妨
+            this.pushQuad(cursorX - info.paddingLeft, y, info.pw / FONT_SCALE, lineHeight, color, {
                 u0: u0,
                 v0: v0,
                 u1: u1,
                 v1: v1
             });
-            cursorX += info.width;
+            cursorX += info.advance;
         }
     };
     _proto.dispose = function dispose() {
@@ -22705,7 +22903,6 @@ var Graphics = /*#__PURE__*/ function() {
                 aUV: {
                     size: 2,
                     offset: 0,
-                    releasable: true,
                     type: glContext.FLOAT,
                     data: new Float32Array([
                         0,
@@ -22853,7 +23050,6 @@ var Graphics = /*#__PURE__*/ function() {
     };
     _proto.configureMaterial = function configureMaterial(renderer) {
         var side = renderer.side, occlusion = renderer.occlusion, blendMode = renderer.blending, texture = renderer.texture;
-        var maskMode = this.maskManager.maskMode;
         var material = this.material;
         material.blending = true;
         material.depthTest = true;
@@ -22868,7 +23064,6 @@ var Graphics = /*#__PURE__*/ function() {
         texParams.x = renderer.occlusion ? +renderer.transparentOcclusion : 1;
         texParams.y = preMultiAlpha;
         texParams.z = renderer.renderMode;
-        texParams.w = maskMode;
         material.setVector4("_TexParams", texParams);
         if (texParams.x === 0 || this.maskManager.alphaMaskEnabled) {
             material.enableMacro("ALPHA_CLIP");
@@ -22896,9 +23091,9 @@ var Graphics = /*#__PURE__*/ function() {
             blending: (_renderer_blending = renderer.blending) != null ? _renderer_blending : BlendingMode.ALPHA,
             texture: renderer.texture ? this.engine.findObject(renderer.texture) : this.engine.whiteTexture,
             occlusion: !!renderer.occlusion,
-            transparentOcclusion: !!renderer.transparentOcclusion || this.maskManager.maskMode === exports.MaskMode.MASK,
+            transparentOcclusion: !!renderer.transparentOcclusion || this.maskManager.isMask,
             side: (_renderer_side = renderer.side) != null ? _renderer_side : SideMode.DOUBLE,
-            mask: this.maskManager.getRefValue()
+            mask: 1
         };
         this.configureMaterial(this.renderer);
     };
@@ -24965,6 +25160,50 @@ var SpriteLoader = /*#__PURE__*/ function(Plugin) {
     return SpriteLoader;
 }(_wrap_native_super(Plugin));
 
+exports.SpriteRotation = void 0;
+(function(SpriteRotation) {
+    /** 不旋转 */ SpriteRotation[SpriteRotation["None"] = 0] = "None";
+    /** UV 旋转 90°（对应老 splits flip=1） */ SpriteRotation[SpriteRotation["Rotate90"] = 1] = "Rotate90";
+})(exports.SpriteRotation || (exports.SpriteRotation = {}));
+exports.Sprite = /*#__PURE__*/ function(EffectsObject) {
+    _inherits(Sprite, EffectsObject);
+    function Sprite(engine, props) {
+        var _this;
+        _this = EffectsObject.call(this, engine) || this;
+        /** 归一化 UV 矩形 [x, y, w, h]，默认整张纹理 */ _this.rect = [
+            0,
+            0,
+            1,
+            1
+        ];
+        /** UV 旋转方式（对应老 splits 的 flip 0/1） */ _this.rotation = 0;
+        if (props) {
+            _this.fromData(props);
+        }
+        return _this;
+    }
+    var _proto = Sprite.prototype;
+    _proto.fromData = function fromData(data) {
+        EffectsObject.prototype.fromData.call(this, data);
+        // findObject 对 Texture 实例原样返回，对 {id} 解析为 Texture 实例，
+        // 兼容反序列化（data.texture 为 {id}）与手动构造（data.texture 为 Texture 实例）两条路径。
+        this.texture = data.texture ? this.engine.findObject(data.texture) : this.engine.whiteTexture;
+        var _data_rect;
+        this.rect = (_data_rect = data.rect) != null ? _data_rect : [
+            0,
+            0,
+            1,
+            1
+        ];
+        var _data_rotation;
+        this.rotation = (_data_rotation = data.rotation) != null ? _data_rotation : 0;
+    };
+    return Sprite;
+}(EffectsObject);
+exports.Sprite = __decorate([
+    effectsClass("Sprite")
+], exports.Sprite);
+
 /**
  * 动画图可播放节点对象
  * @since 2.0.0
@@ -25551,6 +25790,36 @@ var SpriteColorMixerPlayable = /*#__PURE__*/ function(TrackMixerPlayable) {
     return SpriteColorMixerPlayable;
 }(TrackMixerPlayable);
 
+/**
+ * Sprite 属性 K 帧 mixer。对象引用不混合：取首个激活 clip 的阶梯采样值，
+ * 赋值 boundObject.sprite 触发 setter（同步纹理 + 重建 UV）。
+ * 不继承 PropertyMixerPlayable（其 evaluate 开头"读当前值为 null 则 return"
+ * 会阻断无初始 sprite 组件的 K 帧）。
+ */ var SpritePropertyMixerPlayable = /*#__PURE__*/ function(TrackMixerPlayable) {
+    _inherits(SpritePropertyMixerPlayable, TrackMixerPlayable);
+    function SpritePropertyMixerPlayable() {
+        return TrackMixerPlayable.apply(this, arguments);
+    }
+    var _proto = SpritePropertyMixerPlayable.prototype;
+    _proto.evaluate = function evaluate(context) {
+        var boundObject = context.output.getUserData();
+        if (!boundObject) {
+            return;
+        }
+        // 对象引用不混合：取首个激活 clip 的采样值
+        for(var i = 0; i < this.clipPlayables.length; i++){
+            if (this.getClipWeight(i) > 0) {
+                var clip = this.getClipPlayable(i);
+                if (_instanceof1(clip, PropertyClipPlayable) && clip.value) {
+                    boundObject.sprite = clip.value;
+                }
+                break;
+            }
+        }
+    };
+    return SpritePropertyMixerPlayable;
+}(TrackMixerPlayable);
+
 var SubCompositionClipPlayable = /*#__PURE__*/ function(Playable) {
     _inherits(SubCompositionClipPlayable, Playable);
     function SubCompositionClipPlayable() {
@@ -25594,94 +25863,148 @@ var SubCompositionMixerPlayable = /*#__PURE__*/ function(TrackMixerPlayable) {
     return SubCompositionMixerPlayable;
 }(TrackMixerPlayable);
 
-var TransformMixerPlayable = /*#__PURE__*/ function(TrackMixerPlayable) {
-    _inherits(TransformMixerPlayable, TrackMixerPlayable);
-    function TransformMixerPlayable() {
-        return TrackMixerPlayable.apply(this, arguments);
-    }
-    var _proto = TransformMixerPlayable.prototype;
-    _proto.evaluate = function evaluate(context) {};
-    return TransformMixerPlayable;
-}(TrackMixerPlayable);
-
-var Vector4PropertyMixerPlayable = /*#__PURE__*/ function(PropertyMixerPlayable) {
-    _inherits(Vector4PropertyMixerPlayable, PropertyMixerPlayable);
-    function Vector4PropertyMixerPlayable() {
-        return PropertyMixerPlayable.apply(this, arguments);
-    }
-    var _proto = Vector4PropertyMixerPlayable.prototype;
-    _proto.resetPropertyValue = function resetPropertyValue() {
-        this.propertyValue.x = 0;
-        this.propertyValue.y = 0;
-        this.propertyValue.z = 0;
-        this.propertyValue.w = 0;
-    };
-    _proto.addWeightedValue = function addWeightedValue(curveValue, weight) {
-        var result = this.propertyValue;
-        result.x += curveValue.x * weight;
-        result.y += curveValue.y * weight;
-        result.z += curveValue.z * weight;
-        result.w += curveValue.w * weight;
-    };
-    return Vector4PropertyMixerPlayable;
-}(PropertyMixerPlayable);
-var Vector3PropertyMixerPlayable = /*#__PURE__*/ function(PropertyMixerPlayable) {
-    _inherits(Vector3PropertyMixerPlayable, PropertyMixerPlayable);
-    function Vector3PropertyMixerPlayable() {
-        return PropertyMixerPlayable.apply(this, arguments);
-    }
-    var _proto = Vector3PropertyMixerPlayable.prototype;
-    _proto.resetPropertyValue = function resetPropertyValue() {
-        this.propertyValue.x = 0;
-        this.propertyValue.y = 0;
-        this.propertyValue.z = 0;
-    };
-    _proto.addWeightedValue = function addWeightedValue(curveValue, weight) {
-        var result = this.propertyValue;
-        result.x += curveValue.x * weight;
-        result.y += curveValue.y * weight;
-        result.z += curveValue.z * weight;
-    };
-    return Vector3PropertyMixerPlayable;
-}(PropertyMixerPlayable);
-var Vector2PropertyMixerPlayable = /*#__PURE__*/ function(PropertyMixerPlayable) {
-    _inherits(Vector2PropertyMixerPlayable, PropertyMixerPlayable);
-    function Vector2PropertyMixerPlayable() {
-        return PropertyMixerPlayable.apply(this, arguments);
-    }
-    var _proto = Vector2PropertyMixerPlayable.prototype;
-    _proto.resetPropertyValue = function resetPropertyValue() {
-        this.propertyValue.x = 0;
-        this.propertyValue.y = 0;
+/**
+ * 对 TransformTrack 当前激活的 Transform clip contribution 做帧内合成。
+ * position 与 rotation 使用增量语义，scale 使用乘子语义；结果由 flush 统一写回。
+ */ var TransformClipMixer = /*#__PURE__*/ function() {
+    function TransformClipMixer() {
+        this.hasContribution = false;
+        this.hasPosition = false;
+        this.hasRotation = false;
+        this.hasScale = false;
+        this.appliedPosition = false;
+        this.appliedRotation = false;
+        this.appliedScale = false;
+        this.outPos = new Vector3();
+        this.outRot = new Euler();
+        this.outScale = new Vector3(1, 1, 1);
+        this.weightedRot = new Euler();
+    }
+    var _proto = TransformClipMixer.prototype;
+    _proto.captureBasePose = function captureBasePose(item) {
+        this.ensureBasePose(item);
+    };
+    /**
+   * orbital position 的 contribution 依赖 base position。
+   * 这里返回 mixer 持有的 base，确保采样和合成使用同一份参考姿态。
+   */ _proto.getBasePosition = function getBasePosition() {
+        var _this_basePose;
+        return (_this_basePose = this.basePose) == null ? void 0 : _this_basePose.position;
+    };
+    _proto.resetFrame = function resetFrame() {
+        this.hasContribution = false;
+        this.hasPosition = false;
+        this.hasRotation = false;
+        this.hasScale = false;
+    };
+    _proto.addContribution = function addContribution(item, contribution, weight) {
+        if (weight <= 0) {
+            return;
+        }
+        this.ensureBasePose(item);
+        if (!this.hasContribution) {
+            var base = this.basePose;
+            this.outPos.copyFrom(base.position);
+            this.outRot.copyFrom(base.rotation);
+            this.outScale.copyFrom(base.scale);
+            this.hasContribution = true;
+        }
+        if (contribution.hasPosition) {
+            this.hasPosition = true;
+            this.outPos.x += contribution.position.x * weight;
+            this.outPos.y += contribution.position.y * weight;
+            this.outPos.z += contribution.position.z * weight;
+        }
+        if (contribution.hasRotation) {
+            this.hasRotation = true;
+            this.weightedRot.set(contribution.rotation.x * weight, contribution.rotation.y * weight, contribution.rotation.z * weight, contribution.rotation.order);
+            this.outRot.addEulers(this.outRot, this.weightedRot);
+        }
+        if (contribution.hasScale) {
+            this.hasScale = true;
+            // Scale contribution 使用乘子语义，weight 用于支持 clip blend/crossfade。
+            this.outScale.x *= Math.pow(contribution.scale.x, weight);
+            this.outScale.y *= Math.pow(contribution.scale.y, weight);
+            this.outScale.z *= Math.pow(contribution.scale.z, weight);
+        }
+    };
+    _proto.flush = function flush(item) {
+        var base = this.basePose;
+        if (!base || !this.hasContribution && !this.appliedPosition && !this.appliedRotation && !this.appliedScale) {
+            return;
+        }
+        if (this.hasPosition) {
+            item.transform.setPosition(this.outPos.x, this.outPos.y, this.outPos.z);
+            this.appliedPosition = true;
+        } else if (this.appliedPosition) {
+            item.transform.setPosition(base.position.x, base.position.y, base.position.z);
+            this.appliedPosition = false;
+        }
+        if (this.hasRotation) {
+            item.transform.setRotation(this.outRot.x, this.outRot.y, this.outRot.z);
+            this.appliedRotation = true;
+        } else if (this.appliedRotation) {
+            item.transform.setRotation(base.rotation.x, base.rotation.y, base.rotation.z);
+            this.appliedRotation = false;
+        }
+        if (this.hasScale) {
+            item.transform.setScale(this.outScale.x, this.outScale.y, this.outScale.z);
+            this.appliedScale = true;
+        } else if (this.appliedScale) {
+            item.transform.setScale(base.scale.x, base.scale.y, base.scale.z);
+            this.appliedScale = false;
+        }
     };
-    _proto.addWeightedValue = function addWeightedValue(curveValue, weight) {
-        var result = this.propertyValue;
-        result.x += curveValue.x * weight;
-        result.y += curveValue.y * weight;
+    _proto.dispose = function dispose() {
+        this.basePose = undefined;
+        this.boundInstanceId = undefined;
+        this.appliedPosition = false;
+        this.appliedRotation = false;
+        this.appliedScale = false;
+        this.resetFrame();
+    };
+    _proto.ensureBasePose = function ensureBasePose(item) {
+        if (!this.basePose || this.boundInstanceId !== item.getInstanceId()) {
+            var scale = item.transform.scale;
+            this.basePose = {
+                position: item.transform.position.clone(),
+                rotation: item.transform.getRotation().clone(),
+                scale: new Vector3(scale.x, scale.y, scale.x)
+            };
+            this.boundInstanceId = item.getInstanceId();
+            this.appliedPosition = false;
+            this.appliedRotation = false;
+            this.appliedScale = false;
+        }
     };
-    return Vector2PropertyMixerPlayable;
-}(PropertyMixerPlayable);
+    return TransformClipMixer;
+}();
 
 var tempRot$1 = new Euler();
-var tempSize$1 = new Vector3(1, 1, 1);
 var tempPos = new Vector3();
+var createEmptyContribution = function() {
+    return {
+        hasPosition: false,
+        position: new Vector3(),
+        hasRotation: false,
+        rotation: new Euler(),
+        hasScale: false,
+        scale: new Vector3(1, 1, 1)
+    };
+};
 /**
  * @since 2.0.0
  */ var TransformPlayable = /*#__PURE__*/ function(Playable) {
     _inherits(TransformPlayable, Playable);
     function TransformPlayable() {
-        return Playable.apply(this, arguments);
+        var _this;
+        _this = Playable.apply(this, arguments) || this;
+        _this.started = false;
+        _this.contribution = createEmptyContribution();
+        return _this;
     }
     var _proto = TransformPlayable.prototype;
     _proto.start = function start() {
-        var boundItem = this.boundObject;
-        var scale = boundItem.transform.scale;
-        this.originalTransform = {
-            position: boundItem.transform.position.clone(),
-            rotation: boundItem.transform.getRotation().clone(),
-            // TODO 编辑器 scale 没有z轴控制
-            scale: new Vector3(scale.x, scale.y, scale.x)
-        };
         var positionOverLifetime = this.data.positionOverLifetime;
         var rotationOverLifetime = this.data.rotationOverLifetime;
         var sizeOverLifetime = this.data.sizeOverLifetime;
@@ -25689,7 +26012,7 @@ var tempPos = new Vector3();
         if (positionOverLifetime && Object.keys(positionOverLifetime).length !== 0) {
             this.positionOverLifetime = positionOverLifetime;
             if (positionOverLifetime.path) {
-                this.originalTransform.path = createValueGetter(positionOverLifetime.path);
+                this.pathGetter = createValueGetter(positionOverLifetime.path);
             }
             var linearVelEnable = positionOverLifetime.linearX || positionOverLifetime.linearY || positionOverLifetime.linearZ;
             if (linearVelEnable) {
@@ -25745,37 +26068,53 @@ var tempPos = new Vector3();
         this.velocity.multiply(this.startSpeed);
     };
     _proto.processFrame = function processFrame(context) {
-        if (!this.boundObject) {
-            var boundObject = context.output.getUserData();
-            if (_instanceof1(boundObject, exports.VFXItem)) {
-                this.boundObject = boundObject;
-                this.start();
-            }
-        }
-        if (this.boundObject && this.boundObject.composition) {
-            this.sampleAnimation();
+        this.ensureStarted();
+        var boundObject = context.output.getUserData();
+        if (!this.originalTransform && _instanceof1(boundObject, exports.VFXItem)) {
+            this.captureOriginalTransform(boundObject);
         }
     };
     /**
-   * 应用时间轴K帧数据到对象
-   */ _proto.sampleAnimation = function sampleAnimation() {
+   * 采样当前帧相对 base pose 的 transform contribution。
+   * 返回值为内部复用对象，调用方应在当前帧同步消费，不应缓存。
+   * @param basePosition - orbital position 计算 contribution 时使用的参考位置。
+   */ _proto.getContribution = function getContribution(basePosition) {
+        this.ensureStarted();
+        this.sampleAnimation(basePosition);
+        return this.contribution;
+    };
+    _proto.ensureStarted = function ensureStarted() {
+        if (!this.started) {
+            this.start();
+            this.started = true;
+        }
+    };
+    _proto.sampleAnimation = function sampleAnimation(basePosition) {
         var _this = this;
-        var boundItem = this.boundObject;
+        var out = this.contribution;
+        out.hasPosition = false;
+        out.hasRotation = false;
+        out.hasScale = false;
         var duration = this.getDuration();
+        if (duration <= 0) {
+            return;
+        }
         var life = this.time / duration;
         life = life < 0 ? 0 : life;
         if (this.sizeXOverLifetime) {
-            tempSize$1.x = this.sizeXOverLifetime.getValue(life);
+            out.hasScale = true;
+            out.scale.x = this.sizeXOverLifetime.getValue(life);
             if (this.sizeSeparateAxes) {
-                tempSize$1.y = this.sizeYOverLifetime.getValue(life);
-                tempSize$1.z = this.sizeZOverLifetime.getValue(life);
+                out.scale.y = this.sizeYOverLifetime.getValue(life);
+                out.scale.z = this.sizeZOverLifetime.getValue(life);
             } else {
-                tempSize$1.z = tempSize$1.y = tempSize$1.x;
+                out.scale.z = out.scale.y = out.scale.x;
             }
-            var startSize = this.originalTransform.scale;
-            boundItem.transform.setScale(tempSize$1.x * startSize.x, tempSize$1.y * startSize.y, tempSize$1.z * startSize.z);
+        } else {
+            out.hasScale = false;
         }
         if (this.rotationOverLifetime) {
+            out.hasRotation = true;
             var func = function(v) {
                 return _this.rotationOverLifetime.asRotation ? v.getValue(life) : v.getIntegrateValue(0, life, duration);
             };
@@ -25784,16 +26123,42 @@ var tempPos = new Vector3();
             tempRot$1.x = separateAxes ? func(this.rotationOverLifetime.x) : 0;
             tempRot$1.y = separateAxes ? func(this.rotationOverLifetime.y) : 0;
             tempRot$1.z = incZ;
-            var rot = tempRot$1.addEulers(this.originalTransform.rotation, tempRot$1);
-            boundItem.transform.setRotation(rot.x, rot.y, rot.z);
+            out.rotation.copyFrom(tempRot$1);
+        } else {
+            out.hasRotation = false;
         }
         if (this.positionOverLifetime) {
-            var pos = tempPos;
-            calculateTranslation(pos, this, this.gravity, this.time, duration, this.originalTransform.position, this.velocity);
-            if (this.originalTransform.path) {
-                pos.add(this.originalTransform.path.getValue(life));
+            var _this_orbitalVelOverLifetime;
+            out.hasPosition = true;
+            // Orbital position 依赖参考位置；普通 position 可直接从零向量采样位移贡献。
+            var orbitalEnabled = !!((_this_orbitalVelOverLifetime = this.orbitalVelOverLifetime) == null ? void 0 : _this_orbitalVelOverLifetime.enabled);
+            if (orbitalEnabled && basePosition) {
+                calculateTranslation(out.position, this, this.gravity, this.time, duration, basePosition, this.velocity);
+                if (this.pathGetter) {
+                    out.position.add(this.pathGetter.getValue(life));
+                }
+                out.position.subtract(basePosition);
+            } else {
+                tempPos.set(0, 0, 0);
+                calculateTranslation(out.position, this, this.gravity, this.time, duration, tempPos, this.velocity);
+                if (this.pathGetter) {
+                    out.position.add(this.pathGetter.getValue(life));
+                }
             }
-            boundItem.transform.setPosition(pos.x, pos.y, pos.z);
+        } else {
+            out.hasPosition = false;
+        }
+    };
+    _proto.captureOriginalTransform = function captureOriginalTransform(boundItem) {
+        var scale = boundItem.transform.scale;
+        this.originalTransform = {
+            position: boundItem.transform.position.clone(),
+            rotation: boundItem.transform.getRotation().clone(),
+            // TODO 编辑器 scale 没有z轴控制
+            scale: new Vector3(scale.x, scale.y, scale.x)
+        };
+        if (this.pathGetter) {
+            this.originalTransform.path = this.pathGetter;
         }
     };
     return TransformPlayable;
@@ -25818,6 +26183,104 @@ exports.TransformPlayableAsset = __decorate([
     effectsClass(DataType.TransformPlayableAsset)
 ], exports.TransformPlayableAsset);
 
+/**
+ * TransformTrack 的 mixer。
+ * 收集当前激活的 Transform clip contribution，并委托 TransformClipMixer 合成当前帧输出。
+ */ var TransformMixerPlayable = /*#__PURE__*/ function(TrackMixerPlayable) {
+    _inherits(TransformMixerPlayable, TrackMixerPlayable);
+    function TransformMixerPlayable() {
+        var _this;
+        _this = TrackMixerPlayable.apply(this, arguments) || this;
+        _this.clipMixer = new TransformClipMixer();
+        return _this;
+    }
+    var _proto = TransformMixerPlayable.prototype;
+    _proto.dispose = function dispose() {
+        this.clipMixer.dispose();
+        TrackMixerPlayable.prototype.dispose.call(this);
+    };
+    _proto.evaluate = function evaluate(context) {
+        var item = context.output.getUserData();
+        if (!_instanceof1(item, exports.VFXItem)) {
+            return;
+        }
+        this.clipMixer.captureBasePose(item);
+        this.clipMixer.resetFrame();
+        for(var i = 0; i < this.clipPlayables.length; i++){
+            var weight = this.clipWeights[i];
+            // RuntimeClip 会把已结束且 destroy 的 clip 权重置 0，这类 clip 不参与当前帧合成。
+            if (!weight || weight <= 0) {
+                continue;
+            }
+            var playable = this.clipPlayables[i];
+            if (!_instanceof1(playable, TransformPlayable)) {
+                continue;
+            }
+            this.clipMixer.addContribution(item, playable.getContribution(this.clipMixer.getBasePosition()), weight);
+        }
+        this.clipMixer.flush(item);
+    };
+    return TransformMixerPlayable;
+}(TrackMixerPlayable);
+
+var Vector4PropertyMixerPlayable = /*#__PURE__*/ function(PropertyMixerPlayable) {
+    _inherits(Vector4PropertyMixerPlayable, PropertyMixerPlayable);
+    function Vector4PropertyMixerPlayable() {
+        return PropertyMixerPlayable.apply(this, arguments);
+    }
+    var _proto = Vector4PropertyMixerPlayable.prototype;
+    _proto.resetPropertyValue = function resetPropertyValue() {
+        this.propertyValue.x = 0;
+        this.propertyValue.y = 0;
+        this.propertyValue.z = 0;
+        this.propertyValue.w = 0;
+    };
+    _proto.addWeightedValue = function addWeightedValue(curveValue, weight) {
+        var result = this.propertyValue;
+        result.x += curveValue.x * weight;
+        result.y += curveValue.y * weight;
+        result.z += curveValue.z * weight;
+        result.w += curveValue.w * weight;
+    };
+    return Vector4PropertyMixerPlayable;
+}(PropertyMixerPlayable);
+var Vector3PropertyMixerPlayable = /*#__PURE__*/ function(PropertyMixerPlayable) {
+    _inherits(Vector3PropertyMixerPlayable, PropertyMixerPlayable);
+    function Vector3PropertyMixerPlayable() {
+        return PropertyMixerPlayable.apply(this, arguments);
+    }
+    var _proto = Vector3PropertyMixerPlayable.prototype;
+    _proto.resetPropertyValue = function resetPropertyValue() {
+        this.propertyValue.x = 0;
+        this.propertyValue.y = 0;
+        this.propertyValue.z = 0;
+    };
+    _proto.addWeightedValue = function addWeightedValue(curveValue, weight) {
+        var result = this.propertyValue;
+        result.x += curveValue.x * weight;
+        result.y += curveValue.y * weight;
+        result.z += curveValue.z * weight;
+    };
+    return Vector3PropertyMixerPlayable;
+}(PropertyMixerPlayable);
+var Vector2PropertyMixerPlayable = /*#__PURE__*/ function(PropertyMixerPlayable) {
+    _inherits(Vector2PropertyMixerPlayable, PropertyMixerPlayable);
+    function Vector2PropertyMixerPlayable() {
+        return PropertyMixerPlayable.apply(this, arguments);
+    }
+    var _proto = Vector2PropertyMixerPlayable.prototype;
+    _proto.resetPropertyValue = function resetPropertyValue() {
+        this.propertyValue.x = 0;
+        this.propertyValue.y = 0;
+    };
+    _proto.addWeightedValue = function addWeightedValue(curveValue, weight) {
+        var result = this.propertyValue;
+        result.x += curveValue.x * weight;
+        result.y += curveValue.y * weight;
+    };
+    return Vector2PropertyMixerPlayable;
+}(PropertyMixerPlayable);
+
 /**
  * @since 2.0.0
  */ var TimelineClip = /*#__PURE__*/ function() {
@@ -26207,6 +26670,24 @@ exports.ColorPropertyTrack = __decorate([
     effectsClass(DataType.ColorPropertyTrack)
 ], exports.ColorPropertyTrack);
 
+exports.SpritePropertyTrack = /*#__PURE__*/ function(PropertyTrack) {
+    _inherits(SpritePropertyTrack, PropertyTrack);
+    function SpritePropertyTrack() {
+        return PropertyTrack.apply(this, arguments);
+    }
+    var _proto = SpritePropertyTrack.prototype;
+    _proto.createTrackMixer = function createTrackMixer() {
+        return new SpritePropertyMixerPlayable();
+    };
+    _proto.updateAnimatedObject = function updateAnimatedObject(boundObject) {
+        return boundObject.getComponent(exports.SpriteComponent);
+    };
+    return SpritePropertyTrack;
+}(PropertyTrack);
+exports.SpritePropertyTrack = __decorate([
+    effectsClass("SpritePropertyTrack")
+], exports.SpritePropertyTrack);
+
 var Cone = /*#__PURE__*/ function() {
     function Cone(props) {
         var _this = this;
@@ -29711,8 +30192,6 @@ exports.ParticleSystem = /*#__PURE__*/ function(Component) {
             occlusion: !!renderer.occlusion,
             transparentOcclusion: !!renderer.transparentOcclusion,
             maxCount: options.maxCount,
-            mask: this.maskManager.getRefValue(),
-            maskMode: this.maskManager.maskMode,
             forceTarget: forceTarget,
             diffuse: renderer.texture ? this.engine.findObject(renderer.texture) : undefined,
             sizeOverLifetime: sizeOverLifetimeGetter,
@@ -29807,9 +30286,7 @@ exports.ParticleSystem = /*#__PURE__*/ function(Component) {
                 shaderCachePrefix: shaderCachePrefix,
                 lifetime: this.trails.lifetime,
                 occlusion: !!trails.occlusion,
-                transparentOcclusion: !!trails.transparentOcclusion,
-                mask: this.maskManager.getRefValue(),
-                maskMode: this.maskManager.maskMode
+                transparentOcclusion: !!trails.transparentOcclusion
             };
             if (trails.colorOverLifetime && trails.colorOverLifetime[0] === ValueType.GRADIENT_COLOR) {
                 trailMeshProps.colorOverLifetime = trails.colorOverLifetime[1];
@@ -30038,6 +30515,44 @@ exports.FloatPropertyPlayableAsset = __decorate([
     effectsClass(DataType.FloatPropertyPlayableAsset)
 ], exports.FloatPropertyPlayableAsset);
 
+exports.SpritePropertyPlayableAsset = /*#__PURE__*/ function(PlayableAsset) {
+    _inherits(SpritePropertyPlayableAsset, PlayableAsset);
+    function SpritePropertyPlayableAsset() {
+        var _this;
+        _this = PlayableAsset.apply(this, arguments) || this;
+        _this.curveData = [
+            REFERENCE_CURVE,
+            []
+        ];
+        return _this;
+    }
+    var _proto = SpritePropertyPlayableAsset.prototype;
+    _proto.fromData = function fromData(data) {
+        PlayableAsset.prototype.fromData.call(this, data);
+        var items = data.curveData[1];
+        // 把 DataPath 解析为 Sprite 实例
+        var referenceCurveData = [];
+        for(var i = 0; i < items.length; i++){
+            var _items_i = items[i], t = _items_i[0], ref = _items_i[1];
+            referenceCurveData.push([
+                t,
+                this.engine.findObject(ref)
+            ]);
+        }
+        this.curveData[1] = referenceCurveData;
+    };
+    _proto.createPlayable = function createPlayable() {
+        var clip = new PropertyClipPlayable();
+        clip.curve = createValueGetter(this.curveData);
+        clip.value = clip.curve.getValue(0);
+        return clip;
+    };
+    return SpritePropertyPlayableAsset;
+}(PlayableAsset);
+exports.SpritePropertyPlayableAsset = __decorate([
+    effectsClass("SpritePropertyPlayableAsset")
+], exports.SpritePropertyPlayableAsset);
+
 exports.SubCompositionPlayableAsset = /*#__PURE__*/ function(PlayableAsset) {
     _inherits(SubCompositionPlayableAsset, PlayableAsset);
     function SubCompositionPlayableAsset() {
@@ -30285,15 +30800,6 @@ var TimelineInstance = /*#__PURE__*/ function() {
     return TimelineInstance;
 }();
 
-var singleSplits = [
-    [
-        0,
-        0,
-        1,
-        1,
-        0
-    ]
-];
 var seed$3 = 0;
 exports.SpriteColorPlayableAsset = /*#__PURE__*/ function(PlayableAsset) {
     _inherits(SpriteColorPlayableAsset, PlayableAsset);
@@ -30381,9 +30887,6 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         _this = MaskableGraphic.call(this, engine) || this;
         _this.time = 0;
         _this.duration = 1;
-        /**
-   * @internal
-  */ _this.splits = singleSplits;
         _this.name = "MSprite" + seed$3++;
         if (props) {
             _this.fromData(props);
@@ -30417,38 +30920,33 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         if (textureAnimation) {
             var _this_material_getVector4;
             var total = textureAnimation.total || textureAnimation.row * textureAnimation.col;
-            var texRectX = 0;
-            var texRectY = 0;
-            var texRectW = 1;
-            var texRectH = 1;
-            var flip;
-            if (this.splits) {
-                var sp = this.splits[0];
-                flip = sp[4];
-                texRectX = sp[0];
-                texRectY = sp[1];
-                if (flip) {
-                    texRectW = sp[3];
-                    texRectH = sp[2];
-                } else {
-                    texRectW = sp[2];
-                    texRectH = sp[3];
-                }
-            }
-            var dx, dy;
-            if (flip) {
-                dx = 1 / textureAnimation.row * texRectW;
-                dy = 1 / textureAnimation.col * texRectH;
-            } else {
-                dx = 1 / textureAnimation.col * texRectW;
-                dy = 1 / textureAnimation.row * texRectH;
-            }
+            // 帧动画不与多 split（splits.length>1）同时存在，故此处仅读 sprite 单 rect。
+            // sprite 缺省时按整图 [0,0,1,1] 不旋转处理。
+            var sprite = this.sprite;
+            var _sprite_rect;
+            var rect = (_sprite_rect = sprite == null ? void 0 : sprite.rect) != null ? _sprite_rect : [
+                0,
+                0,
+                1,
+                1
+            ];
+            var _sprite_rotation;
+            var flip = (_sprite_rotation = sprite == null ? void 0 : sprite.rotation) != null ? _sprite_rotation : exports.SpriteRotation.None;
+            var isRotate90 = flip === exports.SpriteRotation.Rotate90;
+            // rect 在纹理上的归一化矩形 [x, y, w, h]；旋转 90° 时宽高互换。
+            var rectX = rect[0];
+            var rectY = rect[1];
+            var rectW = isRotate90 ? rect[3] : rect[2];
+            var rectH = isRotate90 ? rect[2] : rect[3];
+            // 每帧在 rect 内的偏移步长；旋转 90° 时 row/col 对调。
+            var dx = isRotate90 ? 1 / textureAnimation.row * rectW : 1 / textureAnimation.col * rectW;
+            var dy = isRotate90 ? 1 / textureAnimation.col * rectH : 1 / textureAnimation.row * rectH;
             var texOffset;
             if (textureAnimation.animate) {
                 var frameIndex = Math.round(life * (total - 1));
                 var yIndex = Math.floor(frameIndex / textureAnimation.col);
                 var xIndex = frameIndex - yIndex * textureAnimation.col;
-                texOffset = flip ? [
+                texOffset = isRotate90 ? [
                     dx * yIndex,
                     dy * (textureAnimation.col - xIndex)
                 ] : [
@@ -30462,8 +30960,8 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
                 ];
             }
             (_this_material_getVector4 = this.material.getVector4("_TexOffset")) == null ? void 0 : _this_material_getVector4.setFromArray([
-                texRectX + texOffset[0],
-                texRectH + texRectY - texOffset[1],
+                rectX + texOffset[0],
+                rectH + rectY - texOffset[1],
                 dx,
                 dy
             ]);
@@ -30484,19 +30982,31 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         }
     };
     _proto.updateGeometry = function updateGeometry(geometry) {
-        var split = this.textureSheetAnimation ? [
+        var sprite = this.sprite;
+        var _sprite_rotation;
+        // sprite 缺省时按整图 [0,0,1,1] 不旋转处理，等价旧默认 splits=[[0,0,1,1,0]]。
+        var flip = (_sprite_rotation = sprite == null ? void 0 : sprite.rotation) != null ? _sprite_rotation : exports.SpriteRotation.None;
+        var _sprite_rect;
+        var rect = (_sprite_rect = sprite == null ? void 0 : sprite.rect) != null ? _sprite_rect : [
             0,
             0,
             1,
+            1
+        ];
+        var _ref = this.textureSheetAnimation ? [
+            0,
+            0,
             1,
-            this.splits[0][4]
-        ] : this.splits[0];
-        var uvTransform = split;
-        var x = uvTransform[0];
-        var y = uvTransform[1];
-        var isRotate90 = Boolean(uvTransform[4]);
-        var width = isRotate90 ? uvTransform[3] : uvTransform[2];
-        var height = isRotate90 ? uvTransform[2] : uvTransform[3];
+            1
+        ] : [
+            rect[0],
+            rect[1],
+            rect[2],
+            rect[3]
+        ], x = _ref[0], y = _ref[1], w = _ref[2], h = _ref[3];
+        var isRotate90 = flip === exports.SpriteRotation.Rotate90;
+        var width = isRotate90 ? h : w;
+        var height = isRotate90 ? w : h;
         var angle = isRotate90 ? -Math.PI / 2 : 0;
         var aUV = geometry.getAttributeData("aUV");
         var aPos = geometry.getAttributeData("aPos");
@@ -30533,11 +31043,51 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
             });
         }
     };
+    _proto.fromData = function fromData(data) {
+        MaskableGraphic.prototype.fromData.call(this, data); // MaskableGraphic: 设 renderer.texture（whiteTexture 或 data.renderer.texture）、_MainTex、_Color
+        // 单 split / 新数据流：引用 Sprite 资产，渲染读 this.sprite
+        if (data.sprite) {
+            var sprite = this.engine.findObject(data.sprite);
+            if (sprite) {
+                this.applySpriteToRenderer(sprite);
+            }
+        }
+        this.textureSheetAnimation = data.textureSheetAnimation;
+        var geometry = data.geometry ? this.engine.findObject(data.geometry) : this.defaultGeometry;
+        var splits = data.splits;
+        if (splits && splits.length > 1) {
+            // 原有打包纹理拆分逻辑（多 split，2x2 纹理打包），保留向后兼容；
+            // 不依赖组件 splits 字段，直接用 data.splits。
+            this.updateGeometryFromMultiSplit(splits);
+        } else {
+            this.updateGeometry(geometry);
+        }
+        this.interaction = data.interaction;
+        var startColor = data.options.startColor || [
+            1,
+            1,
+            1,
+            1
+        ];
+        this.material.setColor("_Color", new Color().setFromArray(startColor));
+        var _data_duration;
+        //@ts-expect-error
+        this.duration = (_data_duration = data.duration) != null ? _data_duration : this.item.duration;
+    };
+    /**
+   * 应用 Sprite 资产到渲染器：同步纹理并重绑 _MainTex。不重建几何体。
+   * fromData（后续自行 updateGeometry）与 sprite setter（随后 updateGeometry）共用。
+   * 直接写 _sprite，避免经 setter 触发 updateGeometry。
+   */ _proto.applySpriteToRenderer = function applySpriteToRenderer(sprite) {
+        this._sprite = sprite;
+        this.renderer.texture = sprite.texture;
+        this.material.setTexture("_MainTex", sprite.texture);
+    };
     /**
    * @deprecated
-   * 原有打包纹理拆分逻辑，待移除
-   */ _proto.updateGeometryFromMultiSplit = function updateGeometryFromMultiSplit() {
-        var _this = this, splits = _this.splits, textureSheetAnimation = _this.textureSheetAnimation;
+   * 原有打包纹理拆分逻辑，仅在老数据 splits.length>1（2x2 纹理打包）时使用，保留向后兼容。
+   * 不依赖组件状态，splits 由参数传入（同时存在帧动画与多 split 的数据不存在）。
+   */ _proto.updateGeometryFromMultiSplit = function updateGeometryFromMultiSplit(splits) {
         var sx = 1, sy = 1;
         var geometry = this.defaultGeometry;
         var originData = [
@@ -30558,14 +31108,7 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         for(var x = 0; x < col; x++){
             for(var y = 0; y < row; y++){
                 var base = (y * 2 + x) * 4;
-                // @ts-expect-error
-                var split = textureSheetAnimation ? [
-                    0,
-                    0,
-                    1,
-                    1,
-                    splits[0][4]
-                ] : splits[y * 2 + x];
+                var split = splits[y * 2 + x];
                 var texOffset = split[4] ? [
                     0,
                     0,
@@ -30611,33 +31154,21 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         geometry.setAttributeData("aUV", new Float32Array(aUV));
         geometry.setDrawCount(index.length);
     };
-    _proto.fromData = function fromData(data) {
-        MaskableGraphic.prototype.fromData.call(this, data);
-        var _data_splits;
-        var splits = (_data_splits = data.splits) != null ? _data_splits : singleSplits;
-        var textureSheetAnimation = data.textureSheetAnimation;
-        this.splits = splits;
-        this.textureSheetAnimation = textureSheetAnimation;
-        var geometry = data.geometry ? this.engine.findObject(data.geometry) : this.defaultGeometry;
-        if (splits.length === 1) {
-            this.updateGeometry(geometry);
-        } else {
-            // TODO: 原有打包纹理拆分逻辑，待移除
-            //-------------------------------------------------------------------------
-            this.updateGeometryFromMultiSplit();
+    _create_class(SpriteComponent, [
+        {
+            key: "sprite",
+            get: /**
+   * 当前 Sprite 资产。设置时同步纹理、重绑 _MainTex 并重建几何体 UV。
+   * @since 2.10.0
+   */ function get() {
+                return this._sprite;
+            },
+            set: function set(sprite) {
+                this.applySpriteToRenderer(sprite);
+                this.updateGeometry(this.geometry);
+            }
         }
-        this.interaction = data.interaction;
-        var startColor = data.options.startColor || [
-            1,
-            1,
-            1,
-            1
-        ];
-        this.material.setColor("_Color", new Color().setFromArray(startColor));
-        var _data_duration;
-        //@ts-expect-error
-        this.duration = (_data_duration = data.duration) != null ? _data_duration : this.item.duration;
-    };
+    ]);
     return SpriteComponent;
 }(MaskableGraphic);
 exports.SpriteComponent = __decorate([
@@ -30652,6 +31183,54 @@ var ParticleLoader = /*#__PURE__*/ function(Plugin) {
     return ParticleLoader;
 }(_wrap_native_super(Plugin));
 
+/**
+ * 文本换行机会判定：UAX #14 风格的"换行机会"模型。
+ *
+ * - CJK 表意字 / 假名 / 韩文音节：任意两个字之间都是合法断点（字符级）
+ * - 空格 / 制表符 / NBSP：可断，且断行时被吞掉（不留在行尾 / 行首）
+ * - 西文字母 / 数字：词内不可断；整体超宽时由调用方退化到字符级断（overflow-wrap）
+ *
+ * 不含 kinsoku 禁则（句号 / 逗号不进行首等留作后续）。
+ */ /** 换行机会类型（断点字符之后）：决定断点字符归属及断行时是否吞掉 */ /**
+ * 是否为可换行断点字符（空格 / 制表符 / NBSP）。
+ * 断在此字符之前，且断行时该字符被吞掉（不进旧行也不进新行）。
+ * @param ch - 当前字符
+ */ function isBreakChar(ch) {
+    return ch === " " || ch === "	" || ch === "\xa0";
+}
+/**
+ * 是否为 CJK 类字符（中文表意字 / 假名 / 韩文音节）。可在其与相邻字符之间换行。
+ * 用码点判定以支持 CJK 扩展 B 等代理对字符（不能用 /u 正则，browserslist 为 iOS 9）。
+ * @param ch - 当前字符（须为完整码点，调用方应使用 Array.from 遍历）
+ */ function isCJKLike(ch) {
+    var _ch_codePointAt;
+    var cp = (_ch_codePointAt = ch.codePointAt(0)) != null ? _ch_codePointAt : 0;
+    return cp >= 0x3400 && cp <= 0x4DBF || // CJK 统一表意扩展 A
+    cp >= 0x4E00 && cp <= 0x9FFF || // CJK 统一表意
+    cp >= 0xF900 && cp <= 0xFAFF || // CJK 兼容表意
+    cp >= 0x20000 && cp <= 0x2FA1F || // CJK 扩展 B~F + 兼容增补（代理对）
+    cp >= 0x3040 && cp <= 0x309F || // 平假名
+    cp >= 0x30A0 && cp <= 0x30FF || // 片假名
+    cp >= 0x31F0 && cp <= 0x31FF || // 片假名语音扩展
+    cp >= 0xAC00 && cp <= 0xD7AF // 韩文音节
+    ;
+}
+/**
+ * 计算 prev（已推入的字符）之后是否为换行机会。只看 prev，不看后续字符。
+ * @param prev - 前一字符（已推入旧行）
+ * @returns 'swallow'=prev 是空格类，断行时吞掉 prev；'keep'=prev 是 CJK，prev 留本行末、下行从其后起；false=不可断
+ */ function breakOpportunityAfter(prev) {
+    // prev 是空格类 → 断在 prev 处，断行时吞掉 prev（不进旧行也不进新行）
+    if (isBreakChar(prev)) {
+        return "swallow";
+    }
+    // prev 是 CJK → prev 留本行末，下行从 prev 之后起（字符级断点，不吞）
+    if (isCJKLike(prev)) {
+        return "keep";
+    }
+    return false;
+}
+
 var TextLayout = /*#__PURE__*/ function() {
     function TextLayout(options) {
         this.width = 0;
@@ -31100,9 +31679,6 @@ var DEFAULT_FONTS = [
     "courier"
 ];
 /** 检测字符串是否包含需要 RTL 和连写排版的字符（阿拉伯语等） */ var HAS_RTL_OR_JOINING = /[\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF]/;
-/** 可换行断点：空格、制表符等 */ var IS_BREAK_CHAR = function(ch) {
-    return ch === " " || ch === "	" || ch === "\xa0";
-};
 var seed$2 = 0;
 exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
     _inherits(TextComponent, MaskableGraphic);
@@ -31202,13 +31778,15 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
         var lineCount = 1;
         var x = 0;
         var charCountInLine = 0;
+        // 使用码点遍历，正确处理 emoji 与 CJK 扩展 B 等代理对字符
+        var chars = Array.from(text);
         if (context) {
             context.font = this.getFontDesc(this.textStyle.fontSize);
         }
         if (overflow === TextOverflow.display) {
-            for(var i = 0; i < text.length; i++){
+            for(var _iterator = _create_for_of_iterator_helper_loose(chars), _step; !(_step = _iterator()).done;){
+                var str = _step.value;
                 var _context_measureText;
-                var str = text[i];
                 var _context_measureText_width;
                 var textMetrics = (_context_measureText_width = context == null ? void 0 : (_context_measureText = context.measureText(str)) == null ? void 0 : _context_measureText.width) != null ? _context_measureText_width : 0;
                 if (str === "\n") {
@@ -31227,12 +31805,12 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
             return lineCount;
         }
         if (this.textLayout.keepWordIntact) {
-            // 单词完整换行：优先在空格处断行，避免从单词中间断开
+            // 单词完整换行：优先在换行机会处断行（空格吞断 / CJK 字间可断），避免从西文词中间断开
             var lastBreakX = 0;
             var countAtBreak = 0;
-            for(var i1 = 0; i1 < text.length; i1++){
+            for(var _iterator1 = _create_for_of_iterator_helper_loose(chars), _step1; !(_step1 = _iterator1()).done;){
+                var str1 = _step1.value;
                 var _context_measureText1;
-                var str1 = text[i1];
                 var _context_measureText_width1;
                 var textMetrics1 = (_context_measureText_width1 = context == null ? void 0 : (_context_measureText1 = context.measureText(str1)) == null ? void 0 : _context_measureText1.width) != null ? _context_measureText_width1 : 0;
                 if (str1 === "\n") {
@@ -31265,22 +31843,23 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                 }
                 x += textMetrics1;
                 charCountInLine++;
-                if (IS_BREAK_CHAR(str1)) {
+                // 记换行机会：str 之后可断（空格 swallow / CJK keep）。lastBreakX 含 str 宽度（str 留本行末）
+                if (breakOpportunityAfter(str1) !== false) {
                     lastBreakX = x;
                     countAtBreak = charCountInLine;
                 }
             }
         } else {
             // 逐字符换行：允许在任意字符处断开
-            for(var i2 = 0; i2 < text.length; i2++){
+            for(var i = 0; i < chars.length; i++){
                 var _context_measureText2;
-                var str2 = text[i2];
+                var str2 = chars[i];
                 var _context_measureText_width2;
                 var textMetrics2 = (_context_measureText_width2 = context == null ? void 0 : (_context_measureText2 = context.measureText(str2)) == null ? void 0 : _context_measureText2.width) != null ? _context_measureText_width2 : 0;
                 if (charCountInLine > 0) {
                     x += letterSpace;
                 }
-                if (x + textMetrics2 > width && i2 > 0 || str2 === "\n") {
+                if (x + textMetrics2 > width && i > 0 || str2 === "\n") {
                     lineCount++;
                     this.maxLineWidth = Math.max(this.maxLineWidth, x);
                     x = 0;
@@ -31373,8 +31952,11 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
             var charsArray = [];
             var charOffsetX = [];
             if (layout.keepWordIntact) {
-                // 单词完整换行：优先在空格处断行，避免从单词中间断开
+                // 单词完整换行：优先在换行机会处断行（空格吞断 / CJK 字间可断），避免从西文词中间断开。
+                // lastBreakIdx 指向断点字符在 charsArray 中的索引；breakSwallow=true 时该字符被吞（空格），
+                // false 时该字符留本行末（CJK），下行均从 lastBreakIdx+1 起。
                 var lastBreakIdx = -1;
+                var breakSwallow = false;
                 for(var i = 0; i < char.length; i++){
                     var str = char[i];
                     var textMetrics = context.measureText(str);
@@ -31390,15 +31972,18 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                         charsArray = [];
                         charOffsetX = [];
                         lastBreakIdx = -1;
+                        breakSwallow = false;
                         continue;
                     }
                     var spacing = charsArray.length > 0 ? layout.letterSpace : 0;
                     var willWidth = x + spacing + textMetrics.width;
                     if (willWidth > baseWidth && charsArray.length > 0) {
                         if (lastBreakIdx > 0) {
-                            // 在空格处换行
-                            var lineChars = charsArray.slice(0, lastBreakIdx);
-                            var lineOffsets = charOffsetX.slice(0, lastBreakIdx);
+                            // 在换行机会处断行：swallow 取 [0,lastBreakIdx)（吞掉断点字符），
+                            // keep 取 [0,lastBreakIdx]（断点字符留本行末），下行均从 lastBreakIdx+1 起。
+                            var endIdx = breakSwallow ? lastBreakIdx : lastBreakIdx + 1;
+                            var lineChars = charsArray.slice(0, endIdx);
+                            var lineOffsets = charOffsetX.slice(0, endIdx);
                             var lineWidth = lineChars.length > 0 ? lineOffsets[lineOffsets.length - 1] + context.measureText(lineChars[lineChars.length - 1]).width : 0;
                             charsInfo.push({
                                 y: y,
@@ -31419,6 +32004,7 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                                 x += context.measureText(charsArray[j]).width;
                             }
                             lastBreakIdx = -1;
+                            breakSwallow = false;
                         } else {
                             charsInfo.push({
                                 y: y,
@@ -31431,6 +32017,7 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                             charsArray = [];
                             charOffsetX = [];
                             lastBreakIdx = -1;
+                            breakSwallow = false;
                         }
                     }
                     if (charsArray.length > 0) {
@@ -31439,8 +32026,12 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                     charOffsetX.push(x);
                     charsArray.push(str);
                     x += textMetrics.width;
-                    if (IS_BREAK_CHAR(str)) {
+                    // 记换行机会：str 之后可断。lastBreakIdx 指向 str（charsArray 末尾），
+                    // swallow=吞 str（空格），keep=str 留本行末（CJK）。
+                    var opp = breakOpportunityAfter(str);
+                    if (opp !== false) {
                         lastBreakIdx = charsArray.length - 1;
+                        breakSwallow = opp === "swallow";
                     }
                 }
             } else {
@@ -33390,7 +33981,6 @@ exports.ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
         var material = Material.create(this.engine, materialProps);
         var renderer = rendererOptions;
         var side = renderer.side, occlusion = renderer.occlusion, blendMode = renderer.blending, texture = renderer.texture;
-        var maskMode = this.maskManager.maskMode;
         material.blending = true;
         material.depthTest = true;
         material.depthMask = occlusion;
@@ -33404,7 +33994,6 @@ exports.ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
         texParams.x = renderer.occlusion ? +renderer.transparentOcclusion : 1;
         texParams.y = preMultiAlpha;
         texParams.z = renderer.renderMode;
-        texParams.w = maskMode;
         material.setVector4("_TexParams", texParams);
         if (texParams.x === 0 || this.maskManager.alphaMaskEnabled) {
             material.enableMacro("ALPHA_CLIP");
@@ -33427,9 +34016,9 @@ exports.ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
             blending: (_renderer_blending = renderer.blending) != null ? _renderer_blending : BlendingMode.ALPHA,
             texture: renderer.texture ? this.engine.findObject(renderer.texture) : this.engine.whiteTexture,
             occlusion: !!renderer.occlusion,
-            transparentOcclusion: !!renderer.transparentOcclusion || this.maskManager.maskMode === exports.MaskMode.MASK,
+            transparentOcclusion: !!renderer.transparentOcclusion || this.maskManager.isMask,
             side: (_renderer_side = renderer.side) != null ? _renderer_side : SideMode.DOUBLE,
-            mask: this.maskManager.getRefValue()
+            mask: 1
         };
         var _data_strokeCap;
         this.strokeCap = (_data_strokeCap = data.strokeCap) != null ? _data_strokeCap : LineCap.Butt;
@@ -34411,7 +35000,7 @@ function getStandardInteractContent(ui) {
     return ret;
 }
 
-var currentMaskComponent;
+var currentMaskComponentId;
 var componentMap = new Map();
 var itemMap = new Map();
 /**
@@ -35073,12 +35662,21 @@ function version36Migration(json) {
     for(var _iterator3 = _create_for_of_iterator_helper_loose(json.compositions), _step3; !(_step3 = _iterator3()).done;){
         var composition = _step3.value;
         composition.children = [];
+        currentMaskComponentId = undefined;
+        //@ts-expect-error
+        var legacyCompositionItems = composition.items;
+        if (Array.isArray(legacyCompositionItems)) {
+            processMaskReferenceItems(legacyCompositionItems, itemMap, componentMap);
+        }
         for(var _iterator4 = _create_for_of_iterator_helper_loose(composition.components), _step4; !(_step4 = _iterator4()).done;){
             var componentDataPath = _step4.value;
             var componentData = componentMap.get(componentDataPath.id);
             if (componentData.dataType === DataType.CompositionComponent) {
                 var compositionComponent = componentData;
-                for(var _iterator5 = _create_for_of_iterator_helper_loose(compositionComponent.items), _step5; !(_step5 = _iterator5()).done;){
+                var _compositionComponent_items;
+                var compositionItems = (_compositionComponent_items = compositionComponent.items) != null ? _compositionComponent_items : [];
+                processMaskReferenceItems(compositionItems, itemMap, componentMap);
+                for(var _iterator5 = _create_for_of_iterator_helper_loose(compositionItems), _step5; !(_step5 = _iterator5()).done;){
                     var itemPath = _step5.value;
                     var item1 = itemMap.get(itemPath.id);
                     if (item1.parentId === undefined) {
@@ -35108,6 +35706,72 @@ function version36Migration(json) {
     json.version = JSONSceneVersion["3_7"];
     return json;
 }
+/**
+ * 3.8 数据适配：SpriteComponent 的 renderer.texture + splits 迁移为独立 Sprite 资产。
+ *
+ * - 遍历所有未引用 sprite 的 SpriteComponentData，按 splits[0]（无则整图 [0,0,1,1]）生成
+ *   Sprite 资产对象放入 miscs，并把组件的 sprite 指向它。
+ * - 删除组件的 splits 与 renderer.texture（纹理归属 sprite，renderer 仅保留渲染状态）。
+ * - 卫语句 `if (sc.sprite) continue` 处理混合数据（部分组件已用 sprite）。
+ * - 多 split（splits.length>1，2x2 纹理打包）保留原 splits 不迁移，仍走 updateGeometryFromMultiSplit 旧路径。
+ *
+ * 由 getStandardJSON 以 `minorVersion < 8` 守卫调用，数据生命周期内只跑一次。
+ * version 字段设为字符串 '3.8'（JSONSceneVersion 枚举无此值，运行时不依赖枚举）。
+ */ function version37Migration(json) {
+    var _json;
+    var _miscs;
+    (_miscs = (_json = json).miscs) != null ? _miscs : _json.miscs = [];
+    for(var _iterator = _create_for_of_iterator_helper_loose(json.components), _step; !(_step = _iterator()).done;){
+        var component = _step.value;
+        var _sc_renderer;
+        if (component.dataType !== DataType.SpriteComponent) {
+            continue;
+        }
+        // 本地扩展 sprite 字段（spec 包不可改）。ComponentData 是 SpriteComponentData 的超集，
+        // 故直接当 SpriteComponentData 用；sprite 需要写到对象上，用宽松类型承载。
+        var sc = component;
+        if (sc.sprite) {
+            continue; // 已迁移/新数据
+        }
+        var splits = sc.splits;
+        if (splits && splits.length > 1) {
+            continue;
+        }
+        var first = splits == null ? void 0 : splits[0];
+        var rect = first ? [
+            first[0],
+            first[1],
+            first[2],
+            first[3]
+        ] : [
+            0,
+            0,
+            1,
+            1
+        ];
+        var _first_;
+        // rotation: 0=None 不旋转, 1=Rotate90（值与 Sprite.SpriteRotation 枚举一致，序列化兼容）
+        var rotation = (_first_ = first == null ? void 0 : first[4]) != null ? _first_ : 0;
+        var spriteData = {
+            id: generateGUID(),
+            dataType: "Sprite",
+            // 可能为 undefined（纯色元素）→ Sprite.fromData 兜底 whiteTexture
+            texture: (_sc_renderer = sc.renderer) == null ? void 0 : _sc_renderer.texture,
+            rect: rect,
+            rotation: rotation
+        };
+        json.miscs.push(spriteData);
+        sc.sprite = {
+            id: spriteData.id
+        };
+        delete sc.splits;
+        if (sc.renderer) {
+            delete sc.renderer.texture; // 纹理归属 sprite，renderer 仅保留渲染状态
+        }
+    }
+    json.version = "3.8";
+    return json;
+}
 /**
  * 确保文本组件有版本标识字段
  */ function ensureTextVerticalAlign(options) {
@@ -35218,6 +35882,21 @@ function processContent(composition) {
         }
     }
 }
+function processMaskReferenceItems(items, itemMap, componentMap) {
+    for(var _iterator = _create_for_of_iterator_helper_loose(items), _step; !(_step = _iterator()).done;){
+        var item = _step.value;
+        var itemProps = itemMap.get(item.id);
+        if (!itemProps) {
+            continue;
+        }
+        if (itemProps.type === ItemType.sprite || itemProps.type === ItemType.particle || itemProps.type === ItemType.spine || itemProps.type === ItemType.text || itemProps.type === ItemType.richtext || itemProps.type === ItemType.video || itemProps.type === ItemType.shape || itemProps.type === ItemType.mesh) {
+            var component = componentMap.get(itemProps.components[0].id);
+            if (component) {
+                processMaskReference(component);
+            }
+        }
+    }
+}
 function processMask(renderContent) {
     var renderer = renderContent.renderer;
     var maskMode = renderer == null ? void 0 : renderer.maskMode;
@@ -35228,16 +35907,34 @@ function processMask(renderContent) {
         renderContent.mask = {
             isMask: true
         };
-        currentMaskComponent = renderContent.id;
+        currentMaskComponentId = renderContent.id;
     } else if (maskMode === ObscuredMode.OBSCURED || maskMode === ObscuredMode.REVERSE_OBSCURED) {
         renderContent.mask = {
             inverted: maskMode === ObscuredMode.REVERSE_OBSCURED ? true : false,
             reference: {
-                "id": currentMaskComponent
+                "id": currentMaskComponentId
             }
         };
     }
 }
+function processMaskReference(renderContent) {
+    var mask = renderContent.mask;
+    if (mask && !mask.references && mask.reference) {
+        var _mask_isMask, _mask_alphaMaskEnabled, _mask_inverted;
+        // 处理旧版 mask 格式（mask.reference 和 mask.inverted 字段）
+        // 将旧版单蒙版格式转换为 references 数组
+        renderContent.mask = {
+            isMask: (_mask_isMask = mask.isMask) != null ? _mask_isMask : false,
+            alphaMaskEnabled: (_mask_alphaMaskEnabled = mask.alphaMaskEnabled) != null ? _mask_alphaMaskEnabled : false,
+            references: [
+                {
+                    mask: mask.reference,
+                    inverted: (_mask_inverted = mask.inverted) != null ? _mask_inverted : false
+                }
+            ]
+        };
+    }
+}
 function convertParam(content) {
     if (!content) {
         return;
@@ -35912,7 +36609,7 @@ function getStandardSpriteContent(sprite, transform) {
     return ret;
 }
 
-var version$2 = "2.10.0-alpha.0";
+var version$2 = "2.10.0-alpha.1";
 var v0 = /^(\d+)\.(\d+)\.(\d+)(-(\w+)\.\d+)?$/;
 var standardVersion = /^(\d+)\.(\d+)$/;
 var reverseParticle = false;
@@ -35930,7 +36627,7 @@ function getStandardJSON(json) {
     if (v0.test(json.version)) {
         var _exec;
         reverseParticle = ((_exec = /^(\d+)/.exec(json.version)) == null ? void 0 : _exec[0]) === "0";
-        return version36Migration(version35Migration(version34Migration(version33Migration(version32Migration(version31Migration(version30Migration(version21Migration(getStandardJSONFromV0(json)))))))));
+        return version37Migration(version36Migration(version35Migration(version34Migration(version33Migration(version32Migration(version31Migration(version30Migration(version21Migration(getStandardJSONFromV0(json))))))))));
     }
     reverseParticle = false;
     var vs = standardVersion.exec(json.version) || [];
@@ -35967,6 +36664,9 @@ function getStandardJSON(json) {
             if (minorVersion < 7) {
                 json = version36Migration(json);
             }
+            if (minorVersion < 8) {
+                json = version37Migration(json);
+            }
         }
         return json;
     }
@@ -36425,11 +37125,15 @@ var seed$1 = 1;
     var _proto = AssetManager.prototype;
     _proto.updateOptions = function updateOptions(options) {
         if (options === void 0) options = {};
-        this.options = options;
-        if (!options.pluginData) {
-            options.pluginData = {};
+        var _options_useCompressedTexture, _options_useHevcVideo;
+        this.options = _extends({}, options, {
+            useCompressedTexture: (_options_useCompressedTexture = options.useCompressedTexture) != null ? _options_useCompressedTexture : true,
+            useHevcVideo: (_options_useHevcVideo = options.useHevcVideo) != null ? _options_useHevcVideo : true
+        });
+        if (!this.options.pluginData) {
+            this.options.pluginData = {};
         }
-        var _options_timeout = options.timeout, timeout = _options_timeout === void 0 ? 10 : _options_timeout;
+        var _this_options = this.options, _this_options_timeout = _this_options.timeout, timeout = _this_options_timeout === void 0 ? 10 : _this_options_timeout;
         this.timeout = timeout;
     };
     /**
@@ -36687,12 +37391,19 @@ var seed$1 = 1;
         if (canUseKTX2 === void 0) canUseKTX2 = false;
         var _this = this;
         return _async_to_generator(function() {
-            var _this_options, useCompressedTexture, variables, disableWebP, disableAVIF, baseUrl, jobs, loadedImages;
+            var _this_options, useCompressedTexture, variables, disableWebP, disableAVIF, isKTX2PluginRegistered, canUseCompressedTexture, baseUrl, jobs, loadedImages;
             return __generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         _this_options = _this.options, useCompressedTexture = _this_options.useCompressedTexture, variables = _this_options.variables, disableWebP = _this_options.disableWebP, disableAVIF = _this_options.disableAVIF;
+                        isKTX2PluginRegistered = !!pluginLoaderMap.ktx2;
+                        canUseCompressedTexture = useCompressedTexture && canUseKTX2 && isKTX2PluginRegistered;
                         baseUrl = _this.baseUrl;
+                        if (useCompressedTexture && canUseKTX2 && !isKTX2PluginRegistered && images.some(function(img) {
+                            return "ktx2" in img && img.ktx2;
+                        })) {
+                            logger.warn("The plugin 'ktx2' is not found, unable to use compressed textures." + getPluginUsageInfo("ktx2"));
+                        }
                         jobs = images.map(/*#__PURE__*/ _async_to_generator(function(img, idx) {
                             var png, webp, avif, ktx2, imageURL, webpURL, avifURL, ktx2URL, id, template, background, url, isVideo, loadFn, resultImage, e, _ref, url1, image, _tmp;
                             return __generator(this, function(_state) {
@@ -36707,7 +37418,7 @@ var seed$1 = 1;
                                         // eslint-disable-next-line compat/compat
                                         avifURL = !disableAVIF && avif ? new URL(avif, baseUrl).href : undefined;
                                         // eslint-disable-next-line compat/compat
-                                        ktx2URL = ktx2 && useCompressedTexture && canUseKTX2 ? new URL(ktx2, baseUrl).href : undefined;
+                                        ktx2URL = ktx2 && canUseCompressedTexture ? new URL(ktx2, baseUrl).href : undefined;
                                         id = img.id;
                                         if (!("template" in img)) return [
                                             3,
@@ -36859,7 +37570,7 @@ var seed$1 = 1;
                     case 0:
                         return [
                             4,
-                            PluginSystem.onAssetsLoadStart(scene, _this.options)
+                            PluginSystem.notifyAssetsLoadStart(scene, _this.options)
                         ];
                     case 1:
                         _state.sent();
@@ -37941,7 +38652,7 @@ var PreRenderTickData = /*#__PURE__*/ function(TickData) {
             _this.onItemMessage = onItemMessage;
         }
         _this.createRenderFrame();
-        PluginSystem.initializeComposition(_assert_this_initialized(_this), scene);
+        PluginSystem.notifyCompositionCreated(_assert_this_initialized(_this), scene);
         return _this;
     }
     var _proto = Composition.prototype;
@@ -38305,18 +39016,13 @@ var PreRenderTickData = /*#__PURE__*/ function(TickData) {
     // }
     };
     _proto.lost = function lost(e) {
-        this.videoState = this.textures.map(function(tex) {
-            if ("video" in tex.source) {
-                tex.source.video.pause();
-                return tex.source.video.currentTime;
-            }
-        });
-        this.textures.map(function(tex) {
-            return tex.dispose();
-        });
-        this.dispose();
+    // GPU 资源由引擎统一 rebuild，合成仅保留纯 JS 运行时状态，此处无需处理。
     };
     /**
+   * 上下文恢复后的空操作。
+   * GPU 资源已由引擎统一重建，视频纹理会在下次渲染时自然更新，不自动重新播放。
+   */ _proto.restore = function restore() {};
+    /**
    * 合成对象销毁
    */ _proto.dispose = function dispose() {
         var _this = this;
@@ -38341,7 +39047,7 @@ var PreRenderTickData = /*#__PURE__*/ function(TickData) {
         this.root.dispose();
         // FIXME: 注意这里增加了renderFrame销毁
         this.renderFrame.dispose();
-        PluginSystem.destroyComposition(this);
+        PluginSystem.notifyCompositionDestroy(this);
         this.update = function() {
             {
                 logger.error("Update disposed composition: " + _this.name + ".");
@@ -40255,12 +40961,20 @@ var DEFAULT_FPS = 60;
    * 计时器
    * 手动渲染 `manualRender=true` 时不创建计时器
    */ _this.ticker = null;
+        /**
+   * 是否不处理上下文丢失恢复（构造期配置，默认 true）
+   */ _this.doNotHandleContextLost = true;
+        /**
+   * WebGL 上下文是否处于丢失状态
+   */ _this.contextWasLost = false;
         _this._disposed = false;
         _this.textures = [];
         _this.materials = [];
         _this.geometries = [];
         _this.meshes = [];
         _this.renderPasses = [];
+        _this.framebuffers = [];
+        _this.renderbuffers = [];
         _this.clearAction = {
             stencilAction: exports.TextureLoadAction.clear,
             clearStencil: 0,
@@ -40277,6 +40991,8 @@ var DEFAULT_FPS = 60;
         _this.canvas = canvas;
         var _options_env;
         _this.env = (_options_env = options == null ? void 0 : options.env) != null ? _options_env : "";
+        var _options_doNotHandleContextLost;
+        _this.doNotHandleContextLost = (_options_doNotHandleContextLost = options == null ? void 0 : options.doNotHandleContextLost) != null ? _options_doNotHandleContextLost : true;
         var _options_name;
         _this.name = (_options_name = options == null ? void 0 : options.name) != null ? _options_name : _this.name;
         var _options_pixelRatio;
@@ -40302,6 +41018,7 @@ var DEFAULT_FPS = 60;
             // @ts-expect-error
             currentFrame: {}
         };
+        PluginSystem.notifyEngineCreated(_assert_this_initialized(_this));
         return _this;
     }
     var _proto = Engine.prototype;
@@ -40401,6 +41118,10 @@ var DEFAULT_FPS = 60;
         (_this_ticker = this.ticker) == null ? void 0 : _this_ticker.add(renderFunction);
     };
     _proto.mainLoop = function mainLoop(dt) {
+        // 上下文丢失/恢复期间跳过渲染，避免打到失效的 GL 上下文。
+        if (this.contextWasLost) {
+            return;
+        }
         var renderErrors = this.renderErrors;
         if (renderErrors.size > 0) {
             var // 有渲染错误时暂停播放
@@ -40613,6 +41334,30 @@ var DEFAULT_FPS = 60;
         }
         removeItem(this.renderPasses, pass);
     };
+    _proto.addFramebuffer = function addFramebuffer(framebuffer) {
+        if (this.disposed) {
+            return;
+        }
+        addItem(this.framebuffers, framebuffer);
+    };
+    _proto.removeFramebuffer = function removeFramebuffer(framebuffer) {
+        if (this.disposed) {
+            return;
+        }
+        removeItem(this.framebuffers, framebuffer);
+    };
+    _proto.addRenderbuffer = function addRenderbuffer(renderbuffer) {
+        if (this.disposed) {
+            return;
+        }
+        addItem(this.renderbuffers, renderbuffer);
+    };
+    _proto.removeRenderbuffer = function removeRenderbuffer(renderbuffer) {
+        if (this.disposed) {
+            return;
+        }
+        removeItem(this.renderbuffers, renderbuffer);
+    };
     _proto.addComposition = function addComposition(composition) {
         if (this.disposed) {
             return;
@@ -40722,6 +41467,7 @@ var DEFAULT_FPS = 60;
             return;
         }
         this._disposed = true;
+        PluginSystem.notifyEngineDestroy(this);
         var info = [];
         if (this.renderPasses.length > 0) {
             info.push("Pass " + this.renderPasses.length);
@@ -40897,8 +41643,8 @@ var PassTextureCache = /*#__PURE__*/ function() {
                     case 1:
                         loadedScene = _state.sent();
                         engine.clearResources();
-                        // 触发插件系统 pluginSystem 的回调 onAssetsLoadFinish
-                        PluginSystem.onAssetsLoadFinish(loadedScene, assetManager.options, engine);
+                        // 通过 PluginSystem.notifyAssetsLoadFinish 通知所有插件的 onAssetsLoadFinish 回调
+                        PluginSystem.notifyAssetsLoadFinish(loadedScene, assetManager.options, engine);
                         engine.assetService.prepareAssets(loadedScene, loadedScene.assets);
                         engine.assetService.updateTextVariables(loadedScene, options.variables);
                         composition = _this.createComposition(loadedScene, engine, options);
@@ -40959,8 +41705,8 @@ var PrecompositionManager = /*#__PURE__*/ function() {
         var options = precomposition.options;
         var engine = composition.engine;
         engine.clearResources();
-        // 触发插件系统 pluginSystem 的回调 onAssetsLoadFinish
-        PluginSystem.onAssetsLoadFinish(scene, options, engine);
+        // 通过 PluginSystem.notifyAssetsLoadFinish 通知所有插件的 onAssetsLoadFinish 回调
+        PluginSystem.notifyAssetsLoadFinish(scene, options, engine);
         engine.assetService.prepareAssets(scene, scene.assets);
         engine.assetService.updateTextVariables(scene, options.variables);
         composition.createTexturesFromData(scene.textureOptions);
@@ -41000,7 +41746,7 @@ registerPlugin("text", TextLoader);
 registerPlugin("sprite", SpriteLoader);
 registerPlugin("particle", ParticleLoader);
 registerPlugin("interact", InteractLoader);
-var version$1 = "2.10.0-alpha.0";
+var version$1 = "2.10.0-alpha.1";
 logger.info("Core version: " + version$1 + ".");
 
 var _obj;
@@ -42284,8 +43030,8 @@ var ThreeRenderer = /*#__PURE__*/ function(Renderer) {
                                             _$scene = _state.sent();
                                             engine = _this.engine;
                                             engine.clearResources();
-                                            // 触发插件系统 pluginSystem 的回调 onAssetsLoadFinish
-                                            PluginSystem.onAssetsLoadFinish(_$scene, assetManager.options, engine);
+                                            // 通过 PluginSystem.notifyAssetsLoadFinish 通知所有插件的 onAssetsLoadFinish 回调
+                                            PluginSystem.notifyAssetsLoadFinish(_$scene, assetManager.options, engine);
                                             _this.assetService.prepareAssets(_$scene, assetManager.getAssets());
                                             _this.assetService.updateTextVariables(_$scene, assetManager.options.variables);
                                             composition = _this.createComposition(_$scene, opts);
@@ -42580,7 +43326,7 @@ applyMixins(exports.ThreeTextComponent, [
  */ Mesh.create = function(engine, props) {
     return new ThreeMesh(engine, props);
 };
-var version = "2.10.0-alpha.0";
+var version = "2.10.0-alpha.1";
 logger.info("THREEJS plugin version: " + version + ".");
 
 exports.ATLAS_SIZE = ATLAS_SIZE;
@@ -42712,6 +43458,7 @@ exports.Precomposition = Precomposition;
 exports.PrecompositionManager = PrecompositionManager;
 exports.PropertyClipPlayable = PropertyClipPlayable;
 exports.PropertyTrack = PropertyTrack;
+exports.REFERENCE_CURVE = REFERENCE_CURVE;
 exports.RENDER_PREFER_LOOKUP_TEXTURE = RENDER_PREFER_LOOKUP_TEXTURE;
 exports.RUNTIME_ENV = RUNTIME_ENV;
 exports.RandomSetValue = RandomSetValue;
@@ -42720,6 +43467,7 @@ exports.RandomVectorValue = RandomVectorValue;
 exports.RaycastResult = RaycastResult;
 exports.RectTransform = RectTransform;
 exports.Rectangle = Rectangle$1;
+exports.ReferenceCurve = ReferenceCurve;
 exports.RenderFrame = RenderFrame;
 exports.RenderPass = RenderPass;
 exports.RenderPassPriorityNormal = RenderPassPriorityNormal;
@@ -42743,6 +43491,7 @@ exports.ShaderVariant = ShaderVariant;
 exports.SpriteColorMixerPlayable = SpriteColorMixerPlayable;
 exports.SpriteComponentTimeTrack = SpriteComponentTimeTrack;
 exports.SpriteLoader = SpriteLoader;
+exports.SpritePropertyMixerPlayable = SpritePropertyMixerPlayable;
 exports.StateMachineNode = StateMachineNode;
 exports.StateNode = StateNode;
 exports.StaticValue = StaticValue;
@@ -42787,6 +43536,7 @@ exports.applyMixins = applyMixins;
 exports.assertExist = assertExist;
 exports.asserts = asserts;
 exports.base64ToFile = base64ToFile;
+exports.breakOpportunityAfter = breakOpportunityAfter;
 exports.buildBezierData = buildBezierData;
 exports.buildEasingCurve = buildEasingCurve;
 exports.buildLine = buildLine;
@@ -42852,6 +43602,8 @@ exports.interpolateColor = interpolateColor;
 exports.isAlipayMiniApp = isAlipayMiniApp;
 exports.isAndroid = isAndroid;
 exports.isArray = isArray;
+exports.isBreakChar = isBreakChar;
+exports.isCJKLike = isCJKLike;
 exports.isCanvas = isCanvas;
 exports.isFunction = isFunction;
 exports.isIOS = isIOS;