[NPE] Migrating attractors (#17643)

Adds attractors to the migration tool.
Adds some missing docs for the linter.

PG to test: #DEZ79M#72
<img width="1578" height="1254" alt="image"
src="https://github.com/user-attachments/assets/3deea5a4-55c4-4973-8dd0-7901bfff70c3"
/>

Author: VicenteCartas

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

@@ -1,3 +1,4 @@
+import type { Attractor } from "../attractor";
 import type { Color3Gradient, ColorGradient } from "core/Misc";
 import type { Nullable } from "core/types";
 import type { BaseTexture } from "core/Materials/Textures/baseTexture";
@@ -45,6 +46,7 @@ import { SetupSpriteSheetBlock } from "./Blocks/Emitters/setupSpriteSheetBlock";
 import { SphereShapeBlock } from "./Blocks/Emitters/sphereShapeBlock";
 import { UpdateAngleBlock } from "./Blocks/Update/updateAngleBlock";
 import { BasicSpriteUpdateBlock } from "./Blocks/Update/basicSpriteUpdateBlock";
+import { UpdateAttractorBlock } from "./Blocks/Update/updateAttractorBlock";
 import { UpdateColorBlock } from "./Blocks/Update/updateColorBlock";
 import { UpdateDirectionBlock } from "./Blocks/Update/updateDirectionBlock";
 import { UpdateNoiseBlock } from "./Blocks/Update/updateNoiseBlock";
@@ -459,6 +461,10 @@ function _UpdateParticleBlockGroup(inputParticle: NodeParticleConnectionPoint, o
 
     updatedParticle = _UpdateParticlePositionBlockGroup(updatedParticle, oldSystem.isLocal, context);
 
+    if (oldSystem.attractors && oldSystem.attractors.length > 0) {
+        updatedParticle = _UpdateParticleAttractorBlockGroup(updatedParticle, oldSystem.attractors);
+    }
+
     if (oldSystem._limitVelocityGradients && oldSystem._limitVelocityGradients.length > 0 && oldSystem.limitVelocityDamping !== 0) {
         updatedParticle = _UpdateParticleVelocityLimitGradientBlockGroup(updatedParticle, oldSystem._limitVelocityGradients, oldSystem.limitVelocityDamping, context);
     }
@@ -725,6 +731,28 @@ function _UpdateParticlePositionBlockGroup(inputParticle: NodeParticleConnection
     return updatePosition.output;
 }
 
+/**
+ * Creates the group of blocks that represent the particle attractor update
+ * @param inputParticle The input particle to update
+ * @param attractors The attractors (if any)
+ * @returns The output of the group of blocks that represent the particle attractor update
+ */
+function _UpdateParticleAttractorBlockGroup(inputParticle: NodeParticleConnectionPoint, attractors: Attractor[]): NodeParticleConnectionPoint {
+    let outputParticle = inputParticle;
+
+    // Chain update attractor blocks for each attractor
+    for (let i = 0; i < attractors.length; i++) {
+        const attractor = attractors[i];
+        const attractorBlock = new UpdateAttractorBlock(`Attractor Block ${i}`);
+        outputParticle.connectTo(attractorBlock.particle);
+        _CreateAndConnectInput("Attractor Position", attractor.position.clone(), attractorBlock.attractor);
+        _CreateAndConnectInput("Attractor Strength", attractor.strength, attractorBlock.strength);
+        outputParticle = attractorBlock.output;
+    }
+
+    return outputParticle;
+}
+
 /**
  * Creates the group of blocks that represent the particle size update
  * @param inputParticle The input particle to update

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

@@ -889,6 +889,13 @@ export class BaseParticleSystem implements IClipPlanesHolder {
         throw new Error("Method not implemented.");
     }
 
+    /**
+     * Creates a Cone Emitter for the particle system (emits from the cone to the particle position)
+     * @param radius The radius of the cone to emit from
+     * @param angle The base angle of the cone
+     * @param direction1 Particles are emitted between the direction1 and direction2 from within the cone
+     * @param direction2 Particles are emitted between the direction1 and direction2 from within the cone
+     */
     public createDirectedConeEmitter(radius = 1, angle = Math.PI / 4, direction1 = new Vector3(0, 1.0, 0), direction2 = new Vector3(0, 1.0, 0)): ConeDirectedParticleEmitter {
         throw new Error("Method not implemented.");
     }

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

@@ -218,6 +218,10 @@ export class ParticleSystem extends ThinParticleSystem {
         }
     }
 
+    /**
+     * Starts the particle system and begins to emit
+     * @param delay defines the delay in milliseconds before starting the system (this.startDelay by default)
+     */
     public override start(delay = this.startDelay): void {
         if (!this.canStart()) {
             return;
@@ -309,6 +313,14 @@ export class ParticleSystem extends ThinParticleSystem {
         return particleEmitter;
     }
 
+    /**
+     * Creates a Cone Emitter for the particle system (emits from the cone to the particle position)
+     * @param radius The radius of the cone to emit from
+     * @param angle The base angle of the cone
+     * @param direction1 Particles are emitted between the direction1 and direction2 from within the cone
+     * @param direction2 Particles are emitted between the direction1 and direction2 from within the cone
+     * @returns the emitter
+     */
     public override createDirectedConeEmitter(
         radius = 1,
         angle = Math.PI / 4,

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

@@ -495,6 +495,9 @@ export class ThinParticleSystem extends BaseParticleSystem implements IDisposabl
         return this._indexBuffer;
     }
 
+    /**
+     * Gets or sets a texture used to add random noise to particle positions
+     */
     public override get noiseTexture() {
         return this._noiseTexture;
     }
@@ -759,6 +762,10 @@ export class ThinParticleSystem extends BaseParticleSystem implements IDisposabl
         // Do nothing
     };
 
+    /**
+     * Serializes the particle system to a JSON object.
+     * @param _serializeTexture Whether to serialize the texture information
+     */
     serialize(_serializeTexture: boolean) {
         throw new Error("Method not implemented.");
     }
@@ -831,6 +838,9 @@ export class ThinParticleSystem extends BaseParticleSystem implements IDisposabl
         }
     }
 
+    /**
+     * The amount of time the particle system is running (depends of the overall update speed).
+     */
     public override get targetStopDuration(): number {
         return this._targetStopDuration;
     }
@@ -1571,7 +1581,6 @@ export class ThinParticleSystem extends BaseParticleSystem implements IDisposabl
      */
     public start(delay = this.startDelay): void {
         if (!this.targetStopDuration && this._hasTargetStopDurationDependantGradient()) {
-            // eslint-disable-next-line no-throw-literal
             throw "Particle system started with a targetStopDuration dependant gradient (eg. startSizeGradients) but no targetStopDuration set";
         }
         if (delay) {

packages/tools/nodeParticleEditor/src/graphSystem/registerToDisplayLedger.ts

@@ -11,6 +11,9 @@ import { TeleportInDisplayManager } from "./display/teleportInDisplayManager";
 import { ConditionDisplayManager } from "./display/conditionDisplayManager";
 import { TriggerDisplayManager } from "./display/triggerDisplayManager";
 
+/**
+ * Registers all display managers to the display ledger
+ */
 export const RegisterToDisplayManagers = () => {
     DisplayLedger.RegisteredControls["ParticleInputBlock"] = InputDisplayManager;
     DisplayLedger.RegisteredControls["ParticleTextureSourceBlock"] = TextureDisplayManager;
@@ -36,6 +39,7 @@ export const RegisterToDisplayManagers = () => {
     DisplayLedger.RegisteredControls["BasicPositionUpdateBlock"] = UpdateDisplayManager;
     DisplayLedger.RegisteredControls["BasicSpriteUpdateBlock"] = UpdateDisplayManager;
     DisplayLedger.RegisteredControls["BasicColorUpdateBlock"] = UpdateDisplayManager;
+    DisplayLedger.RegisteredControls["UpdateAttractorBlock"] = UpdateDisplayManager;
     DisplayLedger.RegisteredControls["UpdateFlowMapBlock"] = UpdateDisplayManager;
     DisplayLedger.RegisteredControls["UpdateNoiseBlock"] = UpdateDisplayManager;
     DisplayLedger.RegisteredControls["UpdateRemapBlock"] = UpdateDisplayManager;