pixospritz-core 0.10.1 → 1.0.1

package/src/engine/core/render/ParticleManager.js

@@ -0,0 +1,529 @@
+/*                                                 *\
+** ----------------------------------------------- **
+**          Calliope - Pixos Game Engine   	       **
+** ----------------------------------------------- **
+**  Copyright (c) 2020-2025 - Kyle Derby MacInnis  **
+**                                                 **
+**    Any unauthorized distribution or transfer    **
+**       of this work is strictly prohibited.      **
+**                                                 **
+**               All Rights Reserved.              **
+** ----------------------------------------------- **
+\*                                                 */
+
+import { Vector } from '../../utils/math/vector.js';
+
+/**
+ * @typedef {object} ParticleConfig
+ * @property {number} [count=8] - Number of particles to emit.
+ * @property {number} [life=1000] - Lifetime in milliseconds.
+ * @property {number} [speed=0.02] - Initial speed.
+ * @property {number} [spread=0.5] - Spread factor for direction.
+ * @property {number} [size=0.5] - Particle size.
+ * @property {number[]} [color=[1.0, 0.7, 0.2]] - RGB color array.
+ * @property {number[]} [gravity=[0, -0.00098, 0]] - Gravity vector.
+ * @property {number} [drag=0.995] - Drag coefficient.
+ * @property {string} [preset] - Preset name for quick config.
+ */
+
+/**
+ * @typedef {object} Particle
+ * @property {number[]} pos - Position [x, y, z].
+ * @property {number[]} vel - Velocity [vx, vy, vz].
+ * @property {number} life - Total lifetime.
+ * @property {number} age - Current age.
+ * @property {number} size - Size scalar.
+ * @property {number[]} color - RGB color.
+ * @property {number[]} gravity - Gravity vector.
+ * @property {number} drag - Drag coefficient.
+ */
+
+/**
+ * ParticleManager - Manages particle effects in the Pixos game engine.
+ * Handles emission, physics updates, and rendering of particles.
+ */
+export default class ParticleManager {
+  /**
+   * Creates an instance of ParticleManager.
+   * @param {import('./manager.js').default} renderManager - The render manager instance.
+   */
+  constructor(renderManager) {
+    /** @type {import('./manager.js').default} */
+    this.renderManager = renderManager;
+    /** @type {import('../index.js').default} */
+    this.engine = renderManager.engine;
+    /** @type {Particle[]} */
+    this.particles = [];
+    /** @type {boolean} */
+    this.initialized = false;
+    /** @type {WebGLBuffer|null} */
+    this.vertexPosBuf = null;
+    /** @type {WebGLBuffer|null} */
+    this.vertexTexBuf = null;
+    /** @type {number|null} */
+    this.lastUpdateTime = null;
+    
+    // Instanced rendering buffers
+    /** @type {WebGLBuffer|null} */
+    this.instancePositionBuf = null;
+    /** @type {WebGLBuffer|null} */
+    this.instanceColorBuf = null;
+    /** @type {WebGLBuffer|null} */
+    this.instanceSizeBuf = null;
+    /** @type {boolean} */
+    this.useInstancing = true;
+    /** @type {number} */
+    this.maxInstances = 10000;
+    /** @type {Float32Array|null} */
+    this.instancePositions = null;
+    /** @type {Float32Array|null} */
+    this.instanceColors = null;
+    /** @type {Float32Array|null} */
+    this.instanceSizes = null;
+  }
+
+  /**
+   * Initializes GL buffers. Called after RenderManager has initialized shaders/GL.
+   * @returns {void}
+   */
+  init = () => {
+    /** @type {WebGL2RenderingContext} */
+    const gl = this.engine.gl;
+    if (!gl) return;
+
+    // A simple unit quad centered at origin (two triangles)
+    const quad = [
+      -0.5, -0.5, 0,
+      -0.5, 0.5, 0,
+      0.5, 0.5, 0,
+      -0.5, -0.5, 0,
+      0.5, 0.5, 0,
+      0.5, -0.5, 0,
+    ];
+    // Simple UVs (not used when not texturing)
+    const uvs = [
+      0, 0,
+      0, 1,
+      1, 1,
+      0, 0,
+      1, 1,
+      1, 0,
+    ];
+
+    this.vertexPosBuf = this.renderManager.createBuffer(quad, gl.STATIC_DRAW, 3);
+    this.vertexTexBuf = this.renderManager.createBuffer(uvs, gl.STATIC_DRAW, 2);
+    
+    // Initialize instanced rendering buffers
+    this.initInstancedBuffers();
+    
+    this.initialized = true;
+  };
+
+  /**
+   * Initializes buffers for instanced rendering.
+   * @returns {void}
+   */
+  initInstancedBuffers = () => {
+    const gl = this.engine.gl;
+    if (!gl) return;
+
+    // Pre-allocate typed arrays for instance data
+    this.instancePositions = new Float32Array(this.maxInstances * 3);
+    this.instanceColors = new Float32Array(this.maxInstances * 4);
+    this.instanceSizes = new Float32Array(this.maxInstances);
+
+    // Create instance buffers
+    this.instancePositionBuf = gl.createBuffer();
+    this.instanceColorBuf = gl.createBuffer();
+    this.instanceSizeBuf = gl.createBuffer();
+  };
+
+  /**
+   * Updates instance buffers with current particle data.
+   * @returns {number} Number of particles to render.
+   */
+  updateInstanceBuffers = () => {
+    const gl = this.engine.gl;
+    if (!gl || !this.particles.length) return 0;
+
+    const count = Math.min(this.particles.length, this.maxInstances);
+    
+    // Sort particles back-to-front for proper alpha blending
+    const cameraPos = this.renderManager.camera.cameraPosition;
+    const sortedParticles = [...this.particles].sort((a, b) => {
+      const distA = Math.pow(a.pos[0] - cameraPos.x, 2) + 
+                    Math.pow(a.pos[1] - cameraPos.y, 2) + 
+                    Math.pow(a.pos[2] - cameraPos.z, 2);
+      const distB = Math.pow(b.pos[0] - cameraPos.x, 2) + 
+                    Math.pow(b.pos[1] - cameraPos.y, 2) + 
+                    Math.pow(b.pos[2] - cameraPos.z, 2);
+      return distB - distA;
+    });
+
+    // Fill instance arrays
+    for (let i = 0; i < count; i++) {
+      const p = sortedParticles[i];
+      const lifeRatio = p.age / p.life;
+      const alpha = Math.max(0, 1.0 - lifeRatio * lifeRatio);
+
+      // Position (x, y, z)
+      this.instancePositions[i * 3] = p.pos[0];
+      this.instancePositions[i * 3 + 1] = p.pos[1];
+      this.instancePositions[i * 3 + 2] = p.pos[2];
+
+      // Color (r, g, b, a)
+      this.instanceColors[i * 4] = p.color[0];
+      this.instanceColors[i * 4 + 1] = p.color[1];
+      this.instanceColors[i * 4 + 2] = p.color[2];
+      this.instanceColors[i * 4 + 3] = alpha;
+
+      // Size
+      this.instanceSizes[i] = p.size;
+    }
+
+    // Upload to GPU
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.instancePositionBuf);
+    gl.bufferData(gl.ARRAY_BUFFER, this.instancePositions.subarray(0, count * 3), gl.DYNAMIC_DRAW);
+
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceColorBuf);
+    gl.bufferData(gl.ARRAY_BUFFER, this.instanceColors.subarray(0, count * 4), gl.DYNAMIC_DRAW);
+
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceSizeBuf);
+    gl.bufferData(gl.ARRAY_BUFFER, this.instanceSizes.subarray(0, count), gl.DYNAMIC_DRAW);
+
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+
+    return count;
+  };
+
+  /**
+   * Emits particles based on a config object.
+   * @param {number[]|Vector} [position=[0, 0, 0]] - Position [x, y, z] or Vector.
+   * @param {ParticleConfig} [config={}] - Configuration for particles.
+   * @returns {void}
+   */
+  emit = (position = [0, 0, 0], config = {}) => {
+    /** @type {number[]} */
+    let pos = Array.isArray(position) ? position : position.toArray ? position.toArray() : [0, 0, 0];
+    let x = pos[0], y = pos[1], zOffset = pos[2] || 0;
+    /** @type {import('../../scene/zone.js').Zone|null} */
+    let zone = this.engine.spritz.world.zoneContaining(x, y);
+    let z = zOffset;
+    if (zone) {
+      z += zone.getHeight(x, y);
+    }
+
+    pos = [x, y, z];
+
+    /** @type {ParticleConfig} */
+    const c = Object.assign(
+      {
+        count: 8,
+        life: 1000, // ms
+        speed: 0.02,
+        spread: 0.5,
+        size: 0.5,
+        color: [1.0, 0.7, 0.2],
+        gravity: [0, -0.00098, 0],
+        drag: 0.995,
+      },
+      config
+    );
+
+    for (let i = 0; i < c.count; i++) {
+      // random direction in unit sphere
+      const rx = (Math.random() * 2 - 1) * c.spread;
+      const ry = (Math.random() * 2 - 1) * c.spread;
+      const rz = (Math.random() * 2 - 1) * c.spread;
+      const vx = rx * c.speed * (0.5 + Math.random() * 1.5);
+      const vy = ry * c.speed * (0.5 + Math.random() * 1.5);
+      const vz = rz * c.speed * (0.5 + Math.random() * 1.5);
+
+      /** @type {Particle} */
+      const particle = {
+        pos: [pos[0], pos[1], pos[2]],
+        vel: [vx, vy, vz],
+        life: c.life,
+        age: 0,
+        size: c.size * (0.8 + Math.random() * 0.8),
+        color: c.color,
+        gravity: c.gravity,
+        drag: c.drag,
+      };
+      this.particles.push(particle);
+    }
+  };
+
+  /**
+   * Returns a preset configuration for particles.
+   * @param {string} name - The preset name.
+   * @returns {ParticleConfig|null} The preset config or null if not found.
+   */
+  preset = (name) => {
+    switch ((name || '').toLowerCase()) {
+      case 'sparks':
+        return { count: 12, life: 700, speed: 0.06, spread: 1.2, size: 0.15, color: [1, 0.8, 0.2], gravity: [0, -0.002, 0] };
+      case 'flame':
+        return { count: 200, life: 2000, speed: 0.02, spread: 0.8, size: 0.06, color: [1, 0.5, 0.1], gravity: [0, -0.0003, 0], drag: 0.995 };
+      case 'water':
+        return { count: 20, life: 800, speed: 0.05, spread: 1.5, size: 0.12, color: [0.6, 0.7, 1.0], gravity: [0, -0.003, 0], drag: 0.996 };
+      case 'weapon':
+        return { count: 6, life: 600, speed: 0.08, spread: 0.3, size: 0.18, color: [1, 1, 0.6], gravity: [0, -0.001, 0] };
+      default:
+        return null;
+    }
+  };
+
+  /**
+   * Updates particle physics. Timestamp in ms.
+   * @param {number} timestamp - Current timestamp.
+   * @returns {void}
+   */
+  update = (timestamp) => {
+    if (!this.lastUpdateTime) this.lastUpdateTime = timestamp;
+    const dt = timestamp - this.lastUpdateTime;
+    this.lastUpdateTime = timestamp;
+    if (!dt) return;
+
+    // Update particle physics
+    for (let i = this.particles.length - 1; i >= 0; i--) {
+      /** @type {Particle} */
+      const p = this.particles[i];
+      // apply gravity
+      p.vel[0] += (p.gravity[0] || 0) * dt;
+      p.vel[1] += (p.gravity[1] || 0) * dt;
+      p.vel[2] += (p.gravity[2] || 0) * dt;
+      // apply drag
+      p.vel[0] *= Math.pow(p.drag || 1, dt / 16.6667);
+      p.vel[1] *= Math.pow(p.drag || 1, dt / 16.6667);
+      p.vel[2] *= Math.pow(p.drag || 1, dt / 16.6667);
+      // integrate
+      p.pos[0] += p.vel[0] * dt;
+      p.pos[1] += p.vel[1] * dt;
+      p.pos[2] += p.vel[2] * dt;
+      p.age += dt;
+      if (p.age >= p.life) {
+        this.particles.splice(i, 1);
+      }
+    }
+  };
+
+  /**
+   * Renders particles using instanced rendering for optimal performance.
+   * Falls back to individual draw calls if instancing is not available.
+   * @returns {void}
+   */
+  render = () => {
+    if (!this.initialized) this.init();
+    if (!this.initialized) return;
+    if (!this.particles.length) return;
+
+    /** @type {import('./manager.js').default} */
+    const rm = this.renderManager;
+    /** @type {WebGL2RenderingContext} */
+    const gl = this.engine.gl;
+    /** @type {WebGLProgram} */
+    const shader = rm.particleShaderProgram;
+    if (!shader) return;
+
+    // Check for instanced rendering support (WebGL2)
+    const supportsInstancing = typeof gl.drawArraysInstanced === 'function';
+    
+    if (supportsInstancing && this.useInstancing && shader.aInstancePosition !== undefined) {
+      this.renderInstanced();
+    } else {
+      this.renderNonInstanced();
+    }
+  };
+
+  /**
+   * Renders particles using WebGL2 instanced rendering.
+   * Single draw call for all particles - massive performance improvement.
+   * @returns {void}
+   */
+  renderInstanced = () => {
+    const rm = this.renderManager;
+    const gl = this.engine.gl;
+    const shader = rm.particleShaderProgram;
+
+    // Update instance buffers with current particle data
+    const instanceCount = this.updateInstanceBuffers();
+    if (instanceCount === 0) return;
+
+    // Reset vertex attrib arrays
+    for (let i = 0; i < 8; i++) {
+      gl.disableVertexAttribArray(i);
+    }
+
+    gl.useProgram(shader);
+
+    // Enable blending for transparency - additive blending for glow
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+    gl.depthMask(false);
+
+    // Bind quad vertex data (shared for all instances)
+    gl.enableVertexAttribArray(shader.aVertexPosition);
+    rm.bindBuffer(this.vertexPosBuf, shader.aVertexPosition);
+
+    gl.enableVertexAttribArray(shader.aTextureCoord);
+    rm.bindBuffer(this.vertexTexBuf, shader.aTextureCoord);
+
+    // Bind instance position buffer
+    if (shader.aInstancePosition !== undefined) {
+      gl.enableVertexAttribArray(shader.aInstancePosition);
+      gl.bindBuffer(gl.ARRAY_BUFFER, this.instancePositionBuf);
+      gl.vertexAttribPointer(shader.aInstancePosition, 3, gl.FLOAT, false, 0, 0);
+      gl.vertexAttribDivisor(shader.aInstancePosition, 1);
+    }
+
+    // Bind instance color buffer
+    if (shader.aInstanceColor !== undefined) {
+      gl.enableVertexAttribArray(shader.aInstanceColor);
+      gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceColorBuf);
+      gl.vertexAttribPointer(shader.aInstanceColor, 4, gl.FLOAT, false, 0, 0);
+      gl.vertexAttribDivisor(shader.aInstanceColor, 1);
+    }
+
+    // Bind instance size buffer
+    if (shader.aInstanceSize !== undefined) {
+      gl.enableVertexAttribArray(shader.aInstanceSize);
+      gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceSizeBuf);
+      gl.vertexAttribPointer(shader.aInstanceSize, 1, gl.FLOAT, false, 0, 0);
+      gl.vertexAttribDivisor(shader.aInstanceSize, 1);
+    }
+
+    // Set projection/view matrices
+    if (shader.setMatrixUniforms) {
+      shader.setMatrixUniforms({});
+    }
+
+    // Draw all particles in a single instanced call
+    gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, instanceCount);
+
+    // Reset divisors
+    if (shader.aInstancePosition !== undefined) {
+      gl.vertexAttribDivisor(shader.aInstancePosition, 0);
+      gl.disableVertexAttribArray(shader.aInstancePosition);
+    }
+    if (shader.aInstanceColor !== undefined) {
+      gl.vertexAttribDivisor(shader.aInstanceColor, 0);
+      gl.disableVertexAttribArray(shader.aInstanceColor);
+    }
+    if (shader.aInstanceSize !== undefined) {
+      gl.vertexAttribDivisor(shader.aInstanceSize, 0);
+      gl.disableVertexAttribArray(shader.aInstanceSize);
+    }
+
+    // Cleanup
+    gl.depthMask(true);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    gl.disableVertexAttribArray(shader.aVertexPosition);
+    gl.disableVertexAttribArray(shader.aTextureCoord);
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+    gl.useProgram(null);
+  };
+
+  /**
+   * Renders particles without instancing (fallback for older systems).
+   * @returns {void}
+   */
+  renderNonInstanced = () => {
+    const rm = this.renderManager;
+    const gl = this.engine.gl;
+    const shader = rm.particleShaderProgram;
+
+    // Reset all vertex attrib arrays to prevent errors from other shaders
+    for (let i = 0; i < 8; i++) {
+      gl.disableVertexAttribArray(i);
+    }
+
+    // Use particle shader
+    gl.useProgram(shader);
+
+    // Enable blending for transparency - additive blending for glow effects
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+    
+    // Disable depth writing (but keep depth test) for proper transparency
+    gl.depthMask(false);
+
+    // Enable vertex attributes for particle shader
+    gl.enableVertexAttribArray(shader.aVertexPosition);
+    gl.enableVertexAttribArray(shader.aTextureCoord);
+
+    // Sort particles back-to-front based on distance from camera
+    const cameraPos = rm.camera.cameraPosition;
+    const sortedParticles = [...this.particles].sort((a, b) => {
+      const distA = Math.pow(a.pos[0] - cameraPos.x, 2) + 
+                    Math.pow(a.pos[1] - cameraPos.y, 2) + 
+                    Math.pow(a.pos[2] - cameraPos.z, 2);
+      const distB = Math.pow(b.pos[0] - cameraPos.x, 2) + 
+                    Math.pow(b.pos[1] - cameraPos.y, 2) + 
+                    Math.pow(b.pos[2] - cameraPos.z, 2);
+      return distB - distA; // Back to front
+    });
+
+    for (const p of sortedParticles) {
+      rm.mvPushMatrix();
+      
+      // Set model matrix translation only (billboarding handled in shader)
+      const m = rm.uModelMat;
+      // Reset to identity
+      for (let i = 0; i < 16; i++) m[i] = (i % 5 === 0) ? 1 : 0;
+      // Set translation
+      m[12] = p.pos[0];
+      m[13] = p.pos[1];
+      m[14] = p.pos[2];
+
+      // Calculate alpha based on particle age (fade out towards end of life)
+      const lifeRatio = p.age / p.life;
+      const alpha = Math.max(0, 1.0 - lifeRatio * lifeRatio); // Quadratic fade
+
+      // Set scale and matrix uniforms with alpha
+      const scaleVec = new Vector(p.size, p.size, p.size);
+      shader.setMatrixUniforms({ scale: scaleVec, color: p.color, alpha: alpha });
+
+      // Bind buffers and draw
+      rm.bindBuffer(this.vertexPosBuf, shader.aVertexPosition);
+      rm.bindBuffer(this.vertexTexBuf, shader.aTextureCoord);
+      gl.drawArrays(gl.TRIANGLES, 0, this.vertexPosBuf.numItems);
+
+      rm.mvPopMatrix();
+    }
+
+    // Restore depth mask and blending
+    gl.depthMask(true);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    
+    // Disable vertex attrib arrays to prevent WebGL state issues
+    gl.disableVertexAttribArray(shader.aVertexPosition);
+    gl.disableVertexAttribArray(shader.aTextureCoord);
+    
+    // cleanup
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+    gl.useProgram(null);
+  };
+
+  /**
+   * Gets particle count for debugging/stats.
+   * @returns {number} Current particle count.
+   */
+  getParticleCount = () => this.particles.length;
+
+  /**
+   * Clears all particles.
+   * @returns {void}
+   */
+  clear = () => {
+    this.particles = [];
+  };
+
+  /**
+   * Sets whether to use instanced rendering.
+   * @param {boolean} enabled - Whether to use instancing.
+   */
+  setInstancingEnabled = (enabled) => {
+    this.useInstancing = enabled;
+  };
+}