@galacean/effects-threejs 2.9.0-alpha.1 → 2.9.0-alpha.2

package/dist/index.mjs

@@ -3,7 +3,7 @@
  * Description: Galacean Effects runtime threejs plugin for the web
  * Author: Ant Group CO., Ltd.
  * Contributors: 燃然,飂兮,十弦,云垣,茂安,意绮
- * Version: v2.9.0-alpha.1
+ * Version: v2.9.0-alpha.2
  */
 
 import * as THREE from 'three';
@@ -4095,7 +4095,7 @@ function getDirectStore(target) {
     function EffectsObject(engine) {
         this.engine = engine;
         this.guid = generateGUID();
-        this.defination = {};
+        this.definition = {};
         this.engine.addInstance(this);
     }
     var _proto = EffectsObject.prototype;
@@ -6999,6 +6999,11 @@ function _create_class(Constructor, protoProps, staticProps) {
     // OVERRIDE
     };
     /**
+   * 当父级或间接父级发生改变时调用
+   */ _proto.onParentChanged = function onParentChanged() {
+    // OVERRIDE
+    };
+    /**
    * @internal
    */ _proto.enable = function enable() {
         if (this.item.composition) {
@@ -9229,7 +9234,6 @@ var MaterialRenderType;
         for(var _iterator4 = _create_for_of_iterator_helper_loose(frameClipMasks), _step4; !(_step4 = _iterator4()).done;){
             var frameClipMask1 = _step4.value;
             this.removeMaskReference(frameClipMask1);
-            maskedComponent.frameClipMasks = [];
         }
     };
     /**
@@ -10667,7 +10671,6 @@ BoundingBox.tempVector2 = new Vector3();
         _this.materials = [];
         /**
    * @hidden
-   * @internal
    * Internal utility.
    * Not part of the public API — do not rely on this in your code.
    */ _this.frameClipMasks = [];
@@ -10691,6 +10694,9 @@ BoundingBox.tempVector2 = new Vector3();
         var _this_item_composition;
         (_this_item_composition = this.item.composition) == null ? void 0 : _this_item_composition.renderFrame.removeMeshFromDefaultRenderPass(this);
     };
+    _proto.onParentChanged = function onParentChanged() {
+        this.frameClipMasks = [];
+    };
     /**
    * 获取包围盒信息
    */ _proto.getBoundingBoxInfo = function getBoundingBoxInfo() {
@@ -13209,6 +13215,7 @@ var VFXItem = /*#__PURE__*/ function(EffectsObject) {
         if (!this.composition && vfxItem.composition) {
             this.composition = vfxItem.composition;
         }
+        this.onParentChanged();
         if (!this.isDuringPlay && vfxItem.isDuringPlay) {
             this.awake();
             this.beginPlay();
@@ -13341,6 +13348,122 @@ var VFXItem = /*#__PURE__*/ function(EffectsObject) {
     // OVERRIDE
     };
     /**
+   * 对当前元素及其子节点进行射线命中测试
+   *
+   * @param ray - 射线
+   * @param x - 归一化屏幕坐标 x
+   * @param y - 归一化屏幕坐标 y
+   * @param regions - 命中结果收集数组
+   * @param hitPositions - 共享的命中位置数组，所有 region 共享同一引用
+   * @param force - 是否强制测试无交互信息的元素
+   * @param options - 额外选项（maxCount、stop、skip）
+   * @returns 是否有任何命中
+   */ _proto.hitTest = function hitTest(ray, x, y, regions, hitPositions, force, options) {
+        var _this_composition;
+        if (!this.isActive) {
+            return false;
+        }
+        var hitTestSuccess = false;
+        var maxCount = options == null ? void 0 : options.maxCount;
+        var hitParams = this.getHitTestParams(force);
+        // 1. 测试自身
+        if (hitParams) {
+            var clipMasks = hitParams.clipMasks;
+            var clipPassed = true;
+            if (clipMasks.length > 0 && !hitTestMask(ray, clipMasks)) {
+                clipPassed = false;
+            }
+            if (clipPassed) {
+                var success = false;
+                var intersectPoint = new Vector3();
+                if (hitParams.type === HitTestType.triangle) {
+                    var triangles = hitParams.triangles, backfaceCulling = hitParams.backfaceCulling;
+                    for(var j = 0; j < triangles.length; j++){
+                        if (ray.intersectTriangle(triangles[j], intersectPoint, backfaceCulling)) {
+                            success = true;
+                            hitPositions.push(intersectPoint);
+                            break;
+                        }
+                    }
+                } else if (hitParams.type === HitTestType.box) {
+                    var center = hitParams.center, size = hitParams.size;
+                    var boxMin = center.clone().addScaledVector(size, 0.5);
+                    var boxMax = center.clone().addScaledVector(size, -0.5);
+                    if (ray.intersectBox({
+                        min: boxMin,
+                        max: boxMax
+                    }, intersectPoint)) {
+                        success = true;
+                        hitPositions.push(intersectPoint);
+                    }
+                } else if (hitParams.type === HitTestType.sphere) {
+                    var center1 = hitParams.center, radius = hitParams.radius;
+                    if (ray.intersectSphere({
+                        center: center1,
+                        radius: radius
+                    }, intersectPoint)) {
+                        success = true;
+                        hitPositions.push(intersectPoint);
+                    }
+                } else if (hitParams.type === HitTestType.custom) {
+                    var tempPosition = hitParams.collect(ray, new Vector2(x, y));
+                    if (tempPosition && tempPosition.length > 0) {
+                        tempPosition.forEach(function(pos) {
+                            hitPositions.push(pos);
+                        });
+                        success = true;
+                    }
+                }
+                if (success) {
+                    var _options_stop;
+                    var region = {
+                        id: this.getInstanceId(),
+                        name: this.name,
+                        position: hitPositions[hitPositions.length - 1],
+                        parentId: this.parentId,
+                        hitPositions: hitPositions,
+                        behavior: hitParams.behavior,
+                        item: this,
+                        composition: this.composition
+                    };
+                    regions.push(region);
+                    hitTestSuccess = true;
+                    if (options == null ? void 0 : (_options_stop = options.stop) == null ? void 0 : _options_stop.call(options, region)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        // 2. 递归测试子节点
+        for(var _iterator = _create_for_of_iterator_helper_loose(this.children), _step; !(_step = _iterator()).done;){
+            var child = _step.value;
+            var _options_skip;
+            if (maxCount !== undefined && regions.length >= maxCount) {
+                break;
+            }
+            if (options == null ? void 0 : (_options_skip = options.skip) == null ? void 0 : _options_skip.call(options, child)) {
+                continue;
+            }
+            if (child.hitTest(ray, x, y, regions, hitPositions, force, options)) {
+                hitTestSuccess = true;
+            }
+        }
+        // 3. composition 元素：子元素命中时，将自身也加入结果（根元素除外）
+        if (VFXItem.isComposition(this) && hitTestSuccess && this !== ((_this_composition = this.composition) == null ? void 0 : _this_composition.rootItem)) {
+            regions.push({
+                id: this.getInstanceId(),
+                name: this.name,
+                position: hitPositions[hitPositions.length - 1],
+                parentId: this.parentId,
+                hitPositions: hitPositions,
+                behavior: InteractBehavior.NONE,
+                item: this,
+                composition: this.composition
+            });
+        }
+        return hitTestSuccess;
+    };
+    /**
    * 获取元素当前世界坐标
    */ _proto.getCurrentPosition = function getCurrentPosition() {
         var pos = new Vector3();
@@ -13376,7 +13499,7 @@ var VFXItem = /*#__PURE__*/ function(EffectsObject) {
         // 重新设置当前元素和组件的 ID 以及子元素和子元素组件的 ID，避免实例化新的对象时产生碰撞
         this.refreshGUIDRecursive();
         var newItem = this.engine.findObject({
-            id: this.defination.id
+            id: this.definition.id
         });
         newItem.refreshGUIDRecursive();
         this.refreshGUIDRecursive(previousObjectIDMap);
@@ -13452,6 +13575,16 @@ var VFXItem = /*#__PURE__*/ function(EffectsObject) {
             }
         }
     };
+    _proto.onParentChanged = function onParentChanged() {
+        for(var _iterator = _create_for_of_iterator_helper_loose(this.components), _step; !(_step = _iterator()).done;){
+            var component = _step.value;
+            component.onParentChanged();
+        }
+        for(var _iterator1 = _create_for_of_iterator_helper_loose(this.children), _step1; !(_step1 = _iterator1()).done;){
+            var child = _step1.value;
+            child.onParentChanged();
+        }
+    };
     /**
    * @internal
    */ _proto.setRendererComponentOrder = function setRendererComponentOrder(renderOrder) {
@@ -13471,7 +13604,7 @@ var VFXItem = /*#__PURE__*/ function(EffectsObject) {
         this.parentId = parentId;
         this.components.length = 0;
         if (VFXItem.isComposition(this)) {
-            var refId = this.defination.content.options.refId;
+            var refId = this.definition.content.options.refId;
             var compositionData = this.engine.findEffectsObjectData(refId);
             if (!compositionData) {
                 throw new Error("Referenced precomposition with Id: " + refId + " does not exist.");
@@ -13518,24 +13651,24 @@ var VFXItem = /*#__PURE__*/ function(EffectsObject) {
     };
     _proto.toData = function toData() {
         var _this_parent;
-        this.defination.id = this.guid;
-        this.defination.transform = this.transform.toData();
-        this.defination.dataType = DataType.VFXItemData;
+        this.definition.id = this.guid;
+        this.definition.transform = this.transform.toData();
+        this.definition.dataType = DataType.VFXItemData;
         if (((_this_parent = this.parent) == null ? void 0 : _this_parent.name) !== "rootItem") {
             var _this_parent1;
-            this.defination.parentId = (_this_parent1 = this.parent) == null ? void 0 : _this_parent1.guid;
+            this.definition.parentId = (_this_parent1 = this.parent) == null ? void 0 : _this_parent1.guid;
         }
         // TODO 统一 sprite 等其他组件的序列化逻辑
-        if (!this.defination.components) {
-            this.defination.components = [];
+        if (!this.definition.components) {
+            this.definition.components = [];
             for(var _iterator = _create_for_of_iterator_helper_loose(this.components), _step; !(_step = _iterator()).done;){
                 var component = _step.value;
                 if (_instanceof1(component, EffectComponent)) {
-                    this.defination.components.push(component);
+                    this.definition.components.push(component);
                 }
             }
         }
-        this.defination.content = {};
+        this.definition.content = {};
     };
     /**
    * 销毁元素
@@ -13792,6 +13925,47 @@ var Item;
     }
     Item.isNull = isNull;
 })(Item || (Item = {}));
+/**
+ * 遮罩命中测试：检查射线是否通过所有遮罩区域
+ * 根据每个遮罩的 transform（size、scale、position、rotation、anchor）构建世界空间矩形，
+ * 然后检测射线是否与该矩形相交。所有遮罩都必须通过才算测试通过。
+ * @param ray - 射线
+ * @param clipMasks - 遮罩列表
+ * @returns 射线是否通过所有遮罩测试
+ */ function hitTestMask(ray, clipMasks) {
+    for(var _iterator = _create_for_of_iterator_helper_loose(clipMasks), _step; !(_step = _iterator()).done;){
+        var mask = _step.value;
+        var item = mask.item;
+        if (!item.isActive || !item.transform.getValid()) {
+            continue;
+        }
+        var transform = item.transform;
+        var worldMatrix = transform.getWorldMatrix();
+        var sx = transform.size.x;
+        var sy = transform.size.y;
+        // 将遮罩矩形的四个顶点从本地空间变换到世界空间
+        // 本地空间顶点为单位矩形 (-0.5, -0.5) 到 (0.5, 0.5)，按 size 缩放
+        var p0 = new Vector3(-0.5 * sx, 0.5 * sy, 0).applyMatrix(worldMatrix);
+        var p1 = new Vector3(-0.5 * sx, -0.5 * sy, 0).applyMatrix(worldMatrix);
+        var p2 = new Vector3(0.5 * sx, 0.5 * sy, 0).applyMatrix(worldMatrix);
+        var p3 = new Vector3(0.5 * sx, -0.5 * sy, 0).applyMatrix(worldMatrix);
+        // 矩形由两个三角形组成，检测射线与任一三角形的相交
+        var triangle1 = {
+            p0: p0,
+            p1: p1,
+            p2: p2
+        };
+        var triangle2 = {
+            p0: p2,
+            p1: p1,
+            p2: p3
+        };
+        if (!ray.intersectTriangle(triangle1) && !ray.intersectTriangle(triangle2)) {
+            return false;
+        }
+    }
+    return true;
+}
 
 var toHalf = function() {
     var floatView = new Float32Array(1);
@@ -17399,7 +17573,7 @@ function triangulate(contours) {
    */ _proto.getY = function getY() {
         return this.points[this.points.length - 1];
     };
-    _proto.build = function build(points) {
+    _proto.build = function build(points, screenScale) {
         for(var i = 0; i < this.points.length; i++){
             points[i] = this.points[i];
         }
@@ -17501,11 +17675,10 @@ var RECURSION_LIMIT = 8;
 var FLT_EPSILON = 1.19209290e-7;
 var PATH_DISTANCE_EPSILON = 1.0;
 var defaultBezierSmoothness = 0.5;
-function buildAdaptiveBezier(points, sX, sY, cp1x, cp1y, cp2x, cp2y, eX, eY, smoothness) {
-    // TODO expose as a parameter
-    var scale = 5;
+function buildAdaptiveBezier(points, sX, sY, cp1x, cp1y, cp2x, cp2y, eX, eY, smoothness, scale) {
+    var s = scale != null ? scale : 1;
     var smoothing = Math.min(0.99, Math.max(0, smoothness != null ? smoothness : defaultBezierSmoothness));
-    var distanceTolerance = (PATH_DISTANCE_EPSILON - smoothing) / scale;
+    var distanceTolerance = (PATH_DISTANCE_EPSILON - smoothing) / s;
     distanceTolerance *= distanceTolerance;
     begin(sX, sY, cp1x, cp1y, cp2x, cp2y, eX, eY, points, distanceTolerance);
     return points;
@@ -17695,7 +17868,7 @@ function recursive(x1, y1, x2, y2, x3, y3, x4, y4, points, distanceTolerance, le
     _proto.getY = function getY() {
         return this.y;
     };
-    _proto.build = function build(points) {
+    _proto.build = function build(points, screenScale) {
         var x = this.x;
         var y = this.y;
         var rx = this.halfWidth;
@@ -17705,9 +17878,10 @@ function recursive(x1, y1, x2, y2, x3, y3, x4, y4, points, distanceTolerance, le
         if (!(rx >= 0 && ry >= 0 && dx >= 0 && dy >= 0)) {
             return points;
         }
-        // Choose a number of segments such that the maximum absolute deviation from the circle is approximately 0.029
-        var sampleDensity = 5;
-        var n = Math.ceil(sampleDensity * Math.sqrt(rx + ry));
+        // n 个等分段逼近四分之一椭圆弧，最大弦高误差 ε = R·π²/(8n²)
+        // 屏幕误差 = ε × ppu = ppu·R·π²/(8n²)，令 n = √(ppu·(rx+ry))，则误差 ≈ π²/8 ≈ 1.2px
+        var ppu = screenScale != null ? screenScale : 1;
+        var n = Math.ceil(Math.sqrt(ppu * (rx + ry)));
         var m = n * 8 + (0) + (0);
         if (m === 0) {
             return points;
@@ -17842,7 +18016,7 @@ var PolyStar = /*#__PURE__*/ function(ShapePrimitive) {
     _proto.copyTo = function copyTo(destination) {
         destination.copyFrom(this);
     };
-    _proto.build = function build(points) {
+    _proto.build = function build(points, screenScale) {
         switch(this.starType){
             case 0:
                 {
@@ -17855,13 +18029,13 @@ var PolyStar = /*#__PURE__*/ function(ShapePrimitive) {
                     break;
                 }
         }
-        var smoothness = 1;
+        var ppu = screenScale != null ? screenScale : 1;
         for(var i = 0; i < this.v.length - 2; i += 2){
-            buildAdaptiveBezier(points, this.v[i], this.v[i + 1], this.out[i], this.out[i + 1], this.in[i + 2], this.in[i + 3], this.v[i + 2], this.v[i + 3], smoothness);
+            buildAdaptiveBezier(points, this.v[i], this.v[i + 1], this.out[i], this.out[i + 1], this.in[i + 2], this.in[i + 3], this.v[i + 2], this.v[i + 3], undefined, ppu);
         }
         // draw last curve
         var lastIndex = this.v.length - 1;
-        buildAdaptiveBezier(points, this.v[lastIndex - 1], this.v[lastIndex], this.out[lastIndex - 1], this.out[lastIndex], this.in[0], this.in[1], this.v[0], this.v[1], smoothness);
+        buildAdaptiveBezier(points, this.v[lastIndex - 1], this.v[lastIndex], this.out[lastIndex - 1], this.out[lastIndex], this.in[0], this.in[1], this.v[0], this.v[1], undefined, ppu);
     };
     _proto.triangulate = function triangulate1(points, vertices, verticesOffset, indices, indicesOffset) {
         var triangles = triangulate([
@@ -18006,7 +18180,7 @@ var PolyStar = /*#__PURE__*/ function(ShapePrimitive) {
         rectangle.copyFrom(this);
         return rectangle;
     };
-    _proto.build = function build(points) {
+    _proto.build = function build(points, screenScale) {
         var ry;
         var halfWidth = this.width / 2;
         var halfHeight = this.height / 2;
@@ -18018,10 +18192,10 @@ var PolyStar = /*#__PURE__*/ function(ShapePrimitive) {
         if (!(rx >= 0 && ry >= 0 && dx >= 0 && dy >= 0)) {
             return;
         }
-        // 控制边缘的平滑程度
-        var densityScale = 5;
-        // Choose a number of segments such that the maximum absolute deviation from the circle is approximately 0.029
-        var n = densityScale * Math.ceil(2.3 * Math.sqrt(rx + ry));
+        // n 个等分段逼近四分之一圆角弧，最大弦高误差 ε = R·π²/(8n²)
+        // 屏幕误差 = ε × ppu，令 n = √(ppu·(rx+ry))，则误差 ≈ π²/8 ≈ 1.2px
+        var ppu = screenScale != null ? screenScale : 1;
+        var n = Math.ceil(Math.sqrt(ppu * (rx + ry)));
         var m = n * 8 + (dx ? 4 : 0) + (dy ? 4 : 0);
         if (m === 0) {
             return;
@@ -18230,7 +18404,7 @@ var PolyStar = /*#__PURE__*/ function(ShapePrimitive) {
     _proto.getY = function getY() {
         return this.y;
     };
-    _proto.build = function build(points) {
+    _proto.build = function build(points, screenScale) {
         points[0] = this.x;
         points[1] = this.y;
         points[2] = this.x2;
@@ -18447,7 +18621,7 @@ var PolyStar = /*#__PURE__*/ function(ShapePrimitive) {
         circle.copyFrom(this);
         return circle;
     };
-    _proto.build = function build(points) {
+    _proto.build = function build(points, screenScale) {
         var x = this.x;
         var y = this.y;
         var dx = 0;
@@ -18457,8 +18631,10 @@ var PolyStar = /*#__PURE__*/ function(ShapePrimitive) {
         if (rx <= 0) {
             return;
         }
-        // Choose a number of segments such that the maximum absolute deviation from the circle is approximately 0.029
-        var n = Math.ceil(2.3 * Math.sqrt(rx + ry));
+        // n 个等分段逼近四分之一圆弧，最大弦高误差 ε = R·π²/(8n²)
+        // 屏幕误差 = ε × ppu = ppu·R·π²/(8n²)，令 n = √(ppu·(rx+ry))，则误差 ≈ π²/8 ≈ 1.2px
+        var ppu = screenScale != null ? screenScale : 1;
+        var n = Math.ceil(Math.sqrt(ppu * (rx + ry)));
         var m = n * 8 + (0) + (0);
         if (m === 0) {
             return;
@@ -18568,7 +18744,7 @@ var ShapePath = /*#__PURE__*/ function() {
             switch(action){
                 case "bezierCurveTo":
                     {
-                        this.bezierCurveTo(data[0], data[1], data[2], data[3], data[4], data[5], data[6]);
+                        this.bezierCurveTo(data[0], data[1], data[2], data[3], data[4], data[5], data[6], data[7]);
                         break;
                     }
                 case "moveTo":
@@ -18627,10 +18803,10 @@ var ShapePath = /*#__PURE__*/ function() {
    * @param y - The y-coordinate of the end point.
    * @param smoothness - Optional parameter to adjust the smoothness of the curve.
    * @returns The instance of the current object for chaining.
-   */ _proto.bezierCurveTo = function bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y, smoothness) {
+   */ _proto.bezierCurveTo = function bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y, smoothness, scale) {
         this.ensurePoly();
         var currentPoly = this.currentPoly;
-        buildAdaptiveBezier(currentPoly.points, currentPoly.lastX, currentPoly.lastY, cp1x, cp1y, cp2x, cp2y, x, y, smoothness);
+        buildAdaptiveBezier(currentPoly.points, currentPoly.lastX, currentPoly.lastY, cp1x, cp1y, cp2x, cp2y, x, y, smoothness, scale);
         return this;
     };
     _proto.moveTo = function moveTo(x, y) {
@@ -18795,7 +18971,7 @@ var GraphicsPath = /*#__PURE__*/ function() {
    * @param y - The y-coordinate of the end point.
    * @param smoothness - Optional parameter to adjust the smoothness of the curve.
    * @returns The instance of the current object for chaining.
-   */ _proto.bezierCurveTo = function bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y, smoothness) {
+   */ _proto.bezierCurveTo = function bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y, smoothness, scale) {
         this.instructions.push({
             action: "bezierCurveTo",
             data: [
@@ -18805,7 +18981,8 @@ var GraphicsPath = /*#__PURE__*/ function() {
                 cp2y,
                 x,
                 y,
-                smoothness
+                smoothness,
+                scale
             ]
         });
         this.dirty = true;
@@ -19106,28 +19283,6 @@ var CompositionComponent = /*#__PURE__*/ function(Component) {
             return item.dispose();
         });
     };
-    _proto.hitTest = function hitTest(ray, x, y, regions, force, options) {
-        var _this_item_composition;
-        var isHitTestSuccess = hitTestRecursive(this.item, ray, x, y, regions, force, options);
-        // 子元素碰撞测试成功加入当前预合成元素，判断是否是合成根元素，根元素不加入
-        if (isHitTestSuccess && this.item !== ((_this_item_composition = this.item.composition) == null ? void 0 : _this_item_composition.rootItem)) {
-            var item = this.item;
-            var lastRegion = regions[regions.length - 1];
-            var hitPositions = lastRegion.hitPositions;
-            var region = {
-                id: item.getInstanceId(),
-                name: item.name,
-                position: hitPositions[hitPositions.length - 1],
-                parentId: item.parentId,
-                hitPositions: hitPositions,
-                behavior: InteractBehavior.NONE,
-                item: item,
-                composition: item.composition
-            };
-            regions.push(region);
-        }
-        return isHitTestSuccess;
-    };
     /**
    * 设置当前合成子元素的渲染顺序
    *
@@ -19237,98 +19392,6 @@ __decorate([
 CompositionComponent = __decorate([
     effectsClass("CompositionComponent")
 ], CompositionComponent);
-function hitTestRecursive(item, ray, x, y, regions, force, options) {
-    var _loop = function() {
-        var hitTestItem = _step.value;
-        if (hitTestItem.isActive && hitTestItem.transform.getValid() && !skip(hitTestItem)) {
-            var hitParams = hitTestItem.getHitTestParams(force);
-            if (hitParams) {
-                var success = false;
-                var intersectPoint = new Vector3();
-                if (hitParams.type === HitTestType.triangle) {
-                    var triangles = hitParams.triangles, backfaceCulling = hitParams.backfaceCulling;
-                    for(var j = 0; j < triangles.length; j++){
-                        var triangle = triangles[j];
-                        if (ray.intersectTriangle(triangle, intersectPoint, backfaceCulling)) {
-                            success = true;
-                            hitPositions.push(intersectPoint);
-                            break;
-                        }
-                    }
-                } else if (hitParams.type === HitTestType.box) {
-                    var center = hitParams.center, size = hitParams.size;
-                    var boxMin = center.clone().addScaledVector(size, 0.5);
-                    var boxMax = center.clone().addScaledVector(size, -0.5);
-                    if (ray.intersectBox({
-                        min: boxMin,
-                        max: boxMax
-                    }, intersectPoint)) {
-                        success = true;
-                        hitPositions.push(intersectPoint);
-                    }
-                } else if (hitParams.type === HitTestType.sphere) {
-                    var center1 = hitParams.center, radius = hitParams.radius;
-                    if (ray.intersectSphere({
-                        center: center1,
-                        radius: radius
-                    }, intersectPoint)) {
-                        success = true;
-                        hitPositions.push(intersectPoint);
-                    }
-                } else if (hitParams.type === HitTestType.custom) {
-                    var tempPosition = hitParams.collect(ray, new Vector2(x, y));
-                    if (tempPosition && tempPosition.length > 0) {
-                        tempPosition.forEach(function(pos) {
-                            hitPositions.push(pos);
-                        });
-                        success = true;
-                    }
-                }
-                if (success) {
-                    var region = {
-                        id: hitTestItem.getInstanceId(),
-                        name: hitTestItem.name,
-                        position: hitPositions[hitPositions.length - 1],
-                        parentId: hitTestItem.parentId,
-                        hitPositions: hitPositions,
-                        behavior: hitParams.behavior,
-                        item: hitTestItem,
-                        composition: hitTestItem.composition
-                    };
-                    regions.push(region);
-                    hitTestSuccess = true;
-                    if (stop(region)) {
-                        return {
-                            v: true
-                        };
-                    }
-                }
-            }
-        }
-        if (VFXItem.isComposition(hitTestItem)) {
-            if (hitTestItem.getComponent(CompositionComponent).hitTest(ray, x, y, regions, force, options)) {
-                hitTestSuccess = true;
-            }
-        } else {
-            if (hitTestRecursive(hitTestItem, ray, x, y, regions, force, options)) {
-                hitTestSuccess = true;
-            }
-        }
-    };
-    var hitPositions = [];
-    var stop = (options == null ? void 0 : options.stop) || noop;
-    var skip = (options == null ? void 0 : options.skip) || noop;
-    var maxCount = options == null ? void 0 : options.maxCount;
-    if (maxCount !== undefined && regions.length >= maxCount) {
-        return false;
-    }
-    var hitTestSuccess = false;
-    for(var _iterator = _create_for_of_iterator_helper_loose(item.children), _step; !(_step = _iterator()).done;){
-        var _ret = _loop();
-        if (_type_of(_ret) === "object") return _ret.v;
-    }
-    return hitTestSuccess;
-}
 
 /**
  * Mesh 组件
@@ -19345,7 +19408,8 @@ function hitTestRecursive(item, ray, x, y, regions, force, options) {
             if (area) {
                 return {
                     type: area.type,
-                    triangles: area.area
+                    triangles: area.area,
+                    clipMasks: _this.frameClipMasks
                 };
             }
         };
@@ -21484,7 +21548,8 @@ var Graphics = /*#__PURE__*/ function() {
                         behavior: ((_this_interaction = _this.interaction) == null ? void 0 : _this_interaction.behavior) || 0,
                         type: area.type,
                         triangles: area.area,
-                        backfaceCulling: _this.renderer.side === SideMode.FRONT
+                        backfaceCulling: _this.renderer.side === SideMode.FRONT,
+                        clipMasks: _this.frameClipMasks
                     };
                 }
             }
@@ -21783,7 +21848,8 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
                         behavior: 0,
                         type: area.type,
                         triangles: area.area,
-                        backfaceCulling: _this.rendererOptions.side === SideMode.FRONT
+                        backfaceCulling: _this.rendererOptions.side === SideMode.FRONT,
+                        clipMasks: _this.frameClipMasks
                     };
                 }
             }
@@ -21886,8 +21952,9 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
     };
     _proto.onUpdate = function onUpdate(dt) {
         if (this.shapeDirty) {
-            this.buildPath(this.shapeAttributes);
-            this.buildGeometryFromPath(this.graphicsPath.shapePath);
+            var screenScale = this.computeScreenScale();
+            this.buildPath(this.shapeAttributes, screenScale);
+            this.buildGeometryFromPath(this.graphicsPath.shapePath, screenScale);
             this.shapeDirty = false;
         }
         if (this.materialDirty) {
@@ -21938,7 +22005,7 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
         }
         return this.boundingBoxInfo;
     };
-    _proto.buildGeometryFromPath = function buildGeometryFromPath(shapePath) {
+    _proto.buildGeometryFromPath = function buildGeometryFromPath(shapePath, screenScale) {
         var shapePrimitives = shapePath.shapePrimitives;
         var vertices = [];
         var indices = [];
@@ -21950,7 +22017,7 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
                 var points = [];
                 var indexOffset = indices.length;
                 var vertOffset = vertices.length / 2;
-                shape.build(points);
+                shape.build(points, screenScale);
                 shape.triangulate(points, vertices, vertOffset, indices, indexOffset);
             }
         }
@@ -21970,7 +22037,7 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
                 if (this.shapeAttributes.type === ShapePrimitiveType.Custom) {
                     close = shape1.closePath;
                 }
-                shape1.build(points1);
+                shape1.build(points1, screenScale);
                 buildLine(points1, lineStyle, false, close, vertices, 2, vertOffset1, indices);
             }
         }
@@ -22030,8 +22097,40 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
         strokeSubMesh.offset = fillIndexCount * u16Size;
         strokeSubMesh.indexCount = strokeIndexCount;
     };
-    _proto.buildPath = function buildPath(shapeAttribute) {
+    _proto.computeScreenScale = function computeScreenScale() {
+        var defaultPpu = 1;
+        var composition = this.item.composition;
+        if (!composition) {
+            return defaultPpu;
+        }
+        var camera = composition.camera;
+        if (!camera) {
+            return defaultPpu;
+        }
+        var mvp = camera.getModelViewProjection(ShapeComponent.tempMVP, this.transform.getWorldMatrix());
+        var e = mvp.elements;
+        // 列优先：col0=[e[0],e[1]], col1=[e[4],e[5]]
+        // 透视投影下 MVP 不含 w-divide，cols 0-1 的长度是 clip-space 缩放
+        // 需要除以物体中心的 w 值才能得到 NDC 缩放
+        // 物体局部原点 [0,0,0,1] 经 MVP 后 w = e[15]（≈ 物体到相机距离）
+        var w = Math.abs(e[15]) || 1;
+        var sx = Math.sqrt(e[0] * e[0] + e[1] * e[1]) / w;
+        var sy = Math.sqrt(e[4] * e[4] + e[5] * e[5]) / w;
+        var maxNdcScale = Math.max(sx, sy);
+        // NDC -> 像素: canvasSize / 2
+        var canvasRect = this.engine.canvas.getBoundingClientRect();
+        var ndcToPixels = Math.max(canvasRect.width, canvasRect.height) / 2;
+        // pixelsPerUnit: 1个局部空间单位在屏幕上对应多少像素
+        // 椭圆/圆/矩形中使用 n = ceil(√(ppu × (rx+ry))) 确保圆弧误差 ≈ 1.2px
+        var pixelsPerUnit = maxNdcScale * ndcToPixels * this.engine.pixelRatio;
+        var minPpu = 1;
+        var maxPpu = 2000;
+        return Math.max(minPpu, Math.min(maxPpu, pixelsPerUnit));
+    };
+    _proto.buildPath = function buildPath(shapeAttribute, screenScale) {
+        if (screenScale === void 0) screenScale = 1;
         this.graphicsPath.clear();
+        var ppu = screenScale;
         switch(shapeAttribute.type){
             case ShapePrimitiveType.Custom:
                 {
@@ -22051,7 +22150,7 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
                             var lastPoint = points[lastPointIndex.point];
                             var control1 = easingOuts[lastPointIndex.easingOut];
                             var control2 = easingIns[pointIndex.easingIn];
-                            this.graphicsPath.bezierCurveTo(control1.x + lastPoint.x, control1.y + lastPoint.y, control2.x + point.x, control2.y + point.y, point.x, point.y, 1);
+                            this.graphicsPath.bezierCurveTo(control1.x + lastPoint.x, control1.y + lastPoint.y, control2.x + point.x, control2.y + point.y, point.x, point.y, undefined, ppu);
                         }
                         if (shape.close) {
                             var pointIndex1 = indices[0];
@@ -22060,7 +22159,7 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
                             var lastPoint1 = points[lastPointIndex1.point];
                             var control11 = easingOuts[lastPointIndex1.easingOut];
                             var control21 = easingIns[pointIndex1.easingIn];
-                            this.graphicsPath.bezierCurveTo(control11.x + lastPoint1.x, control11.y + lastPoint1.y, control21.x + point1.x, control21.y + point1.y, point1.x, point1.y, 1);
+                            this.graphicsPath.bezierCurveTo(control11.x + lastPoint1.x, control11.y + lastPoint1.y, control21.x + point1.x, control21.y + point1.y, point1.x, point1.y, undefined, ppu);
                             this.graphicsPath.closePath();
                         }
                     }
@@ -22355,6 +22454,7 @@ var ShapeComponent = /*#__PURE__*/ function(RendererComponent) {
     ]);
     return ShapeComponent;
 }(RendererComponent);
+ShapeComponent.tempMVP = Matrix4.fromIdentity();
 ShapeComponent = __decorate([
     effectsClass("ShapeComponent")
 ], ShapeComponent);
@@ -22501,7 +22601,8 @@ var FrameComponent = /*#__PURE__*/ function(RendererComponent1) {
                 if (area) {
                     return {
                         type: area.type,
-                        triangles: area.area
+                        triangles: area.area,
+                        clipMasks: _this.frameClipMasks
                     };
                 }
             }
@@ -22614,7 +22715,7 @@ var FrameComponent = /*#__PURE__*/ function(RendererComponent1) {
             var child = _step.value;
             var childFrameComponent = child.getComponent(RendererComponent);
             if (childFrameComponent) {
-                childFrameComponent.frameClipMasks.push(this);
+                addItem(childFrameComponent.frameClipMasks, this);
             }
             this.setClipRectangleRecursive(child);
         }
@@ -23151,7 +23252,8 @@ var InteractComponent = /*#__PURE__*/ function(RendererComponent) {
                 return {
                     type: area.type,
                     triangles: area.area,
-                    behavior: behavior
+                    behavior: behavior,
+                    clipMasks: _this.frameClipMasks
                 };
             }
         };
@@ -27555,6 +27657,7 @@ var ParticleSystem = /*#__PURE__*/ function(Component) {
             if (force || interactParams) {
                 return {
                     type: HitTestType.custom,
+                    clipMasks: _this.renderer.frameClipMasks,
                     collect: function(ray) {
                         return _this.raycast({
                             radius: (interactParams == null ? void 0 : interactParams.radius) || 0.4,
@@ -29290,13 +29393,14 @@ var TextLayout = /*#__PURE__*/ function() {
     }
     var _proto = TextLayout.prototype;
     _proto.update = function update(options) {
-        var _options_textHeight = options.textHeight, textHeight = _options_textHeight === void 0 ? 100 : _options_textHeight, _options_textWidth = options.textWidth, textWidth = _options_textWidth === void 0 ? 100 : _options_textWidth, _options_textOverflow = options.textOverflow, textOverflow = _options_textOverflow === void 0 ? TextOverflow.clip : _options_textOverflow, _options_textVerticalAlign = options.textVerticalAlign, textVerticalAlign = _options_textVerticalAlign === void 0 ? TextVerticalAlign.top : _options_textVerticalAlign, _options_textAlign = options.textAlign, textAlign = _options_textAlign === void 0 ? TextAlignment.left : _options_textAlign, _options_letterSpace = options.letterSpace, letterSpace = _options_letterSpace === void 0 ? 0 : _options_letterSpace, fontSize = options.fontSize, _options_lineHeight = options.lineHeight, lineHeight = _options_lineHeight === void 0 ? fontSize : _options_lineHeight;
+        var _options_textHeight = options.textHeight, textHeight = _options_textHeight === void 0 ? 100 : _options_textHeight, _options_textWidth = options.textWidth, textWidth = _options_textWidth === void 0 ? 100 : _options_textWidth, _options_textOverflow = options.textOverflow, textOverflow = _options_textOverflow === void 0 ? TextOverflow.clip : _options_textOverflow, _options_textVerticalAlign = options.textVerticalAlign, textVerticalAlign = _options_textVerticalAlign === void 0 ? TextVerticalAlign.top : _options_textVerticalAlign, _options_textAlign = options.textAlign, textAlign = _options_textAlign === void 0 ? TextAlignment.left : _options_textAlign, _options_letterSpace = options.letterSpace, letterSpace = _options_letterSpace === void 0 ? 0 : _options_letterSpace, fontSize = options.fontSize, _options_lineHeight = options.lineHeight, lineHeight = _options_lineHeight === void 0 ? fontSize : _options_lineHeight, _options_autoResize = options.autoResize, autoResize = _options_autoResize === void 0 ? TextSizeMode.fixed : _options_autoResize;
         this.letterSpace = letterSpace;
         this.overflow = textOverflow;
         this.textVerticalAlign = textVerticalAlign;
         this.textAlign = textAlign;
         this.width = textWidth;
         this.height = textHeight;
+        this.autoResize = autoResize;
         this.lineHeight = lineHeight;
     };
     /**
@@ -29308,7 +29412,6 @@ var TextLayout = /*#__PURE__*/ function() {
    * @param totalLineHeight - 可选的实际总行高，用于替代默认计算
    * @returns - 行高偏移值
    */ _proto.getOffsetY = function getOffsetY(style, lineCount, lineHeight, fontSize, totalLineHeight) {
-        var fontScale = style.fontScale;
         // /3 计算Y轴偏移量，以匹配编辑器行为
         var offsetY = (lineHeight - fontSize) / 3;
         // 计算基础偏移量
@@ -29320,10 +29423,10 @@ var TextLayout = /*#__PURE__*/ function() {
                 offsetResult = baseOffset + offsetY;
                 break;
             case TextVerticalAlign.middle:
-                offsetResult = (this.height * fontScale - commonCalculation + baseOffset) / 2;
+                offsetResult = (this.height - commonCalculation + baseOffset) / 2;
                 break;
             case TextVerticalAlign.bottom:
-                offsetResult = this.height * fontScale - commonCalculation - offsetY;
+                offsetResult = this.height - commonCalculation - offsetY;
                 break;
         }
         return offsetResult;
@@ -29340,10 +29443,10 @@ var TextLayout = /*#__PURE__*/ function() {
                 offsetX = 0;
                 break;
             case TextAlignment.middle:
-                offsetX = (this.width * style.fontScale - maxWidth) / 2;
+                offsetX = (this.width - maxWidth) / 2;
                 break;
             case TextAlignment.right:
-                offsetX = this.width * style.fontScale - maxWidth;
+                offsetX = this.width - maxWidth;
                 break;
         }
         return offsetX;
@@ -29596,8 +29699,8 @@ var TextStyle = /*#__PURE__*/ function() {
     };
     // 通用工具方法
     _proto.getFontDesc = function getFontDesc(size) {
-        var _this_textStyle = this.textStyle, fontSize = _this_textStyle.fontSize, fontScale = _this_textStyle.fontScale, fontFamily = _this_textStyle.fontFamily, textWeight = _this_textStyle.textWeight, fontStyle = _this_textStyle.fontStyle;
-        var fontDesc = "" + (size || fontSize * fontScale).toString() + "px ";
+        var _this_textStyle = this.textStyle, fontSize = _this_textStyle.fontSize, fontFamily = _this_textStyle.fontFamily, textWeight = _this_textStyle.textWeight, fontStyle = _this_textStyle.fontStyle;
+        var fontDesc = "" + (size || fontSize).toString() + "px ";
         if (![
             "serif",
             "sans-serif",
@@ -29627,13 +29730,13 @@ var TextStyle = /*#__PURE__*/ function() {
     };
     _proto.setupShadow = function setupShadow() {
         var context = this.context;
-        var _this_textStyle = this.textStyle, shadowColor = _this_textStyle.shadowColor, shadowBlur = _this_textStyle.shadowBlur, shadowOffsetX = _this_textStyle.shadowOffsetX, shadowOffsetY = _this_textStyle.shadowOffsetY;
+        var _this_textStyle = this.textStyle, shadowColor = _this_textStyle.shadowColor, shadowBlur = _this_textStyle.shadowBlur, shadowOffsetX = _this_textStyle.shadowOffsetX, shadowOffsetY = _this_textStyle.shadowOffsetY, fontScale = _this_textStyle.fontScale;
         var r = shadowColor[0], g = shadowColor[1], b = shadowColor[2], a = shadowColor[3];
         if (context) {
             context.shadowColor = "rgba(" + r * 255 + ", " + g * 255 + ", " + b * 255 + ", " + a + ")";
-            context.shadowBlur = shadowBlur;
-            context.shadowOffsetX = shadowOffsetX;
-            context.shadowOffsetY = -shadowOffsetY;
+            context.shadowBlur = shadowBlur * fontScale;
+            context.shadowOffsetX = shadowOffsetX * fontScale;
+            context.shadowOffsetY = -shadowOffsetY * fontScale;
         }
     };
     // 通用纹理生命周期管理
@@ -29878,30 +29981,40 @@ var TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
             layout.width = this.getTextWidth();
             this.lineCount = this.getLineCount(this.text);
             layout.height = layout.lineHeight * this.lineCount;
+        } else if (layout.autoResize === TextSizeMode.autoHeight) {
+            this.lineCount = this.getLineCount(this.text);
+            layout.height = layout.lineHeight * this.lineCount;
         } else {
             this.lineCount = this.getLineCount(this.text);
         }
-        var baseWidth = (layout.width + style.fontOffset) * fontScale;
-        var baseHeight = layout.height * fontScale;
-        var fontSize = style.fontSize * fontScale;
-        var lineHeight = layout.lineHeight * fontScale;
+        var baseWidth = layout.width + style.fontOffset;
+        var baseHeight = layout.height;
+        var fontSize = style.fontSize;
+        var lineHeight = layout.lineHeight;
         style.fontDesc = this.getFontDesc(fontSize);
         // 使用 Array.from 正确分割 Unicode 字符（包括 emoji）
         var char = Array.from(this.text || "");
         var _this_getEffectPadding = this.getEffectPadding(), padL = _this_getEffectPadding.padL, padR = _this_getEffectPadding.padR, padT = _this_getEffectPadding.padT, padB = _this_getEffectPadding.padB;
         var hasEffect = (padL | padR | padT | padB) !== 0;
-        var texWidth = hasEffect ? Math.ceil(baseWidth + padL + padR) : baseWidth;
-        var texHeight = hasEffect ? Math.ceil(baseHeight + padT + padB) : baseHeight;
+        // 限制 fontScale，确保纹理尺寸不超过 maxTextureSize / 2
+        var maxTexSize = this.engine.gpuCapability.detail.maxTextureSize / 2;
+        var logicalWidth = hasEffect ? baseWidth + padL + padR : baseWidth;
+        var logicalHeight = hasEffect ? baseHeight + padT + padB : baseHeight;
+        var maxLogical = Math.max(logicalWidth, logicalHeight, 1);
+        fontScale = Math.min(fontScale, maxTexSize / maxLogical);
+        var texWidth = Math.ceil(logicalWidth * fontScale);
+        var texHeight = Math.ceil(logicalHeight * fontScale);
         var shiftX = hasEffect ? padL : 0;
         var shiftY = hasEffect ? flipY ? padT : padB : 0;
         // 给渲染层用：扩容比例
-        this.effectScaleX = baseWidth > 0 ? texWidth / baseWidth : 1;
-        this.effectScaleY = baseHeight > 0 ? texHeight / baseHeight : 1;
+        this.effectScaleX = baseWidth > 0 ? texWidth / (baseWidth * fontScale) : 1;
+        this.effectScaleY = baseHeight > 0 ? texHeight / (baseHeight * fontScale) : 1;
         // 默认 camera 下的 world per pixel
         var scaleFactor = 0.11092565;
         var scaleFactor2 = scaleFactor * scaleFactor;
-        this.transform.setSize(baseWidth * scaleFactor2 / fontScale, baseHeight * scaleFactor2 / fontScale);
+        this.transform.setSize(baseWidth * scaleFactor2, baseHeight * scaleFactor2);
         this.renderToTexture(texWidth, texHeight, flipY, function(context) {
+            context.scale(fontScale, fontScale);
             // canvas size 变化后重新刷新 context
             if (_this.maxLineWidth > baseWidth && layout.overflow === TextOverflow.display) {
                 context.font = _this.getFontDesc(fontSize * baseWidth / _this.maxLineWidth);
@@ -29922,7 +30035,7 @@ var TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                 // 和浏览器行为保持一致
                 // 字符间距只应用在字符之间，每行第一个字符不加间距
                 if (charsArray.length > 0) {
-                    x += layout.letterSpace * fontScale;
+                    x += layout.letterSpace;
                 }
                 if (x + textMetrics.width > baseWidth && i > 0 || str === "\n") {
                     charsInfo.push({
@@ -30007,9 +30120,9 @@ var TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
    */ _proto.getEffectPadding = function getEffectPadding() {
         var style = this.textStyle;
         var hasDrawOutline = style.isOutlined && style.outlineWidth > 0;
-        var outlinePad = hasDrawOutline ? Math.ceil(style.outlineWidth * 2 * style.fontScale) : 0;
+        var outlinePad = hasDrawOutline ? Math.ceil(style.outlineWidth * 2) : 0;
         var hasShadow = style.hasShadow && (style.shadowBlur > 0 || style.shadowOffsetX !== 0 || style.shadowOffsetY !== 0);
-        var shadowPad = hasShadow ? Math.ceil((Math.abs(style.shadowOffsetX) + Math.abs(style.shadowOffsetY) + style.shadowBlur) * style.fontScale) : 0;
+        var shadowPad = hasShadow ? Math.ceil(Math.abs(style.shadowOffsetX) + Math.abs(style.shadowOffsetY) + style.shadowBlur) : 0;
         var pad = outlinePad + shadowPad;
         return {
             padL: pad,
@@ -30034,11 +30147,13 @@ var TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
         var width = Math.max(0, Number(value) || 0);
         var layout = this.textLayout;
         // 宽度没变且已是非 autoWidth 模式,直接返回
-        if (layout.width === width && layout.autoResize === TextSizeMode.autoWidth) {
+        if (layout.width === width) {
             return;
         }
         // 手动设置宽度时关闭 autoWidth
-        layout.autoResize = TextSizeMode.autoHeight;
+        if (layout.autoResize === TextSizeMode.autoWidth) {
+            layout.autoResize = TextSizeMode.autoHeight;
+        }
         layout.width = width;
         // 按当前 overflow 模式重新计算 maxLineWidth
         this.isDirty = true;
@@ -30151,7 +30266,7 @@ var TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
    *
    * 说明：
    * - 使用 Canvas 2D 的 measureText，并按当前实现的逐字符排版规则累加宽度（与 updateTexture 保持一致）。
-   * - 结果为"逻辑宽度"（已除去 fontScale，并扣除 fontOffset），可直接写回 options.textWidth。
+   * - 结果为"逻辑宽度"（扣除 fontOffset），可直接写回 options.textWidth。，可直接写回 options.textWidth。
    * - 通过 padding 追加少量冗余像素，用于降低边缘裁切风险。
    *
    * @returns 文本宽度（>= 0）
@@ -30166,10 +30281,8 @@ var TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
         var text = ((_this_text = this.text) != null ? _this_text : "").toString();
         var layout = this.textLayout;
         var style = this.textStyle;
-        var fontScale = style.fontScale || 1;
-        var renderFontSize = style.fontSize * fontScale;
-        // 与 updateTexture 一致：用 render 字号测量
-        ctx.font = this.getFontDesc(renderFontSize);
+        // 与 updateTexture 一致：用逻辑字号测量
+        ctx.font = this.getFontDesc(style.fontSize);
         var maxLineWidthRender = 0;
         var x = 0;
         for(var i = 0; i < text.length; i++){
@@ -30179,17 +30292,14 @@ var TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                 x = 0;
                 continue;
             }
-            // 与 updateTexture 一致：每个字符前加一次 letterSpace * fontScale
-            x += (layout.letterSpace || 0) * fontScale;
+            // 与 updateTexture 一致：每个字符前加一次 letterSpace
+            x += layout.letterSpace || 0;
             x += ctx.measureText(ch).width;
         }
         maxLineWidthRender = Math.max(maxLineWidthRender, x);
-        // render -> 逻辑宽度
-        var logicalMax = maxLineWidthRender / fontScale;
-        // 反推 layout.width：renderWidth = (layout.width + fontOffset) * fontScale
         var padding = 2;
         var EPS = 1e-4;
-        var w = Math.ceil(logicalMax - (style.fontOffset || 0) - EPS) + padding;
+        var w = Math.ceil(maxLineWidthRender - (style.fontOffset || 0) - EPS) + padding;
         return Math.max(0, w);
     };
     _proto.getDefaultProps = function getDefaultProps() {
@@ -30301,9 +30411,9 @@ var SerializationHelper = /*#__PURE__*/ function() {
             }
         }
         // TODO 待移除 tagggedProperties 为没有装饰器的临时方案
-        for(var _iterator1 = _create_for_of_iterator_helper_loose(Object.keys(effectsObject.defination)), _step1; !(_step1 = _iterator1()).done;){
+        for(var _iterator1 = _create_for_of_iterator_helper_loose(Object.keys(effectsObject.definition)), _step1; !(_step1 = _iterator1()).done;){
             var key1 = _step1.value;
-            var value1 = effectsObject.defination[key1];
+            var value1 = effectsObject.definition[key1];
             if (typeof value1 === "number" || typeof value1 === "string" || typeof value1 === "boolean" || SerializationHelper.checkTypedArray(value1)) {
                 // TODO json 数据避免传 typedArray
                 serializedData[key1] = value1;
@@ -30327,7 +30437,7 @@ var SerializationHelper = /*#__PURE__*/ function() {
         return serializedData;
     };
     SerializationHelper.deserialize = function deserialize(serializedData, effectsObject) {
-        effectsObject.defination = serializedData;
+        effectsObject.definition = serializedData;
         var serializedProperties = getMergedStore(effectsObject);
         var engine = effectsObject.engine;
         if (serializedProperties) {
@@ -30342,7 +30452,7 @@ var SerializationHelper = /*#__PURE__*/ function() {
                 effectsObject[key] = SerializationHelper.deserializeProperty(value, engine, 0, propertyType);
             }
         }
-        effectsObject.fromData(effectsObject.defination);
+        effectsObject.fromData(effectsObject.definition);
     };
     SerializationHelper.checkTypedArray = function checkTypedArray(obj) {
         return _instanceof1(obj, Int8Array) || _instanceof1(obj, Uint8Array) || _instanceof1(obj, Uint8ClampedArray) || _instanceof1(obj, Int16Array) || _instanceof1(obj, Uint16Array) || _instanceof1(obj, Int32Array) || _instanceof1(obj, Uint32Array) || _instanceof1(obj, Float32Array) || _instanceof1(obj, Float64Array) || _instanceof1(obj, ArrayBuffer);
@@ -30473,7 +30583,7 @@ var SerializationHelper = /*#__PURE__*/ function() {
         var effectsObjectData = this.findData(guid);
         var effectsObject;
         if (!effectsObjectData) {
-            console.error("Object data with uuid: " + guid + " not found.");
+            console.warn("Object data with uuid: " + guid + " not found.");
             return undefined;
         }
         switch(effectsObjectData.dataType){
@@ -30495,7 +30605,7 @@ var SerializationHelper = /*#__PURE__*/ function() {
                 }
         }
         if (!effectsObject) {
-            console.error("Constructor for DataType: " + effectsObjectData.dataType + " not found.");
+            console.warn("Constructor for DataType: " + effectsObjectData.dataType + " not found.");
             return undefined;
         }
         effectsObject.setInstanceId(effectsObjectData.id);
@@ -32337,7 +32447,7 @@ function getStandardSpriteContent(sprite, transform) {
     return ret;
 }
 
-var version$2 = "2.9.0-alpha.1";
+var version$2 = "2.9.0-alpha.2";
 var v0 = /^(\d+)\.(\d+)\.(\d+)(-(\w+)\.\d+)?$/;
 var standardVersion = /^(\d+)\.(\d+)$/;
 var reverseParticle = false;
@@ -34656,7 +34766,9 @@ var PreRenderTickData = /*#__PURE__*/ function(TickData) {
         }
         var regions = [];
         var ray = this.getHitTestRay(x, y);
-        this.rootComposition.hitTest(ray, x, y, regions, force, options);
+        // 所有命中的元素共享同一个 hitPositions 数组，保持与原有行为一致
+        var hitPositions = [];
+        this.rootItem.hitTest(ray, x, y, regions, hitPositions, force, options);
         return regions;
     };
     /**
@@ -37224,10 +37336,6 @@ var PassTextureCache = /*#__PURE__*/ function() {
             height: renderer.getHeight(),
             event: engine.eventSystem
         }), scene);
-        // 中低端设备降帧到 30fps·
-        if (engine.ticker && options.renderLevel === RenderLevel.B) {
-            engine.ticker.setFPS(Math.min(engine.ticker.getFPS(), 30));
-        }
         // TODO 目前编辑器会每帧调用 loadScene, 在这编译会导致闪帧，待编辑器渲染逻辑优化后移除。
         if (engine.env !== PLAYER_OPTIONS_ENV_EDITOR) {
             engine.assetService.createShaderVariant();
@@ -37292,7 +37400,7 @@ registerPlugin("text", TextLoader);
 registerPlugin("sprite", SpriteLoader);
 registerPlugin("particle", ParticleLoader);
 registerPlugin("interact", InteractLoader);
-var version$1 = "2.9.0-alpha.1";
+var version$1 = "2.9.0-alpha.2";
 logger.info("Core version: " + version$1 + ".");
 
 var _obj;
@@ -38450,11 +38558,21 @@ var seed = 1;
     }
     var _proto = ThreeComposition.prototype;
     _proto.prepareRender = function prepareRender() {
-        var _this_rootItem_getComponent;
         var render = this.renderer;
         var frame = this.renderFrame;
         frame.renderPasses[0].meshes.length = 0;
-        (_this_rootItem_getComponent = this.rootItem.getComponent(RendererComponent)) == null ? void 0 : _this_rootItem_getComponent.render(render);
+        var items = this.rootItem.getDescendants();
+        // 主合成元素
+        for(var _iterator = _create_for_of_iterator_helper_loose(items), _step; !(_step = _iterator()).done;){
+            var vfxItem = _step.value;
+            var rendererComponents = vfxItem.getComponents(RendererComponent);
+            for(var _iterator1 = _create_for_of_iterator_helper_loose(rendererComponents), _step1; !(_step1 = _iterator1()).done;){
+                var rendererComponent = _step1.value;
+                if (rendererComponent.isActiveAndEnabled) {
+                    rendererComponent.render(render);
+                }
+            }
+        }
     };
     return ThreeComposition;
 }(Composition);
@@ -38858,7 +38976,7 @@ applyMixins(ThreeTextComponent, [
  */ Mesh.create = function(engine, props) {
     return new ThreeMesh(engine, props);
 };
-var version = "2.9.0-alpha.1";
+var version = "2.9.0-alpha.2";
 logger.info("THREEJS plugin version: " + version + ".");
 
 export { ActivationMixerPlayable, ActivationPlayable, ActivationPlayableAsset, ActivationTrack, AndNode, AndNodeData, Animatable, AnimationClip, AnimationClipNode, AnimationClipNodeData, AnimationEvent, AnimationGraphAsset, Animator, ApplyAdditiveNode, ApplyAdditiveNodeData, Asset, AssetLoader, AssetManager, AssetService, BYTES_TYPE_MAP, Behaviour, BezierCurve, BezierCurvePath, BezierCurveQuat, BinaryAsset, BlendNode, BlendNodeData, BoolValueNode, BoundingBoxInfo, CONSTANT_MAP_BLEND, CONSTANT_MAP_DEPTH, CONSTANT_MAP_STENCIL_FUNC, CONSTANT_MAP_STENCIL_OP, COPY_FRAGMENT_SHADER, COPY_MESH_SHADER_ID, COPY_VERTEX_SHADER, Camera, CameraController, CameraVFXItemLoader, ColorCurve, ColorPlayable, ColorPropertyMixerPlayable, ColorPropertyPlayableAsset, ColorPropertyTrack, Component, ComponentTimePlayable, ComponentTimePlayableAsset, ComponentTimeTrack, Composition, CompositionComponent, CompressTextureCapabilityType, ConstBoolNode, ConstBoolNodeData, ConstFloatNode, ConstFloatNodeData, ConstraintTarget, ControlParameterBoolNode, ControlParameterBoolNodeData, ControlParameterFloatNode, ControlParameterFloatNodeData, ControlParameterTriggerNode, ControlParameterTriggerNodeData, DEFAULT_FONTS, DEFAULT_FPS, Database, Deferred, DestroyOptions, Downloader, DrawObjectPass, EFFECTS_COPY_MESH_NAME, EVENT_TYPE_CLICK, EVENT_TYPE_TOUCH_END, EVENT_TYPE_TOUCH_MOVE, EVENT_TYPE_TOUCH_START, EffectComponent, EffectComponentTimeTrack, EffectsObject, EffectsPackage, Ellipse, Engine, EqualNodeData, EventEmitter, EventSystem, Fake3DAnimationMode, Fake3DComponent, FilterMode, Float16ArrayWrapper, FloatComparisonNode, FloatComparisonNodeData, FloatPropertyMixerPlayable, FloatPropertyPlayableAsset, FloatPropertyTrack, FloatValueNode, FrameComponent, Framebuffer, GLSLVersion, GPUCapability, Geometry, GlobalUniforms, GradientValue, GraphInstance, GraphNode, GraphNodeData, Graphics, GraphicsPath, GreaterNodeData, HELP_LINK, HitTestType, InteractComponent, InteractLoader, InteractMesh, InvalidIndex, Item, LayerBlendNode, LayerBlendNodeData, LessNodeData, LineSegments, LinearValue, MaskMode, MaskProcessor, MaskableGraphic, Material, MaterialDataBlock, MaterialRenderType, MaterialTrack, Mesh, NodeTransform, NotNode, NotNodeData, NotifyEvent, ObjectBindingTrack, OrNode, OrNodeData, OrderType, PLAYER_OPTIONS_ENV_EDITOR, POST_PROCESS_SETTINGS, ParticleBehaviourPlayable, ParticleBehaviourPlayableAsset, ParticleLoader, ParticleMesh, ParticleMixerPlayable, ParticleSystem, ParticleSystemRenderer, ParticleTrack, PassTextureCache, PathSegments, PlayState, Playable, PlayableAsset, PlayableOutput, Plugin, PluginSystem, PointerEventData, PointerEventType, PolyStar, Polygon, Pose, PoseNode, PositionConstraint, PostProcessVolume, Precomposition, PrecompositionManager, PropertyClipPlayable, PropertyTrack, RENDER_PREFER_LOOKUP_TEXTURE, RUNTIME_ENV, RandomSetValue, RandomValue, RandomVectorValue, RaycastResult, RenderFrame, RenderPass, RenderPassAttachmentStorageType, RenderPassDestroyAttachmentType, RenderPassPriorityNormal, RenderPassPriorityPostprocess, RenderPassPriorityPrepare, RenderTargetHandle, RenderTargetPool, RenderTextureFormat, Renderbuffer, Renderer, RendererComponent, RuntimeClip, SEMANTIC_MAIN_PRE_COLOR_ATTACHMENT_0, SEMANTIC_MAIN_PRE_COLOR_ATTACHMENT_SIZE_0, SEMANTIC_PRE_COLOR_ATTACHMENT_0, SEMANTIC_PRE_COLOR_ATTACHMENT_SIZE_0, SPRITE_VERTEX_STRIDE, Scene, SceneLoader, SerializationHelper, Shader, ShaderCompileResultStatus, ShaderFactory, ShaderType, ShaderVariant, ShapeComponent, ShapePath, SourceType, SpriteColorMixerPlayable, SpriteColorPlayableAsset, SpriteColorTrack, SpriteComponent, SpriteComponentTimeTrack, SpriteLoader, StarType, StateMachineNode, StateMachineNodeData, StateNode, StateNodeData, StaticValue, SubCompositionClipPlayable, SubCompositionMixerPlayable, SubCompositionPlayableAsset, SubCompositionTrack, TEMPLATE_USE_OFFSCREEN_CANVAS, TEXTURE_UNIFORM_MAP, TangentMode, TextComponent, TextComponentBase, TextLayout, TextLoader, TextStyle, Texture, TextureFactory, TextureLoadAction, TexturePaintScaleMode, TextureSourceType, TextureStoreAction, ThreeComposition, ThreeDisplayObject, ThreeEngine, ThreeMaterial, ThreeSpriteComponent, ThreeTextComponent, ThreeTexture, Ticker, TimelineAsset, TimelineClip, TimelineInstance, TrackAsset, TrackMixerPlayable, TrackType, Transform, TransformMixerPlayable, TransformPlayable, TransformPlayableAsset, TransformTrack, TransitionNode, TransitionNodeData, TransitionState, UpdateModes, VFXItem, ValueGetter, ValueNode, Vector2Curve, Vector2PropertyMixerPlayable, Vector2PropertyPlayableAsset, Vector2PropertyTrack, Vector3Curve, Vector3PropertyMixerPlayable, Vector3PropertyTrack, Vector3ropertyPlayableAsset, Vector4Curve, Vector4PropertyMixerPlayable, Vector4PropertyPlayableAsset, Vector4PropertyTrack, WeightedMode, addByOrder, addItem, addItemWithOrder, applyMixins, assertExist, asserts, base64ToFile, buildLine, calculateTranslation, canUseBOM, canvasPool, closePointEps, colorGradingFrag, colorStopsFromGradient, colorToArr$1 as colorToArr, combineImageTemplate, createGLContext, createKeyFrameMeta, createShape, createValueGetter, curveEps, decimalEqual, deserializeMipmapTexture, earcut, effectsClass, effectsClassStore, enlargeBuffer, ensureFixedNumber, ensureVec3, extractMinAndMax, gaussianDownHFrag, gaussianDownVFrag, gaussianUpFrag, generateEmptyTypedArray, generateGUID, generateHalfFloatTexture, generateTransparentTexture, generateWhiteTexture, getBackgroundImage, getClass, getColorFromGradientStops, getConfig, getDefaultTextureFactory, getGeometryByShape, getGeometryTriangles, getKeyFrameMetaByRawValue, getMergedStore, getNodeDataClass, getParticleMeshShader, getPixelRatio, getPluginUsageInfo, getPreMultiAlpha, getStandardComposition, getStandardImage, getStandardItem, getStandardJSON, getTextureSize, glContext, glType2VertexFormatType, gpuTimer, imageDataFromColor, imageDataFromGradient, initErrors, initGLContext, integrate, interpolateColor, isAlipayMiniApp, isAndroid, isArray, isCanvas, isFunction, isIOS, isIOSByUA, isMiniProgram, isObject, isOpenHarmony, isPlainObject, isPowerOfTwo, isSafeFontFamily, isSimulatorCellPhone, isString, isUniformStruct, isUniformStructArray, isValidFontFamily, isWebGL2, isWechatMiniApp, itemFrag, itemVert, loadAVIFOptional, loadBinary, loadBlob, loadImage, loadMedia, loadVideo, loadWebPOptional, logger, index as math, modifyMaxKeyframeShader, nearestPowerOfTwo, nodeDataClass, noop, normalizeColor, numberToFix, oldBezierKeyFramesToNew, parsePercent$1 as parsePercent, particleFrag, particleOriginTranslateMap$1 as particleOriginTranslateMap, particleUniformTypeMap, particleVert, passRenderLevel, pluginLoaderMap, randomInRange, registerPlugin, removeItem, rotateVec2, screenMeshVert, serialize, setBlendMode, setConfig, setDefaultTextureFactory, setMaskMode, setRayFromCamera, setSideMode, setUniformValue, sortByOrder, index$1 as spec, textureLoaderRegistry, thresholdFrag, throwDestroyedError, trailVert, translatePoint, trianglesFromRect, unregisterPlugin, valIfUndefined, value, valueDefine, vecFill, vecMulCombine, version, vertexFormatType2GLType };