💥 SWParticle Reference

/*
File: swParticle.js
Date: 2026-05-13
Author: klp + GitHub Copilot
Workspace: SketchWaveTNT2026-05-01-Stg9
Purpose: SWParticle class for SketchWaveJS

SWParticle represents a single physics-driven particle for explosion, fire, confetti,
sparks, and other burst or emitter effects. Each particle launches from a spawn point
with a random velocity, decelerates under configurable drag, accelerates downward under
gravity, and fades out as its alpha decreases each frame. When alpha reaches zero the
particle is "dead" and should be removed from your array.

Physics model (applied once per call to update()):
  vel  *= drag          — velocity drag (slows the particle over time)
  vel  += acc           — constant acceleration (gravity, always pointing down)
  pos  += vel           — position update
  alpha -= alphaDecay   — fade out

Typical usage pattern:
  // Spawn a burst of 100 particles at the click position
  for (let i = 0; i < 100; i++) {
    particles.push(new SWParticle(mouseX, mouseY, { hueMin: 0, hueMax: 30 }));
  }

  // In draw():
  for (let i = particles.length - 1; i >= 0; i--) {
    particles[i].update();
    particles[i].draw();
    if (particles[i].isDead()) particles.splice(i, 1);
  }

Constructor:
  new SWParticle(x, y, options)

  x, y    : number  — spawn position in canvas pixel coordinates
  options :
    speedMin   : number  — min initial speed in pixels/frame (default 5)
    speedMax   : number  — max initial speed in pixels/frame (default 20)
    gravity    : number  — downward acceleration per frame in pixels (default 0.15)
    drag       : number  — velocity multiplier per frame, 0–1 (default 0.95)
    alphaDecay : number  — alpha reduction per frame on 0–100 scale (default 1.5)
    sizeMin    : number  — min particle diameter in pixels (default 4)
    sizeMax    : number  — max particle diameter in pixels (default 20)
    hueMin     : number  — min HSB hue, 0–360 (default 0)
    hueMax     : number  — max HSB hue, 0–360 (default 30)
    saturation : number  — HSB saturation, 0–100 (default 100)
    brightness : number  — HSB brightness, 0–100 (default 100)
    shape          : string  — 'circle' | 'square' | 'star' | 'mix' (default 'circle')
    starPointsMin  : number  — min star points for random selection, 3–9 (default 3)
    starPointsMax  : number  — max star points for random selection, 3–9 (default 6)
    angle          : number  — fixed launch angle in radians (default: random full circle)
    spread         : number  — angular spread in radians around angle (default: TWO_PI)
    rotSpeedMin    : number  — min rotation speed in radians/frame (default -0.15)
    rotSpeedMax    : number  — max rotation speed in radians/frame (default  0.15)

  'mix' shape: each particle randomly resolves to circle, square, or star at spawn time.
  Star geometry: outer radius = size/2, inner radius = outer * 0.45, points chosen
  randomly between starPointsMin and starPointsMax each time a star particle spawns.

Key methods:
  update()              — advance physics one frame; call once per frame
  draw()                — draw at current pixel position (primary draw method)
  drawOnGrid(grid)      — draw with position converted via grid.screenToUser()
  isDead()              — returns true when alpha ≤ 0 (particle fully faded)
  finished()            — alias for isDead() (backward compatibility)
  reset(x, y)           — respawn at (x, y) with fresh random vel/size/hue/alpha
  setGravity(g)         — update gravity acceleration
  setDrag(d)            — update drag coefficient
  setAlphaDecay(a)      — update alpha decay rate
  setHueRange(min, max) — update hue range
  setSizeRange(min, max)— update size range
  setSpeedRange(min, max)— update speed range
  setDirectionAngle(angle, spread) — fix launch direction with optional spread
  setShape(shape)            — change particle shape ('circle' | 'square' | 'star' | 'mix')
  setRotationSpeed(min, max) — set spin speed range for square and star particles (rad/frame)

Dependencies: p5.js, SWColor, SWPoint, SWDisk, SWGrid
*/

console.log("[swParticle.js] SWParticle class loaded.");

class SWParticle {

    /**
     * Creates a new particle at the given pixel coordinates.
     *
     * @param {number}  x           - Spawn x in canvas pixel coordinates
     * @param {number}  y           - Spawn y in canvas pixel coordinates
     * @param {Object}  [options={}]
     *   speedMin   : number  — min initial speed in pixels/frame (default 5)
     *   speedMax   : number  — max initial speed in pixels/frame (default 20)
     *   gravity    : number  — downward acceleration per frame (default 0.15)
     *   drag       : number  — velocity damping per frame, 0–1 (default 0.95)
     *   alphaDecay : number  — alpha lost per frame on 0–100 scale (default 1.5)
     *   sizeMin    : number  — minimum particle diameter in pixels (default 4)
     *   sizeMax    : number  — maximum particle diameter in pixels (default 20)
     *   hueMin     : number  — minimum HSB hue, 0–360 (default 0)
     *   hueMax     : number  — maximum HSB hue, 0–360 (default 30)
     *   saturation : number  — HSB saturation, 0–100 (default 100)
     *   brightness : number  — HSB brightness, 0–100 (default 100)
     *   shape         : string  — 'circle' | 'square' | 'star' | 'mix' (default 'circle')
     *   starPointsMin : number  — min star points when shape is 'star' or 'mix' (default 3)
     *   starPointsMax : number  — max star points when shape is 'star' or 'mix' (default 6)
     *   angle         : number  — fixed launch angle in radians (default: random)
     *   spread        : number  — angular spread in radians around angle (default TWO_PI)
     *   rotSpeedMin   : number  — min rotation speed in radians/frame (default -0.15)
     *   rotSpeedMax   : number  — max rotation speed in radians/frame (default  0.15)
     */
    constructor(x, y, options = {}) {
        this.speedMin      = options.speedMin      !== undefined ? options.speedMin      : 5;
        this.speedMax      = options.speedMax      !== undefined ? options.speedMax      : 20;
        this.gravity       = options.gravity       !== undefined ? options.gravity       : 0.15;
        this.drag          = options.drag          !== undefined ? options.drag          : 0.95;
        this.alphaDecay    = options.alphaDecay    !== undefined ? options.alphaDecay    : 1.5;
        this.sizeMin       = options.sizeMin       !== undefined ? options.sizeMin       : 4;
        this.sizeMax       = options.sizeMax       !== undefined ? options.sizeMax       : 20;
        this.hueMin        = options.hueMin        !== undefined ? options.hueMin        : 0;
        this.hueMax        = options.hueMax        !== undefined ? options.hueMax        : 30;
        this.saturation    = options.saturation    !== undefined ? options.saturation    : 100;
        this.brightness    = options.brightness    !== undefined ? options.brightness    : 100;
        this.shape         = options.shape         !== undefined ? options.shape         : 'circle';
        this.starPointsMin = options.starPointsMin !== undefined ? options.starPointsMin : 3;
        this.starPointsMax = options.starPointsMax !== undefined ? options.starPointsMax : 6;
        this.rotSpeedMin   = options.rotSpeedMin   !== undefined ? options.rotSpeedMin   : -0.15;
        this.rotSpeedMax   = options.rotSpeedMax   !== undefined ? options.rotSpeedMax   :  0.15;
        this._angle        = options.angle;                 // undefined = random each time
        this._spread       = options.spread !== undefined   ? options.spread : TWO_PI;

        // Store original spawn point for reset() with no arguments
        this._spawnX = x;
        this._spawnY = y;

        // Live physics state — initialized by _init()
        this.pos        = null;
        this.vel        = null;
        this.acc        = null;
        this.alpha      = 100;
        this.size       = 0;
        this.hue        = 0;
        this._resolvedShape = this.shape; // resolved concrete shape (no 'mix')
        this._starPoints    = 5;          // point count for star, set in _init()
        this._rot           = 0;          // current rotation angle (radians)
        this._rotVel        = 0;          // rotation velocity (radians/frame)

        this._init(x, y);
    }//end constructor

    // ── Internal ──────────────────────────────────────────────────────────

    /**
     * Initializes (or re-initializes) all live physics state with fresh random values.
     * Called by the constructor and by reset().
     * @param {number} x  - spawn x in pixel coordinates
     * @param {number} y  - spawn y in pixel coordinates
     */
    _init(x, y) {
        this.pos   = createVector(x, y);
        this.acc   = createVector(0, this.gravity);
        this.alpha = 100;
        this.size  = random(this.sizeMin, this.sizeMax);
        this.hue   = random(this.hueMin, this.hueMax);

        // Resolve 'mix' to a concrete shape for this particle's lifetime
        if (this.shape === 'mix') {
            const shapes = ['circle', 'square', 'star'];
            this._resolvedShape = shapes[Math.floor(random(shapes.length))];
        } else {
            this._resolvedShape = this.shape;
        }

        // Pick a random star point count within the configured range
        this._starPoints = Math.round(random(
            Math.max(3, this.starPointsMin),
            Math.min(9, this.starPointsMax)
        ));

        // Launch velocity: random direction, or within a spread cone around a fixed angle
        const speed = random(this.speedMin, this.speedMax);
        let launchAngle;
        if (this._angle !== undefined) {
            launchAngle = this._angle + random(-this._spread / 2, this._spread / 2);
        } else {
            launchAngle = random(TWO_PI);
        }
        this.vel = createVector(
            cos(launchAngle) * speed,
            sin(launchAngle) * speed
        );

        // Rotation state — randomized each spawn for square and star particles
        this._rot    = random(TWO_PI);
        this._rotVel = random(this.rotSpeedMin, this.rotSpeedMax);
    }//_init

    // ── Physics ───────────────────────────────────────────────────────────

    /**
     * Advances the particle physics one frame.
     * Applies drag to velocity, adds gravitational acceleration,
     * moves the position, and decrements alpha.
     * Call once per frame before draw().
     */
    update() {
        this.vel.mult(this.drag);
        this.vel.add(this.acc);
        this.pos.add(this.vel);
        this.alpha -= this.alphaDecay;
        this._rot  += this._rotVel;
    }//end update

    // ── Rendering ─────────────────────────────────────────────────────────

    /**
     * Draws the particle at its current canvas pixel position.
     * Requires p5.js colorMode(HSB, 360, 100, 100, 100).
     */
    draw() {
        const safeAlpha = Math.max(0, this.alpha);
        const pColor = new SWColor(this.hue, this.saturation, this.brightness, safeAlpha);
        const r = this.size / 2;

        if (this._resolvedShape === 'square') {
            push();
            colorMode(HSB, 360, 100, 100, 100);
            fill(this.hue, this.saturation, this.brightness, safeAlpha);
            noStroke();
            translate(this.pos.x, this.pos.y);
            rotate(this._rot);
            rectMode(CENTER);
            rect(0, 0, this.size, this.size);
            pop();
        } else if (this._resolvedShape === 'star') {
            push();
            colorMode(HSB, 360, 100, 100, 100);
            fill(this.hue, this.saturation, this.brightness, safeAlpha);
            noStroke();
            translate(this.pos.x, this.pos.y);
            rotate(this._rot);
            SWParticle._drawStar(0, 0, r * 0.45, r, this._starPoints);
            pop();
        } else {
            // Default: circle
            const pt   = new SWPoint(this.pos.x, this.pos.y);
            const disk = new SWDisk(pt, r, 0, pColor);
            disk.setShowCenter(false);
            disk.draw();
        }
    }//end draw

    /**
     * Draws the particle with its position converted from pixel coordinates
     * to user/grid coordinates via the provided SWGrid.
     *
     * Because particles move in pixel space, this method uses grid.screenToUser()
     * to find the current user-space position, then converts the pixel-sized radius
     * to user units via grid.xScale before rendering.
     *
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        const safeAlpha = Math.max(0, this.alpha);
        const pColor = new SWColor(this.hue, this.saturation, this.brightness, safeAlpha);

        // Convert pixel position to user coordinates
        const uc = grid.screenToUser(this.pos.x, this.pos.y);
        // Convert pixel radius to user units using the grid's horizontal scale
        const rUser = (this.size / 2) / grid.xScale;

        if (this._resolvedShape === 'square') {
            const screenPt = grid.userToScreen(uc.x, uc.y);
            push();
            colorMode(HSB, 360, 100, 100, 100);
            fill(this.hue, this.saturation, this.brightness, safeAlpha);
            noStroke();
            translate(screenPt.x, screenPt.y);
            rotate(this._rot);
            rectMode(CENTER);
            rect(0, 0, this.size, this.size);
            pop();
        } else if (this._resolvedShape === 'star') {
            const screenPt = grid.userToScreen(uc.x, uc.y);
            push();
            colorMode(HSB, 360, 100, 100, 100);
            fill(this.hue, this.saturation, this.brightness, safeAlpha);
            noStroke();
            translate(screenPt.x, screenPt.y);
            rotate(this._rot);
            SWParticle._drawStar(0, 0, rUser * 0.45 * grid.xScale, rUser * grid.xScale, this._starPoints);
            pop();
        } else {
            const pt   = new SWPoint(uc.x, uc.y);
            const disk = new SWDisk(pt, rUser, 0, pColor);
            disk.setShowCenter(false);
            disk.drawOnGrid(grid);
        }
    }//end drawOnGrid

    // ── Lifecycle ─────────────────────────────────────────────────────────

    /**
     * Returns true when the particle has fully faded out (alpha ≤ 0).
     * Check this after update() and remove dead particles from your array.
     * @returns {boolean}
     */
    isDead() {
        return this.alpha <= 0;
    }//end isDead

    /**
     * Alias for isDead(). Provided for backward compatibility with sketches
     * that used the original Particle class from Crosby's Bomb Saga.
     * @returns {boolean}
     */
    finished() {
        return this.isDead();
    }//end finished

    /**
     * Respawns the particle at a new position with fresh random velocity,
     * size, hue, and full alpha. All physics constants (gravity, drag, etc.)
     * are preserved from construction.
     * @param {number} [x] - new spawn x in pixel coords (defaults to original spawn x)
     * @param {number} [y] - new spawn y in pixel coords (defaults to original spawn y)
     */
    reset(x, y) {
        this._init(
            x !== undefined ? x : this._spawnX,
            y !== undefined ? y : this._spawnY
        );
    }//end reset

    // ── Setters ───────────────────────────────────────────────────────────

    /**
     * Set gravity (downward acceleration added to velocity each frame, in pixels).
     * @param {number} g
     */
    setGravity(g) {
        this.gravity = g;
        this.acc = createVector(0, g);
    }//end setGravity

    /**
     * Set drag (velocity multiplier applied each frame; 0 = instant stop, 1 = no drag).
     * @param {number} d
     */
    setDrag(d) {
        this.drag = d;
    }//end setDrag

    /**
     * Set the alpha decay rate (alpha units lost per frame on 0–100 scale).
     * Higher values make particles disappear faster.
     * @param {number} a
     */
    setAlphaDecay(a) {
        this.alphaDecay = a;
    }//end setAlphaDecay

    /**
     * Set the HSB hue range. New particles spawned after this call will use the updated range.
     * @param {number} minHue  — 0–360
     * @param {number} maxHue  — 0–360
     */
    setHueRange(minHue, maxHue) {
        this.hueMin = minHue;
        this.hueMax = maxHue;
    }//end setHueRange

    /**
     * Set the particle diameter range in pixels.
     * @param {number} minSize
     * @param {number} maxSize
     */
    setSizeRange(minSize, maxSize) {
        this.sizeMin = minSize;
        this.sizeMax = maxSize;
    }//end setSizeRange

    /**
     * Set the initial speed range in pixels/frame.
     * @param {number} minSpeed
     * @param {number} maxSpeed
     */
    setSpeedRange(minSpeed, maxSpeed) {
        this.speedMin = minSpeed;
        this.speedMax = maxSpeed;
    }//end setSpeedRange

    /**
     * Fix the launch direction. Pass undefined as angle to restore full random direction.
     * @param {number|undefined} angle   - launch angle in radians (undefined = random)
     * @param {number}           [spread=TWO_PI] - angular spread in radians around angle
     */
    setDirectionAngle(angle, spread = TWO_PI) {
        this._angle  = angle;
        this._spread = spread;
    }//end setDirectionAngle

    /**
     * Set the particle shape.
     * @param {string} shape  - 'circle' | 'square' | 'star' | 'mix'
     */
    setShape(shape) {
        this.shape = shape;
    }//end setShape

    /**
     * Set the star point count range. Used when shape is 'star' or 'mix'.
     * Values are clamped to [3, 9].
     * @param {number} minPts  - minimum number of star points
     * @param {number} maxPts  - maximum number of star points
     */
    setStarPointsRange(minPts, maxPts) {
        this.starPointsMin = Math.max(3, Math.min(9, minPts));
        this.starPointsMax = Math.max(3, Math.min(9, maxPts));
    }//end setStarPointsRange

    /**
     * Set the rotation speed range for square and star particles (radians/frame).
     * Each spawned square or star picks a random speed in [minSpeed, maxSpeed].
     * Negative values rotate counter-clockwise; positive values rotate clockwise.
     * Circles are symmetric and ignore rotation.
     * @param {number} minSpeed  — most counter-clockwise speed (e.g. -0.3)
     * @param {number} maxSpeed  — most clockwise speed (e.g. 0.3)
     */
    setRotationSpeed(minSpeed, maxSpeed) {
        this.rotSpeedMin = minSpeed;
        this.rotSpeedMax = maxSpeed;
    }//end setRotationSpeed

    // ── Static helper ─────────────────────────────────────────────────────

    /**
     * Draws a star polygon centered at (cx, cy) using p5.js beginShape/vertex.
     * Caller is responsible for setting fill/stroke and any translate before calling.
     * @param {number} cx         - center x
     * @param {number} cy         - center y
     * @param {number} innerRadius
     * @param {number} outerRadius
     * @param {number} npoints    - number of points
     */
    static _drawStar(cx, cy, innerRadius, outerRadius, npoints) {
        const angle = TWO_PI / npoints;
        const halfAngle = angle / 2;
        beginShape();
        for (let a = -HALF_PI; a < TWO_PI - HALF_PI; a += angle) {
            vertex(cx + cos(a) * outerRadius,         cy + sin(a) * outerRadius);
            vertex(cx + cos(a + halfAngle) * innerRadius, cy + sin(a + halfAngle) * innerRadius);
        }
        endShape(CLOSE);
    }//end _drawStar

}//end class SWParticle