@aura3d/rendering 1.0.6

package/src/effects/TrailModule.ts

@@ -0,0 +1,72 @@
+import { cloneVector3, type Particle, type Vector3Like } from "./Particle.js";
+import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
+
+export interface TrailPoint {
+  position: Vector3Like;
+  age: number;
+}
+
+export interface TrailModuleOptions {
+  maxPoints?: number;
+  minDistance?: number;
+  lifetime?: number;
+}
+
+function distanceSquared(left: Vector3Like, right: Vector3Like): number {
+  const x = left.x - right.x;
+  const y = left.y - right.y;
+  const z = left.z - right.z;
+  return x * x + y * y + z * z;
+}
+
+export class TrailModule implements ParticleModule {
+  readonly name = "TrailModule";
+  readonly maxPoints: number;
+  readonly minDistance: number;
+  readonly lifetime: number;
+
+  constructor(options: TrailModuleOptions = {}) {
+    this.maxPoints = options.maxPoints ?? 16;
+    this.minDistance = options.minDistance ?? 0.05;
+    this.lifetime = options.lifetime ?? 0.5;
+
+    if (this.maxPoints <= 0 || this.minDistance < 0 || this.lifetime <= 0) {
+      throw new RangeError("TrailModule maxPoints and lifetime must be positive, and minDistance must be non-negative.");
+    }
+  }
+
+  onSpawn(particle: Particle, _context: ParticleUpdateContext): void {
+    particle.userData.trail = [{ position: cloneVector3(particle.position), age: 0 }] satisfies TrailPoint[];
+  }
+
+  afterIntegrate(particle: Particle, context: ParticleUpdateContext): void {
+    const trail = this.getTrail(particle);
+    for (const point of trail) {
+      point.age += context.deltaTime;
+    }
+
+    while (trail.length > 0 && trail[0].age > this.lifetime) {
+      trail.shift();
+    }
+
+    const last = trail[trail.length - 1];
+    if (!last || distanceSquared(last.position, particle.position) >= this.minDistance * this.minDistance) {
+      trail.push({ position: cloneVector3(particle.position), age: 0 });
+    }
+
+    while (trail.length > this.maxPoints) {
+      trail.shift();
+    }
+  }
+
+  getTrail(particle: Particle): TrailPoint[] {
+    const trail = particle.userData.trail;
+    if (!Array.isArray(trail)) {
+      const next: TrailPoint[] = [];
+      particle.userData.trail = next;
+      return next;
+    }
+
+    return trail as TrailPoint[];
+  }
+}

package/src/effects/VelocityModule.ts

@@ -0,0 +1,75 @@
+import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
+import type { Particle, Vector3Like } from "./Particle.js";
+
+export interface VectorKeyframe {
+  time: number;
+  value: Vector3Like;
+}
+
+function validateKeyframes(keyframes: readonly VectorKeyframe[]): void {
+  if (keyframes.length === 0) {
+    throw new RangeError("VelocityModule requires at least one keyframe.");
+  }
+
+  let previous = -Number.POSITIVE_INFINITY;
+  for (const keyframe of keyframes) {
+    if (keyframe.time < 0 || keyframe.time > 1 || keyframe.time < previous) {
+      throw new RangeError("VelocityModule keyframe times must be sorted in the normalized range [0, 1].");
+    }
+    previous = keyframe.time;
+  }
+}
+
+function sampleVectorKeyframes(keyframes: readonly VectorKeyframe[], time: number): Vector3Like {
+  if (time <= keyframes[0].time) {
+    return { ...keyframes[0].value };
+  }
+
+  for (let index = 1; index < keyframes.length; index += 1) {
+    const next = keyframes[index];
+    if (time <= next.time) {
+      const previous = keyframes[index - 1];
+      const span = next.time - previous.time || 1;
+      const alpha = (time - previous.time) / span;
+
+      return {
+        x: previous.value.x + (next.value.x - previous.value.x) * alpha,
+        y: previous.value.y + (next.value.y - previous.value.y) * alpha,
+        z: previous.value.z + (next.value.z - previous.value.z) * alpha,
+      };
+    }
+  }
+
+  return { ...keyframes[keyframes.length - 1].value };
+}
+
+export class VelocityModule implements ParticleModule {
+  readonly name = "VelocityModule";
+  readonly keyframes: readonly VectorKeyframe[];
+  readonly mode: "replace" | "add";
+
+  constructor(keyframes: readonly VectorKeyframe[], mode: "replace" | "add" = "replace") {
+    this.keyframes = keyframes;
+    this.mode = mode;
+    validateKeyframes(keyframes);
+  }
+
+  update(particle: Particle, context: ParticleUpdateContext): void {
+    const velocity = sampleVectorKeyframes(this.keyframes, context.normalizedAge);
+
+    if (this.mode === "add") {
+      particle.velocity.x += velocity.x;
+      particle.velocity.y += velocity.y;
+      particle.velocity.z += velocity.z;
+      return;
+    }
+
+    particle.velocity.x = velocity.x;
+    particle.velocity.y = velocity.y;
+    particle.velocity.z = velocity.z;
+  }
+}
+
+export function constantVelocity(value: Vector3Like, mode: "replace" | "add" = "replace"): VelocityModule {
+  return new VelocityModule([{ time: 0, value }], mode);
+}

package/src/effects/index.ts

@@ -0,0 +1,15 @@
+export * from "./Particle.js";
+export * from "./ParticleEmitter.js";
+export * from "./ParticleModule.js";
+export * from "./VelocityModule.js";
+export * from "./ColorModule.js";
+export * from "./SizeModule.js";
+export * from "./ForceModule.js";
+export * from "./CollisionModule.js";
+export * from "./TrailModule.js";
+export * from "./ParticleRenderer.js";
+export * from "./ParticleRenderPass.js";
+export * from "./GPUParticleBackend.js";
+export * from "./ParticleSystem.js";
+export * from "./ParticleEffectPresets.js";
+export * from "./ParticleDiagnostics.js";