@guinetik/gcanvas 1.0.5 → 2.0.0

package/src/physics/physics-updaters.js

@@ -0,0 +1,333 @@
+/**
+ * @module physics/physics-updaters
+ * @description Composable physics updaters for ParticleSystem.
+ * 
+ * These updaters add physics behavior to particles:
+ * - Mutual attraction/repulsion between particles
+ * - Particle-particle elastic collisions
+ * - 3D boundary bouncing
+ * - Gravity fields
+ * 
+ * @example
+ * import { ParticleSystem, PhysicsUpdaters } from '@guinetik/gcanvas';
+ * 
+ * const system = new ParticleSystem(game, {
+ *   updaters: [
+ *     Updaters.velocity,
+ *     Updaters.lifetime,
+ *     PhysicsUpdaters.mutualAttraction(50, 100),
+ *     PhysicsUpdaters.particleCollisions(0.9),
+ *     PhysicsUpdaters.bounds3D({ minX: 0, maxX: 800, minY: 0, maxY: 600, minZ: -200, maxZ: 200 }),
+ *   ]
+ * });
+ */
+
+import { Physics } from './physics.js';
+
+/**
+ * Physics updaters for ParticleSystem
+ */
+export const PhysicsUpdaters = {
+  /**
+   * Apply mutual attraction/repulsion between all particles.
+   * Uses inverse-square law (like gravity).
+   * 
+   * @param {number} [strength=100] - Force strength (positive=attract, negative=repel)
+   * @param {number} [cutoffDistance=200] - Max distance for force calculation (optimization)
+   * @param {number} [minDistance=5] - Minimum distance to prevent extreme forces
+   * @returns {Function} Updater function
+   * 
+   * @example
+   * PhysicsUpdaters.mutualAttraction(50, 150) // Gravity-like attraction
+   * PhysicsUpdaters.mutualAttraction(-100, 100) // Repulsion
+   */
+  mutualAttraction: (strength = 100, cutoffDistance = 200, minDistance = 5) => {
+    const cutoffSq = cutoffDistance * cutoffDistance;
+    
+    return (p, dt, system) => {
+      if (!p.alive) return;
+      
+      const particles = system.particles;
+      const mass1 = p.mass ?? p.custom?.mass ?? 1;
+      
+      for (let i = 0; i < particles.length; i++) {
+        const other = particles[i];
+        if (other === p || !other.alive) continue;
+        
+        // Quick distance check (squared for performance)
+        const dx = other.x - p.x;
+        const dy = other.y - p.y;
+        const dz = (other.z || 0) - (p.z || 0);
+        const distSq = dx * dx + dy * dy + dz * dz;
+        
+        if (distSq > cutoffSq || distSq < 0.01) continue;
+        
+        const dist = Math.sqrt(distSq);
+        const safeDist = Math.max(dist, minDistance);
+        
+        // Mass-weighted force: F = G * m1 * m2 / r²
+        const mass2 = other.mass ?? other.custom?.mass ?? 1;
+        const force = (strength * mass1 * mass2) / (safeDist * safeDist);
+        
+        // Apply to velocity (normalized direction * force * dt)
+        const f = force * dt / dist;
+        p.vx += dx * f;
+        p.vy += dy * f;
+        if (p.vz !== undefined) p.vz += dz * f;
+      }
+    };
+  },
+
+  /**
+   * Apply linear mutual attraction/repulsion (constant force, not inverse-square).
+   * 
+   * @param {number} [strength=50] - Force strength
+   * @param {number} [cutoffDistance=100] - Max distance for force
+   * @returns {Function} Updater function
+   */
+  mutualAttractionLinear: (strength = 50, cutoffDistance = 100) => {
+    const cutoffSq = cutoffDistance * cutoffDistance;
+    
+    return (p, dt, system) => {
+      if (!p.alive) return;
+      
+      for (const other of system.particles) {
+        if (other === p || !other.alive) continue;
+        
+        const dx = other.x - p.x;
+        const dy = other.y - p.y;
+        const dz = (other.z || 0) - (p.z || 0);
+        const distSq = dx * dx + dy * dy + dz * dz;
+        
+        if (distSq > cutoffSq || distSq < 0.01) continue;
+        
+        const dist = Math.sqrt(distSq);
+        const f = strength * dt / dist;
+        
+        p.vx += dx * f;
+        p.vy += dy * f;
+        if (p.vz !== undefined) p.vz += dz * f;
+      }
+    };
+  },
+
+  /**
+   * Handle particle-particle elastic collisions with momentum conservation.
+   * 
+   * @param {number} [restitution=0.9] - Bounciness (0-1)
+   * @param {number} [threshold=1.0] - Collision distance multiplier
+   * @returns {Function} Updater function
+   * 
+   * @example
+   * PhysicsUpdaters.particleCollisions(0.95) // High bounce
+   * PhysicsUpdaters.particleCollisions(0.5)  // Low bounce (more energy loss)
+   */
+  particleCollisions: (restitution = 0.9, threshold = 1.0) => {
+    // Track processed pairs to avoid double-processing
+    const processedPairs = new Set();
+    
+    return (p, dt, system) => {
+      if (!p.alive) return;
+      
+      // Clear set at start of new frame (check first particle)
+      if (system.particles.indexOf(p) === 0) {
+        processedPairs.clear();
+      }
+      
+      const pIndex = system.particles.indexOf(p);
+      
+      for (let i = pIndex + 1; i < system.particles.length; i++) {
+        const other = system.particles[i];
+        if (!other.alive) continue;
+        
+        // Create unique pair key
+        const pairKey = `${pIndex}-${i}`;
+        if (processedPairs.has(pairKey)) continue;
+        
+        const collision = Physics.checkCollision(p, other, threshold);
+        if (collision) {
+          processedPairs.add(pairKey);
+          
+          // Separate overlapping particles
+          Physics.separate(p, other, collision, 0.5);
+          
+          // Apply elastic collision response
+          const response = Physics.elasticCollision(p, other, collision, restitution);
+          if (response) {
+            p.vx = response.v1.vx;
+            p.vy = response.v1.vy;
+            p.vz = response.v1.vz;
+            
+            other.vx = response.v2.vx;
+            other.vy = response.v2.vy;
+            other.vz = response.v2.vz;
+          }
+        }
+      }
+    };
+  },
+
+  /**
+   * Bounce particles off 3D box boundaries.
+   * 
+   * @param {Object} bounds - Boundary box
+   * @param {number} bounds.minX - Left boundary
+   * @param {number} bounds.maxX - Right boundary
+   * @param {number} bounds.minY - Top boundary
+   * @param {number} bounds.maxY - Bottom boundary
+   * @param {number} [bounds.minZ] - Near boundary (optional for 3D)
+   * @param {number} [bounds.maxZ] - Far boundary (optional for 3D)
+   * @param {number} [restitution=0.9] - Bounciness
+   * @returns {Function} Updater function
+   */
+  bounds3D: (bounds, restitution = 0.9) => (p, dt) => {
+    if (!p.alive) return;
+    Physics.boundsCollision(p, bounds, restitution);
+  },
+
+  /**
+   * Bounce particles inside a spherical boundary.
+   * 
+   * @param {Object} sphere - Sphere definition
+   * @param {number} sphere.x - Center X
+   * @param {number} sphere.y - Center Y
+   * @param {number} [sphere.z=0] - Center Z
+   * @param {number} sphere.radius - Sphere radius
+   * @param {number} [restitution=0.9] - Bounciness
+   * @returns {Function} Updater function
+   */
+  sphereBounds: (sphere, restitution = 0.9) => (p, dt) => {
+    if (!p.alive) return;
+    Physics.sphereBoundsCollision(p, sphere, restitution, true);
+  },
+
+  /**
+   * Attract particles toward a point.
+   * 
+   * @param {Object|Function} target - Target {x, y, z} or function returning target
+   * @param {number} [strength=100] - Attraction strength
+   * @param {number} [minDist=10] - Minimum distance
+   * @returns {Function} Updater function
+   */
+  attractToPoint: (target, strength = 100, minDist = 10) => (p, dt) => {
+    if (!p.alive) return;
+    const t = typeof target === 'function' ? target() : target;
+    const force = Physics.attract(p, t, strength, minDist);
+    p.vx += force.fx * dt;
+    p.vy += force.fy * dt;
+    if (p.vz !== undefined) p.vz += force.fz * dt;
+  },
+
+  /**
+   * Apply uniform gravity (constant downward acceleration).
+   * 
+   * @param {number} [gx=0] - Gravity X component
+   * @param {number} [gy=200] - Gravity Y component (positive = down)
+   * @param {number} [gz=0] - Gravity Z component
+   * @returns {Function} Updater function
+   */
+  gravity: (gx = 0, gy = 200, gz = 0) => (p, dt) => {
+    if (!p.alive) return;
+    p.vx += gx * dt;
+    p.vy += gy * dt;
+    if (p.vz !== undefined) p.vz += gz * dt;
+  },
+
+  /**
+   * Clamp particle velocity to a maximum speed.
+   * 
+   * @param {number} maxSpeed - Maximum speed
+   * @returns {Function} Updater function
+   */
+  maxSpeed: (maxSpeed) => (p, dt) => {
+    if (!p.alive) return;
+    Physics.clampVelocity(p, maxSpeed);
+  },
+
+  /**
+   * Apply drag/friction proportional to velocity squared.
+   * 
+   * @param {number} [coefficient=0.01] - Drag coefficient
+   * @returns {Function} Updater function
+   */
+  drag: (coefficient = 0.01) => (p, dt) => {
+    if (!p.alive) return;
+    const speed = Physics.speed(p);
+    if (speed > 0.01) {
+      const dragForce = coefficient * speed * speed;
+      const dragFactor = Math.max(0, 1 - (dragForce * dt / speed));
+      p.vx *= dragFactor;
+      p.vy *= dragFactor;
+      if (p.vz !== undefined) p.vz *= dragFactor;
+    }
+  },
+
+  /**
+   * Apply separation force to prevent particle overlap.
+   * Lighter-weight alternative to full collision response.
+   * 
+   * @param {number} [strength=100] - Separation force strength
+   * @param {number} [threshold=1.2] - How close before separating (multiplier of combined radii)
+   * @returns {Function} Updater function
+   */
+  separation: (strength = 100, threshold = 1.2) => (p, dt, system) => {
+    if (!p.alive) return;
+    
+    for (const other of system.particles) {
+      if (other === p || !other.alive) continue;
+      
+      const collision = Physics.checkCollision(p, other, threshold);
+      if (collision) {
+        // Repulsion force based on overlap
+        const force = strength * collision.overlap;
+        const nx = -collision.dx / collision.dist;
+        const ny = -collision.dy / collision.dist;
+        const nz = -collision.dz / collision.dist;
+        
+        p.vx += nx * force * dt;
+        p.vy += ny * force * dt;
+        if (p.vz !== undefined) p.vz += nz * force * dt;
+      }
+    }
+  },
+
+  /**
+   * Apply thermal motion (random velocity jitter based on temperature).
+   * 
+   * @param {number|Function} temperature - Temperature value or function returning temperature
+   * @param {number} [scale=10] - Scale factor for jitter
+   * @returns {Function} Updater function
+   */
+  thermal: (temperature, scale = 10) => (p, dt) => {
+    if (!p.alive) return;
+    const temp = typeof temperature === 'function' ? temperature() : temperature;
+    const jitter = temp * scale * dt;
+    p.vx += (Math.random() - 0.5) * jitter;
+    p.vy += (Math.random() - 0.5) * jitter;
+    if (p.vz !== undefined) p.vz += (Math.random() - 0.5) * jitter;
+  },
+
+  /**
+   * Orbital motion around a center point.
+   * Applies centripetal force for stable orbits.
+   * 
+   * @param {Object} center - Orbit center {x, y, z}
+   * @param {number} [strength=100] - Orbital force strength
+   * @returns {Function} Updater function
+   */
+  orbital: (center, strength = 100) => (p, dt) => {
+    if (!p.alive) return;
+    
+    const dx = center.x - p.x;
+    const dy = center.y - p.y;
+    const dz = (center.z || 0) - (p.z || 0);
+    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1;
+    
+    // Centripetal force = v² / r, but we use strength as a constant
+    const force = strength / dist;
+    
+    p.vx += (dx / dist) * force * dt;
+    p.vy += (dy / dist) * force * dt;
+    if (p.vz !== undefined) p.vz += (dz / dist) * force * dt;
+  },
+};

package/src/physics/physics.js

@@ -0,0 +1,375 @@
+/**
+ * @module physics/physics
+ * @description Stateless physics calculations for particle systems.
+ * 
+ * Provides core physics primitives:
+ * - Collision detection (particle-particle, particle-boundary)
+ * - Elastic collision response with momentum conservation
+ * - Force calculations (attraction, repulsion, gravity)
+ * - Kinetic energy calculations
+ * 
+ * All methods are static and pure - no internal state.
+ * 
+ * @example
+ * import { Physics } from '@guinetik/gcanvas';
+ * 
+ * // Check collision between two particles
+ * const collision = Physics.checkCollision(p1, p2);
+ * if (collision) {
+ *   const response = Physics.elasticCollision(p1, p2, collision);
+ *   if (response) {
+ *     Object.assign(p1, response.v1);
+ *     Object.assign(p2, response.v2);
+ *   }
+ * }
+ */
+
+/**
+ * Physics - Stateless physics calculations
+ * @class
+ */
+export class Physics {
+  /**
+   * Calculate attraction/repulsion force between two points using inverse square law.
+   * @param {Object} p1 - First position {x, y, z}
+   * @param {Object} p2 - Second position {x, y, z}
+   * @param {number} [strength=100] - Force multiplier (positive=attract, negative=repel)
+   * @param {number} [minDist=1] - Minimum distance to prevent infinite force
+   * @returns {{fx: number, fy: number, fz: number, dist: number}} Force vector and distance
+   */
+  static attract(p1, p2, strength = 100, minDist = 1) {
+    const dx = p2.x - p1.x;
+    const dy = p2.y - p1.y;
+    const dz = (p2.z || 0) - (p1.z || 0);
+
+    const distSq = dx * dx + dy * dy + dz * dz;
+    const dist = Math.sqrt(distSq) || minDist;
+    const safeDist = Math.max(dist, minDist);
+
+    // Inverse square law: F = strength / dist^2
+    const force = strength / (safeDist * safeDist);
+
+    // Normalize direction and apply force
+    return {
+      fx: (dx / dist) * force,
+      fy: (dy / dist) * force,
+      fz: (dz / dist) * force,
+      dist: dist,
+    };
+  }
+
+  /**
+   * Calculate linear attraction force (constant strength, not inverse square).
+   * @param {Object} p1 - First position {x, y, z}
+   * @param {Object} p2 - Second position {x, y, z}
+   * @param {number} [strength=100] - Force multiplier
+   * @returns {{fx: number, fy: number, fz: number, dist: number}} Force vector and distance
+   */
+  static attractLinear(p1, p2, strength = 100) {
+    const dx = p2.x - p1.x;
+    const dy = p2.y - p1.y;
+    const dz = (p2.z || 0) - (p1.z || 0);
+
+    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1;
+
+    return {
+      fx: (dx / dist) * strength,
+      fy: (dy / dist) * strength,
+      fz: (dz / dist) * strength,
+      dist: dist,
+    };
+  }
+
+  /**
+   * Check if two particles are colliding based on their sizes.
+   * @param {Object} p1 - First particle {x, y, z, size}
+   * @param {Object} p2 - Second particle {x, y, z, size}
+   * @param {number} [threshold=1.0] - Collision distance multiplier
+   * @returns {{dist: number, overlap: number, dx: number, dy: number, dz: number}|null} Collision data or null
+   */
+  static checkCollision(p1, p2, threshold = 1.0) {
+    const dx = p2.x - p1.x;
+    const dy = p2.y - p1.y;
+    const dz = (p2.z || 0) - (p1.z || 0);
+
+    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    const r1 = (p1.size || p1.radius || 1);
+    const r2 = (p2.size || p2.radius || 1);
+    const collisionDist = (r1 + r2) * threshold;
+
+    if (dist < collisionDist && dist > 0) {
+      return {
+        dist: dist,
+        overlap: collisionDist - dist,
+        dx: dx,
+        dy: dy,
+        dz: dz,
+      };
+    }
+    return null;
+  }
+
+  /**
+   * Calculate elastic collision response with conservation of momentum.
+   * @param {Object} p1 - First particle {vx, vy, vz, mass}
+   * @param {Object} p2 - Second particle {vx, vy, vz, mass}
+   * @param {Object} collision - Collision data from checkCollision
+   * @param {number} [restitution=0.9] - Coefficient of restitution (0-1, 1=perfectly elastic)
+   * @returns {{v1: {vx, vy, vz}, v2: {vx, vy, vz}}|null} New velocities or null if separating
+   */
+  static elasticCollision(p1, p2, collision, restitution = 0.9) {
+    const m1 = p1.mass ?? p1.custom?.mass ?? 1;
+    const m2 = p2.mass ?? p2.custom?.mass ?? 1;
+    const totalMass = m1 + m2;
+
+    // Normalize collision axis
+    const dist = collision.dist || 1;
+    const nx = collision.dx / dist;
+    const ny = collision.dy / dist;
+    const nz = collision.dz / dist;
+
+    // Relative velocity along collision axis
+    const dvx = p1.vx - p2.vx;
+    const dvy = p1.vy - p2.vy;
+    const dvz = (p1.vz || 0) - (p2.vz || 0);
+    const relVel = dvx * nx + dvy * ny + dvz * nz;
+
+    // Don't resolve if already moving apart
+    if (relVel < 0) {
+      return null;
+    }
+
+    // Impulse magnitude (conservation of momentum + restitution)
+    const impulse = (-(1 + restitution) * relVel) / totalMass;
+
+    return {
+      v1: {
+        vx: p1.vx + impulse * m2 * nx,
+        vy: p1.vy + impulse * m2 * ny,
+        vz: (p1.vz || 0) + impulse * m2 * nz,
+      },
+      v2: {
+        vx: p2.vx - impulse * m1 * nx,
+        vy: p2.vy - impulse * m1 * ny,
+        vz: (p2.vz || 0) - impulse * m1 * nz,
+      },
+    };
+  }
+
+  /**
+   * Separate two overlapping particles to prevent sticking.
+   * @param {Object} p1 - First particle {x, y, z}
+   * @param {Object} p2 - Second particle {x, y, z}
+   * @param {Object} collision - Collision data from checkCollision
+   * @param {number} [separationFactor=0.5] - How much overlap to resolve (0-1)
+   */
+  static separate(p1, p2, collision, separationFactor = 0.5) {
+    const m1 = p1.mass ?? p1.custom?.mass ?? 1;
+    const m2 = p2.mass ?? p2.custom?.mass ?? 1;
+    const totalMass = m1 + m2;
+
+    const dist = collision.dist || 1;
+    const nx = collision.dx / dist;
+    const ny = collision.dy / dist;
+    const nz = collision.dz / dist;
+
+    const separation = collision.overlap * separationFactor;
+
+    // Move particles apart proportional to inverse mass
+    const move1 = separation * (m2 / totalMass);
+    const move2 = separation * (m1 / totalMass);
+
+    p1.x -= nx * move1;
+    p1.y -= ny * move1;
+    if (p1.z !== undefined) p1.z -= nz * move1;
+
+    p2.x += nx * move2;
+    p2.y += ny * move2;
+    if (p2.z !== undefined) p2.z += nz * move2;
+  }
+
+  /**
+   * Check and respond to 3D boundary collision with bounce.
+   * @param {Object} p - Particle {x, y, z, vx, vy, vz, size}
+   * @param {Object} bounds - Boundary box {minX, maxX, minY, maxY, minZ, maxZ}
+   * @param {number} [restitution=0.9] - Bounciness (0-1)
+   * @returns {boolean} True if collision occurred
+   */
+  static boundsCollision(p, bounds, restitution = 0.9) {
+    const radius = (p.size || p.radius || 1) / 2;
+    let collided = false;
+
+    // X bounds
+    if (bounds.minX !== undefined) {
+      const minX = bounds.minX + radius;
+      const maxX = bounds.maxX - radius;
+
+      if (p.x < minX) {
+        p.x = minX;
+        if (p.vx < 0) p.vx = -p.vx * restitution;
+        collided = true;
+      } else if (p.x > maxX) {
+        p.x = maxX;
+        if (p.vx > 0) p.vx = -p.vx * restitution;
+        collided = true;
+      }
+    }
+
+    // Y bounds
+    if (bounds.minY !== undefined) {
+      const minY = bounds.minY + radius;
+      const maxY = bounds.maxY - radius;
+
+      if (p.y < minY) {
+        p.y = minY;
+        if (p.vy < 0) p.vy = -p.vy * restitution;
+        collided = true;
+      } else if (p.y > maxY) {
+        p.y = maxY;
+        if (p.vy > 0) p.vy = -p.vy * restitution;
+        collided = true;
+      }
+    }
+
+    // Z bounds (optional for 3D)
+    if (bounds.minZ !== undefined && p.z !== undefined) {
+      const minZ = bounds.minZ + radius;
+      const maxZ = bounds.maxZ - radius;
+
+      if (p.z < minZ) {
+        p.z = minZ;
+        if (p.vz < 0) p.vz = -p.vz * restitution;
+        collided = true;
+      } else if (p.z > maxZ) {
+        p.z = maxZ;
+        if (p.vz > 0) p.vz = -p.vz * restitution;
+        collided = true;
+      }
+    }
+
+    return collided;
+  }
+
+  /**
+   * Check collision with a spherical boundary.
+   * @param {Object} p - Particle {x, y, z, vx, vy, vz, size}
+   * @param {Object} sphere - Sphere {x, y, z, radius}
+   * @param {number} [restitution=0.9] - Bounciness (0-1)
+   * @param {boolean} [inside=true] - True to contain inside, false to bounce off outside
+   * @returns {boolean} True if collision occurred
+   */
+  static sphereBoundsCollision(p, sphere, restitution = 0.9, inside = true) {
+    const dx = p.x - sphere.x;
+    const dy = p.y - sphere.y;
+    const dz = (p.z || 0) - (sphere.z || 0);
+    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    const particleRadius = (p.size || p.radius || 1) / 2;
+    const effectiveRadius = sphere.radius - particleRadius;
+
+    if (inside && dist > effectiveRadius) {
+      // Particle outside sphere - bounce back in
+      const nx = dx / dist;
+      const ny = dy / dist;
+      const nz = dz / dist;
+
+      // Position correction
+      p.x = sphere.x + nx * effectiveRadius;
+      p.y = sphere.y + ny * effectiveRadius;
+      if (p.z !== undefined) p.z = sphere.z + nz * effectiveRadius;
+
+      // Velocity reflection
+      const vDotN = p.vx * nx + p.vy * ny + (p.vz || 0) * nz;
+      if (vDotN > 0) {
+        p.vx -= 2 * vDotN * nx * restitution;
+        p.vy -= 2 * vDotN * ny * restitution;
+        if (p.vz !== undefined) p.vz -= 2 * vDotN * nz * restitution;
+      }
+
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Calculate kinetic energy of a particle.
+   * @param {Object} p - Particle {vx, vy, vz, mass}
+   * @returns {number} Kinetic energy (0.5 * m * v²)
+   */
+  static kineticEnergy(p) {
+    const vx = p.vx || 0;
+    const vy = p.vy || 0;
+    const vz = p.vz || 0;
+    const mass = p.mass ?? p.custom?.mass ?? 1;
+    return 0.5 * mass * (vx * vx + vy * vy + vz * vz);
+  }
+
+  /**
+   * Calculate speed (velocity magnitude) of a particle.
+   * @param {Object} p - Particle {vx, vy, vz}
+   * @returns {number} Speed
+   */
+  static speed(p) {
+    const vx = p.vx || 0;
+    const vy = p.vy || 0;
+    const vz = p.vz || 0;
+    return Math.sqrt(vx * vx + vy * vy + vz * vz);
+  }
+
+  /**
+   * Calculate distance between two particles.
+   * @param {Object} p1 - First position {x, y, z}
+   * @param {Object} p2 - Second position {x, y, z}
+   * @returns {number} Distance
+   */
+  static distance(p1, p2) {
+    const dx = p2.x - p1.x;
+    const dy = p2.y - p1.y;
+    const dz = (p2.z || 0) - (p1.z || 0);
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+  }
+
+  /**
+   * Calculate squared distance between two particles (faster than distance).
+   * @param {Object} p1 - First position {x, y, z}
+   * @param {Object} p2 - Second position {x, y, z}
+   * @returns {number} Squared distance
+   */
+  static distanceSquared(p1, p2) {
+    const dx = p2.x - p1.x;
+    const dy = p2.y - p1.y;
+    const dz = (p2.z || 0) - (p1.z || 0);
+    return dx * dx + dy * dy + dz * dz;
+  }
+
+  /**
+   * Clamp velocity magnitude to a maximum.
+   * @param {Object} p - Particle {vx, vy, vz}
+   * @param {number} maxSpeed - Maximum speed
+   */
+  static clampVelocity(p, maxSpeed) {
+    const speed = Physics.speed(p);
+    if (speed > maxSpeed) {
+      const scale = maxSpeed / speed;
+      p.vx *= scale;
+      p.vy *= scale;
+      if (p.vz !== undefined) p.vz *= scale;
+    }
+  }
+
+  /**
+   * Apply a force to a particle (F = ma, so a = F/m).
+   * @param {Object} p - Particle {vx, vy, vz, mass}
+   * @param {number} fx - Force X component
+   * @param {number} fy - Force Y component
+   * @param {number} fz - Force Z component
+   * @param {number} dt - Delta time
+   */
+  static applyForce(p, fx, fy, fz, dt) {
+    const mass = p.mass ?? p.custom?.mass ?? 1;
+    const invMass = mass > 0 ? 1 / mass : 0;
+    p.vx += fx * invMass * dt;
+    p.vy += fy * invMass * dt;
+    if (p.vz !== undefined) p.vz += (fz || 0) * invMass * dt;
+  }
+}