@directivegames/genesys.js 3.1.24

package/src/components/visual/ParticleEmitterComponent.ts

@@ -0,0 +1,628 @@
+/**
+ * ParticleEmitterComponent spawns and animates simple particles in the scene.
+ *
+ * @deprecated This component is deprecated. For new projects, consider VFXComponent which uses
+ * the wawa-vfx-vanilla particle system with more features and better performance. Note that
+ * VFXComponent is not a drop-in replacement - it uses a different API (JSON-based definitions)
+ * and feature set. ParticleEmitterComponent will continue to work for existing games.
+ *
+ * For new VFX work:
+ * - Use VFXComponent with JSON definitions (see assets/dev/vfx/fire-example.json)
+ * - Use GlobalParticleManager.spawnVFX() for ad-hoc effects
+ * - See wawa-vfx-vanilla documentation for advanced features
+ *
+ * Using THREE.Points under the hood, it supports several emission shapes and
+ * optional textures. Particles have configurable lifetime, speed, color, and can
+ * emit continuously or in bursts. The component updates particle positions each
+ * tick and exposes hooks for custom emission rates or external texture loading.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Set `particleTextureUrl` or `particleTexture` to give particles a visual
+ *   style.
+ * - Choose an `EmissionShape` and tune emitter options for the desired effect.
+ * - Call `emitParticles` manually for one-shot bursts if `emitContinuously` is
+ *   false.
+ */
+import * as THREE from 'three';
+
+import { UrlTexture } from '../../render/Texture.js';
+import { EngineClass } from '../../systems/ClassRegistry.js';
+import { SceneComponent } from '../SceneComponent.js';
+
+import type { EditorClassMeta } from '../../utils/EditorClassMeta.js';
+import type { SceneComponentOptions } from '../SceneComponent.js';
+
+
+/**
+ * @deprecated Use VFXComponent instead
+ */
+export enum EmissionShape {
+  Sphere = 'sphere',    // Emit in all directions (default)
+  Cone = 'cone',        // Emit within a cone
+  Disc = 'disc',        // Emit within a flat circular area
+  Box = 'box'           // Emit within a box-shaped area
+}
+
+/**
+ * @deprecated Use VFXComponentOptions instead
+ */
+export interface ParticleEmitterComponentOptions extends SceneComponentOptions {
+  particleCount: number;
+  particleSize: number;
+  particleColor: THREE.Color;
+  particleSpeed: number;
+  particleLifetime: number;
+  emitterPosition?: THREE.Vector3;
+  emitterRotation?: THREE.Euler;
+  emitterRate?: number;
+  emitContinuously?: boolean;
+
+  // Emission direction and shape options
+  emissionDirection?: THREE.Vector3;        // Direction of emission (default is random in all directions)
+  emissionShape?: EmissionShape;            // Shape of the emission area
+  emissionAngle?: number;                   // For cone emission, the angle of the cone in degrees
+  emissionRadius?: number;                  // For disc or cone base radius
+  emissionDimensions?: THREE.Vector3;       // For box emission, the dimensions of the box
+
+  // Texture options
+  particleTexture?: THREE.Texture;          // Texture to use for particles
+  particleTextureUrl?: string;              // URL to load texture from
+  particleAlphaTest?: number;               // Alpha test value for the texture
+  particleAlphaMap?: THREE.Texture;         // Alpha map for particles
+}
+
+@EngineClass('ParticleEmitterComponent')
+export class ParticleEmitterComponent extends SceneComponent<ParticleEmitterComponentOptions> {
+  private particles: THREE.Points | null = null;
+  private particleSystem: THREE.BufferGeometry | null = null;
+  private particleMaterial: THREE.PointsMaterial | null = null;
+
+  private particlePositions: Float32Array | null = null;
+  private particleVelocities: Float32Array | null = null;
+  private particleLifetimes: Float32Array | null = null;
+
+  private positionAttribute: THREE.BufferAttribute | null = null;
+  private sizeAttribute: THREE.BufferAttribute | null = null;
+
+  private timeAccumulator: number = 0;
+  private hasEmittedOnce: boolean = false;
+
+  // Default emission direction is up
+  private emissionDirection: THREE.Vector3 = new THREE.Vector3(0, 1, 0);
+
+  // For texture loading
+  private particleTexture: THREE.Texture | null = null;
+
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    ...SceneComponent.EDITOR_CLASS_META,
+    emissionShape: { select: Object.values(EmissionShape) },
+  } as const;
+
+  static override get DEFAULT_OPTIONS(): ParticleEmitterComponentOptions {
+    return {
+      ...SceneComponent.DEFAULT_OPTIONS,
+      particleCount: 100,
+      particleSize: 1,
+      particleColor: new THREE.Color(1, 1, 1),
+      particleSpeed: 1,
+      particleLifetime: 1,
+      emitterRate: 10,
+      emitContinuously: true,
+      emissionShape: EmissionShape.Sphere,
+      emissionDirection: new THREE.Vector3(0, 1, 0),
+      emissionAngle: 30,
+      emissionRadius: 1,
+      emissionDimensions: new THREE.Vector3(1, 1, 1),
+      particleAlphaTest: 0.1,
+      particleTexture: undefined,
+      particleTextureUrl: undefined,
+      particleAlphaMap: undefined
+    };
+  }
+
+  constructor(options: ParticleEmitterComponentOptions) {
+    super(options);
+
+    // Initialize emission direction if provided
+    if (options.emissionDirection) {
+      this.emissionDirection = options.emissionDirection.clone().normalize();
+    }
+
+    // Handle texture loading before initializing the particle system
+    this.loadTextures();
+    this.initializeParticleSystem();
+  }
+
+  /**
+   * Load any textures needed for the particle system
+   */
+  private loadTextures(): void {
+    // If a texture URL is provided, load it
+    if (this.options.particleTextureUrl) {
+      try {
+        this.particleTexture = new UrlTexture({ url: this.options.particleTextureUrl });
+        this.options.particleTexture = this.particleTexture;
+      } catch (error) {
+        console.error('Failed to load particle texture:', error);
+      }
+    } else if (this.options.particleTexture) {
+      // Use provided texture directly
+      this.particleTexture = this.options.particleTexture;
+    }
+  }
+
+  private initializeParticleSystem(): void {
+    const particleCount = this.options.particleCount;
+
+    // Create geometry for particles
+    this.particleSystem = new THREE.BufferGeometry();
+
+    // Create arrays for particle data
+    this.particlePositions = new Float32Array(particleCount * 3);
+    this.particleVelocities = new Float32Array(particleCount * 3);
+    this.particleLifetimes = new Float32Array(particleCount);
+
+    // Initialize particle data
+    for (let i = 0; i < particleCount; i++) {
+      // Set all particles to inactive initially
+      this.particleLifetimes[i] = 0;
+    }
+
+    // Create buffer attributes
+    this.positionAttribute = new THREE.BufferAttribute(this.particlePositions, 3);
+    this.particleSystem.setAttribute('position', this.positionAttribute);
+
+    const sizes = new Float32Array(particleCount);
+    for (let i = 0; i < particleCount; i++) {
+      sizes[i] = this.options.particleSize;
+    }
+    this.sizeAttribute = new THREE.BufferAttribute(sizes, 1);
+    this.particleSystem.setAttribute('size', this.sizeAttribute);
+
+    // Create material with texture support
+    this.createParticleMaterial();
+
+    // Create the particle system
+    this.particles = new THREE.Points(this.particleSystem, this.particleMaterial!);
+    this.add(this.particles);
+
+    // Set initial position from options
+    if (this.options.emitterPosition) {
+      this.position.copy(this.options.emitterPosition);
+    }
+
+    // Set initial rotation from options
+    if (this.options.emitterRotation) {
+      this.rotation.copy(this.options.emitterRotation);
+    }
+  }
+
+  /**
+   * Create the particle material with texture support
+   */
+  private createParticleMaterial(): void {
+    // Create material options
+    const materialOptions: THREE.PointsMaterialParameters = {
+      color: this.options.particleColor,
+      size: this.options.particleSize,
+      blending: THREE.AdditiveBlending,
+      transparent: true,
+      sizeAttenuation: true,
+      depthWrite: false
+    };
+
+    // Add texture if available
+    if (this.particleTexture) {
+      materialOptions.map = this.particleTexture;
+    }
+
+    // Add alpha map if provided
+    if (this.options.particleAlphaMap) {
+      materialOptions.alphaMap = this.options.particleAlphaMap;
+    }
+
+    // Add alpha test if specified
+    if (this.options.particleAlphaTest !== undefined) {
+      materialOptions.alphaTest = this.options.particleAlphaTest;
+    }
+
+    // Create the material
+    this.particleMaterial = new THREE.PointsMaterial(materialOptions);
+  }
+
+  public override beginPlay(): void {
+    super.beginPlay();
+
+    // Register for tick updates
+    const actor = this.getActor();
+    if (actor) {
+      this.onTickPostPhysics.add((_, deltaTime) => this.updateParticles(deltaTime));
+    }
+  }
+
+  public override endPlay(): void {
+    super.endPlay();
+
+    // Clean up textures if needed
+    this.disposeTextures();
+  }
+
+  /**
+   * Dispose of any textures when the component is destroyed
+   */
+  private disposeTextures(): void {
+    // Only dispose textures that we created internally
+    if (this.particleTexture && this.options.particleTextureUrl) {
+      this.particleTexture.dispose();
+    }
+  }
+
+  /**
+   * Generate a random position and velocity for a particle based on emission shape
+   * @returns Object containing position and velocity
+   */
+  private generateEmissionVectors(): { position: THREE.Vector3, velocity: THREE.Vector3 } {
+    const emissionShape = this.options.emissionShape ?? EmissionShape.Sphere;
+    const position = new THREE.Vector3(0, 0, 0);
+    let velocity = new THREE.Vector3();
+
+    switch (emissionShape) {
+      case EmissionShape.Sphere:
+        // Random direction in sphere (default behavior)
+        velocity = this.generateRandomSphereDirection();
+        break;
+
+      case EmissionShape.Cone:
+        // Random direction within a cone
+        velocity = this.generateRandomConeDirection();
+        break;
+
+      case EmissionShape.Disc:
+        // Position in a disc, velocity perpendicular to disc
+        position.copy(this.generateRandomDiscPosition());
+        velocity = this.emissionDirection.clone();
+        break;
+
+      case EmissionShape.Box:
+        // Random position within a box
+        position.copy(this.generateRandomBoxPosition());
+        velocity = this.emissionDirection.clone();
+        break;
+    }
+
+    // Scale velocity by particle speed
+    velocity.multiplyScalar(this.options.particleSpeed);
+
+    return { position, velocity };
+  }
+
+  /**
+   * Generate a random direction in a full sphere
+   */
+  private generateRandomSphereDirection(): THREE.Vector3 {
+    return new THREE.Vector3(
+      (Math.random() - 0.5) * 2,
+      (Math.random() - 0.5) * 2,
+      (Math.random() - 0.5) * 2
+    ).normalize();
+  }
+
+  /**
+   * Generate a random direction within a cone
+   */
+  private generateRandomConeDirection(): THREE.Vector3 {
+    // Default cone angle is 45 degrees if not specified
+    const coneAngleRadians = THREE.MathUtils.degToRad(this.options.emissionAngle ?? 45);
+    const cosAngle = Math.cos(coneAngleRadians);
+
+    // Generate a random direction on a sphere
+    const direction = this.generateRandomSphereDirection();
+
+    // Create a quaternion to rotate from up vector to emission direction
+    const rotationQuat = new THREE.Quaternion();
+    rotationQuat.setFromUnitVectors(new THREE.Vector3(0, 1, 0), this.emissionDirection);
+
+    // Random angle around the cone
+    const theta = Math.random() * Math.PI * 2;
+
+    // Random height on the cone (using cosAngle as the lower bound for z)
+    const z = Math.random() * (1 - cosAngle) + cosAngle;
+
+    // Calculate x and y on the cone base
+    const r = Math.sqrt(1 - z * z);
+    const x = r * Math.cos(theta);
+    const y = r * Math.sin(theta);
+
+    // Create the direction vector and rotate it to align with emission direction
+    const coneDirection = new THREE.Vector3(x, y, z).normalize();
+    coneDirection.applyQuaternion(rotationQuat);
+
+    return coneDirection;
+  }
+
+  /**
+   * Generate a random position on a disc
+   */
+  private generateRandomDiscPosition(): THREE.Vector3 {
+    const radius = this.options.emissionRadius ?? 1.0;
+    const angle = Math.random() * Math.PI * 2;
+    const distance = Math.sqrt(Math.random()) * radius; // sqrt gives uniform distribution
+
+    // Calculate position on a disc in the XZ plane
+    const x = distance * Math.cos(angle);
+    const z = distance * Math.sin(angle);
+
+    // Create perpendicular axes to the emission direction
+    const up = this.emissionDirection.clone().normalize();
+    const right = new THREE.Vector3(0, 1, 0).cross(up).normalize();
+    if (right.lengthSq() < 0.001) {
+      right.set(1, 0, 0); // Fallback if emission direction is parallel to up
+    }
+    const forward = up.clone().cross(right).normalize();
+
+    // Position on the disc oriented perpendicular to emission direction
+    const position = new THREE.Vector3();
+    position.addScaledVector(right, x);
+    position.addScaledVector(forward, z);
+
+    return position;
+  }
+
+  /**
+   * Generate a random position within a box
+   */
+  private generateRandomBoxPosition(): THREE.Vector3 {
+    const dimensions = this.options.emissionDimensions ?? new THREE.Vector3(1, 1, 1);
+
+    // Random position within the box, centered at origin
+    const position = new THREE.Vector3(
+      (Math.random() - 0.5) * dimensions.x,
+      (Math.random() - 0.5) * dimensions.y,
+      (Math.random() - 0.5) * dimensions.z
+    );
+
+    return position;
+  }
+
+  private emitSingleParticle(index: number): void {
+    if (!this.particlePositions || !this.particleVelocities || !this.particleLifetimes) {
+      return;
+    }
+
+    // Generate position and velocity based on emission shape
+    const { position, velocity } = this.generateEmissionVectors();
+
+    // Set particle data
+    const baseIndex = index * 3;
+
+    // Set position based on emission shape
+    this.particlePositions[baseIndex] = position.x;
+    this.particlePositions[baseIndex + 1] = position.y;
+    this.particlePositions[baseIndex + 2] = position.z;
+
+    // Set velocity based on emission shape
+    this.particleVelocities[baseIndex] = velocity.x;
+    this.particleVelocities[baseIndex + 1] = velocity.y;
+    this.particleVelocities[baseIndex + 2] = velocity.z;
+
+    // Set lifetime
+    this.particleLifetimes[index] = this.options.particleLifetime;
+  }
+
+  private emitParticle(): void {
+    if (!this.particlePositions || !this.particleVelocities || !this.particleLifetimes) {
+      return;
+    }
+
+    // Find an inactive particle
+    for (let i = 0; i < this.options.particleCount; i++) {
+      if (this.particleLifetimes[i] <= 0) {
+        this.emitSingleParticle(i);
+
+        // We found and updated a particle, so we're done
+        break;
+      }
+    }
+
+    // Mark attribute as needing update
+    if (this.positionAttribute) {
+      this.positionAttribute.needsUpdate = true;
+    }
+  }
+
+  private updateParticles(deltaTime: number): void {
+    if (!this.particlePositions || !this.particleVelocities || !this.particleLifetimes || !this.positionAttribute) {
+      return;
+    }
+
+    // Check if we should emit continuously or just once
+    const emitContinuously = this.options.emitContinuously ?? true;
+
+    // If we should emit just once and haven't done so yet, emit a burst
+    if (!emitContinuously && !this.hasEmittedOnce) {
+      this.hasEmittedOnce = true;
+    }
+    // Otherwise, if continuous emission is enabled, emit based on rate
+    else if (emitContinuously) {
+      // Emit particles based on rate
+      const emitterRate = this.options.emitterRate ?? 10; // Default to 10 particles per second
+      this.timeAccumulator += deltaTime;
+
+      const timeBetweenParticles = 1 / emitterRate;
+      while (this.timeAccumulator >= timeBetweenParticles) {
+        this.emitParticle();
+        this.timeAccumulator -= timeBetweenParticles;
+      }
+    }
+
+    // Update all active particles
+    let needsUpdate = false;
+
+    for (let i = 0; i < this.options.particleCount; i++) {
+      if (this.particleLifetimes[i] > 0) {
+        // Decrease lifetime
+        this.particleLifetimes[i] -= deltaTime;
+
+        // Update position based on velocity
+        const baseIndex = i * 3;
+        this.particlePositions[baseIndex] += this.particleVelocities[baseIndex] * deltaTime;
+        this.particlePositions[baseIndex + 1] += this.particleVelocities[baseIndex + 1] * deltaTime;
+        this.particlePositions[baseIndex + 2] += this.particleVelocities[baseIndex + 2] * deltaTime;
+
+        needsUpdate = true;
+      }
+    }
+
+    // Update the buffer geometry if needed
+    if (needsUpdate) {
+      this.positionAttribute.needsUpdate = true;
+    }
+  }
+
+  // Helper method to set emission rate
+  public setEmissionRate(rate: number): void {
+    this.options.emitterRate = rate;
+  }
+
+  // Helper method to set particle color
+  public setParticleColor(color: THREE.Color): void {
+    if (this.particleMaterial) {
+      this.particleMaterial.color = color;
+    }
+    this.options.particleColor = color;
+  }
+
+  // Helper method to set particle size
+  public setParticleSize(size: number): void {
+    if (this.particleMaterial) {
+      this.particleMaterial.size = size;
+    }
+    this.options.particleSize = size;
+
+    // Update size attribute if it exists
+    if (this.sizeAttribute) {
+      const sizes = this.sizeAttribute.array as Float32Array;
+      for (let i = 0; i < this.options.particleCount; i++) {
+        sizes[i] = size;
+      }
+      this.sizeAttribute.needsUpdate = true;
+    }
+  }
+
+  // Helper method to set continuous emission mode
+  public setEmitContinuously(continuous: boolean): void {
+    this.options.emitContinuously = continuous;
+
+    // If switching from non-continuous to continuous, reset the hasEmittedOnce flag
+    if (continuous) {
+      this.hasEmittedOnce = false;
+    }
+
+  }
+
+  // Helper method to restart emission for one-time emitters
+  public restart(): void {
+    this.hasEmittedOnce = false;
+  }
+
+  // Helper method to set emission direction
+  public setEmissionDirection(direction: THREE.Vector3): void {
+    this.emissionDirection = direction.clone().normalize();
+    this.options.emissionDirection = this.emissionDirection.clone();
+  }
+
+  // Helper method to set emission shape
+  public setEmissionShape(shape: EmissionShape): void {
+    this.options.emissionShape = shape;
+  }
+
+  // Helper method to set emission angle for cone shape
+  public setEmissionAngle(angleDegrees: number): void {
+    this.options.emissionAngle = angleDegrees;
+  }
+
+  // Helper method to set emission radius for disc or cone shape
+  public setEmissionRadius(radius: number): void {
+    this.options.emissionRadius = radius;
+  }
+
+  // Helper method to set emission dimensions for box shape
+  public setEmissionDimensions(dimensions: THREE.Vector3): void {
+    this.options.emissionDimensions = dimensions.clone();
+  }
+
+  // Helper method to set particle speed
+  public setParticleSpeed(speed: number): void {
+    this.options.particleSpeed = speed;
+  }
+
+  // Helper method to set particle lifetime
+  public setParticleLifetime(lifetime: number): void {
+    this.options.particleLifetime = lifetime;
+  }
+
+  /**
+   * Set a texture for the particles from a URL
+   * @param url URL of the texture to load
+   */
+  public async setParticleTexture(url: string): Promise<void> {
+    try {
+      // Load the texture
+      const texture = new UrlTexture({ url });
+
+      // Apply it to the material
+      if (this.particleMaterial) {
+        this.particleMaterial.map = texture;
+        this.particleMaterial.needsUpdate = true;
+      }
+
+      // Store in options
+      // Dispose old texture if we loaded it
+      if (this.particleTexture && this.options.particleTextureUrl) {
+        this.particleTexture.dispose();
+      }
+
+      this.options.particleTexture = texture;
+      this.options.particleTextureUrl = url;
+      this.particleTexture = texture;
+    } catch (error) {
+      console.error('Failed to load particle texture:', error);
+    }
+  }
+
+  /**
+   * Set an existing texture for particles
+   * @param texture The texture to use
+   */
+  public setParticleTextureObject(texture: THREE.Texture): void {
+    if (this.particleMaterial) {
+      this.particleMaterial.map = texture;
+      this.particleMaterial.needsUpdate = true;
+    }
+
+    this.options.particleTexture = texture;
+    // Don't store a URL since this was passed as an object
+    this.options.particleTextureUrl = undefined;
+  }
+
+  /**
+   * Set the alpha test value for the particle material
+   * @param alphaTest Alpha test value (0.0-1.0)
+   */
+  public setAlphaTest(alphaTest: number): void {
+    if (this.particleMaterial) {
+      this.particleMaterial.alphaTest = alphaTest;
+      this.particleMaterial.needsUpdate = true;
+    }
+
+    this.options.particleAlphaTest = alphaTest;
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_ParticleEmitter';
+  }
+}