@galacean/effects-core 2.8.0-alpha.3 → 2.8.0-alpha.4

package/dist/index.js

@@ -3,7 +3,7 @@
  * Description: Galacean Effects runtime core for the web
  * Author: Ant Group CO., Ltd.
  * Contributors: 燃然,飂兮,十弦,云垣,茂安,意绮
- * Version: v2.8.0-alpha.3
+ * Version: v2.8.0-alpha.4
  */
 
 'use strict';
@@ -2883,7 +2883,6 @@ var plugins = [];
     pluginLoaderMap[name] = pluginClass;
     var pluginInstance = new pluginClass();
     pluginInstance.name = name;
-    pluginInstance.initialize();
     plugins.push(pluginInstance);
     plugins.sort(function(a, b) {
         return a.order - b.order;
@@ -2907,29 +2906,29 @@ var PluginSystem = /*#__PURE__*/ function() {
     };
     PluginSystem.initializeComposition = function initializeComposition(composition, scene) {
         plugins.forEach(function(loader) {
-            return loader.onCompositionConstructed(composition, scene);
+            return loader.onCompositionCreated(composition, scene);
         });
     };
     PluginSystem.destroyComposition = function destroyComposition(comp) {
         plugins.forEach(function(loader) {
-            return loader.onCompositionDestroyed(comp);
+            return loader.onCompositionDestroy(comp);
         });
     };
-    PluginSystem.processAssets = function processAssets(scene, options) {
+    PluginSystem.onAssetsLoadStart = function onAssetsLoadStart(scene, options) {
         return _async_to_generator(function() {
             return __generator(this, function(_state) {
                 return [
                     2,
                     Promise.all(plugins.map(function(plugin) {
-                        return plugin.processAssets(scene, options);
+                        return plugin.onAssetsLoadStart(scene, options);
                     }))
                 ];
             });
         })();
     };
-    PluginSystem.loadResources = function loadResources(scene, options, engine) {
+    PluginSystem.onAssetsLoadFinish = function onAssetsLoadFinish(scene, options, engine) {
         plugins.forEach(function(loader) {
-            return loader.prepareResource(scene, options, engine);
+            return loader.onAssetsLoadFinish(scene, options, engine);
         });
     };
     return PluginSystem;
@@ -2959,20 +2958,18 @@ function getPluginUsageInfo(name) {
 /**
  * 抽象插件类
  * 注册合成不同生命周期的回调函数
- */ var AbstractPlugin = /*#__PURE__*/ function() {
-    function AbstractPlugin() {
+ */ var Plugin = /*#__PURE__*/ function() {
+    function Plugin() {
         this.order = 100;
-        this.name = "";
+        this.name = "Plugin";
     }
-    var _proto = AbstractPlugin.prototype;
-    _proto.initialize = function initialize() {};
+    var _proto = Plugin.prototype;
     /**
-   * loadScene 函数调用的时候会触发此函数，
-   * 此阶段可以加载插件所需类型资源，并返回原始资源和加载后的资源。
-   * @param scene
-   * @param options
-   * @returns
-   */ _proto.processAssets = function processAssets(scene, options) {
+   * 场景加载时触发，用于加载插件所需的自定义资源。
+   * 此阶段适合发起异步资源请求。
+   * @param scene - 场景对象
+   * @param options - 场景加载选项
+   */ _proto.onAssetsLoadStart = function onAssetsLoadStart(scene, options) {
         return _async_to_generator(function() {
             return __generator(this, function(_state) {
                 return [
@@ -2982,17 +2979,22 @@ function getPluginUsageInfo(name) {
         })();
     };
     /**
-   * loadScene 函数调用的时候会触发此函数，
-   * 此阶段时，json 中的图片和二进制已经被加载完成，可以对加载好的资源做进一步处理，
-   * 如果 promise 被 reject, loadScene 函数同样会被 reject，表示场景加载失败。
-   * 请记住，整个 load 阶段都不要创建 GL 相关的对象，只创建 JS 对象
-   * 此阶段晚于 processAssets
-   * @param {Scene} scene
-   * @param {SceneLoadOptions} options
-   */ _proto.prepareResource = function prepareResource(scene, options, engine) {};
-    _proto.onCompositionConstructed = function onCompositionConstructed(composition, scene) {};
-    _proto.onCompositionDestroyed = function onCompositionDestroyed(composition) {};
-    return AbstractPlugin;
+   * 场景资源加载完成后触发。
+   * 此时 JSON 中的图片和二进制已加载完成，可对资源做进一步处理。
+   * @param scene - 场景对象
+   * @param options - 场景加载选项
+   * @param engine - 引擎实例
+   */ _proto.onAssetsLoadFinish = function onAssetsLoadFinish(scene, options, engine) {};
+    /**
+   * 合成创建完成后触发。
+   * @param composition - 合成对象
+   * @param scene - 场景对象
+   */ _proto.onCompositionCreated = function onCompositionCreated(composition, scene) {};
+    /**
+   * 合成销毁时触发。
+   * @param composition - 合成对象
+   */ _proto.onCompositionDestroy = function onCompositionDestroy(composition) {};
+    return Plugin;
 }();
 
 function _set_prototype_of(o, p) {
@@ -10652,6 +10654,9 @@ var DrawObjectPass = /*#__PURE__*/ function(RenderPass) {
                 stencilAction: exports.TextureLoadAction.clear
             });
         }
+        this.meshes.sort(function(a, b) {
+            return a.priority - b.priority;
+        });
         renderer.renderMeshes(this.meshes);
     };
     _proto.onCameraCleanup = function onCameraCleanup(renderer) {
@@ -16589,13 +16594,49 @@ exports.CameraController = __decorate([
     effectsClass(DataType.CameraController)
 ], exports.CameraController);
 
-var CameraVFXItemLoader = /*#__PURE__*/ function(AbstractPlugin) {
-    _inherits(CameraVFXItemLoader, AbstractPlugin);
+function _get_prototype_of(o) {
+    _get_prototype_of = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
+        return o.__proto__ || Object.getPrototypeOf(o);
+    };
+    return _get_prototype_of(o);
+}
+
+function _is_native_function(fn) {
+    return Function.toString.call(fn).indexOf("[native code]") !== -1;
+}
+
+function _wrap_native_super(Class) {
+    var _cache = typeof Map === "function" ? new Map() : undefined;
+    _wrap_native_super = function _wrap_native_super(Class) {
+        if (Class === null || !_is_native_function(Class)) return Class;
+        if (typeof Class !== "function") throw new TypeError("Super expression must either be null or a function");
+        if (typeof _cache !== "undefined") {
+            if (_cache.has(Class)) return _cache.get(Class);
+            _cache.set(Class, Wrapper);
+        }
+        function Wrapper() {
+            return _construct(Class, arguments, _get_prototype_of(this).constructor);
+        }
+        Wrapper.prototype = Object.create(Class.prototype, {
+            constructor: {
+                value: Wrapper,
+                enumerable: false,
+                writable: true,
+                configurable: true
+            }
+        });
+        return _set_prototype_of(Wrapper, Class);
+    };
+    return _wrap_native_super(Class);
+}
+
+var CameraVFXItemLoader = /*#__PURE__*/ function(Plugin) {
+    _inherits(CameraVFXItemLoader, Plugin);
     function CameraVFXItemLoader() {
-        return AbstractPlugin.apply(this, arguments);
+        return Plugin.apply(this, arguments);
     }
     return CameraVFXItemLoader;
-}(AbstractPlugin);
+}(_wrap_native_super(Plugin));
 
 exports.HitTestType = void 0;
 (function(HitTestType) {
@@ -16879,13 +16920,13 @@ function getCoord(event) {
     };
 }
 
-var InteractLoader = /*#__PURE__*/ function(AbstractPlugin) {
-    _inherits(InteractLoader, AbstractPlugin);
+var InteractLoader = /*#__PURE__*/ function(Plugin) {
+    _inherits(InteractLoader, Plugin);
     function InteractLoader() {
-        return AbstractPlugin.apply(this, arguments);
+        return Plugin.apply(this, arguments);
     }
     return InteractLoader;
-}(AbstractPlugin);
+}(_wrap_native_super(Plugin));
 
 var vertex = "\nprecision highp float;\n\nattribute vec2 aPoint;\nuniform vec4 uPos;\nuniform vec2 uSize;\nuniform vec4 uQuat;\nuniform vec4 uColor;\nuniform mat4 effects_ObjectToWorld;\nuniform mat4 effects_MatrixInvV;\nuniform mat4 effects_MatrixVP;\nvarying vec4 vColor;\n\nvec3 rotateByQuat(vec3 a, vec4 quat){\n  vec3 qvec = quat.xyz;\n  vec3 uv = cross(qvec, a);\n  vec3 uuv = cross(qvec, uv) * 2.;\n  return a +(uv * 2. * quat.w + uuv);\n}\n\nvoid main() {\n  vec4 _pos = uPos;\n  vec3 point = rotateByQuat(vec3(aPoint.xy * uSize, 0.),uQuat);\n  vec4 pos = vec4(_pos.xyz, 1.0);\n  pos = effects_ObjectToWorld * pos;\n  pos.xyz += effects_MatrixInvV[0].xyz * point.x+ effects_MatrixInvV[1].xyz * point.y;\n  gl_Position = effects_MatrixVP * pos;\n  vColor = uColor;\n}\n";
 var fragment = "\nprecision highp float;\n\n#define fragColor gl_FragColor\n\nvarying vec4 vColor;\nvoid main() {\n  gl_FragColor = vColor*vColor.a;\n}\n";
@@ -17484,16 +17525,16 @@ function shouldIgnoreBouncing(arg, mul) {
     return MeshCollider;
 }();
 
-var SpriteLoader = /*#__PURE__*/ function(AbstractPlugin) {
-    _inherits(SpriteLoader, AbstractPlugin);
+var SpriteLoader = /*#__PURE__*/ function(Plugin) {
+    _inherits(SpriteLoader, Plugin);
     function SpriteLoader() {
         var _this;
-        _this = AbstractPlugin.apply(this, arguments) || this;
+        _this = Plugin.apply(this, arguments) || this;
         _this.name = "sprite";
         return _this;
     }
     return SpriteLoader;
-}(AbstractPlugin);
+}(_wrap_native_super(Plugin));
 
 /**
  * 动画图可播放节点对象
@@ -19984,7 +20025,7 @@ function calculateDirection(prePoint, point, nextPoint) {
             if (this.time >= 0 && this.time < particleSystem.item.duration && particleSystem.isEnded()) {
                 particleSystem.reset();
             }
-            particleSystem.update(this.time - particleSystem.time);
+            particleSystem.simulate(this.time - particleSystem.time);
         }
         this.lastTime = this.time;
     };
@@ -21435,126 +21476,133 @@ exports.ParticleSystem = /*#__PURE__*/ function(Component) {
         this.initEmitterTransform();
     };
     _proto.onUpdate = function onUpdate(dt) {
-        this.update(dt);
+        if (!this.frozen) {
+            this.update(dt);
+        }
+    };
+    _proto.simulate = function simulate(time) {
+        this.update(time * 1000);
+        this.frozen = true;
     };
     _proto.update = function update(delta) {
         var _this = this;
-        if (this.started && !this.frozen) {
-            var now = this.time + delta / 1000;
-            var options = this.options;
-            var loopStartTime = this.loopStartTime;
-            var emission = this.emission;
-            this.time = now;
-            this.upDirectionWorld = null;
-            this.renderer.updateTime(now, delta);
-            var link = this.particleLink;
-            var emitterLifetime = (now - loopStartTime) / this.item.duration;
-            var timePassed = this.timePassed;
-            var trailUpdated = false;
-            var updateTrail = function() {
-                if (_this.trails && !trailUpdated) {
-                    trailUpdated = true;
-                    link.forEach(function(param) {
-                        var time = param[0], pointIndex = param[1], delay = param[2], point = param[3];
-                        if (time < timePassed) {
-                            _this.clearPointTrail(pointIndex);
-                        } else if (timePassed > delay) {
-                            _this.updatePointTrail(pointIndex, emitterLifetime, point, delay);
-                        }
-                    });
+        if (!this.started) {
+            return;
+        }
+        var now = this.time + delta / 1000;
+        var options = this.options;
+        var loopStartTime = this.loopStartTime;
+        var emission = this.emission;
+        this.time = now;
+        this.upDirectionWorld = null;
+        this.renderer.updateTime(now, delta);
+        var link = this.particleLink;
+        var emitterLifetime = (now - loopStartTime) / this.item.duration;
+        var timePassed = this.timePassed;
+        var trailUpdated = false;
+        var updateTrail = function() {
+            if (_this.trails && !trailUpdated) {
+                trailUpdated = true;
+                link.forEach(function(param) {
+                    var time = param[0], pointIndex = param[1], delay = param[2], point = param[3];
+                    if (time < timePassed) {
+                        _this.clearPointTrail(pointIndex);
+                    } else if (timePassed > delay) {
+                        _this.updatePointTrail(pointIndex, emitterLifetime, point, delay);
+                    }
+                });
+            }
+        };
+        if (!this.ended) {
+            var duration = this.item.duration;
+            var lifetime = this.lifetime;
+            if (timePassed < duration) {
+                var interval = 1 / emission.rateOverTime.getValue(lifetime);
+                var pointCount = Math.floor((timePassed - this.lastEmitTime) / interval);
+                var maxEmissionCount = pointCount;
+                var timeDelta = interval / pointCount;
+                var meshTime = now;
+                var maxCount = options.maxCount;
+                this.updateEmitterTransform(timePassed);
+                var shouldSkipGenerate = function() {
+                    var first = link.first;
+                    return _this.emissionStopped || link.length === maxCount && first && first.content[0] - loopStartTime > timePassed;
+                };
+                for(var i = 0; i < maxEmissionCount && i < maxCount; i++){
+                    if (shouldSkipGenerate()) {
+                        break;
+                    }
+                    var p = this.createPoint(lifetime);
+                    p.delay += meshTime + i * timeDelta;
+                    this.addParticle(p, maxCount);
+                    this.lastEmitTime = timePassed;
                 }
-            };
-            if (!this.ended) {
-                var duration = this.item.duration;
-                var lifetime = this.lifetime;
-                if (timePassed < duration) {
-                    var interval = 1 / emission.rateOverTime.getValue(lifetime);
-                    var pointCount = Math.floor((timePassed - this.lastEmitTime) / interval);
-                    var maxEmissionCount = pointCount;
-                    var timeDelta = interval / pointCount;
-                    var meshTime = now;
-                    var maxCount = options.maxCount;
-                    this.updateEmitterTransform(timePassed);
-                    var shouldSkipGenerate = function() {
-                        var first = link.first;
-                        return _this.emissionStopped || link.length === maxCount && first && first.content[0] - loopStartTime > timePassed;
-                    };
-                    for(var i = 0; i < maxEmissionCount && i < maxCount; i++){
-                        if (shouldSkipGenerate()) {
-                            break;
-                        }
-                        var p = this.createPoint(lifetime);
-                        p.delay += meshTime + i * timeDelta;
-                        this.addParticle(p, maxCount);
-                        this.lastEmitTime = timePassed;
+                var bursts = emission.bursts;
+                for(var j = (bursts == null ? void 0 : bursts.length) - 1, cursor = 0; j >= 0 && cursor < maxCount; j--){
+                    if (shouldSkipGenerate()) {
+                        break;
                     }
-                    var bursts = emission.bursts;
-                    for(var j = (bursts == null ? void 0 : bursts.length) - 1, cursor = 0; j >= 0 && cursor < maxCount; j--){
-                        if (shouldSkipGenerate()) {
-                            break;
+                    var burst = bursts[j];
+                    var opts = !burst.disabled && burst.getGeneratorOptions(timePassed, lifetime);
+                    if (opts) {
+                        var originVec = [
+                            0,
+                            0,
+                            0
+                        ];
+                        var offsets = emission.burstOffsets[j];
+                        var burstOffset = offsets && offsets[opts.cycleIndex] || originVec;
+                        if (burst.once) {
+                            this.removeBurst(j);
                         }
-                        var burst = bursts[j];
-                        var opts = !burst.disabled && burst.getGeneratorOptions(timePassed, lifetime);
-                        if (opts) {
-                            var originVec = [
-                                0,
-                                0,
-                                0
-                            ];
-                            var offsets = emission.burstOffsets[j];
-                            var burstOffset = offsets && offsets[opts.cycleIndex] || originVec;
-                            if (burst.once) {
-                                this.removeBurst(j);
-                            }
-                            for(var i1 = 0; i1 < opts.count && cursor < maxCount; i1++){
-                                var _p_transform;
-                                if (shouldSkipGenerate()) {
-                                    break;
-                                }
-                                var p1 = this.initPoint(this.shape.generate({
-                                    total: opts.total,
-                                    index: opts.index,
-                                    burstIndex: i1,
-                                    burstCount: opts.count
-                                }));
-                                p1.delay += meshTime;
-                                cursor++;
-                                (_p_transform = p1.transform).translate.apply(_p_transform, [].concat(burstOffset));
-                                this.addParticle(p1, maxCount);
+                        for(var i1 = 0; i1 < opts.count && cursor < maxCount; i1++){
+                            var _p_transform;
+                            if (shouldSkipGenerate()) {
+                                break;
                             }
+                            var p1 = this.initPoint(this.shape.generate({
+                                total: opts.total,
+                                index: opts.index,
+                                burstIndex: i1,
+                                burstCount: opts.count
+                            }));
+                            p1.delay += meshTime;
+                            cursor++;
+                            (_p_transform = p1.transform).translate.apply(_p_transform, [].concat(burstOffset));
+                            this.addParticle(p1, maxCount);
                         }
                     }
-                } else if (this.item.endBehavior === EndBehavior.restart) {
-                    updateTrail();
-                    this.loopStartTime = now - duration;
-                    this.lastEmitTime -= duration;
-                    this.time -= duration;
-                    emission.bursts.forEach(function(b) {
-                        return b.reset();
-                    });
-                    this.particleLink.forEach(function(content) {
-                        content[0] -= duration;
-                        content[2] -= duration;
-                        content[3].delay -= duration;
-                    });
-                    this.renderer.minusTimeForLoop(duration);
-                } else {
-                    this.ended = true;
-                    var endBehavior = this.item.endBehavior;
-                    if (endBehavior === EndBehavior.freeze) {
-                        this.frozen = true;
-                    }
                 }
-            } else if (this.item.endBehavior !== EndBehavior.restart) {
-                if (EndBehavior.destroy === this.item.endBehavior) {
-                    var node = link.last;
-                    if (node && node.content[0] < this.time) {
-                        this.destroyed = true;
-                    }
+            } else if (this.item.endBehavior === EndBehavior.restart) {
+                updateTrail();
+                this.loopStartTime = now - duration;
+                this.lastEmitTime -= duration;
+                this.time -= duration;
+                emission.bursts.forEach(function(b) {
+                    return b.reset();
+                });
+                this.particleLink.forEach(function(content) {
+                    content[0] -= duration;
+                    content[2] -= duration;
+                    content[3].delay -= duration;
+                });
+                this.renderer.minusTimeForLoop(duration);
+            } else {
+                this.ended = true;
+                var endBehavior = this.item.endBehavior;
+                if (endBehavior === EndBehavior.freeze) {
+                    this.frozen = true;
+                }
+            }
+        } else if (this.item.endBehavior !== EndBehavior.restart) {
+            if (EndBehavior.destroy === this.item.endBehavior) {
+                var node = link.last;
+                if (node && node.content[0] < this.time) {
+                    this.destroyed = true;
                 }
             }
-            updateTrail();
         }
+        updateTrail();
     };
     _proto.drawStencilMask = function drawStencilMask(renderer) {
         if (!this.isActiveAndEnabled) {
@@ -25594,7 +25642,6 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         _this = MaskableGraphic.call(this, engine) || this;
         _this.time = 0;
         _this.duration = 1;
-        _this.loop = true;
         /**
    * @internal
   */ _this.splits = singleSplits;
@@ -25609,11 +25656,15 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         var _this = this;
         var time = this.time;
         var duration = this.duration;
-        if (time > duration && this.loop) {
+        var textureAnimation = this.textureSheetAnimation;
+        var _textureAnimation_loop;
+        // TODO: Update textureAnimation spec.
+        // @ts-expect-error
+        var loop = (_textureAnimation_loop = textureAnimation == null ? void 0 : textureAnimation.loop) != null ? _textureAnimation_loop : true;
+        if (time > duration && loop) {
             time = time % duration;
         }
         var life = Math.min(Math.max(time / duration, 0.0), 1.0);
-        var ta = this.textureSheetAnimation;
         var video = this.renderer.texture.source.video;
         if (video) {
             if (time === 0) {
@@ -25625,9 +25676,9 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
             }
             this.renderer.texture.uploadCurrentVideoFrame();
         }
-        if (ta) {
+        if (textureAnimation) {
             var _this_material_getVector4;
-            var total = ta.total || ta.row * ta.col;
+            var total = textureAnimation.total || textureAnimation.row * textureAnimation.col;
             var texRectX = 0;
             var texRectY = 0;
             var texRectW = 1;
@@ -25648,20 +25699,20 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
             }
             var dx, dy;
             if (flip) {
-                dx = 1 / ta.row * texRectW;
-                dy = 1 / ta.col * texRectH;
+                dx = 1 / textureAnimation.row * texRectW;
+                dy = 1 / textureAnimation.col * texRectH;
             } else {
-                dx = 1 / ta.col * texRectW;
-                dy = 1 / ta.row * texRectH;
+                dx = 1 / textureAnimation.col * texRectW;
+                dy = 1 / textureAnimation.row * texRectH;
             }
             var texOffset;
-            if (ta.animate) {
+            if (textureAnimation.animate) {
                 var frameIndex = Math.round(life * (total - 1));
-                var yIndex = Math.floor(frameIndex / ta.col);
-                var xIndex = frameIndex - yIndex * ta.col;
+                var yIndex = Math.floor(frameIndex / textureAnimation.col);
+                var xIndex = frameIndex - yIndex * textureAnimation.col;
                 texOffset = flip ? [
                     dx * yIndex,
-                    dy * (ta.col - xIndex)
+                    dy * (textureAnimation.col - xIndex)
                 ] : [
                     dx * xIndex,
                     dy * (1 + yIndex)
@@ -25849,8 +25900,6 @@ exports.SpriteComponent = /*#__PURE__*/ function(MaskableGraphic) {
         var _data_duration;
         //@ts-expect-error
         this.duration = (_data_duration = data.duration) != null ? _data_duration : this.item.duration;
-        var _data_loop;
-        this.loop = (_data_loop = data.loop) != null ? _data_loop : true;
     };
     return SpriteComponent;
 }(MaskableGraphic);
@@ -25858,21 +25907,21 @@ exports.SpriteComponent = __decorate([
     effectsClass(DataType.SpriteComponent)
 ], exports.SpriteComponent);
 
-var ParticleLoader = /*#__PURE__*/ function(AbstractPlugin) {
-    _inherits(ParticleLoader, AbstractPlugin);
+var ParticleLoader = /*#__PURE__*/ function(Plugin) {
+    _inherits(ParticleLoader, Plugin);
     function ParticleLoader() {
-        return AbstractPlugin.apply(this, arguments);
+        return Plugin.apply(this, arguments);
     }
     return ParticleLoader;
-}(AbstractPlugin);
+}(_wrap_native_super(Plugin));
 
-var CalculateLoader = /*#__PURE__*/ function(AbstractPlugin) {
-    _inherits(CalculateLoader, AbstractPlugin);
+var CalculateLoader = /*#__PURE__*/ function(Plugin) {
+    _inherits(CalculateLoader, Plugin);
     function CalculateLoader() {
-        return AbstractPlugin.apply(this, arguments);
+        return Plugin.apply(this, arguments);
     }
     return CalculateLoader;
-}(AbstractPlugin);
+}(_wrap_native_super(Plugin));
 
 // Based on:
 /**
@@ -28974,6 +29023,12 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
         /**
    * 每一行文本的最大宽度
    */ _this.maxLineWidth = 0;
+        /**
+   * 初始文本宽度，用于计算缩放比例
+   */ _this.baseTextWidth = 0;
+        /**
+   * 初始 `transform.size.x`，用于按比例更新显示宽度
+   */ _this.baseScaleX = 1;
         _this.name = "MText" + seed$1++;
         // 初始化canvas资源
         _this.canvas = canvasPool.getCanvas();
@@ -28999,10 +29054,11 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
                 text: "默认文本",
                 fontFamily: "AlibabaSans-BoldItalic",
                 fontSize: 40,
+                // 统一使用 0-1 颜色值
                 textColor: [
-                    255,
-                    255,
-                    255,
+                    1,
+                    1,
+                    1,
                     1
                 ],
                 fontWeight: TextWeight.normal,
@@ -29039,6 +29095,10 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
         // TextComponentBase
         this.updateWithOptions(options);
         this.renderText(options);
+        // 记录初始的 textWidth 和 x 缩放，用于后续按比例更新显示宽度
+        // 添加兜底值 1 防止除 0
+        this.baseTextWidth = options.textWidth || this.textLayout.width || 1;
+        this.baseScaleX = this.item.transform.size.x;
         // 恢复默认颜色
         this.material.setColor("_Color", new Color(1, 1, 1, 1));
     };
@@ -29237,9 +29297,9 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
             if (style.isOutlined) {
                 _this.setupOutline();
             }
-            // 文本颜色 - 直接使用 vec4 原值，不乘以 255
+            // textColor 统一是 0-1，写入 canvas 时乘 255
             var _style_textColor = style.textColor, r = _style_textColor[0], g = _style_textColor[1], b = _style_textColor[2], a = _style_textColor[3];
-            context.fillStyle = "rgba(" + r + ", " + g + ", " + b + ", " + a + ")";
+            context.fillStyle = "rgba(" + r * 255 + ", " + g * 255 + ", " + b * 255 + ", " + a + ")";
             var charsInfo = [];
             var x = 0;
             var y = layout.getOffsetY(style, _this.lineCount, lineHeight, fontSize);
@@ -29301,6 +29361,46 @@ exports.TextComponent = /*#__PURE__*/ function(MaskableGraphic) {
         layout.autoWidth = normalizedValue;
         this.isDirty = true;
     };
+    /**
+   * 设置文本框宽度
+   * 手动设置宽度时会自动关闭 `autoWidth`
+   * 同时会按比例更新 `transform.size.x`，让 UI 框宽度也跟着变化
+   * @param value - 文本框宽度
+   */ _proto.setTextWidth = function setTextWidth(value) {
+        var width = Math.max(0, Number(value) || 0);
+        var layout = this.textLayout;
+        // 宽度没变且已是非 autoWidth 模式,直接返回
+        if (layout.width === width && layout.autoWidth === false) {
+            return;
+        }
+        // 手动设置宽度时关闭 autoWidth
+        layout.autoWidth = false;
+        layout.width = width;
+        // 按当前 overflow 模式重新计算行数和 maxLineWidth
+        this.lineCount = this.getLineCount(this.text || "");
+        this.isDirty = true;
+        // 同步更新外层显示宽度(按比例缩放 transform)
+        // 这样 UI 框的视觉宽度也会跟着文本宽度变化
+        if (this.baseTextWidth > 0) {
+            var scale = width / this.baseTextWidth;
+            this.item.transform.size.x = this.baseScaleX * scale;
+        }
+    };
+    /**
+   * 设置文本框高度
+   * @param value - 文本框高度
+   */ _proto.setTextHeight = function setTextHeight(value) {
+        var height = Math.max(0, Number(value) || 0);
+        if (height === 0) {
+            return;
+        }
+        var layout = this.textLayout;
+        if (layout.height === height) {
+            return;
+        }
+        layout.height = height;
+        this.isDirty = true;
+    };
     _proto.setFontSize = function setFontSize(value) {
         if (this.textStyle.fontSize === value) {
             return;
@@ -29368,13 +29468,13 @@ applyMixins(exports.TextComponent, [
 ]);
 
 // TODO: 注册必须用
-var TextLoader = /*#__PURE__*/ function(AbstractPlugin) {
-    _inherits(TextLoader, AbstractPlugin);
+var TextLoader = /*#__PURE__*/ function(Plugin) {
+    _inherits(TextLoader, Plugin);
     function TextLoader() {
-        return AbstractPlugin.apply(this, arguments);
+        return Plugin.apply(this, arguments);
     }
     return TextLoader;
-}(AbstractPlugin);
+}(_wrap_native_super(Plugin));
 
 var Asset = /*#__PURE__*/ function(EffectsObject) {
     _inherits(Asset, EffectsObject);
@@ -30431,6 +30531,10 @@ function version35Migration(json) {
             if (component.dataType === DataType.TextComponent || component.dataType === DataType.RichTextComponent && component.options) {
                 ensureTextVerticalAlign(component.options);
             }
+            // 处理文本颜色从 0-255 到 0-1 的转换
+            if (component.dataType === DataType.TextComponent) {
+                convertTextColorTo01(component.options);
+            }
         }
     }
     //@ts-expect-error
@@ -30450,6 +30554,22 @@ function version35Migration(json) {
         options.TextVerticalAlign = options.textBaseline;
     }
 }
+/**
+ * 将文本颜色从 0-255 转换到 0-1
+ */ function convertTextColorTo01(options) {
+    if (!options || !options.textColor) {
+        return;
+    }
+    var textColor = options.textColor;
+    var _textColor_;
+    // 将 RGB 从 0-255 转换到 0-1（alpha 通道已经是 0-1，不需要转换）
+    options.textColor = [
+        textColor[0] / 255.0,
+        textColor[1] / 255.0,
+        textColor[2] / 255.0,
+        (_textColor_ = textColor[3]) != null ? _textColor_ : 1
+    ];
+}
 /**
  * 根据形状获取形状几何体数据
  * @param shape - 形状
@@ -31372,7 +31492,7 @@ function getStandardSpriteContent(sprite, transform) {
     return ret;
 }
 
-var version$1 = "2.8.0-alpha.3";
+var version$1 = "2.8.0-alpha.4";
 var v0 = /^(\d+)\.(\d+)\.(\d+)(-(\w+)\.\d+)?$/;
 var standardVersion = /^(\d+)\.(\d+)$/;
 var reverseParticle = false;
@@ -32012,8 +32132,8 @@ var seed = 1;
                                 };
                                 return [
                                     4,
-                                    hookTimeInfo("plugin:processAssets", function() {
-                                        return _this.processPluginAssets(scene);
+                                    hookTimeInfo("plugin:onAssetsLoadStart", function() {
+                                        return _this.onPluginSceneLoadStart(scene);
                                     })
                                 ];
                             case 6:
@@ -32301,7 +32421,7 @@ var seed = 1;
             });
         })();
     };
-    _proto.processPluginAssets = function processPluginAssets(scene) {
+    _proto.onPluginSceneLoadStart = function onPluginSceneLoadStart(scene) {
         var _this = this;
         return _async_to_generator(function() {
             return __generator(this, function(_state) {
@@ -32309,7 +32429,7 @@ var seed = 1;
                     case 0:
                         return [
                             4,
-                            PluginSystem.processAssets(scene, _this.options)
+                            PluginSystem.onAssetsLoadStart(scene, _this.options)
                         ];
                     case 1:
                         _state.sent();
@@ -35010,8 +35130,8 @@ var SceneLoader = /*#__PURE__*/ function() {
                     case 1:
                         loadedScene = _state.sent();
                         engine.clearResources();
-                        // 触发插件系统 pluginSystem 的回调 prepareResource
-                        PluginSystem.loadResources(loadedScene, assetManager.options, engine);
+                        // 触发插件系统 pluginSystem 的回调 onAssetsLoadFinish
+                        PluginSystem.onAssetsLoadFinish(loadedScene, assetManager.options, engine);
                         engine.assetService.prepareAssets(loadedScene, loadedScene.assets);
                         engine.assetService.updateTextVariables(loadedScene, options.variables);
                         engine.assetService.initializeTexture(loadedScene);
@@ -35073,10 +35193,9 @@ registerPlugin("sprite", SpriteLoader);
 registerPlugin("particle", ParticleLoader);
 registerPlugin("cal", CalculateLoader);
 registerPlugin("interact", InteractLoader);
-var version = "2.8.0-alpha.3";
+var version = "2.8.0-alpha.4";
 logger.info("Core version: " + version + ".");
 
-exports.AbstractPlugin = AbstractPlugin;
 exports.ActivationMixerPlayable = ActivationMixerPlayable;
 exports.ActivationPlayable = ActivationPlayable;
 exports.AndNode = AndNode;
@@ -35176,6 +35295,7 @@ exports.PathSegments = PathSegments;
 exports.Playable = Playable;
 exports.PlayableAsset = PlayableAsset;
 exports.PlayableOutput = PlayableOutput;
+exports.Plugin = Plugin;
 exports.PluginSystem = PluginSystem;
 exports.PointerEventData = PointerEventData;
 exports.PolyStar = PolyStar;