[NPE] New blocks and support for size gradients (#17455)

This PR adds:
- A new updateSize block to update the size of a particle.
- A new contextual value to expose the current particle size.
- A new mode for RandomBlock: OncePerParticle that evaluates a random
value once per particle in a system. This is required for gradients that
have two factors, as the random value between the two factors needs to
be used in multiple updates.
- Support for migrating _sizeGradients, both during the creation phase
and the update phase.

PR to test: #0K3AQ2#3730
<img width="2056" height="1204" alt="image"
src="https://github.com/user-attachments/assets/a8ad7751-7a6f-4d34-b29e-1a02cbb43dcd"
/>

Author: VicenteCartas

packages/dev/core/src/Particles/Node/Blocks/Update/basicColorUpdateBlock.ts

@@ -12,7 +12,7 @@ import { _ConnectAtTheEnd } from "core/Particles/Queue/executionQueue";
  */
 export class BasicColorUpdateBlock extends NodeParticleBlock {
     /**
-     * Create a new UpdateScaleBlock
+     * Create a new BasicColorUpdateBlock
      * @param name defines the block name
      */
     public constructor(name: string) {

packages/dev/core/src/Particles/Node/Blocks/Update/basicPositionUpdateBlock.ts

@@ -12,7 +12,7 @@ import { _ConnectAtTheEnd } from "core/Particles/Queue/executionQueue";
  */
 export class BasicPositionUpdateBlock extends NodeParticleBlock {
     /**
-     * Create a new UpdateScaleBlock
+     * Create a new BasicPositionUpdateBlock
      * @param name defines the block name
      */
     public constructor(name: string) {

packages/dev/core/src/Particles/Node/Blocks/Update/updateSizeBlock.ts

@@ -0,0 +1,89 @@
+import type { Particle } from "core/Particles/particle";
+import type { ThinParticleSystem } from "core/Particles/thinParticleSystem";
+import type { NodeParticleConnectionPoint } from "core/Particles/Node/nodeParticleBlockConnectionPoint";
+import type { NodeParticleBuildState } from "core/Particles/Node/nodeParticleBuildState";
+
+import { RegisterClass } from "core/Misc/typeStore";
+import { NodeParticleBlock } from "core/Particles/Node/nodeParticleBlock";
+import { NodeParticleBlockConnectionPointTypes } from "core/Particles/Node/Enums/nodeParticleBlockConnectionPointTypes";
+import { _ConnectAtTheEnd } from "core/Particles/Queue/executionQueue";
+
+/**
+ * Block used to update the size of a particle
+ */
+export class UpdateSizeBlock extends NodeParticleBlock {
+    /**
+     * Create a new UpdateSizeBlock
+     * @param name defines the block name
+     */
+    public constructor(name: string) {
+        super(name);
+
+        this.registerInput("particle", NodeParticleBlockConnectionPointTypes.Particle);
+        this.registerInput("size", NodeParticleBlockConnectionPointTypes.Float);
+        this.registerOutput("output", NodeParticleBlockConnectionPointTypes.Particle);
+    }
+
+    /**
+     * Gets the particle component
+     */
+    public get particle(): NodeParticleConnectionPoint {
+        return this._inputs[0];
+    }
+
+    /**
+     * Gets the size input component
+     */
+    public get size(): NodeParticleConnectionPoint {
+        return this._inputs[1];
+    }
+
+    /**
+     * Gets the output component
+     */
+    public get output(): NodeParticleConnectionPoint {
+        return this._outputs[0];
+    }
+
+    /**
+     * Gets the current class name
+     * @returns the class name
+     */
+    public override getClassName() {
+        return "UpdateSizeBlock";
+    }
+
+    /**
+     * Builds the block
+     * @param state defines the current build state
+     */
+    public override _build(state: NodeParticleBuildState) {
+        const system = this.particle.getConnectedValue(state) as ThinParticleSystem;
+
+        this.output._storedValue = system;
+
+        if (!this.size.isConnected) {
+            return;
+        }
+
+        const processSize = (particle: Particle) => {
+            state.particleContext = particle;
+            state.systemContext = system;
+            particle.size = this.size.getConnectedValue(state) as number;
+        };
+
+        const sizeProcessing = {
+            process: processSize,
+            previousItem: null,
+            nextItem: null,
+        };
+
+        if (system._updateQueueStart) {
+            _ConnectAtTheEnd(sizeProcessing, system._updateQueueStart);
+        } else {
+            system._updateQueueStart = sizeProcessing;
+        }
+    }
+}
+
+RegisterClass("BABYLON.UpdateSizeBlock", UpdateSizeBlock);

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

@@ -8,6 +8,7 @@ export * from "./Update/updateDirectionBlock";
 export * from "./Update/updatePositionBlock";
 export * from "./Update/updateColorBlock";
 export * from "./Update/updateScaleBlock";
+export * from "./Update/updateSizeBlock";
 export * from "./Update/updateAngleBlock";
 export * from "./Update/updateAgeBlock";
 export * from "./Update/basicPositionUpdateBlock";

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

@@ -149,6 +149,7 @@ export class ParticleInputBlock extends NodeParticleBlock {
                 case NodeParticleContextualSources.Lifetime:
                 case NodeParticleContextualSources.Angle:
                 case NodeParticleContextualSources.AgeGradient:
+                case NodeParticleContextualSources.Size:
                     this._type = NodeParticleBlockConnectionPointTypes.Float;
                     break;
                 case NodeParticleContextualSources.SpriteCellEnd:

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

@@ -1,12 +1,13 @@
-import { RegisterClass } from "../../../Misc/typeStore";
-import { Vector2, Vector3 } from "../../../Maths/math.vector";
-import type { Nullable } from "../../../types";
+import type { Nullable } from "core/types";
+import type { NodeParticleConnectionPoint } from "core/Particles/Node/nodeParticleBlockConnectionPoint";
+import type { NodeParticleBuildState } from "core/Particles/Node/nodeParticleBuildState";
+
 import { PropertyTypeForEdition, editableInPropertyPage } from "core/Decorators/nodeDecorator";
-import { NodeParticleBlock } from "../nodeParticleBlock";
-import { NodeParticleBlockConnectionPointTypes } from "../Enums/nodeParticleBlockConnectionPointTypes";
-import type { NodeParticleConnectionPoint } from "../nodeParticleBlockConnectionPoint";
-import type { NodeParticleBuildState } from "../nodeParticleBuildState";
+import { RegisterClass } from "core/Misc/typeStore";
 import { Color4 } from "core/Maths/math.color";
+import { Vector2, Vector3 } from "core/Maths/math.vector";
+import { NodeParticleBlock } from "core/Particles/Node/nodeParticleBlock";
+import { NodeParticleBlockConnectionPointTypes } from "core/Particles/Node/Enums/nodeParticleBlockConnectionPointTypes";
 
 /**
  * Locks supported by the random block
@@ -18,13 +19,17 @@ export enum ParticleRandomBlockLocks {
     PerParticle = 1,
     /** PerSystem */
     PerSystem = 2,
+    /** OncePerParticle */
+    OncePerParticle = 3,
 }
 
 /**
  * Block used to get a random number
  */
 export class ParticleRandomBlock extends NodeParticleBlock {
     private _currentLockId = -2;
+    private _oncePerParticleMap: Map<number, any> = new Map();
+
     /**
      * Gets or sets a value indicating if that block will lock its value for a specific event
      */
@@ -35,6 +40,7 @@ export class ParticleRandomBlock extends NodeParticleBlock {
             { label: "None", value: ParticleRandomBlockLocks.None },
             { label: "Per particle", value: ParticleRandomBlockLocks.PerParticle },
             { label: "Per system", value: ParticleRandomBlockLocks.PerSystem },
+            { label: "Once per particle", value: ParticleRandomBlockLocks.OncePerParticle },
         ],
     })
     public lockMode = ParticleRandomBlockLocks.PerParticle;
@@ -103,6 +109,7 @@ export class ParticleRandomBlock extends NodeParticleBlock {
     public override _build() {
         let func: Nullable<(state: NodeParticleBuildState) => any> = null;
         this._currentLockId = -2;
+        this._oncePerParticleMap.clear();
 
         switch (this.min.type) {
             case NodeParticleBlockConnectionPointTypes.AutoDetect:
@@ -147,23 +154,39 @@ export class ParticleRandomBlock extends NodeParticleBlock {
         }
 
         this.output._storedFunction = (state) => {
-            let lockId = 0;
-
-            switch (this.lockMode) {
-                case ParticleRandomBlockLocks.PerParticle:
-                    lockId = state.particleContext?.id ?? -1;
-                    break;
-                case ParticleRandomBlockLocks.PerSystem:
-                    lockId = state.buildId ?? 0;
-                    break;
-            }
+            if (this.lockMode === ParticleRandomBlockLocks.OncePerParticle) {
+                const particleId = state.particleContext?.id ?? -1;
+                let cachedValue = this._oncePerParticleMap.get(particleId);
+
+                if (!cachedValue) {
+                    cachedValue = func!(state);
+                    this._oncePerParticleMap.set(particleId, cachedValue);
+                }
 
-            if (this._currentLockId !== lockId) {
-                if (this.lockMode !== ParticleRandomBlockLocks.None) {
-                    this._currentLockId = lockId;
+                this.output._storedValue = cachedValue;
+            } else {
+                let lockId = -2;
+
+                switch (this.lockMode) {
+                    case ParticleRandomBlockLocks.PerParticle:
+                        lockId = state.particleContext?.id ?? -1;
+                        break;
+                    case ParticleRandomBlockLocks.PerSystem:
+                        lockId = state.buildId ?? 0;
+                        break;
+                    default:
+                        break;
+                }
+
+                if (this.lockMode === ParticleRandomBlockLocks.None || this._currentLockId !== lockId) {
+                    if (this.lockMode !== ParticleRandomBlockLocks.None) {
+                        this._currentLockId = lockId;
+                    }
+
+                    this.output._storedValue = func!(state);
                 }
-                this.output._storedValue = func!(state);
             }
+
             return this.output._storedValue;
         };
     }

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

@@ -256,6 +256,10 @@ export class SystemBlock extends NodeParticleBlock {
         return particleSystem;
     }
 
+    /**
+     * Serializes the system block
+     * @returns The serialized object
+     */
     public override serialize(): any {
         const serializationObject = super.serialize();
 
@@ -275,6 +279,10 @@ export class SystemBlock extends NodeParticleBlock {
         return serializationObject;
     }
 
+    /**
+     * Deserializes the system block
+     * @param serializationObject The serialized system
+     */
     public override _deserialize(serializationObject: any) {
         super._deserialize(serializationObject);
 

packages/dev/core/src/Particles/Node/Enums/nodeParticleContextualSources.ts

@@ -41,4 +41,6 @@ export enum NodeParticleContextualSources {
     ScaledColorStep = 0x0017,
     /** Local Position Updated */
     LocalPositionUpdated = 0x0018,
+    /** Size */
+    Size = 0x0019,
 }

packages/dev/core/src/Particles/Node/nodeParticleBuildState.ts

@@ -131,6 +131,8 @@ export class NodeParticleBuildState {
                 return this.particleContext.angle;
             case NodeParticleContextualSources.Scale:
                 return this.particleContext.scale;
+            case NodeParticleContextualSources.Size:
+                return this.particleContext.size;
             case NodeParticleContextualSources.AgeGradient:
                 return this.particleContext.age / this.particleContext.lifeTime;
             case NodeParticleContextualSources.SpriteCellEnd: