@galacean/engine-core 2.0.0-alpha.36 → 2.0.0-alpha.37

package/dist/main.js

@@ -33892,8 +33892,10 @@ var ParticleStopMode = /*#__PURE__*/ function(ParticleStopMode) {
     /**
    * @internal
    */ _proto._onEnable = function _onEnable() {
-        if (this.generator.main.playOnEnabled) {
-            this.generator.play(false);
+        var generator = this.generator;
+        generator._setTransformFeedback();
+        if (generator.main.playOnEnabled) {
+            generator.play(false);
         }
     };
     /**
@@ -34488,6 +34490,14 @@ ParticleTransformFeedbackSimulator._deltaTimeProperty = ShaderProperty.getByName
     return ParticleGradientMode;
 }({});
 
+/**
+ * Particle sub emitter trigger type.
+ */ var ParticleSubEmitterType = /*#__PURE__*/ function(ParticleSubEmitterType) {
+    /** Triggered when a parent particle is born. */ ParticleSubEmitterType[ParticleSubEmitterType["Birth"] = 0] = "Birth";
+    /** Triggered when a parent particle dies (lifetime expired). */ ParticleSubEmitterType[ParticleSubEmitterType["Death"] = 1] = "Death";
+    return ParticleSubEmitterType;
+}({});
+
 /**
  * @internal
  */ var ParticleRandomSubSeeds = /*#__PURE__*/ function(ParticleRandomSubSeeds) {
@@ -34509,6 +34519,7 @@ ParticleTransformFeedbackSimulator._deltaTimeProperty = ShaderProperty.getByName
     ParticleRandomSubSeeds[ParticleRandomSubSeeds["ForceOverLifetime"] = 3875246972] = "ForceOverLifetime";
     ParticleRandomSubSeeds[ParticleRandomSubSeeds["LimitVelocityOverLifetime"] = 3047300990] = "LimitVelocityOverLifetime";
     ParticleRandomSubSeeds[ParticleRandomSubSeeds["Noise"] = 4105357473] = "Noise";
+    ParticleRandomSubSeeds[ParticleRandomSubSeeds["SubEmitter"] = 2622110509] = "SubEmitter";
     ParticleRandomSubSeeds[ParticleRandomSubSeeds["EmissionRate"] = 2625893077] = "EmissionRate";
     return ParticleRandomSubSeeds;
 }({});
@@ -34578,6 +34589,12 @@ ParticleTransformFeedbackSimulator._deltaTimeProperty = ShaderProperty.getByName
    * @param colorKeys - The color keys
    * @param alphaKeys - The alpha keys
    */ _proto.setKeys = function setKeys(colorKeys, alphaKeys) {
+        if (colorKeys.length > 4) {
+            throw new Error("Gradient can only have 4 color keys");
+        }
+        if (alphaKeys.length > 4) {
+            throw new Error("Gradient can only have 4 alpha keys");
+        }
         var currentColorKeys = this._colorKeys;
         var currentAlphaKeys = this._alphaKeys;
         for(var i = 0, n = currentColorKeys.length; i < n; i++){
@@ -34632,6 +34649,60 @@ ParticleTransformFeedbackSimulator._deltaTimeProperty = ShaderProperty.getByName
         }
         return typeArray;
     };
+    /**
+   * @internal
+   */ _proto._evaluate = function _evaluate(time, out) {
+        var alphaKeys = this._alphaKeys;
+        var alphaCount = alphaKeys.length;
+        if (alphaCount === 0) {
+            out.a = 0;
+        } else {
+            var alphaMaxTime = alphaKeys[alphaCount - 1].time;
+            var alphaT = Math.min(time, alphaMaxTime);
+            for(var i = 0; i < alphaCount; i++){
+                var key = alphaKeys[i];
+                if (alphaT <= key.time) {
+                    if (i === 0) {
+                        out.a = key.alpha;
+                    } else {
+                        var lastKey = alphaKeys[i - 1];
+                        var age = (alphaT - lastKey.time) / (key.time - lastKey.time);
+                        out.a = lastKey.alpha + (key.alpha - lastKey.alpha) * age;
+                    }
+                    break;
+                }
+            }
+        }
+        var colorKeys = this._colorKeys;
+        var colorCount = colorKeys.length;
+        if (colorCount === 0) {
+            out.r = 0;
+            out.g = 0;
+            out.b = 0;
+        } else {
+            var colorMaxTime = colorKeys[colorCount - 1].time;
+            var colorT = Math.min(time, colorMaxTime);
+            for(var i1 = 0; i1 < colorCount; i1++){
+                var key1 = colorKeys[i1];
+                if (colorT <= key1.time) {
+                    var c = key1.color;
+                    if (i1 === 0) {
+                        out.r = c.r;
+                        out.g = c.g;
+                        out.b = c.b;
+                    } else {
+                        var lastKey1 = colorKeys[i1 - 1];
+                        var last = lastKey1.color;
+                        var age1 = (colorT - lastKey1.time) / (key1.time - lastKey1.time);
+                        out.r = last.r + (c.r - last.r) * age1;
+                        out.g = last.g + (c.g - last.g) * age1;
+                        out.b = last.b + (c.b - last.b) * age1;
+                    }
+                    break;
+                }
+            }
+        }
+    };
     _proto._addKey = function _addKey(keys, key) {
         var time = key.time;
         var count = keys.length;
@@ -34811,6 +34882,17 @@ __decorate([
             case ParticleGradientMode.TwoConstants:
                 engineMath.Color.lerp(this.constantMin, this.constantMax, lerpFactor, out);
                 break;
+            case ParticleGradientMode.Gradient:
+                this.gradientMax._evaluate(time, out);
+                break;
+            case ParticleGradientMode.TwoGradients:
+                {
+                    var tmp = ParticleCompositeGradient._tempColor;
+                    this.gradientMin._evaluate(time, tmp);
+                    this.gradientMax._evaluate(time, out);
+                    engineMath.Color.lerp(tmp, out, lerpFactor, out);
+                    break;
+                }
         }
     };
     _create_class(ParticleCompositeGradient, [
@@ -34839,6 +34921,7 @@ __decorate([
     ]);
     return ParticleCompositeGradient;
 }();
+ParticleCompositeGradient._tempColor = new engineMath.Color();
 __decorate([
     deepClone
 ], ParticleCompositeGradient.prototype, "constantMin", void 0);
@@ -35016,6 +35099,31 @@ __decorate([
     };
     /**
    * @internal
+   */ _proto._evaluateCumulative = function _evaluateCumulative(normalizedAge, lerpFactor) {
+        switch(this.mode){
+            case ParticleCurveMode.Constant:
+                return this.constantMax * normalizedAge;
+            case ParticleCurveMode.TwoConstants:
+                return (this.constantMin + (this.constantMax - this.constantMin) * lerpFactor) * normalizedAge;
+            case ParticleCurveMode.Curve:
+                var _this_curveMax;
+                var _this_curveMax__evaluateCumulative;
+                return (_this_curveMax__evaluateCumulative = (_this_curveMax = this.curveMax) == null ? void 0 : _this_curveMax._evaluateCumulative(normalizedAge)) != null ? _this_curveMax__evaluateCumulative : 0;
+            case ParticleCurveMode.TwoCurves:
+                {
+                    var _this_curveMin, _this_curveMax1;
+                    var _this_curveMin__evaluateCumulative;
+                    var min = (_this_curveMin__evaluateCumulative = (_this_curveMin = this.curveMin) == null ? void 0 : _this_curveMin._evaluateCumulative(normalizedAge)) != null ? _this_curveMin__evaluateCumulative : 0;
+                    var _this_curveMax__evaluateCumulative1;
+                    var max = (_this_curveMax__evaluateCumulative1 = (_this_curveMax1 = this.curveMax) == null ? void 0 : _this_curveMax1._evaluateCumulative(normalizedAge)) != null ? _this_curveMax__evaluateCumulative1 : 0;
+                    return min + (max - min) * lerpFactor;
+                }
+            default:
+                return 0;
+        }
+    };
+    /**
+   * @internal
    */ _proto._getMax = function _getMax() {
         switch(this.mode){
             case ParticleCurveMode.Constant:
@@ -36860,6 +36968,34 @@ __decorate([
     };
     /**
    * @internal
+   */ _proto._evaluateCumulative = function _evaluateCumulative(normalizedAge) {
+        var keys = this.keys;
+        var length = keys.length;
+        if (length === 0) return 0;
+        // Single key is a constant curve (matches `_evaluate`); its integral is value × age.
+        if (length === 1) return keys[0].value * normalizedAge;
+        var firstKey = keys[0];
+        if (normalizedAge <= firstKey.time) return firstKey.value * normalizedAge;
+        var cumulative = firstKey.value * firstKey.time;
+        for(var i = 1; i < length; i++){
+            var key = keys[i];
+            var lastKey = keys[i - 1];
+            var segmentTime = key.time - lastKey.time;
+            if (segmentTime <= 0) continue;
+            if (key.time >= normalizedAge) {
+                var offsetTime = normalizedAge - lastKey.time;
+                var t = offsetTime / segmentTime;
+                var currentValue = lastKey.value + (key.value - lastKey.value) * t;
+                cumulative += (lastKey.value + currentValue) * 0.5 * offsetTime;
+                return cumulative;
+            }
+            cumulative += (lastKey.value + key.value) * 0.5 * segmentTime;
+        }
+        var lastKey1 = keys[length - 1];
+        return cumulative + lastKey1.value * (normalizedAge - lastKey1.time);
+    };
+    /**
+   * @internal
    */ _proto._getTypeArray = function _getTypeArray() {
         var typeArray = this._typeArray || (this._typeArray = new Float32Array(4 * 2));
         if (this._typeArrayDirty) {
@@ -37670,6 +37806,221 @@ __decorate([
     deepClone
 ], VelocityOverLifetimeModule.prototype, "_velocityZ", void 0);
 
+/**
+ * Optional parent properties a sub-emitter inherits
+ * Sub particles are always emitted at the parent particle's position; these flags only select
+ * which additional properties are inherited on top of that.
+ */ var ParticleSubEmitterInheritProperty = /*#__PURE__*/ function(ParticleSubEmitterInheritProperty) {
+    /** Inherit no additional properties; sub particles are still emitted at the parent's position. */ ParticleSubEmitterInheritProperty[ParticleSubEmitterInheritProperty["None"] = 0] = "None";
+    /** Multiply parent's current color into the sub particle's start color. */ ParticleSubEmitterInheritProperty[ParticleSubEmitterInheritProperty["Color"] = 1] = "Color";
+    /** Multiply parent's current size into the sub particle's start size. */ ParticleSubEmitterInheritProperty[ParticleSubEmitterInheritProperty["Size"] = 2] = "Size";
+    /** Add parent's current rotation onto the sub particle's start rotation. */ ParticleSubEmitterInheritProperty[ParticleSubEmitterInheritProperty["Rotation"] = 4] = "Rotation";
+    /** Emit the sub particle along the parent's velocity direction. */ ParticleSubEmitterInheritProperty[ParticleSubEmitterInheritProperty["Velocity"] = 8] = "Velocity";
+    return ParticleSubEmitterInheritProperty;
+}({});
+
+/**
+ * One slot in `SubEmittersModule.subEmitters`. Configures which sub-emitter
+ * fires, on which parent event, with what inheritance, probability, and count.
+ */ var SubEmitter = /*#__PURE__*/ function() {
+    function SubEmitter() {
+        /** Bitmask of properties inherited from the parent particle. */ this.inheritProperties = ParticleSubEmitterInheritProperty.None;
+        /** Probability (0..1) the sub-emitter fires for any given event. */ this.emitProbability = 1;
+        /** Number of sub particles emitted per parent event. */ this.emitCount = 1;
+        /** @internal */ this._module = null;
+        this._emitter = null;
+        this._type = ParticleSubEmitterType.Birth;
+    }
+    _create_class(SubEmitter, [
+        {
+            key: "emitter",
+            get: /**
+   * Target particle renderer the sub particles emit into.
+   */ function get() {
+                return this._emitter;
+            },
+            set: function set(value) {
+                var _this__module;
+                if (value === this._emitter) return;
+                (_this__module = this._module) == null ? void 0 : _this__module._validateEmitter(value);
+                this._emitter = value;
+            }
+        },
+        {
+            key: "type",
+            get: /**
+   * Which parent-particle event drives this slot.
+   */ function get() {
+                return this._type;
+            },
+            set: function set(value) {
+                var _this__module;
+                if (value === this._type) return;
+                this._type = value;
+                (_this__module = this._module) == null ? void 0 : _this__module._generator._setTransformFeedback();
+            }
+        }
+    ]);
+    return SubEmitter;
+}();
+__decorate([
+    ignoreClone
+], SubEmitter.prototype, "_module", void 0);
+
+/**
+ * Fires sub-emitters on parent particle lifecycle events (Birth / Death).
+ * @remarks Requires WebGL2; the module stays inactive on WebGL1.
+ */ var SubEmittersModule = /*#__PURE__*/ function(ParticleGeneratorModule) {
+    _inherits(SubEmittersModule, ParticleGeneratorModule);
+    function SubEmittersModule() {
+        var _this;
+        _this = ParticleGeneratorModule.apply(this, arguments) || this, _this._subEmitters = [], _this._probabilityRand = new engineMath.Rand(0, ParticleRandomSubSeeds.SubEmitter);
+        return _this;
+    }
+    var _proto = SubEmittersModule.prototype;
+    /**
+   * Add a sub-emitter slot.
+   * @param emitter - Target particle renderer
+   * @param type - Trigger event (`Birth` / `Death`)
+   * @param inheritProperties - Bitmask of properties inherited from the parent particle
+   * @param emitProbability - Per-event fire probability [0, 1]
+   * @param emitCount - Number of sub particles emitted per parent event
+   */ _proto.addSubEmitter = function addSubEmitter(emitter, type, inheritProperties, emitProbability, emitCount) {
+        if (inheritProperties === void 0) inheritProperties = ParticleSubEmitterInheritProperty.None;
+        if (emitProbability === void 0) emitProbability = 1;
+        if (emitCount === void 0) emitCount = 1;
+        if (SubEmittersModule._wouldCreateCycle(emitter, this._generator)) {
+            throw new Error("Sub-emitter would create a cycle");
+        }
+        var sub = new SubEmitter();
+        sub.emitter = emitter;
+        sub.type = type;
+        sub.inheritProperties = inheritProperties;
+        sub.emitProbability = emitProbability;
+        sub.emitCount = emitCount;
+        sub._module = this;
+        this._subEmitters.push(sub);
+        this._generator._setTransformFeedback();
+    };
+    /**
+   * Remove the sub-emitter at the given index.
+   * @param index - Index of the sub-emitter to remove
+   */ _proto.removeSubEmitterByIndex = function removeSubEmitterByIndex(index) {
+        this._subEmitters.splice(index, 1);
+        this._generator._setTransformFeedback();
+    };
+    /**
+   * @internal
+   */ _proto._dispatchEvent = function _dispatchEvent(type, worldPosition, parentColor, parentSize, parentRotation, worldDirection) {
+        var subEmitters = this.subEmitters;
+        for(var i = 0, n = subEmitters.length; i < n; i++){
+            var sub = subEmitters[i];
+            if (sub.type !== type) continue;
+            var target = sub.emitter;
+            if (target === null || target.destroyed) continue;
+            var count = sub.emitCount;
+            if (count <= 0) continue;
+            if (sub.emitProbability < 1.0 && this._probabilityRand.random() >= sub.emitProbability) {
+                continue;
+            }
+            var inherit = sub.inheritProperties;
+            var colorOverride = (inherit & ParticleSubEmitterInheritProperty.Color) !== 0 ? parentColor : null;
+            var sizeOverride = (inherit & ParticleSubEmitterInheritProperty.Size) !== 0 ? parentSize : null;
+            var rotationOverride = (inherit & ParticleSubEmitterInheritProperty.Rotation) !== 0 ? parentRotation : null;
+            var directionOverride = (inherit & ParticleSubEmitterInheritProperty.Velocity) !== 0 ? worldDirection : null;
+            target.generator._emitFromSubEmitter(count, worldPosition, colorOverride, sizeOverride, rotationOverride, directionOverride);
+        }
+    };
+    /**
+   * @internal
+   */ _proto._resetRandomSeed = function _resetRandomSeed(seed) {
+        this._probabilityRand.reset(seed, ParticleRandomSubSeeds.SubEmitter);
+    };
+    /**
+   * @internal
+   */ _proto._hasSubEmitterOfType = function _hasSubEmitterOfType(type) {
+        if (!this.enabled) return false;
+        var subEmitters = this.subEmitters;
+        for(var i = 0, n = subEmitters.length; i < n; i++){
+            if (subEmitters[i].type === type) return true;
+        }
+        return false;
+    };
+    /**
+   * @internal
+   */ _proto._cloneTo = function _cloneTo(target) {
+        // _module is @ignoreClone, so re-link each cloned slot back to its new module
+        var subEmitters = target._subEmitters;
+        for(var i = 0, n = subEmitters.length; i < n; i++){
+            subEmitters[i]._module = target;
+        }
+    };
+    /**
+   * @internal
+   */ _proto._validateEmitter = function _validateEmitter(emitter) {
+        if (emitter && SubEmittersModule._wouldCreateCycle(emitter, this._generator)) {
+            throw new Error("Sub-emitter would create a cycle");
+        }
+    };
+    SubEmittersModule._wouldCreateCycle = function _wouldCreateCycle(target, root) {
+        var visited = SubEmittersModule._cycleVisited;
+        var stack = SubEmittersModule._cycleStack;
+        visited.clear();
+        stack.length = 0;
+        stack.push(target.generator);
+        var found = false;
+        while(stack.length > 0){
+            var cur = stack.pop();
+            if (cur === root) {
+                found = true;
+                break;
+            }
+            if (visited.has(cur)) continue;
+            visited.add(cur);
+            var slots = cur.subEmitters.subEmitters;
+            for(var i = 0, n = slots.length; i < n; i++){
+                var _slots_i_emitter;
+                var child = (_slots_i_emitter = slots[i].emitter) == null ? void 0 : _slots_i_emitter.generator;
+                if (child && !visited.has(child)) stack.push(child);
+            }
+        }
+        visited.clear();
+        stack.length = 0;
+        return found;
+    };
+    _create_class(SubEmittersModule, [
+        {
+            key: "subEmitters",
+            get: /**
+   * The configured sub-emitters.
+   */ function get() {
+                return this._subEmitters;
+            }
+        },
+        {
+            key: "enabled",
+            get: function get() {
+                return this._enabled && this._generator._renderer.engine._hardwareRenderer.isWebGL2;
+            },
+            set: function set(value) {
+                if (value !== this._enabled) {
+                    this._enabled = value;
+                    this._generator._setTransformFeedback();
+                }
+            }
+        }
+    ]);
+    return SubEmittersModule;
+}(ParticleGeneratorModule);
+SubEmittersModule._cycleVisited = new Set();
+SubEmittersModule._cycleStack = [];
+__decorate([
+    deepClone
+], SubEmittersModule.prototype, "_subEmitters", void 0);
+__decorate([
+    ignoreClone
+], SubEmittersModule.prototype, "_probabilityRand", void 0);
+
 /**
  * Particle Generator.
  */ var ParticleGenerator = /*#__PURE__*/ function() {
@@ -37689,6 +38040,7 @@ __decorate([
         /** @internal */ this._subPrimitive = new SubMesh(0, 0, MeshTopology.Triangles);
         /** @internal */ this._useTransformFeedback = false;
         /** @internal */ this._feedbackBindingIndex = -1;
+        this._feedbackReadback = null;
         this._isPlaying = false;
         this._instanceBufferResized = false;
         this._waitProcessRetiredElementCount = 0;
@@ -37697,6 +38049,13 @@ __decorate([
         this._firstActiveTransformedBoundingBox = 0;
         this._firstFreeTransformedBoundingBox = 0;
         this._playStartDelay = 0;
+        this._eventPos = new engineMath.Vector3();
+        this._eventColor = new engineMath.Color();
+        this._eventSize = new engineMath.Vector3();
+        this._eventRotation = new engineMath.Vector3();
+        this._eventDir = new engineMath.Vector3();
+        this._emitLocalPos = new engineMath.Vector3();
+        this._emitDirection = new engineMath.Vector3();
         this._renderer = renderer;
         var subPrimitive = new SubPrimitive();
         subPrimitive.start = 0;
@@ -37709,6 +38068,7 @@ __decorate([
         this.sizeOverLifetime = new SizeOverLifetimeModule(this);
         this.limitVelocityOverLifetime = new LimitVelocityOverLifetimeModule(this);
         this.noise = new NoiseModule(this);
+        this.subEmitters = new SubEmittersModule(this);
         this.customData = new CustomDataModule(this);
         this.emission.enabled = true;
     }
@@ -38040,11 +38400,12 @@ __decorate([
         this.rotationOverLifetime._resetRandomSeed(seed);
         this.colorOverLifetime._resetRandomSeed(seed);
         this.noise._resetRandomSeed(seed);
+        this.subEmitters._resetRandomSeed(seed);
     };
     /**
    * @internal
    */ _proto._setTransformFeedback = function _setTransformFeedback() {
-        var needed = this.limitVelocityOverLifetime.enabled || this.noise.enabled;
+        var needed = this._renderer.engine._hardwareRenderer.isWebGL2 && (this.limitVelocityOverLifetime.enabled || this.noise.enabled || this.subEmitters._hasSubEmitterOfType(ParticleSubEmitterType.Death));
         if (needed === this._useTransformFeedback) return;
         this._useTransformFeedback = needed;
         // Switching TF mode invalidates all active particle state: feedback buffers and instance
@@ -38205,7 +38566,7 @@ __decorate([
             this._transformedBoundsArray[previousFreeElement * ParticleBufferUtils.boundsFloatStride + boundsTimeOffset] = this._playTime;
         }
     };
-    _proto._addNewParticle = function _addNewParticle(position, direction, transform, playTime, emitWorldPositionOverride) {
+    _proto._addNewParticle = function _addNewParticle(position, direction, transform, playTime, emitWorldPositionOverride, inheritColor, inheritSize, inheritRotation) {
         var firstFreeElement = this._firstFreeElement;
         var nextFreeElement = firstFreeElement + 1;
         if (nextFreeElement >= this._currentParticleCount) {
@@ -38243,7 +38604,7 @@ __decorate([
         // Time
         instanceVertices[offset + ParticleBufferUtils.timeOffset] = playTime;
         // Color
-        var startColor = ParticleGenerator._tempColor0;
+        var startColor = ParticleGenerator._tempColor;
         main.startColor.evaluate(undefined, main._startColorRand.random(), startColor);
         startColor.copyToArray(instanceVertices, offset + 8);
         var duration = this.main.duration;
@@ -38344,11 +38705,79 @@ __decorate([
         if (limitVelocityOverLifetime.enabled && (limitVelocityOverLifetime._isSpeedRandomMode() || limitVelocityOverLifetime._isDragRandomMode())) {
             instanceVertices[offset + 41] = limitVelocityOverLifetime._speedRand.random();
         }
+        // Apply sub-emit inherit: multiply color/size, add rotation
+        if (inheritColor) {
+            instanceVertices[offset + 8] *= inheritColor.r;
+            instanceVertices[offset + 9] *= inheritColor.g;
+            instanceVertices[offset + 10] *= inheritColor.b;
+            instanceVertices[offset + 11] *= inheritColor.a;
+        }
+        if (inheritSize) {
+            instanceVertices[offset + 12] *= inheritSize.x;
+            instanceVertices[offset + 13] *= inheritSize.y;
+            instanceVertices[offset + 14] *= inheritSize.z;
+        }
+        if (inheritRotation) {
+            instanceVertices[offset + 15] += inheritRotation.x;
+            instanceVertices[offset + 16] += inheritRotation.y;
+            instanceVertices[offset + 17] += inheritRotation.z;
+        }
         // Initialize feedback buffer for this particle
         if (this._useTransformFeedback) {
             this._addFeedbackParticle(firstFreeElement, position, direction, startSpeed, transform, pos);
         }
         this._firstFreeElement = nextFreeElement;
+        if (this.subEmitters._hasSubEmitterOfType(ParticleSubEmitterType.Birth)) {
+            this._onParticleBirth(offset, position, direction, transform);
+        }
+    };
+    _proto._onParticleBirth = function _onParticleBirth(offset, position, direction, transform) {
+        var worldRotation = transform.worldRotationQuaternion;
+        var birthPos = this._eventPos;
+        engineMath.Vector3.transformByQuat(position, worldRotation, birthPos);
+        birthPos.add(transform.worldPosition);
+        // Birth emission direction is known directly; Death reads it back from the feedback buffer
+        var worldDirection = this._eventDir;
+        engineMath.Vector3.transformByQuat(direction, worldRotation, worldDirection);
+        var parentColor = this._eventColor;
+        var parentSize = this._eventSize;
+        var parentRotation = this._eventRotation;
+        this._evaluateOverLifetime(offset, 0, parentColor, parentSize, parentRotation);
+        this.subEmitters._dispatchEvent(ParticleSubEmitterType.Birth, birthPos, parentColor, parentSize, parentRotation, worldDirection);
+    };
+    /**
+   * @internal
+   */ _proto._emitFromSubEmitter = function _emitFromSubEmitter(count, worldPosition, inheritColor, inheritSize, inheritRotation, worldDirection) {
+        if (count <= 0) return;
+        var main = this.main;
+        var notRetired = this._getNotRetiredParticleCount();
+        var available = main.maxParticles - notRetired;
+        if (available <= 0) return;
+        if (count > available) count = available;
+        var transform = this._renderer.entity.transform;
+        var emitterWorldPosition = transform.worldPosition, emitterWorldRotation = transform.worldRotationQuaternion;
+        // Convert event world position into local emission space for a_ShapePos
+        var localPos = this._emitLocalPos;
+        engineMath.Vector3.subtract(worldPosition, emitterWorldPosition, localPos);
+        var invRot = ParticleGenerator._tempQuat0;
+        engineMath.Quaternion.invert(emitterWorldRotation, invRot);
+        engineMath.Vector3.transformByQuat(localPos, invRot, localPos);
+        var direction = this._emitDirection;
+        if (worldDirection) {
+            engineMath.Vector3.transformByQuat(worldDirection, invRot, direction);
+            var len = Math.sqrt(direction.x * direction.x + direction.y * direction.y + direction.z * direction.z);
+            if (len > engineMath.MathUtil.zeroTolerance) {
+                direction.set(direction.x / len, direction.y / len, direction.z / len);
+            } else {
+                direction.set(0, 0, -1);
+            }
+        } else {
+            direction.set(0, 0, -1);
+        }
+        var playTime = this._playTime;
+        for(var i = 0; i < count; i++){
+            this._addNewParticle(localPos, direction, transform, playTime, undefined, inheritColor, inheritSize, inheritRotation);
+        }
     };
     _proto._addFeedbackParticle = function _addFeedbackParticle(index, shapePosition, direction, startSpeed, transform, emitWorldPosition) {
         var position;
@@ -38372,7 +38801,10 @@ __decorate([
         var engine = this._renderer.engine;
         var frameCount = engine.time.frameCount;
         var instanceVertices = this._instanceVertices;
-        while(this._firstActiveElement !== this._firstNewElement){
+        var hasDeathSlot = this.subEmitters._hasSubEmitterOfType(ParticleSubEmitterType.Death);
+        var firstNewElement = this._firstNewElement;
+        var feedbackLoaded = false;
+        while(this._firstActiveElement !== firstNewElement){
             var activeParticleOffset = this._firstActiveElement * ParticleBufferUtils.instanceVertexFloatStride;
             var activeParticleTimeOffset = activeParticleOffset + ParticleBufferUtils.timeOffset;
             var particleAge = this._playTime - instanceVertices[activeParticleTimeOffset];
@@ -38380,6 +38812,13 @@ __decorate([
             if (Math.fround(particleAge) < instanceVertices[activeParticleOffset + ParticleBufferUtils.startLifeTimeOffset]) {
                 break;
             }
+            if (hasDeathSlot) {
+                if (this._feedbackSimulator && !feedbackLoaded) {
+                    this._readbackFeedback(this._firstActiveElement, firstNewElement);
+                    feedbackLoaded = true;
+                }
+                this._onParticleDeath(activeParticleOffset);
+            }
             // Store frame count in time offset to free retired particle
             instanceVertices[activeParticleTimeOffset] = frameCount;
             if (++this._firstActiveElement >= this._currentParticleCount) {
@@ -38389,6 +38828,110 @@ __decorate([
             this._waitProcessRetiredElementCount++;
         }
     };
+    _proto._readbackFeedback = function _readbackFeedback(firstActiveElement, firstNewElement) {
+        var stride = ParticleBufferUtils.feedbackVertexStride;
+        var floatStride = stride / 4;
+        var totalFloatCount = this._currentParticleCount * floatStride;
+        var readback = this._feedbackReadback;
+        if (!readback || readback.length < totalFloatCount) {
+            readback = this._feedbackReadback = new Float32Array(totalFloatCount);
+        }
+        var buffer = this._feedbackSimulator.readBinding.buffer;
+        var wrapped = firstActiveElement >= firstNewElement;
+        var firstSegmentEnd = wrapped ? this._currentParticleCount : firstNewElement;
+        buffer.getData(readback, firstActiveElement * stride, firstActiveElement * floatStride, (firstSegmentEnd - firstActiveElement) * floatStride);
+        if (wrapped && firstNewElement > 0) {
+            buffer.getData(readback, 0, 0, firstNewElement * floatStride);
+        }
+    };
+    _proto._onParticleDeath = function _onParticleDeath(particleOffset) {
+        var instanceVertices = this._instanceVertices;
+        var transform = this._renderer.entity.transform;
+        var simSpaceLocal = this.main.simulationSpace === ParticleSimulationSpace.Local;
+        var worldRotation = transform.worldRotationQuaternion;
+        var ringIndex = particleOffset / ParticleBufferUtils.instanceVertexFloatStride;
+        var feedbackData = this._feedbackReadback;
+        var feedbackOffset = ringIndex * ParticleBufferUtils.feedbackVertexStride / 4;
+        var local = this._eventPos;
+        local.set(feedbackData[feedbackOffset], feedbackData[feedbackOffset + 1], feedbackData[feedbackOffset + 2]);
+        if (simSpaceLocal) {
+            engineMath.Vector3.transformByQuat(local, worldRotation, local);
+            local.add(transform.worldPosition);
+        }
+        var worldDirection = this._eventDir;
+        worldDirection.set(feedbackData[feedbackOffset + 3], feedbackData[feedbackOffset + 4], feedbackData[feedbackOffset + 5]);
+        if (simSpaceLocal) {
+            engineMath.Vector3.transformByQuat(worldDirection, worldRotation, worldDirection);
+        } else {
+            var spawnRotation = ParticleGenerator._tempQuat0;
+            spawnRotation.set(instanceVertices[particleOffset + 30], instanceVertices[particleOffset + 31], instanceVertices[particleOffset + 32], instanceVertices[particleOffset + 33]);
+            engineMath.Vector3.transformByQuat(worldDirection, spawnRotation, worldDirection);
+        }
+        // Evaluate at the parent's normalizedAge so children inherit its visible appearance at death.
+        var lifetime = instanceVertices[particleOffset + 3];
+        var bornTime = instanceVertices[particleOffset + 7];
+        var parentColor = this._eventColor;
+        var parentSize = this._eventSize;
+        var parentRotation = this._eventRotation;
+        var normalizedAge = Math.min(Math.max((this._playTime - bornTime) / lifetime, 0), 1);
+        this._evaluateOverLifetime(particleOffset, normalizedAge, parentColor, parentSize, parentRotation);
+        this.subEmitters._dispatchEvent(ParticleSubEmitterType.Death, local, parentColor, parentSize, parentRotation, worldDirection);
+    };
+    _proto._evaluateOverLifetime = function _evaluateOverLifetime(particleOffset, normalizedAge, parentColor, parentSize, parentRotation) {
+        var instanceVertices = this._instanceVertices;
+        var r = instanceVertices[particleOffset + 8];
+        var g = instanceVertices[particleOffset + 9];
+        var b = instanceVertices[particleOffset + 10];
+        var a = instanceVertices[particleOffset + 11];
+        var col = this.colorOverLifetime;
+        if (col.enabled) {
+            var colorFactor = ParticleGenerator._tempColor;
+            col.color.evaluate(normalizedAge, instanceVertices[particleOffset + 20], colorFactor);
+            r *= colorFactor.r;
+            g *= colorFactor.g;
+            b *= colorFactor.b;
+            a *= colorFactor.a;
+        }
+        parentColor.set(r, g, b, a);
+        var sx = instanceVertices[particleOffset + 12];
+        var sy = instanceVertices[particleOffset + 13];
+        var sz = instanceVertices[particleOffset + 14];
+        var sol = this.sizeOverLifetime;
+        // SOL only contributes in Curve / TwoCurves modes (shader gates on RENDERER_SOL_CURVE_MODE)
+        if (sol.enabled && (sol.sizeX.mode === ParticleCurveMode.Curve || sol.sizeX.mode === ParticleCurveMode.TwoCurves)) {
+            var sizeRand = instanceVertices[particleOffset + 21];
+            if (sol.separateAxes) {
+                sx *= sol.sizeX.evaluate(normalizedAge, sizeRand);
+                sy *= sol.sizeY.evaluate(normalizedAge, sizeRand);
+                sz *= sol.sizeZ.evaluate(normalizedAge, sizeRand);
+            } else {
+                var factor = sol.sizeX.evaluate(normalizedAge, sizeRand);
+                sx *= factor;
+                sy *= factor;
+                sz *= factor;
+            }
+        }
+        parentSize.set(sx, sy, sz);
+        var rx = instanceVertices[particleOffset + 15];
+        var ry = instanceVertices[particleOffset + 16];
+        var rz = instanceVertices[particleOffset + 17];
+        var rol = this.rotationOverLifetime;
+        if (rol.enabled) {
+            var rotRand = instanceVertices[particleOffset + 22];
+            var lifetime = instanceVertices[particleOffset + 3];
+            var rolZ = rol.rotationZ._evaluateCumulative(normalizedAge, rotRand) * lifetime;
+            if (rol.separateAxes) {
+                rx += rol.rotationX._evaluateCumulative(normalizedAge, rotRand) * lifetime;
+                ry += rol.rotationY._evaluateCumulative(normalizedAge, rotRand) * lifetime;
+                rz += rolZ;
+            } else if (this.main.startRotation3D) {
+                rz += rolZ;
+            } else {
+                rx += rolZ; // 2D rotation: shader stores the Z angle in a_StartRotation0.x
+            }
+        }
+        parentRotation.set(rx, ry, rz);
+    };
     _proto._freeRetiredParticles = function _freeRetiredParticles() {
         var frameCount = this._renderer.engine.time.frameCount;
         while(this._firstRetiredElement !== this._firstActiveElement){
@@ -38658,7 +39201,8 @@ ParticleGenerator._tempVector30 = new engineMath.Vector3();
 ParticleGenerator._tempVector31 = new engineMath.Vector3();
 ParticleGenerator._tempVector32 = new engineMath.Vector3();
 ParticleGenerator._tempMat = new engineMath.Matrix();
-ParticleGenerator._tempColor0 = new engineMath.Color();
+ParticleGenerator._tempColor = new engineMath.Color();
+ParticleGenerator._tempQuat0 = new engineMath.Quaternion();
 ParticleGenerator._tempParticleRenderers = new Array();
 ParticleGenerator._particleIncreaseCount = 128;
 ParticleGenerator._transformedBoundsIncreaseCount = 16;
@@ -38693,6 +39237,9 @@ __decorate([
 __decorate([
     deepClone
 ], ParticleGenerator.prototype, "noise", void 0);
+__decorate([
+    deepClone
+], ParticleGenerator.prototype, "subEmitters", void 0);
 __decorate([
     deepClone
 ], ParticleGenerator.prototype, "customData", void 0);
@@ -38732,6 +39279,9 @@ __decorate([
 __decorate([
     ignoreClone
 ], ParticleGenerator.prototype, "_feedbackBindingIndex", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_feedbackReadback", void 0);
 __decorate([
     ignoreClone
 ], ParticleGenerator.prototype, "_isPlaying", void 0);
@@ -38762,6 +39312,27 @@ __decorate([
 __decorate([
     ignoreClone
 ], ParticleGenerator.prototype, "_playStartDelay", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_eventPos", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_eventColor", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_eventSize", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_eventRotation", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_eventDir", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_emitLocalPos", void 0);
+__decorate([
+    ignoreClone
+], ParticleGenerator.prototype, "_emitDirection", void 0);
 
 /**
  * Base material for visual effects like particles and trails.
@@ -41075,6 +41646,8 @@ exports.ParticleShapeArcMode = ParticleShapeArcMode;
 exports.ParticleShapeType = ParticleShapeType;
 exports.ParticleSimulationSpace = ParticleSimulationSpace;
 exports.ParticleStopMode = ParticleStopMode;
+exports.ParticleSubEmitterInheritProperty = ParticleSubEmitterInheritProperty;
+exports.ParticleSubEmitterType = ParticleSubEmitterType;
 exports.PhysicsMaterial = PhysicsMaterial;
 exports.PhysicsMaterialCombineMode = PhysicsMaterialCombineMode;
 exports.PhysicsScene = PhysicsScene;
@@ -41164,6 +41737,8 @@ exports.SpriteTileMode = SpriteTileMode;
 exports.StateMachineScript = StateMachineScript;
 exports.StaticCollider = StaticCollider;
 exports.StencilOperation = StencilOperation;
+exports.SubEmitter = SubEmitter;
+exports.SubEmittersModule = SubEmittersModule;
 exports.SubFont = SubFont;
 exports.SubMesh = SubMesh;
 exports.SubPrimitive = SubPrimitive;