feat(particle): implement rateOverDistance emission

Cherry-picked from #3011 (e2e parts dropped).

- Wire up EmissionModule.rateOverDistance: each frame accumulates the
  delta of the emitter's world position and emits ratePerUnit × distance
  particles (Unity-aligned).
- Sub-interval distance fragment carried across frames; floor-based
  count instead of subtract-loop to avoid float drift dropping a particle
  at exact boundaries.
- Distribute the N per-frame emissions spatially along
  [lastPos → currentPos] in World simulation space, and interpolate
  emit time the same way so age-driven modules (COL/SOL/FOL) render a
  smooth gradient instead of a uniform block.
- Clamp _emit at the maxParticles budget and return the actual count,
  so a setPosition teleport on a rateOverDistance emitter can't expand
  into millions of no-op iterations.
- Reset baseline + accumulator on stop(StopEmitting*) so a play-after-
  clear re-syncs from the current position.

Includes unit tests covering zero-rate, ratePerUnit × distance,
sub-interval accumulation across frames, static emitter, stop+clear
reset, spatial distribution, per-particle emit-time spacing, and
teleport-induced burst guard.

Author: hhhhkrx

packages/core/src/particle/ParticleGenerator.ts

@@ -236,13 +236,17 @@ export class ParticleGenerator {
       }
     } else {
       this._isPlaying = false;
+      // Invalidate the rateOverDistance baseline so emitter movement during the stop
+      // interval doesn't burst on resume.
       if (stopMode === ParticleStopMode.StopEmittingAndClear) {
         this._clearActiveParticles();
         this._playTime = 0;
 
         this._firstActiveTransformedBoundingBox = this._firstFreeTransformedBoundingBox;
 
         this.emission._reset();
+      } else {
+        this.emission._invalidateDistanceBaseline();
       }
     }
   }
@@ -258,37 +262,41 @@ export class ParticleGenerator {
   /**
    * @internal
    */
-  _emit(playTime: number, count: number): void {
-    const { emission } = this;
-    if (emission.enabled) {
-      const { main } = this;
-      // Wait the existing particles to be retired
-      const notRetireParticleCount = this._getNotRetiredParticleCount();
-      if (notRetireParticleCount >= main.maxParticles) {
-        return;
-      }
-      const position = ParticleGenerator._tempVector30;
-      const direction = ParticleGenerator._tempVector31;
-      const transform = this._renderer.entity.transform;
-      const shape = emission.shape;
-      const positionScale = main._getPositionScale();
-      for (let i = 0; i < count; i++) {
-        if (shape?.enabled) {
-          shape._generatePositionAndDirection(emission._shapeRand, playTime, position, direction);
-          position.multiply(positionScale);
-          direction.normalize().multiply(positionScale);
-        } else {
-          position.set(0, 0, 0);
-          direction.set(0, 0, -1);
-          // Speed is scaled by shape scale in world simulation space
-          // So if no shape and in world simulation space, we shouldn't scale the speed
-          if (main.simulationSpace === ParticleSimulationSpace.Local) {
-            direction.multiply(positionScale);
-          }
+  _emit(playTime: number, count: number, emitWorldPositionOverride?: Vector3): number {
+    const { emission, main } = this;
+    if (!emission.enabled) {
+      return 0;
+    }
+    const budget = main.maxParticles - this._getNotRetiredParticleCount();
+    if (count > budget) {
+      count = budget;
+    }
+    if (count <= 0) {
+      return 0;
+    }
+
+    const position = ParticleGenerator._tempVector30;
+    const direction = ParticleGenerator._tempVector31;
+    const transform = this._renderer.entity.transform;
+    const shape = emission.shape;
+    const positionScale = main._getPositionScale();
+    for (let i = 0; i < count; i++) {
+      if (shape?.enabled) {
+        shape._generatePositionAndDirection(emission._shapeRand, playTime, position, direction);
+        position.multiply(positionScale);
+        direction.normalize().multiply(positionScale);
+      } else {
+        position.set(0, 0, 0);
+        direction.set(0, 0, -1);
+        // Speed is scaled by shape scale in world simulation space
+        // So if no shape and in world simulation space, we shouldn't scale the speed
+        if (main.simulationSpace === ParticleSimulationSpace.Local) {
+          direction.multiply(positionScale);
         }
-        this._addNewParticle(position, direction, transform, playTime);
       }
+      this._addNewParticle(position, direction, transform, playTime, emitWorldPositionOverride);
     }
+    return count;
   }
 
   /**
@@ -832,7 +840,13 @@ export class ParticleGenerator {
     }
   }
 
-  private _addNewParticle(position: Vector3, direction: Vector3, transform: Transform, playTime: number): void {
+  private _addNewParticle(
+    position: Vector3,
+    direction: Vector3,
+    transform: Transform,
+    playTime: number,
+    emitWorldPositionOverride?: Vector3
+  ): void {
     const firstFreeElement = this._firstFreeElement;
     let nextFreeElement = firstFreeElement + 1;
     if (nextFreeElement >= this._currentParticleCount) {
@@ -864,7 +878,7 @@ export class ParticleGenerator {
 
     let pos: Vector3, rot: Quaternion;
     if (main.simulationSpace === ParticleSimulationSpace.World) {
-      pos = transform.worldPosition;
+      pos = emitWorldPositionOverride ?? transform.worldPosition;
       rot = transform.worldRotationQuaternion;
     }
 
@@ -1023,7 +1037,7 @@ export class ParticleGenerator {
 
     // Initialize feedback buffer for this particle
     if (this._useTransformFeedback) {
-      this._addFeedbackParticle(firstFreeElement, position, direction, startSpeed, transform);
+      this._addFeedbackParticle(firstFreeElement, position, direction, startSpeed, transform, pos);
     }
 
     this._firstFreeElement = nextFreeElement;
@@ -1034,15 +1048,16 @@ export class ParticleGenerator {
     shapePosition: Vector3,
     direction: Vector3,
     startSpeed: number,
-    transform: Transform
+    transform: Transform,
+    emitWorldPosition?: Vector3
   ): void {
     let position: Vector3;
     if (this.main.simulationSpace === ParticleSimulationSpace.Local) {
       position = shapePosition;
     } else {
       position = ParticleGenerator._tempVector32;
       Vector3.transformByQuat(shapePosition, transform.worldRotationQuaternion, position);
-      position.add(transform.worldPosition);
+      position.add(emitWorldPosition ?? transform.worldPosition);
     }
 
     this._feedbackSimulator.writeParticleData(

packages/core/src/particle/modules/EmissionModule.ts

@@ -1,7 +1,8 @@
-import { Rand } from "@galacean/engine-math";
+import { MathUtil, Rand, Vector3 } from "@galacean/engine-math";
 import { deepClone, ignoreClone } from "../../clone/CloneManager";
 import { ShaderMacro } from "../../shader/ShaderMacro";
 import { ParticleRandomSubSeeds } from "../enums/ParticleRandomSubSeeds";
+import { ParticleSimulationSpace } from "../enums/ParticleSimulationSpace";
 import { Burst } from "./Burst";
 import { ParticleCompositeCurve } from "./ParticleCompositeCurve";
 import { ParticleGeneratorModule } from "./ParticleGeneratorModule";
@@ -14,6 +15,8 @@ export class EmissionModule extends ParticleGeneratorModule {
   /** @internal */
   static readonly _emissionShapeMacro = ShaderMacro.getByName("RENDERER_EMISSION_SHAPE");
 
+  private static _tempEmitPosition = new Vector3();
+
   /**  The rate of particle emission. */
   @deepClone
   rateOverTime: ParticleCompositeCurve = new ParticleCompositeCurve(10);
@@ -29,6 +32,13 @@ export class EmissionModule extends ParticleGeneratorModule {
   /** @internal */
   _frameRateTime: number = 0;
 
+  @ignoreClone
+  private _distanceAccumulator = 0;
+  @ignoreClone
+  private _lastEmitPosition = new Vector3();
+  @ignoreClone
+  private _hasLastEmitPosition = false;
+
   @deepClone
   private _bursts: Burst[] = [];
 
@@ -130,6 +140,7 @@ export class EmissionModule extends ParticleGeneratorModule {
    */
   _emit(lastPlayTime: number, playTime: number): void {
     this._emitByRateOverTime(playTime);
+    this._emitByRateOverDistance(lastPlayTime, playTime);
     this._emitByBurst(lastPlayTime, playTime);
   }
 
@@ -147,6 +158,15 @@ export class EmissionModule extends ParticleGeneratorModule {
   _reset(): void {
     this._frameRateTime = 0;
     this._currentBurstIndex = 0;
+    this._invalidateDistanceBaseline();
+  }
+
+  /**
+   * @internal
+   */
+  _invalidateDistanceBaseline(): void {
+    this._hasLastEmitPosition = false;
+    this._distanceAccumulator = 0;
   }
 
   /**
@@ -171,6 +191,65 @@ export class EmissionModule extends ParticleGeneratorModule {
     }
   }
 
+  private _emitByRateOverDistance(lastPlayTime: number, playTime: number): void {
+    const ratePerUnit = this.rateOverDistance.evaluate(undefined, undefined);
+    const generator = this._generator;
+
+    if (ratePerUnit <= 0) {
+      this._invalidateDistanceBaseline();
+      return;
+    }
+    if (!this._hasLastEmitPosition) {
+      this._lastEmitPosition.copyFrom(generator._renderer.entity.transform.worldPosition);
+      this._hasLastEmitPosition = true;
+      return;
+    }
+
+    const lastPos = this._lastEmitPosition;
+    const currentPos = generator._renderer.entity.transform.worldPosition;
+    const dx = currentPos.x - lastPos.x;
+    const dy = currentPos.y - lastPos.y;
+    const dz = currentPos.z - lastPos.z;
+    const moveLength = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    this._distanceAccumulator += moveLength;
+
+    const emitInterval = 1.0 / ratePerUnit;
+    // `+ zeroTolerance` absorbs float divide error so an exact `N*interval` accumulator doesn't drop 1
+    const count = Math.floor(this._distanceAccumulator / emitInterval + MathUtil.zeroTolerance);
+
+    if (count > 0) {
+      this._distanceAccumulator -= count * emitInterval;
+      // `subFrameAge ∈ [0, 1]`: how far back into the frame a particle was born
+      // (0 = newest at currentPos/playTime, 1 = oldest at lastPos/lastPlayTime).
+      // The initial clamp protects two edges — moveLength ≈ 0 (collapse to frame-end
+      // emit) and a tiny moveLength near the emitInterval edge (would put age > 1).
+      // Local simulation space ignores the position override but still uses emitTime.
+      const isWorld = generator.main.simulationSpace === ParticleSimulationSpace.World;
+      const invMoveLength = moveLength > MathUtil.zeroTolerance ? 1.0 / moveLength : 0;
+      const ageStep = emitInterval * invMoveLength;
+      const dt = playTime - lastPlayTime;
+      let subFrameAge = Math.min(this._distanceAccumulator * invMoveLength, 1.0);
+      const emitPos = EmissionModule._tempEmitPosition;
+      for (let i = 0; i < count; i++) {
+        if (isWorld) {
+          emitPos.set(
+            currentPos.x - dx * subFrameAge,
+            currentPos.y - dy * subFrameAge,
+            currentPos.z - dz * subFrameAge
+          );
+        }
+        if (generator._emit(playTime - dt * subFrameAge, 1, isWorld ? emitPos : undefined) === 0) {
+          // Buffer full: settle the frame's distance budget instead of carrying it over
+          this._distanceAccumulator = 0;
+          break;
+        }
+        subFrameAge += ageStep;
+      }
+    }
+
+    lastPos.copyFrom(currentPos);
+  }
+
   private _emitByBurst(lastPlayTime: number, playTime: number): void {
     const main = this._generator.main;
     const duration = main.duration;