@guinetik/gcanvas 1.0.0

package/src/particle/particle-system.js

@@ -0,0 +1,322 @@
+/**
+ * ParticleSystem - High-performance particle management GameObject
+ *
+ * Features:
+ * - Object pooling to minimize garbage collection
+ * - Composable updaters for physics and effects
+ * - Optional Camera3D integration with depth sorting
+ * - Multiple emitter support
+ * - Blend mode control
+ *
+ * @example
+ * const particles = new ParticleSystem(this, {
+ *   camera: this.camera,
+ *   depthSort: true,
+ *   maxParticles: 3000,
+ *   blendMode: "screen",
+ *   updaters: [Updaters.velocity, Updaters.lifetime, Updaters.gravity(150)],
+ * });
+ * particles.addEmitter("fountain", new ParticleEmitter({ rate: 50 }));
+ * this.pipeline.add(particles);
+ */
+import { GameObject } from "../game/objects/go.js";
+import { Painter } from "../painter/painter.js";
+import { Particle } from "./particle.js";
+import { Updaters } from "./updaters.js";
+
+export class ParticleSystem extends GameObject {
+  /**
+   * @param {Game} game - Game instance
+   * @param {Object} options - System configuration
+   * @param {number} [options.maxParticles=5000] - Maximum active particles
+   * @param {Camera3D} [options.camera] - Optional camera for 3D projection
+   * @param {boolean} [options.depthSort=false] - Enable depth sorting (requires camera)
+   * @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
+   */
+  constructor(game, options = {}) {
+    super(game, options);
+
+    // Particle storage
+    this.particles = [];
+    this.pool = [];
+    this.maxParticles = options.maxParticles ?? 5000;
+
+    // Emitters
+    this.emitters = new Map();
+
+    // Optional Camera3D for 3D projection
+    this.camera = options.camera ?? null;
+    this.depthSort = options.depthSort ?? false;
+
+    // Updaters (composable behaviors)
+    this.updaters = options.updaters ?? [
+      Updaters.velocity,
+      Updaters.lifetime,
+    ];
+
+    // Rendering
+    this.blendMode = options.blendMode ?? "source-over";
+    this.worldSpace = options.worldSpace ?? false;
+
+    // Stats
+    this._particleCount = 0;
+  }
+
+  /**
+   * Add an emitter to the system.
+   * @param {string} name - Emitter identifier
+   * @param {ParticleEmitter} emitter - Emitter instance
+   * @returns {ParticleSystem} this (for chaining)
+   */
+  addEmitter(name, emitter) {
+    this.emitters.set(name, emitter);
+    return this;
+  }
+
+  /**
+   * Remove an emitter from the system.
+   * @param {string} name - Emitter identifier
+   * @returns {ParticleSystem} this (for chaining)
+   */
+  removeEmitter(name) {
+    this.emitters.delete(name);
+    return this;
+  }
+
+  /**
+   * Get an emitter by name.
+   * @param {string} name - Emitter identifier
+   * @returns {ParticleEmitter|undefined}
+   */
+  getEmitter(name) {
+    return this.emitters.get(name);
+  }
+
+  /**
+   * Acquire a particle from pool or create new.
+   * @returns {Particle}
+   */
+  acquire() {
+    if (this.pool.length > 0) {
+      return this.pool.pop();
+    }
+    return new Particle();
+  }
+
+  /**
+   * Release a particle back to pool.
+   * @param {Particle} particle
+   */
+  release(particle) {
+    particle.reset();
+    this.pool.push(particle);
+  }
+
+  /**
+   * Emit particles using an emitter.
+   * @param {number} count - Number of particles to emit
+   * @param {ParticleEmitter} emitter - Emitter to use
+   */
+  emit(count, emitter) {
+    for (let i = 0; i < count && this.particles.length < this.maxParticles; i++) {
+      const p = this.acquire();
+      emitter.emit(p);
+      this.particles.push(p);
+    }
+  }
+
+  /**
+   * Burst spawn particles.
+   * @param {number} count - Number of particles
+   * @param {ParticleEmitter|string} emitterOrName - Emitter instance or name
+   */
+  burst(count, emitterOrName) {
+    const emitter = typeof emitterOrName === "string"
+      ? this.emitters.get(emitterOrName)
+      : emitterOrName;
+
+    if (emitter) {
+      this.emit(count, emitter);
+    }
+  }
+
+  /**
+   * Update all emitters and particles.
+   * @param {number} dt - Delta time in seconds
+   */
+  update(dt) {
+    super.update(dt);
+
+    // Update emitters and spawn particles
+    for (const emitter of this.emitters.values()) {
+      if (emitter.active) {
+        const count = emitter.update(dt);
+        this.emit(count, emitter);
+      }
+    }
+
+    // Update particles (iterate backwards for safe removal)
+    for (let i = this.particles.length - 1; i >= 0; i--) {
+      const p = this.particles[i];
+
+      // Apply all updaters
+      for (const updater of this.updaters) {
+        updater(p, dt, this);
+      }
+
+      // Remove dead particles
+      if (!p.alive) {
+        this.release(p);
+        this.particles.splice(i, 1);
+      }
+    }
+
+    this._particleCount = this.particles.length;
+  }
+
+  /**
+   * Render all particles.
+   */
+  render() {
+    super.render();
+
+    if (this.particles.length === 0) return;
+
+    if (this.camera && this.depthSort) {
+      this.renderWithDepthSort();
+    } else {
+      this.renderSimple();
+    }
+  }
+
+  /**
+   * Simple 2D rendering (no depth sorting).
+   */
+  renderSimple() {
+    Painter.useCtx((ctx) => {
+      ctx.globalCompositeOperation = this.blendMode;
+
+      for (const p of this.particles) {
+        this.drawParticle(ctx, p, p.x, p.y, 1);
+      }
+
+      ctx.globalCompositeOperation = "source-over";
+    });
+  }
+
+  /**
+   * 3D rendering with Camera3D projection and depth sorting.
+   */
+  renderWithDepthSort() {
+    // Build render list with projections
+    const renderList = [];
+
+    for (const p of this.particles) {
+      const projected = this.camera.project(p.x, p.y, p.z);
+
+      // Cull particles behind camera
+      if (projected.z < -this.camera.perspective + 10) continue;
+
+      renderList.push({
+        p,
+        x: projected.x,
+        y: projected.y,
+        z: projected.z,
+        scale: projected.scale,
+      });
+    }
+
+    // Sort back to front
+    renderList.sort((a, b) => b.z - a.z);
+
+    // Draw all particles
+    Painter.useCtx((ctx) => {
+      ctx.globalCompositeOperation = this.blendMode;
+
+      // Translate to center if using camera (camera projects relative to origin)
+      // Only do this if NOT inside a Scene3D (which already handles projection/centering)
+      const isProjected = this.parent && this.parent.constructor.name === "Scene3D";
+
+      if (!this.worldSpace && !isProjected) {
+        ctx.save();
+        ctx.translate(this.game.width / 2, this.game.height / 2);
+      }
+
+      for (const item of renderList) {
+        this.drawParticle(ctx, item.p, item.x, item.y, item.scale);
+      }
+
+      if (!this.worldSpace && !isProjected) {
+        ctx.restore();
+      }
+
+      ctx.globalCompositeOperation = "source-over";
+    });
+  }
+
+  /**
+   * Draw a single particle.
+   * Override this method for custom particle rendering.
+   *
+   * @param {CanvasRenderingContext2D} ctx - Canvas context
+   * @param {Particle} p - Particle to draw
+   * @param {number} x - Screen X position
+   * @param {number} y - Screen Y position
+   * @param {number} scale - Size scale factor (from perspective)
+   */
+  drawParticle(ctx, p, x, y, scale) {
+    const { r, g, b, a } = p.color;
+    const size = p.size * scale;
+
+    if (size < 0.5 || a <= 0) return;
+
+    ctx.fillStyle = `rgba(${Math.floor(r)},${Math.floor(g)},${Math.floor(b)},${a})`;
+
+    const shape = p.shape ?? "circle";
+    const half = size / 2;
+
+    ctx.beginPath();
+
+    if (shape === "circle") {
+      ctx.arc(x, y, half, 0, Math.PI * 2);
+    } else if (shape === "square") {
+      ctx.rect(x - half, y - half, size, size);
+    } else if (shape === "triangle") {
+      ctx.moveTo(x, y - half);
+      ctx.lineTo(x + half, y + half);
+      ctx.lineTo(x - half, y + half);
+      ctx.closePath();
+    }
+
+    ctx.fill();
+  }
+
+  /**
+   * Clear all particles and return them to pool.
+   */
+  clear() {
+    for (const p of this.particles) {
+      this.release(p);
+    }
+    this.particles = [];
+    this._particleCount = 0;
+  }
+
+  /**
+   * Get current particle count.
+   * @type {number}
+   */
+  get particleCount() {
+    return this._particleCount;
+  }
+
+  /**
+   * Get pool size (recycled particles ready for reuse).
+   * @type {number}
+   */
+  get poolSize() {
+    return this.pool.length;
+  }
+}

package/src/particle/particle.js

@@ -0,0 +1,71 @@
+/**
+ * Particle - Lightweight data class for particle systems
+ *
+ * Plain object with no methods for performance (2500+ particles efficient).
+ * Uses object pooling via reset() to minimize garbage collection.
+ */
+export class Particle {
+  constructor() {
+    // Position (3D capable)
+    this.x = 0;
+    this.y = 0;
+    this.z = 0;
+
+    // Velocity
+    this.vx = 0;
+    this.vy = 0;
+    this.vz = 0;
+
+    // Appearance
+    this.size = 1;
+    this.color = { r: 255, g: 255, b: 255, a: 1 };
+    this.shape = "circle"; // "circle", "square", "triangle"
+
+    // Lifecycle
+    this.age = 0;
+    this.lifetime = 1;
+    this.alive = true;
+
+    // Custom data (for domain-specific behaviors like orbital mechanics)
+    this.custom = {};
+  }
+
+  /**
+   * Reset all properties for object pooling.
+   * Called when particle is returned to pool.
+   */
+  reset() {
+    this.x = 0;
+    this.y = 0;
+    this.z = 0;
+
+    this.vx = 0;
+    this.vy = 0;
+    this.vz = 0;
+
+    this.size = 1;
+    this.color.r = 255;
+    this.color.g = 255;
+    this.color.b = 255;
+    this.color.a = 1;
+    this.shape = "circle";
+
+    this.age = 0;
+    this.lifetime = 1;
+    this.alive = true;
+
+    // Clear custom data
+    for (const key in this.custom) {
+      delete this.custom[key];
+    }
+  }
+
+  /**
+   * Progress through lifetime (0 = just born, 1 = about to die).
+   * Useful for fade/shrink effects.
+   * @type {number}
+   */
+  get progress() {
+    return this.lifetime > 0 ? this.age / this.lifetime : 1;
+  }
+}

package/src/particle/updaters.js

@@ -0,0 +1,170 @@
+/**
+ * Updaters - Composable particle behavior functions
+ *
+ * Each updater is a function with signature: (particle, dt, system) => void
+ * Some updaters are factories that return the actual updater function.
+ *
+ * Usage:
+ *   updaters: [Updaters.velocity, Updaters.lifetime, Updaters.gravity(200)]
+ */
+export const Updaters = {
+  /**
+   * Apply velocity to position.
+   */
+  velocity: (p, dt) => {
+    p.x += p.vx * dt;
+    p.y += p.vy * dt;
+    p.z += p.vz * dt;
+  },
+
+  /**
+   * Track age and kill particle when lifetime exceeded.
+   */
+  lifetime: (p, dt) => {
+    p.age += dt;
+    if (p.age >= p.lifetime) {
+      p.alive = false;
+    }
+  },
+
+  /**
+   * Apply downward gravity.
+   * @param {number} [strength=200] - Gravity strength (pixels/second²)
+   * @returns {Function} Updater function
+   */
+  gravity: (strength = 200) => (p, dt) => {
+    p.vy += strength * dt;
+  },
+
+  /**
+   * Apply upward gravity (for rising particles like fire).
+   * @param {number} [strength=100] - Rise strength (pixels/second²)
+   * @returns {Function} Updater function
+   */
+  rise: (strength = 100) => (p, dt) => {
+    p.vy -= strength * dt;
+  },
+
+  /**
+   * Apply velocity damping/friction.
+   * @param {number} [factor=0.98] - Damping factor (0-1, lower = more friction)
+   * @returns {Function} Updater function
+   */
+  damping: (factor = 0.98) => (p, dt) => {
+    // Apply per-frame (not dt-based for simplicity)
+    p.vx *= factor;
+    p.vy *= factor;
+    p.vz *= factor;
+  },
+
+  /**
+   * Fade out alpha over lifetime.
+   */
+  fadeOut: (p, dt) => {
+    p.color.a = Math.max(0, 1 - p.progress);
+  },
+
+  /**
+   * Fade in then out (peak at 50% lifetime).
+   */
+  fadeInOut: (p, dt) => {
+    const t = p.progress;
+    p.color.a = t < 0.5 ? t * 2 : (1 - t) * 2;
+  },
+
+  /**
+   * Shrink size over lifetime.
+   * @param {number} [endScale=0] - Final size multiplier (0 = disappear)
+   * @returns {Function} Updater function
+   */
+  shrink: (endScale = 0) => {
+    // Store initial size on first call
+    return (p, dt) => {
+      if (p.custom._initialSize === undefined) {
+        p.custom._initialSize = p.size;
+      }
+      p.size = p.custom._initialSize * (1 - p.progress * (1 - endScale));
+    };
+  },
+
+  /**
+   * Grow size over lifetime.
+   * @param {number} [endScale=2] - Final size multiplier
+   * @returns {Function} Updater function
+   */
+  grow: (endScale = 2) => {
+    return (p, dt) => {
+      if (p.custom._initialSize === undefined) {
+        p.custom._initialSize = p.size;
+      }
+      p.size = p.custom._initialSize * (1 + p.progress * (endScale - 1));
+    };
+  },
+
+  /**
+   * Interpolate color over lifetime.
+   * @param {Object} startColor - Start color { r, g, b }
+   * @param {Object} endColor - End color { r, g, b }
+   * @returns {Function} Updater function
+   */
+  colorOverLife: (startColor, endColor) => (p, dt) => {
+    const t = p.progress;
+    p.color.r = Math.floor(startColor.r + (endColor.r - startColor.r) * t);
+    p.color.g = Math.floor(startColor.g + (endColor.g - startColor.g) * t);
+    p.color.b = Math.floor(startColor.b + (endColor.b - startColor.b) * t);
+  },
+
+  /**
+   * Add random wobble to velocity.
+   * @param {number} [strength=10] - Wobble strength
+   * @returns {Function} Updater function
+   */
+  wobble: (strength = 10) => (p, dt) => {
+    p.vx += (Math.random() - 0.5) * strength * dt;
+    p.vy += (Math.random() - 0.5) * strength * dt;
+  },
+
+  /**
+   * Bounce off screen boundaries.
+   * @param {Object} bounds - Boundary { left, right, top, bottom }
+   * @param {number} [bounce=0.8] - Bounce factor (0-1)
+   * @returns {Function} Updater function
+   */
+  bounds: (bounds, bounce = 0.8) => (p, dt) => {
+    if (p.x < bounds.left) {
+      p.x = bounds.left;
+      p.vx = Math.abs(p.vx) * bounce;
+    } else if (p.x > bounds.right) {
+      p.x = bounds.right;
+      p.vx = -Math.abs(p.vx) * bounce;
+    }
+
+    if (p.y < bounds.top) {
+      p.y = bounds.top;
+      p.vy = Math.abs(p.vy) * bounce;
+    } else if (p.y > bounds.bottom) {
+      p.y = bounds.bottom;
+      p.vy = -Math.abs(p.vy) * bounce;
+    }
+  },
+
+  /**
+   * Attract particles toward a point.
+   * @param {Object} target - Target position { x, y, z }
+   * @param {number} [strength=100] - Attraction strength
+   * @returns {Function} Updater function
+   */
+  attract: (target, strength = 100) => (p, dt) => {
+    const dx = target.x - p.x;
+    const dy = target.y - p.y;
+    const dz = (target.z ?? 0) - p.z;
+    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (dist > 1) {
+      const force = strength * dt / dist;
+      p.vx += dx * force;
+      p.vy += dy * force;
+      p.vz += dz * force;
+    }
+  },
+};

package/src/shapes/arc.js

@@ -0,0 +1,43 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+/**
+ * Arc - A circular arc (partial circle outline) without connecting to center.
+ */
+export class Arc extends Shape {
+  /**
+   *
+   * @param {number} x
+   * @param {number} y
+   * @param {number} radius
+   * @param {number} startAngle - In radians
+   * @param {number} endAngle - In radians
+   * @param {object} options - Style options
+   */
+  constructor(radius, startAngle, endAngle, options = {}) {
+    super(options);
+    this.radius = radius;
+    this.startAngle = startAngle;
+    this.endAngle = endAngle;
+  }
+
+  draw() {
+    super.draw();
+    Painter.lines.beginPath();
+    Painter.shapes.arc(0, 0, this.radius, this.startAngle, this.endAngle, false);
+
+    if (this.stroke) {
+      Painter.colors.stroke(this.stroke, this.lineWidth);
+    }
+  }
+
+  getBounds() {
+    const r = this.radius;
+    return {
+      x: this.x,
+      y: this.y,
+      width: r * 2,
+      height: r * 2,
+    };
+  }
+}

package/src/shapes/arrow.js

@@ -0,0 +1,33 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+export class Arrow extends Shape {
+  constructor(length, options = {}) {
+    super(options);
+    this.length = length;
+  }
+
+  draw() {
+    super.draw();
+    const halfW = this.width / 2;
+    const headLength = this.length * 0.4;
+    const shaftLength = this.length - headLength;
+
+    Painter.lines.beginPath();
+    Painter.lines.moveTo(-shaftLength / 2, -halfW);
+    Painter.lines.lineTo(shaftLength / 2, -halfW);
+    Painter.lines.lineTo(shaftLength / 2, -this.width);
+    Painter.lines.lineTo(this.length / 2, 0);
+    Painter.lines.lineTo(shaftLength / 2, this.width);
+    Painter.lines.lineTo(shaftLength / 2, halfW);
+    Painter.lines.lineTo(-shaftLength / 2, halfW);
+    Painter.lines.closePath();
+
+    if (this.color) {
+      Painter.colors.fill(this.color);
+    }
+
+    if (this.stroke) {
+      Painter.colors.stroke(this.stroke, this.lineWidth);
+    }
+  }
+}

package/src/shapes/bezier.js

@@ -0,0 +1,42 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+/**
+ * BezierShape - A shape that renders any custom path using Painter.lines.path().
+ * Great for clouds, blobs, tails, ears, capes, bananas.
+ */
+export class BezierShape extends Shape {
+  /**
+   *
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {Array} path - An array of path commands [['M', x, y], ['C', ...], ['Z']]
+   * @param {object} options - color, stroke, etc
+   */
+  constructor(path = [], options = {}) {
+    //this.logger.log("new Bezier", options);
+    super(options);
+    this.path = path;
+  }
+
+  draw() {
+    super.draw();
+    Painter.lines.path(
+      this.path,
+      this.color,
+      this.stroke,
+      this.lineWidth
+    );
+  }
+
+  getBounds() {
+    // Not calculated from path (too complex); just approximate
+    const s = 50;
+    return {
+      x: this.x,
+      y: this.y,
+      width: s * 2,
+      height: s * 2,
+    };
+  }
+}