@zakkster/lite-scratch-fx 1.0.0

package/src/Palette.js

@@ -0,0 +1,37 @@
+/**
+ * Palette resolution -- the one convention every themeable recipe shares.
+ *
+ * A recipe factory takes `{ colors, theme }` alongside its own options and calls
+ * resolvePalette() ONCE at construction (never on the hot path) to pick its ramp:
+ *
+ *   colors  string[]                 an explicit ramp -- wins outright
+ *   theme   { light, mid, dark }     shorthand; mapped to [light, mid, dark]
+ *   (else)  the recipe's own default literal
+ *
+ * Multi-colour recipes index the returned array by a per-particle colour index;
+ * single-colour recipes use ramp[0]. Host code that threads one {light, mid, dark}
+ * triple through every effect gets consistent theming without importing 14 factories.
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+/**
+ * @param {string[]} [colors]                  explicit ramp; highest precedence
+ * @param {{light?:string, mid?:string, dark?:string}} [theme]  shorthand ramp
+ * @param {string[]} fallback                  the recipe's default ramp
+ * @returns {string[]} a non-empty ramp of CSS colour strings
+ */
+export function resolvePalette(colors, theme, fallback) {
+    if (Array.isArray(colors) && colors.length > 0) return colors;
+    if (theme) {
+        const ramp = [];
+        if (theme.light) ramp.push(theme.light);
+        if (theme.mid) ramp.push(theme.mid);
+        if (theme.dark) ramp.push(theme.dark);
+        if (ramp.length > 0) return ramp;
+    }
+    return fallback;
+}
+
+export default resolvePalette;

package/src/ScratchController.js

@@ -0,0 +1,211 @@
+/**
+ * ScratchController -- one-shot scratch-card reveal engine.
+ *
+ * Mounts a reveal recipe, scans the remaining visible pixels of the scratch layer for
+ * spawn points, delegates physics + rendering to the recipe, and auto-cleans up on
+ * completion. The particle engine owns its own requestAnimationFrame loop.
+ *
+ * Recipe interface:
+ *   {
+ *     count,                                      // particles to spawn (0 = pure canvas)
+ *     init(ctx, capacity, w, h),                  // allocate per-particle arrays
+ *     spawn(idx, rng, w, h, spot),                // -> { x, y, vx, vy, life }
+ *     tick(dt, elapsedMs, engine, ctx, src, w, h),// -> true when the effect is complete
+ *     destroy(),                                  // release arrays
+ *   }
+ *
+ * `spot` is a SHARED, MUTABLE object reused for every spawn call in a reveal. A recipe
+ * must read `spot.x` / `spot.y` synchronously inside `spawn` (as all built-ins do) and
+ * never retain the reference -- the next spawn overwrites it in place. This is what keeps
+ * the reveal-start frame allocation-free: no per-pixel `{x, y}` literals.
+ *
+ * Depends on:
+ *   @zakkster/lite-soa-particle-engine
+ *   @zakkster/lite-random
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+import { SoaParticleEngine } from '@zakkster/lite-soa-particle-engine';
+import { Random }            from '@zakkster/lite-random';
+
+/**
+ * @param {HTMLCanvasElement} sourceCanvas  The scratch layer being revealed
+ * @param {HTMLCanvasElement} effectCanvas  Overlay canvas for VFX
+ * @param {Object} [options]
+ */
+export function createScratchController(sourceCanvas, effectCanvas, {
+    maxParticles = 2000,
+    seed = Date.now(),
+    scanPrecision = 32,
+} = {}) {
+    const ctx = effectCanvas.getContext('2d');
+    const engine = new SoaParticleEngine(maxParticles);
+    const rng = new Random(seed);
+    // The SoA engine owns its own requestAnimationFrame loop: start() schedules it, stop()
+    // cancels it, and it computes dt internally. The controller must NOT also drive
+    // engine._loop from an external ticker -- that double-drives the loop and corrupts its
+    // dt, which breaks both particle life decay and completion detection. (An earlier
+    // version accepted a `sharedTicker` and did exactly that; it is removed.)
+
+    let activeRecipe = null;
+    let destroyed = false;
+    let elapsed = 0;
+    let onComplete = null;
+
+    // ── Reveal-scan scratch, all allocated ONCE (zero-GC on the reveal-start frame) ──
+    // The offscreen scan canvas, its context, and the spawn-point arrays are built here
+    // and reused across every reveal. Only getImageData() -- a single small typed array
+    // per reveal, mandated by the 2D canvas API -- is not reusable; the per-pixel object
+    // churn of the previous design (one `{x, y}` literal per surviving pixel) is gone.
+    let scanCanvas = null;
+    let scanCtx = null;
+    let scanW = 0, scanH = 0;
+    let spotX = new Float32Array(0);   // grown lazily if the source canvas is ever resized
+    let spotY = new Float32Array(0);
+    let spotCount = 0;
+    const spot = { x: 0.5, y: 0.5 };   // the single shared, reused spawn point
+
+    function ensureScanBuffers(precision) {
+        const srcW = sourceCanvas.width || sourceCanvas.offsetWidth || 1;
+        const srcH = sourceCanvas.height || sourceCanvas.offsetHeight || 1;
+        const h = Math.max(1, Math.floor(srcH * (precision / srcW)));
+        if (scanCanvas && scanW === precision && scanH === h) return;
+        // Dims changed (or first run): (re)build. Off the hot path -- once per resize.
+        scanW = precision;
+        scanH = h;
+        if (!scanCanvas) {
+            scanCanvas = document.createElement('canvas');
+            scanCtx = scanCanvas.getContext('2d', { willReadFrequently: true });
+        }
+        scanCanvas.width = scanW;
+        scanCanvas.height = scanH;
+        const cap = scanW * scanH;
+        if (spotX.length < cap) {
+            spotX = new Float32Array(cap);
+            spotY = new Float32Array(cap);
+        }
+    }
+
+    // ── Scan remaining visible pixels from the scratch canvas into spotX/spotY ──
+    // Fills the preallocated arrays and sets spotCount. Allocates nothing per pixel.
+    function scanPixels(precision = scanPrecision) {
+        ensureScanBuffers(precision);
+        scanCtx.clearRect(0, 0, scanW, scanH);
+        scanCtx.drawImage(sourceCanvas, 0, 0, scanW, scanH);
+        const data = scanCtx.getImageData(0, 0, scanW, scanH).data;
+        let n = 0;
+        for (let i = 3; i < data.length; i += 4) {
+            if (data[i] > 128) {
+                const p = (i - 3) / 4;
+                spotX[n] = (p % scanW) / scanW;
+                spotY[n] = ((p / scanW) | 0) / scanH;
+                n++;
+            }
+        }
+        spotCount = n;
+    }
+
+    // The particle-view object handed to recipe.tick every frame. Built ONCE and
+    // reused: the engine's SoA arrays are stable references for the life of the engine,
+    // so a fresh `{ x, y, ... }` literal per frame would be a pure zero-GC violation on
+    // the hottest path in the package. Reassign the fields each frame (free) instead.
+    let pView = null;
+
+    // ── Render callback (the engine calls this every frame with raw SoA arrays) ──
+    engine.onTick((dt, x, y, vx, vy, life, invLife, data, max) => {
+        if (destroyed || !activeRecipe) return;
+        elapsed += dt;
+        const w = effectCanvas.width;
+        const h = effectCanvas.height;
+        ctx.clearRect(0, 0, w, h);
+
+        if (pView === null) {
+            pView = { x, y, vx, vy, life, invLife, data, max };
+        } else {
+            pView.x = x; pView.y = y; pView.vx = vx; pView.vy = vy;
+            pView.life = life; pView.invLife = invLife; pView.data = data; pView.max = max;
+        }
+
+        // Delegate everything to the recipe. Returns true when done.
+        const isFinished = activeRecipe.tick(
+            dt, elapsed * 1000, pView, ctx, sourceCanvas, w, h,
+        );
+
+        if (isFinished) {
+            engine.stop();
+            if (activeRecipe.destroy) activeRecipe.destroy();
+            activeRecipe = null;
+            ctx.clearRect(0, 0, w, h);
+            const done = onComplete;
+            onComplete = null;
+            if (done) done();
+        }
+    });
+
+    return {
+        /**
+         * Execute a reveal recipe.
+         * @param {Object} recipe
+         * @param {Function} [onDone]  Called when the effect completes
+         */
+        reveal(recipe, onDone) {
+            if (destroyed || activeRecipe) return;
+
+            activeRecipe = recipe;
+            onComplete = onDone || null;
+            elapsed = 0;
+            engine.clear();
+
+            // Size the effect canvas to match the scratch layer
+            const w = effectCanvas.width = sourceCanvas.offsetWidth || sourceCanvas.width;
+            const h = effectCanvas.height = sourceCanvas.offsetHeight || sourceCanvas.height;
+
+            // Scan spawn points from visible pixels (fills spotX/spotY, sets spotCount).
+            scanPixels();
+
+            // Init recipe
+            recipe.init(ctx, maxParticles, w, h);
+
+            // Populate ring buffer. A recipe may declare `count: 0` (a pure-canvas reveal
+            // like Shine or Implosion that draws no particles); use ?? so an explicit 0 is
+            // honoured rather than falling back to maxParticles.
+            const requested = recipe.count ?? maxParticles;
+            const count = Math.min(requested, maxParticles);
+            for (let i = 0; i < count; i++) {
+                const idx = engine._head;
+                if (spotCount > 0) {
+                    const k = rng.int(0, spotCount - 1);
+                    spot.x = spotX[k];
+                    spot.y = spotY[k];
+                } else {
+                    spot.x = 0.5;
+                    spot.y = 0.5;
+                }
+                const state = recipe.spawn(idx, rng, w, h, spot);
+                engine.emit(state.x, state.y, state.vx, state.vy, state.life, idx);
+            }
+
+            // The engine owns its RAF loop; start() schedules it and drives onTick.
+            engine.start();
+        },
+
+        /** Re-seed the RNG. */
+        seed(s) { rng.reset(s); },
+
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            engine.stop();
+            if (activeRecipe && activeRecipe.destroy) activeRecipe.destroy();
+            activeRecipe = null;
+            onComplete = null;
+            scanCanvas = null;
+            scanCtx = null;
+            engine.destroy();
+        },
+    };
+}
+
+export default createScratchController;