@zakkster/lite-scratch-fx 1.0.0 → 1.2.0

package/src/ScratchStage.js

@@ -0,0 +1,192 @@
+/**
+ * ScratchStage -- concurrent scratch-card reveals over ONE shared particle pool.
+ *
+ * A stage owns a single raw SoaParticleEngine and hands each controller a fixed,
+ * contiguous sub-range of its lanes. Any number of controllers can reveal at the same
+ * time, all rendering from one pool, driven by one clock -- so a grid of scratch boxes
+ * holds one lane pool instead of one per box.
+ *
+ * See decisions/0001-concurrent-shared-reveals.md for why this needs no engine change:
+ * raw-mode tick(dt) is pure dispatch (no physics, no culling), the lanes are public typed
+ * arrays the recipes already write, and each controller owns disjoint slots.
+ *
+ *   const stage = createScratchStage({ maxParticles: 1500, seed: 1 });
+ *   const boxes = cards.map((c) => stage.createController(c.scratch, c.fx, { capacity: 200 }));
+ *   // one clock drives the grid; many boxes reveal at once, one pool:
+ *   function frame(now) { const dt = (now - last) / 1000; last = now; stage.tick(dt);
+ *                         requestAnimationFrame(frame); }
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+import { SoaParticleEngine } from '@zakkster/lite-soa-particle-engine';
+import { Random }            from '@zakkster/lite-random';
+import { createPixelScanner } from './PixelScan.js';
+
+/**
+ * @param {Object} [options]
+ * @param {number} [options.maxParticles=2000]  Total shared pool capacity.
+ * @param {number} [options.seed=Date.now()]     Base seed; each controller derives its own.
+ */
+export function createScratchStage({ maxParticles = 2000, seed = Date.now() } = {}) {
+    const engine = new SoaParticleEngine(maxParticles);
+    const active = new Set();
+    let nextStart = 0;
+    let controllerCount = 0;
+    let destroyed = false;
+
+    // One render dispatch for the whole pool. Raw tick(dt) hands us the lanes and `max`;
+    // we ignore them (each controller holds stable subarray views of its own sub-range) and
+    // fan out to every active reveal. A Set copy is avoided: a controller that completes
+    // removes itself, so iterate a snapshot to stay safe against mid-iteration deletion.
+    engine.onTick((dt) => {
+        if (destroyed || active.size === 0) return;
+        for (const c of active) c._frame(dt);
+    });
+
+    /**
+     * Reserve a sub-range and return a stage-managed controller. The stage drives it; the
+     * controller has no tick() of its own.
+     * @param {HTMLCanvasElement} sourceCanvas
+     * @param {HTMLCanvasElement} effectCanvas
+     * @param {Object} [opts]
+     * @param {number} [opts.capacity=300]      Slots reserved for this controller's particles.
+     * @param {number} [opts.seed]              RNG seed; defaults to base seed + index.
+     * @param {number} [opts.scanPrecision=32]  Pixel-scan resolution.
+     */
+    function createController(sourceCanvas, effectCanvas, { capacity = 300, seed: cSeed, scanPrecision = 32 } = {}) {
+        if (destroyed) throw new Error('createScratchStage: stage is destroyed');
+        if (!(Number.isInteger(capacity) && capacity >= 0)) {
+            throw new TypeError('createController: capacity must be a non-negative integer');
+        }
+        if (nextStart + capacity > maxParticles) {
+            throw new RangeError(
+                `createController: pool exhausted -- ${nextStart}+${capacity} exceeds maxParticles ${maxParticles}`,
+            );
+        }
+        const start = nextStart;
+        nextStart += capacity;
+        const index = controllerCount++;
+
+        const ctx = effectCanvas.getContext('2d');
+        const rng = new Random(cSeed ?? (seed + index));
+        const scanner = createPixelScanner(sourceCanvas);
+
+        // Stable subarray views of this controller's sub-range, built ONCE (the engine's
+        // lanes are fixed for its life). Reused every frame -> zero per-frame allocation.
+        const end = start + capacity;
+        const pView = {
+            x: engine.x.subarray(start, end),
+            y: engine.y.subarray(start, end),
+            vx: engine.vx.subarray(start, end),
+            vy: engine.vy.subarray(start, end),
+            life: engine.life.subarray(start, end),
+            invLife: engine.invLife.subarray(start, end),
+            data: engine.data.subarray(start, end),
+            max: 0,
+        };
+        const spot = { x: 0.5, y: 0.5 };
+
+        let activeRecipe = null;
+        let onComplete = null;
+        let elapsed = 0;
+        let cw = 0, ch = 0;
+        let ctlDestroyed = false;
+
+        const controller = {
+            /** Reveal a recipe. Ignored if this controller is already revealing or destroyed. */
+            reveal(recipe, onDone) {
+                if (ctlDestroyed || activeRecipe) return;
+                activeRecipe = recipe;
+                onComplete = onDone || null;
+                elapsed = 0;
+
+                cw = effectCanvas.width = sourceCanvas.offsetWidth || sourceCanvas.width;
+                ch = effectCanvas.height = sourceCanvas.offsetHeight || sourceCanvas.height;
+
+                const spots = scanner.scan(scanPrecision);
+                recipe.init(ctx, capacity, cw, ch);
+
+                const requested = recipe.count ?? capacity;
+                const count = Math.min(requested, capacity);
+                for (let i = 0; i < count; i++) {
+                    if (spots.count > 0) {
+                        const k = rng.int(0, spots.count - 1);
+                        spot.x = spots.spotX[k];
+                        spot.y = spots.spotY[k];
+                    } else {
+                        spot.x = 0.5;
+                        spot.y = 0.5;
+                    }
+                    const state = recipe.spawn(i, rng, cw, ch, spot);
+                    const g = start + i;
+                    engine.x[g] = state.x;
+                    engine.y[g] = state.y;
+                    engine.vx[g] = state.vx;
+                    engine.vy[g] = state.vy;
+                    engine.life[g] = state.life;
+                    engine.invLife[g] = 1.0 / state.life;
+                    engine.data[g] = i;   // local index -> the recipe reads data[i] === i in its window
+                }
+                pView.max = count;
+                active.add(controller);
+            },
+
+            /** @internal Called by the stage each frame. */
+            _frame(dt) {
+                if (ctlDestroyed || !activeRecipe) return;
+                elapsed += dt;
+                ctx.clearRect(0, 0, cw, ch);
+                const isFinished = activeRecipe.tick(dt, elapsed * 1000, pView, ctx, sourceCanvas, cw, ch);
+                if (isFinished) {
+                    if (activeRecipe.destroy) activeRecipe.destroy();
+                    activeRecipe = null;
+                    ctx.clearRect(0, 0, cw, ch);
+                    active.delete(controller);
+                    const done = onComplete;
+                    onComplete = null;
+                    if (done) done();
+                }
+            },
+
+            /** Re-seed this controller's RNG. */
+            seed(s) { rng.reset(s); },
+
+            /** Remove this controller from the stage. Its sub-range is not reclaimed (v1). */
+            destroy() {
+                if (ctlDestroyed) return;
+                ctlDestroyed = true;
+                if (activeRecipe && activeRecipe.destroy) activeRecipe.destroy();
+                activeRecipe = null;
+                onComplete = null;
+                active.delete(controller);
+                scanner.destroy();
+            },
+        };
+        return controller;
+    }
+
+    return {
+        createController,
+
+        /** Advance every active reveal one frame. `dt` is in SECONDS. */
+        tick(dt) {
+            if (destroyed) return;
+            engine.tick(dt);
+        },
+
+        /** Stop everything and release the shared engine. Controllers become inert. */
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            active.clear();
+            engine.destroy();
+        },
+
+        /** @internal How many slots are still unreserved (for tests / diagnostics). */
+        get remainingCapacity() { return maxParticles - nextStart; },
+    };
+}
+
+export default createScratchStage;