@guinetik/gcanvas 1.0.5 → 2.0.0

package/src/math/heat.js

@@ -200,3 +200,109 @@ export function heatTransferFalloff(temp1, temp2, distance, maxDistance, rate, f
 
   return heatDiff * rate * proximity;
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PARTICLE SYSTEM HEAT TRANSFER
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Apply heat transfer between nearby particles in a particle system.
+ * Uses Newton's law of cooling with distance falloff.
+ * Follows the same pattern as Collision.applyCircleSeparation.
+ *
+ * @param {Array<Object>} particles - Array of particles with { x, y, custom }
+ * @param {Object} [options={}] - Configuration options
+ * @param {number} [options.maxDistance=50] - Maximum distance for heat transfer
+ * @param {number} [options.rate=0.01] - Heat transfer rate coefficient
+ * @param {number} [options.falloff=1] - Distance falloff (1=linear, 2=quadratic)
+ * @param {string} [options.temperatureKey='temperature'] - Key in particle.custom
+ * @param {Function} [options.filter=null] - Filter function (particle) => boolean
+ * @param {boolean} [options.useSizeAsRadius=true] - Use particle.size for distance calc
+ *
+ * @example
+ * // Basic usage - all particles exchange heat
+ * applyParticleHeatTransfer(particles, {
+ *   maxDistance: 40,
+ *   rate: 0.02,
+ * });
+ *
+ * @example
+ * // With filter - exclude sorted particles (Maxwell's Demon)
+ * applyParticleHeatTransfer(particles, {
+ *   maxDistance: 36,
+ *   rate: 0.015,
+ *   filter: (p) => !p.custom.sorted,
+ * });
+ *
+ * @example
+ * // With quadratic falloff for more localized transfer
+ * applyParticleHeatTransfer(particles, {
+ *   maxDistance: 60,
+ *   rate: 0.025,
+ *   falloff: 2,
+ * });
+ */
+export function applyParticleHeatTransfer(particles, options = {}) {
+  const {
+    maxDistance = 50,
+    rate = 0.01,
+    falloff = 1,
+    temperatureKey = 'temperature',
+    filter = null,
+    useSizeAsRadius = true,
+  } = options;
+
+  const n = particles.length;
+  const maxDist2 = maxDistance * maxDistance;
+
+  for (let i = 0; i < n; i++) {
+    const pi = particles[i];
+
+    // Skip filtered particles
+    if (filter && !filter(pi)) continue;
+
+    // Ensure temperature exists
+    if (pi.custom[temperatureKey] === undefined) {
+      pi.custom[temperatureKey] = 0.5;
+    }
+
+    for (let j = i + 1; j < n; j++) {
+      const pj = particles[j];
+
+      // Skip filtered particles
+      if (filter && !filter(pj)) continue;
+
+      // Ensure temperature exists
+      if (pj.custom[temperatureKey] === undefined) {
+        pj.custom[temperatureKey] = 0.5;
+      }
+
+      // Distance check (squared for performance)
+      const dx = pi.x - pj.x;
+      const dy = pi.y - pj.y;
+      const dist2 = dx * dx + dy * dy;
+
+      if (dist2 >= maxDist2 || dist2 < 0.0001) continue;
+
+      const dist = Math.sqrt(dist2);
+
+      // Calculate heat transfer with optional distance falloff
+      const delta = heatTransferFalloff(
+        pi.custom[temperatureKey],
+        pj.custom[temperatureKey],
+        dist,
+        maxDistance,
+        rate,
+        falloff
+      );
+
+      // Apply symmetric transfer (energy conservation)
+      pi.custom[temperatureKey] += delta;
+      pj.custom[temperatureKey] -= delta;
+
+      // Clamp to valid range
+      pi.custom[temperatureKey] = Math.max(0, Math.min(1, pi.custom[temperatureKey]));
+      pj.custom[temperatureKey] = Math.max(0, Math.min(1, pj.custom[temperatureKey]));
+    }
+  }
+}

package/src/math/index.js

@@ -6,6 +6,7 @@ export {Noise} from "./noise.js";
 export {Tensor} from "./tensor.js";
 export {generatePenroseTilingPixels} from "./penrose.js";
 export { BooleanAlgebra } from "./boolean.js";
+export { Attractors, AttractorType, AttractorDimension, getAttractorNames, getAttractor, get3DAttractors, get2DAttractors } from "./attractors.js";
 
 // Physics modules
 export * from "./gr.js";

package/src/mixins/draggable.js

@@ -1,10 +1,10 @@
 export function applyDraggable(go, options = {}) {
   const game = go.game;
-  
+
   // Clear any existing state to avoid duplicates
   go.dragging = false;
   go.dragOffset = { x: 0, y: 0 };
-  
+
   // Clean up any existing event handlers to prevent duplicates
   if (go._dragInputMoveHandler) {
     game.events.off("inputmove", go._dragInputMoveHandler);
@@ -12,26 +12,22 @@ export function applyDraggable(go, options = {}) {
   if (go._dragInputUpHandler) {
     game.events.off("inputup", go._dragInputUpHandler);
   }
-  
+
   // Make sure the object is interactive
-  if (typeof go.enableInteractivity === 'function') {
-    go.enableInteractivity(go);
-  } else {
-    go.interactive = true;
-  }
-  
+  go.interactive = true;
+
   // Define the input handlers and store them on the object to allow cleanup
   go._dragInputDownHandler = (e) => {
-//    console.log("Drag input down", go.constructor.name);
+    //    console.log("Drag input down", go.constructor.name);
     go.dragging = true;
-    
+
     // Calculate offset from mouse position to object center
     go.dragOffset.x = go.x - e.x;
     go.dragOffset.y = go.y - e.y;
-    
+
     if (options.onDragStart) options.onDragStart();
   };
-  
+
   go._dragInputMoveHandler = (e) => {
     //console.log("Drag input move", go.constructor.name, "dragging:", go.dragging);
     if (go.dragging) {
@@ -41,27 +37,27 @@ export function applyDraggable(go, options = {}) {
       go.y = e.y + go.dragOffset.y;
     }
   };
-  
+
   go._dragInputUpHandler = (e) => {
     //console.log("Drag input up", go.constructor.name, "dragging:", go.dragging);
     if (!go.dragging) return;
-    
+
     go.dragging = false;
     if (options.onDragEnd) options.onDragEnd();
   };
-  
+
   // Bind the event handlers
   go.on("inputdown", go._dragInputDownHandler);
   game.events.on("inputmove", go._dragInputMoveHandler);
   game.events.on("inputup", go._dragInputUpHandler);
-  
+
   // Return a cleanup function
   return () => {
     // Remove event listeners
     go.off("inputdown", go._dragInputDownHandler);
     game.events.off("inputmove", go._dragInputMoveHandler);
     game.events.off("inputup", go._dragInputUpHandler);
-    
+
     // Clean up properties
     delete go._dragInputDownHandler;
     delete go._dragInputMoveHandler;
@@ -69,4 +65,4 @@ export function applyDraggable(go, options = {}) {
     delete go.dragging;
     delete go.dragOffset;
   };
-}
+}

package/src/painter/painter.shapes.js

@@ -254,23 +254,29 @@ export class PainterShapes {
    * @param {number} [lineWidth] - Line width
    * @returns {void}
    */
-  static polygon(points, fillColor, strokeColor, lineWidth) {
+  static polygon(points, fillColor, strokeColor, lineWidth, lineJoin) {
     if (points.length < 2) return;
 
-    Painter.lines.beginPath();
-    Painter.lines.moveTo(points[0].x, points[0].y);
+    const ctx = Painter.ctx;
+    
+    // Build the path
+    ctx.beginPath();
+    ctx.moveTo(points[0].x, points[0].y);
 
     for (let i = 1; i < points.length; i++) {
-      Painter.lines.lineTo(points[i].x, points[i].y);
+      ctx.lineTo(points[i].x, points[i].y);
     }
 
-    Painter.lines.closePath();
+    ctx.closePath();
 
+    // Fill using Painter.colors (sets fillStyle and calls fill)
     if (fillColor) {
       Painter.colors.fill(fillColor);
     }
 
+    // Stroke using Painter.colors
     if (strokeColor) {
+      if (lineJoin) ctx.lineJoin = lineJoin;
       Painter.colors.stroke(strokeColor, lineWidth);
     }
   }

package/src/particle/particle-system.js

@@ -7,6 +7,7 @@
  * - Optional Camera3D integration with depth sorting
  * - Multiple emitter support
  * - Blend mode control
+ * - Optional WebGL GPU-accelerated rendering
  *
  * @example
  * const particles = new ParticleSystem(this, {
@@ -14,6 +15,7 @@
  *   depthSort: true,
  *   maxParticles: 3000,
  *   blendMode: "screen",
+ *   useWebGL: true,  // Enable GPU rendering
  *   updaters: [Updaters.velocity, Updaters.lifetime, Updaters.gravity(150)],
  * });
  * particles.addEmitter("fountain", new ParticleEmitter({ rate: 50 }));
@@ -23,6 +25,7 @@ import { GameObject } from "../game/objects/go.js";
 import { Painter } from "../painter/painter.js";
 import { Particle } from "./particle.js";
 import { Updaters } from "./updaters.js";
+import { WebGLParticleRenderer } from "../webgl/webgl-particle-renderer.js";
 
 export class ParticleSystem extends GameObject {
   /**
@@ -34,6 +37,13 @@ export class ParticleSystem extends GameObject {
    * @param {string} [options.blendMode="source-over"] - Canvas blend mode
    * @param {Function[]} [options.updaters] - Array of updater functions
    * @param {boolean} [options.worldSpace=false] - Position particles in world space
+   * @param {boolean} [options.useWebGL=false] - Use GPU-accelerated rendering
+   * @param {WebGLParticleRenderer} [options.webglRenderer] - External WebGL renderer
+   * @param {string} [options.webglShape='circle'] - WebGL particle shape
+   * @param {string} [options.webglBlendMode='alpha'] - WebGL blend mode ('alpha' or 'additive')
+   * @param {boolean} [options.depthShading=false] - Shade particles by depth (closer=brighter)
+   * @param {number} [options.depthShadingMin=0.3] - Minimum brightness for far particles
+   * @param {number} [options.depthShadingMax=1.0] - Maximum brightness for near particles
    */
   constructor(game, options = {}) {
     super(game, options);
@@ -60,6 +70,37 @@ export class ParticleSystem extends GameObject {
     this.blendMode = options.blendMode ?? "source-over";
     this.worldSpace = options.worldSpace ?? false;
 
+    // WebGL rendering (optional GPU acceleration)
+    this.webglRenderer = null;
+    if (options.webglRenderer) {
+      // Use provided renderer
+      this.webglRenderer = options.webglRenderer;
+    } else if (options.useWebGL) {
+      // Auto-create WebGL renderer
+      this.webglRenderer = new WebGLParticleRenderer(this.maxParticles, {
+        width: game.width,
+        height: game.height,
+        shape: options.webglShape ?? 'circle',
+        blendMode: options.webglBlendMode ?? 'alpha',
+      });
+      if (!this.webglRenderer.isAvailable()) {
+        console.warn('WebGL not available, falling back to Canvas 2D');
+        this.webglRenderer = null;
+      }
+    }
+
+    // Depth shading (closer = brighter, further = darker)
+    this.depthShading = options.depthShading ?? false;
+    this.depthShadingMin = options.depthShadingMin ?? 0.3;
+    this.depthShadingMax = options.depthShadingMax ?? 1.0;
+
+    // WebGL offset for particles in local/centered coordinate systems (e.g. inside Scene3D)
+    // When particles use centered coords (-w/2 to w/2), set this to { x: w/2, y: h/2 }
+    this.webglOffset = options.webglOffset ?? null;
+
+    // Reusable array for WebGL render list (avoid allocation per frame)
+    this._webglRenderList = [];
+
     // Stats
     this._particleCount = 0;
   }
@@ -184,13 +225,115 @@ export class ParticleSystem extends GameObject {
 
     if (this.particles.length === 0) return;
 
-    if (this.camera && this.depthSort) {
+    // Use WebGL if available
+    if (this.webglRenderer) {
+      this.renderWebGL();
+    } else if (this.camera && this.depthSort) {
       this.renderWithDepthSort();
     } else {
       this.renderSimple();
     }
   }
 
+  /**
+   * GPU-accelerated rendering using WebGL point sprites.
+   * Projects particles through camera (if available), depth sorts,
+   * and renders via WebGLParticleRenderer.
+   */
+  renderWebGL() {
+    const renderer = this.webglRenderer;
+    const renderList = this._webglRenderList;
+
+    // Resize WebGL canvas if needed
+    if (renderer.width !== this.game.width || renderer.height !== this.game.height) {
+      renderer.resize(this.game.width, this.game.height);
+    }
+
+    // Clear render list
+    renderList.length = 0;
+
+    // Build render list with projections
+    const centerX = this.game.width / 2;
+    const centerY = this.game.height / 2;
+
+    if (this.camera && this.depthSort) {
+      // 3D mode: project through camera
+      for (const p of this.particles) {
+        const proj = this.camera.project(p.x, p.y, p.z);
+
+        // Cull particles behind camera
+        if (proj.z < -this.camera.perspective + 10) continue;
+
+        renderList.push({
+          x: centerX + proj.x,
+          y: centerY + proj.y,
+          z: proj.z,
+          size: p.size * proj.scale,
+          color: p.color,
+        });
+      }
+
+      // Sort back to front (painter's algorithm)
+      renderList.sort((a, b) => b.z - a.z);
+
+      // Apply depth shading if enabled
+      if (this.depthShading && renderList.length > 1) {
+        // Find z range
+        let minZ = Infinity, maxZ = -Infinity;
+        for (const item of renderList) {
+          if (item.z < minZ) minZ = item.z;
+          if (item.z > maxZ) maxZ = item.z;
+        }
+        const zRange = maxZ - minZ;
+
+        if (zRange > 0) {
+          const brightnessRange = this.depthShadingMax - this.depthShadingMin;
+
+          for (const item of renderList) {
+            // Normalize z: 0 = far (maxZ), 1 = near (minZ)
+            const t = (maxZ - item.z) / zRange;
+            const brightness = this.depthShadingMin + t * brightnessRange;
+
+            // Apply brightness to color (create new color object to avoid mutating particle)
+            item.color = {
+              r: item.color.r * brightness,
+              g: item.color.g * brightness,
+              b: item.color.b * brightness,
+              a: item.color.a,
+            };
+          }
+        }
+      }
+    } else {
+      // 2D mode: direct screen coords (with optional offset for centered coordinate systems)
+      const offsetX = this.webglOffset?.x ?? 0;
+      const offsetY = this.webglOffset?.y ?? 0;
+      for (const p of this.particles) {
+        renderList.push({
+          x: p.x + offsetX,
+          y: p.y + offsetY,
+          size: p.size,
+          color: p.color,
+        });
+      }
+    }
+
+    // Upload to GPU and render
+    renderer.clear();
+    const count = renderer.updateParticles(renderList);
+    renderer.render(count);
+
+    // Composite onto main canvas
+    // If using webglOffset, composite at negative offset to counteract Scene3D translation
+    const compositeX = this.webglOffset ? -this.webglOffset.x : 0;
+    const compositeY = this.webglOffset ? -this.webglOffset.y : 0;
+    Painter.useCtx((ctx) => {
+      ctx.globalCompositeOperation = this.blendMode;
+      renderer.compositeOnto(ctx, compositeX, compositeY);
+      ctx.globalCompositeOperation = "source-over";
+    });
+  }
+
   /**
    * Simple 2D rendering (no depth sorting).
    */
@@ -304,6 +447,27 @@ export class ParticleSystem extends GameObject {
     this._particleCount = 0;
   }
 
+  /**
+   * Destroy the particle system and free resources.
+   */
+  destroy() {
+    this.clear();
+    if (this.webglRenderer) {
+      this.webglRenderer.destroy();
+      this.webglRenderer = null;
+    }
+    this.pool = [];
+    this.emitters.clear();
+  }
+
+  /**
+   * Check if WebGL rendering is active.
+   * @type {boolean}
+   */
+  get isWebGL() {
+    return this.webglRenderer !== null && this.webglRenderer.isAvailable();
+  }
+
   /**
    * Get current particle count.
    * @type {number}

package/src/physics/index.js

@@ -0,0 +1,26 @@
+/**
+ * @module physics
+ * @description Physics module for particle simulations.
+ * 
+ * Provides:
+ * - Physics: Stateless physics calculations (collision, forces, kinematics)
+ * - PhysicsUpdaters: Composable updaters for ParticleSystem
+ * 
+ * @example
+ * import { Physics, PhysicsUpdaters } from '@guinetik/gcanvas';
+ * 
+ * // Use Physics directly for custom calculations
+ * const collision = Physics.checkCollision(p1, p2);
+ * 
+ * // Use PhysicsUpdaters with ParticleSystem
+ * const system = new ParticleSystem(game, {
+ *   updaters: [
+ *     Updaters.velocity,
+ *     PhysicsUpdaters.particleCollisions(0.9),
+ *     PhysicsUpdaters.bounds3D(bounds),
+ *   ]
+ * });
+ */
+
+export { Physics } from './physics.js';
+export { PhysicsUpdaters } from './physics-updaters.js';