[NPE] Adding gradients support for lifetime (#17449)

- targetStopDuration is now a block input for SystemBlock
- Adds functions to generate gradients from FactorValues
- Introduces a ConversionContext object to make sure that certain blocks
are re-used in the graph instead of being regenerated constantly.

PG to test: #0K3AQ2#3727
PG to test: #H4GGRI

Ratio block group
<img width="1375" height="879" alt="NewRatio"
src="https://github.com/user-attachments/assets/788d1d1d-c197-43d6-9787-4f9a9eb82dde"
/>

Gradients block group
<img width="560" height="668" alt="LifetimeGradients"
src="https://github.com/user-attachments/assets/e8a4d336-c35d-4c08-a78c-5584ac163cfc"
/>

Author: VicenteCartas

packages/dev/core/src/Particles/Node/Blocks/systemBlock.ts

@@ -51,12 +51,6 @@ export class SystemBlock extends NodeParticleBlock {
     @editableInPropertyPage("Manual emit count", PropertyTypeForEdition.Int, "ADVANCED", { embedded: true, notifiers: { rebuild: true }, min: -1 })
     public manualEmitCount = -1;
 
-    /**
-     * Gets or sets the target stop duration for the particle system
-     */
-    @editableInPropertyPage("Target duration", PropertyTypeForEdition.Float, "ADVANCED", { embedded: true, notifiers: { rebuild: true }, min: 0 })
-    public targetStopDuration = 0;
-
     /**
      * Gets or sets the target stop duration for the particle system
      */
@@ -123,6 +117,7 @@ export class SystemBlock extends NodeParticleBlock {
         this.registerInput("onEnd", NodeParticleBlockConnectionPointTypes.System, true);
         this.registerInput("translationPivot", NodeParticleBlockConnectionPointTypes.Vector2, true);
         this.registerInput("textureMask", NodeParticleBlockConnectionPointTypes.Color4, true);
+        this.registerInput("targetStopDuration", NodeParticleBlockConnectionPointTypes.Float, true, 0, 0);
         this.registerOutput("system", NodeParticleBlockConnectionPointTypes.System);
     }
 
@@ -176,6 +171,13 @@ export class SystemBlock extends NodeParticleBlock {
         return this._inputs[5];
     }
 
+    /**
+     * Gets the targetStopDuration input component
+     */
+    public get targetStopDuration(): NodeParticleConnectionPoint {
+        return this._inputs[6];
+    }
+
     /**
      * Gets the system output component
      */
@@ -203,7 +205,7 @@ export class SystemBlock extends NodeParticleBlock {
         particleSystem.preWarmStepOffset = this.preWarmStepOffset;
         particleSystem.blendMode = this.blendMode;
         particleSystem.name = this.name;
-        particleSystem._targetStopDuration = this.targetStopDuration;
+        particleSystem._targetStopDuration = (this.targetStopDuration.getConnectedValue(state) as number) ?? 0;
         particleSystem.startDelay = this.startDelay;
         particleSystem.isBillboardBased = this.isBillboardBased;
         particleSystem.translationPivot = (this.translationPivot.getConnectedValue(state) as Vector2) || Vector2.Zero();
@@ -268,7 +270,6 @@ export class SystemBlock extends NodeParticleBlock {
         serializationObject.isLocal = this.isLocal;
         serializationObject.disposeOnStop = this.disposeOnStop;
         serializationObject.doNoStart = this.doNoStart;
-        serializationObject.targetStopDuration = this.targetStopDuration;
         serializationObject.startDelay = this.startDelay;
 
         return serializationObject;
@@ -292,10 +293,6 @@ export class SystemBlock extends NodeParticleBlock {
             this.blendMode = serializationObject.blendMode;
         }
 
-        if (serializationObject.targetStopDuration !== undefined) {
-            this.targetStopDuration = serializationObject.targetStopDuration;
-        }
-
         if (serializationObject.startDelay !== undefined) {
             this.startDelay = serializationObject.startDelay;
         }

packages/dev/core/src/Particles/Node/nodeParticleSystemSet.helper.ts

@@ -2,7 +2,7 @@ import type { Nullable } from "core/types";
 import type { Color4 } from "core/Maths/math.color";
 import type { Texture } from "core/Materials/Textures/texture";
 import type { Mesh } from "core/Meshes/mesh";
-import type { ColorGradient } from "core/Misc";
+import type { ColorGradient, FactorGradient } from "core/Misc";
 import type { ParticleSystem } from "core/Particles/particleSystem";
 import type { IParticleSystem } from "core/Particles/IParticleSystem";
 import type { BoxParticleEmitter } from "core/Particles/EmitterTypes/boxParticleEmitter";
@@ -42,6 +42,14 @@ import { UpdateColorBlock } from "./Blocks/Update/updateColorBlock";
 import { UpdateDirectionBlock } from "./Blocks/Update/updateDirectionBlock";
 import { UpdatePositionBlock } from "./Blocks/Update/updatePositionBlock";
 
+/** Represents blocks or groups of blocks that can be used in multiple places in the graph, so they are stored in this context to be reused */
+type ConversionContext = {
+    targetStopDurationBlockOutput: NodeParticleConnectionPoint;
+    timeToStopTimeRatioBlockGroupOutput: NodeParticleConnectionPoint;
+};
+
+type RuntimeConversionContext = Partial<ConversionContext>;
+
 /**
  * Converts a ParticleSystem to a NodeParticleSystemSet.
  * @param name The name of the node particle system set.
@@ -59,16 +67,16 @@ export async function ConvertToNodeParticleSystemSetAsync(name: string, particle
     const promises: Promise<void>[] = [];
 
     for (const particleSystem of particleSystemsList) {
-        promises.push(_ExtractDatafromParticleSystemAsync(nodeParticleSystemSet, particleSystem));
+        promises.push(_ExtractDatafromParticleSystemAsync(nodeParticleSystemSet, particleSystem, {}));
     }
 
     await Promise.all(promises);
     return nodeParticleSystemSet;
 }
 
-async function _ExtractDatafromParticleSystemAsync(newSet: NodeParticleSystemSet, oldSystem: ParticleSystem): Promise<void> {
+async function _ExtractDatafromParticleSystemAsync(newSet: NodeParticleSystemSet, oldSystem: ParticleSystem, context: RuntimeConversionContext): Promise<void> {
     // CreateParticle block
-    const createParticleBlock = _CreateCreateParticleBlock(oldSystem);
+    const createParticleBlock = _CreateCreateParticleBlockGroup(oldSystem, context);
 
     // Emitter Shape block
     const shapeBlock = _CreateEmitterShapeBlock(oldSystem);
@@ -82,27 +90,26 @@ async function _ExtractDatafromParticleSystemAsync(newSet: NodeParticleSystemSet
     positionUpdatedParticle.connectTo(colorUpdateBlock.particle);
 
     // System block
-    const newSystem = _CreateSystemBlock(oldSystem);
+    const newSystem = _CreateSystemBlock(oldSystem, context);
     colorUpdateBlock.output.connectTo(newSystem.particle);
 
     // Register
     newSet.systemBlocks.push(newSystem);
 }
 
-function _CreateSystemBlock(oldSystem: ParticleSystem): SystemBlock {
+function _CreateSystemBlock(oldSystem: ParticleSystem, context: RuntimeConversionContext): SystemBlock {
     const newSystem = new SystemBlock(oldSystem.name);
 
     _CreateAndConnectInput("Translation pivot", oldSystem.translationPivot, newSystem.translationPivot);
     _CreateAndConnectInput("Texture mask", oldSystem.textureMask, newSystem.textureMask);
+    const targetStopDurationOutput = _CreateTargetStopDurationInputBlock(oldSystem, context);
+    targetStopDurationOutput.connectTo(newSystem.targetStopDuration);
 
     newSystem.emitRate = oldSystem.emitRate;
     newSystem.manualEmitCount = oldSystem.manualEmitCount;
-
     newSystem.blendMode = oldSystem.blendMode;
     newSystem.capacity = oldSystem.getCapacity();
-    newSystem.targetStopDuration = oldSystem.targetStopDuration;
     newSystem.startDelay = oldSystem.startDelay;
-    newSystem.targetStopDuration = oldSystem.targetStopDuration;
     newSystem.updateSpeed = oldSystem.updateSpeed;
     newSystem.preWarmCycles = oldSystem.preWarmCycles;
     newSystem.preWarmStepOffset = oldSystem.preWarmStepOffset;
@@ -123,10 +130,15 @@ function _CreateSystemBlock(oldSystem: ParticleSystem): SystemBlock {
     return newSystem;
 }
 
-function _CreateCreateParticleBlock(oldSystem: ParticleSystem): CreateParticleBlock {
+// Create Particle Block Group functions
+
+function _CreateCreateParticleBlockGroup(oldSystem: ParticleSystem, context: RuntimeConversionContext): CreateParticleBlock {
     // Create particle
     const createParticleBlock = new CreateParticleBlock("Create Particle");
 
+    // Lifetime
+    _CreateParticleLifetimeBlockGroup(oldSystem, context).connectTo(createParticleBlock.lifeTime);
+
     // Size
     const randomSizeBlock = new ParticleRandomBlock("Random size");
     _CreateAndConnectInput("Min size", oldSystem.minSize, randomSizeBlock.min);
@@ -156,15 +168,28 @@ function _CreateCreateParticleBlock(oldSystem: ParticleSystem): CreateParticleBl
     _CreateAndConnectInput("Max Rotation", oldSystem.maxInitialRotation, randomRotationBlock.max);
     randomRotationBlock.output.connectTo(createParticleBlock.angle);
 
-    // Lifetime
-    const randomLifetimeBlock = new ParticleRandomBlock("Random Lifetime");
-    _CreateAndConnectInput("Min Lifetime", oldSystem.minLifeTime, randomLifetimeBlock.min);
-    _CreateAndConnectInput("Max Lifetime", oldSystem.maxLifeTime, randomLifetimeBlock.max);
-    randomLifetimeBlock.output.connectTo(createParticleBlock.lifeTime);
-
     return createParticleBlock;
 }
 
+/**
+ * Creates the group of blocks that represent the particle lifetime
+ * @param oldSystem The old particle system to migrate
+ * @param context The system migration context
+ * @returns The output of the group of blocks that represent the particle lifetime
+ */
+function _CreateParticleLifetimeBlockGroup(oldSystem: ParticleSystem, context: RuntimeConversionContext): NodeParticleConnectionPoint {
+    if (oldSystem.targetStopDuration && oldSystem._lifeTimeGradients && oldSystem._lifeTimeGradients.length > 0) {
+        context.timeToStopTimeRatioBlockGroupOutput = _CreateTimeToStopTimeRatioBlockGroup(oldSystem, context);
+        const gradientBlockGroupOutput = _CreateGradientBlockGroup(context.timeToStopTimeRatioBlockGroupOutput, oldSystem._lifeTimeGradients);
+        return gradientBlockGroupOutput;
+    } else {
+        const randomLifetimeBlock = new ParticleRandomBlock("Random Lifetime");
+        _CreateAndConnectInput("Min Lifetime", oldSystem.minLifeTime, randomLifetimeBlock.min);
+        _CreateAndConnectInput("Max Lifetime", oldSystem.maxLifeTime, randomLifetimeBlock.max);
+        return randomLifetimeBlock.output;
+    }
+}
+
 function _CreateEmitterShapeBlock(oldSystem: IParticleSystem): IShapeBlock {
     const emitter = oldSystem.particleEmitterType;
     if (!emitter) {
@@ -536,3 +561,110 @@ function _CreateAndConnectSystemSource(systemBlockName: string, systemSource: No
     input.systemSource = systemSource;
     input.output.connectTo(targetToConnectTo);
 }
+
+/**
+ * Creates the target stop duration input block, as it can be shared in multiple places
+ * This block is stored in the context so the same block is shared in the graph
+ * @param oldSystem The old particle system to migrate
+ * @param context The system migration context
+ * @returns
+ */
+function _CreateTargetStopDurationInputBlock(oldSystem: ParticleSystem, context: RuntimeConversionContext): NodeParticleConnectionPoint {
+    // If we have already created the target stop duration input block, return it
+    if (context.targetStopDurationBlockOutput) {
+        return context.targetStopDurationBlockOutput;
+    }
+
+    // Create the target stop duration input block if not already created
+    const targetStopDurationInputBlock = new ParticleInputBlock("Target Stop Duration");
+    targetStopDurationInputBlock.value = oldSystem.targetStopDuration;
+
+    // Save the output in our context to avoid regenerating it again
+    context.targetStopDurationBlockOutput = targetStopDurationInputBlock.output;
+    return context.targetStopDurationBlockOutput;
+}
+
+/**
+ * Create a group of blocks that calculates the ratio between the actual frame and the target stop duration, clamped between 0 and 1.
+ * This is used to simulate the behavior of the old particle system where several particle gradient values are affected by the target stop duration.
+ * This block group is stored in the context so the same group is shared in the graph
+ * @param oldSystem The old particle system to migrate
+ * @param context The system migration context
+ * @returns The ratio block output connection point
+ */
+function _CreateTimeToStopTimeRatioBlockGroup(oldSystem: ParticleSystem, context: RuntimeConversionContext): NodeParticleConnectionPoint {
+    // If we have already generated this group, return it
+    if (context.timeToStopTimeRatioBlockGroupOutput) {
+        return context.timeToStopTimeRatioBlockGroupOutput;
+    }
+
+    context.targetStopDurationBlockOutput = _CreateTargetStopDurationInputBlock(oldSystem, context);
+
+    // Find the ratio between the actual frame and the target stop duration
+    const ratio = new ParticleMathBlock("Frame/Stop Ratio");
+    ratio.operation = ParticleMathBlockOperations.Divide;
+    _CreateAndConnectSystemSource("Actual Frame", NodeParticleSystemSources.Time, ratio.left);
+    context.targetStopDurationBlockOutput.connectTo(ratio.right);
+
+    // Make sure values is >=0
+    const clampMin = new ParticleMathBlock("Clamp Min 0");
+    clampMin.operation = ParticleMathBlockOperations.Max;
+    _CreateAndConnectInput("Zero", 0, clampMin.left);
+    ratio.output.connectTo(clampMin.right);
+
+    // Make sure values is <=1
+    const clampMax = new ParticleMathBlock("Clamp Max 1");
+    clampMax.operation = ParticleMathBlockOperations.Min;
+    _CreateAndConnectInput("One", 1, clampMax.left);
+    clampMin.output.connectTo(clampMax.right);
+
+    // Save the group output in our context to avoid regenerating it again
+    context.timeToStopTimeRatioBlockGroupOutput = clampMax.output;
+    return context.timeToStopTimeRatioBlockGroupOutput;
+}
+
+/**
+ * Creates the blocks that represent a gradient
+ * @param gradientSelector The value that determines which gradient to use
+ * @param gradientValues The list of gradient values
+ * @returns The output connection point of the gradient block
+ */
+function _CreateGradientBlockGroup(gradientSelector: NodeParticleConnectionPoint, gradientValues: Array<FactorGradient>): NodeParticleConnectionPoint {
+    // Create the gradient block and connect the value that controls the gradient selection
+    const gradientBlock = new ParticleGradientBlock("Gradient Block");
+    gradientSelector.connectTo(gradientBlock.gradient);
+
+    // Create the gradient values
+    for (let i = 0; i < gradientValues.length; i++) {
+        const gradientValueBlockGroupOutput = _CreateGradientValueBlockGroup(gradientValues[i], i);
+        gradientValueBlockGroupOutput.connectTo(gradientBlock.inputs[i + 1]);
+    }
+
+    return gradientBlock.output;
+}
+
+/**
+ * Creates the blocks that represent a gradient value
+ * This can be either a single value or a random between two values
+ * @param gradientStep The gradient step data
+ * @param index The index of the gradient step
+ * @returns The output connection point of the gradient value block
+ */
+function _CreateGradientValueBlockGroup(gradientStep: FactorGradient, index: number): NodeParticleConnectionPoint {
+    const gradientValueBlock = new ParticleGradientValueBlock("Gradient Value " + index);
+    gradientValueBlock.reference = gradientStep.gradient;
+
+    if (gradientStep.factor2 !== undefined) {
+        // Create a random between value1 and value2
+        const randomBlock = new ParticleRandomBlock("Random Gradient Value " + index);
+        randomBlock.lockMode = ParticleRandomBlockLocks.PerParticle;
+        _CreateAndConnectInput("Value 1", gradientStep.factor1, randomBlock.min);
+        _CreateAndConnectInput("Value 2", gradientStep.factor2, randomBlock.max);
+        randomBlock.output.connectTo(gradientValueBlock.value);
+    } else {
+        // Single value
+        _CreateAndConnectInput("Value", gradientStep.factor1, gradientValueBlock.value);
+    }
+
+    return gradientValueBlock.output;
+}

packages/dev/core/src/Particles/thinParticleSystem.ts

@@ -754,7 +754,7 @@ export class ThinParticleSystem extends BaseParticleSystem implements IDisposabl
     }
 
     /** @internal */
-    public _emitFromParticle: (particle: Particle) => void = (particle) => {
+    public _emitFromParticle: (particle: Particle) => void = (_particle) => {
         // Do nothing
     };