@zakkster/lite-scratch-fx 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.7.0] - 2026-08-24
+
+Optional per-frame glow cap for the two haloed particle recipes (B-20). Additive and
+backward compatible: the knob defaults to `Infinity` (unlimited), so default output is
+byte-identical to 1.6.0. The per-frame render path gains one counter and one guard.
+
+### Added
+- **`glowBudget` option on `BurnRecipe` and `DragonBreathRecipe` (default `Infinity` =
+  unlimited).** Caps how many particles paint their outer glow halo per frame. Once the
+  budget is spent that tick, further particles draw only their brighter core arc; the
+  counter resets every frame. The core arc, physics, `alive` accounting, and the
+  offscreen cull are never capped. Uses a strict `g < glowBudget` compare (never a falsy
+  coercion), so `glowBudget: 0` means exactly zero halos (cores only) and the unset
+  default `Infinity` keeps every halo. `glowBudget: 80` matches the game's `GLOW_BUDGET`
+  parity. Zero new hot-path allocation.
+
 ## [1.6.0] - 2026-08-23
 
 Reduced-motion support (N-4). Backward compatible: the new controller/stage option

package/README.md

@@ -268,8 +268,12 @@ current built-in look:
 - **`DragonBreathRecipe`** / **`IceBreathRecipe`** -- `spread` (jet half-angle in radians,
   defaults `0.3` / `0.225`), `speedMin`/`speedMax` (spawn speed range, defaults `12`-`25`
   / `15`-`28`).
-- **`PeelRecipe`** / **`ShineWaveRecipe`** -- `ease` (`(t: number) => number`): the easing
-  applied to progress; defaults to the recipe's built-in curve (`easeIn` / `easeInOut`).
+- **`BurnRecipe`** / **`DragonBreathRecipe`** -- `glowBudget` (default `Infinity` =
+  unlimited): a per-frame cap on how many particles paint their outer glow halo. The
+  brighter core arc, physics, and offscreen cull are never capped -- only the halo is
+  skipped once the budget is spent that frame; the counter resets every tick. `0` means
+  zero halos (cores only); `80` matches the game's `GLOW_BUDGET` parity. Default output is
+  byte-identical to earlier versions.
 
 ### Reduced motion
 
@@ -303,7 +307,7 @@ two ways to respond, plus a flag for building a picker.
 
 | Constant                  | Value                                                        | Meaning                                              |
 | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
-| `VERSION`                 | `'1.6.0'`                                                    | Package version string (synced to package.json).     |
+| `VERSION`                 | `'1.7.0'`                                                    | Package version string (synced to package.json).     |
 | `maxParticles` (default)  | `2000`                                                       | Controller / stage pool capacity.                    |
 | `scanPrecision` (default) | `32`                                                         | Horizontal resolution of the spawn-point scan.       |
 | stage `capacity` (default)| `300`                                                       | Slots a stage controller reserves from the pool.     |

package/index.d.ts

@@ -242,11 +242,11 @@ export interface ThemeableRecipeOptions extends RecipeOptions {
     theme?: Theme;
 }
 
-export function BurnRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function BurnRecipe(opts?: ThemeableRecipeOptions & { glowBudget?: number }): Recipe;
 export function ShatterRecipe(opts?: RecipeOptions & { gravity?: number }): Recipe;
 export function DissolveRecipe(opts?: ThemeableRecipeOptions & { fadeSpeed?: number }): Recipe;
 export function ExplodeRecipe(opts?: ThemeableRecipeOptions & { force?: number }): Recipe;
-export function DragonBreathRecipe(opts?: ThemeableRecipeOptions & { spread?: number; speedMin?: number; speedMax?: number }): Recipe;
+export function DragonBreathRecipe(opts?: ThemeableRecipeOptions & { spread?: number; speedMin?: number; speedMax?: number; glowBudget?: number }): Recipe;
 export function IceBreathRecipe(opts?: ThemeableRecipeOptions & { spread?: number; speedMin?: number; speedMax?: number }): Recipe;
 export function ShineWaveRecipe(opts?: ThemeableRecipeOptions & { beamWidth?: number; particleCount?: number; ease?: (t: number) => number }): Recipe;
 export function LightningCrawlRecipe(opts?: ThemeableRecipeOptions & { boltCount?: number }): Recipe;

package/index.js

@@ -13,7 +13,7 @@
 
 // Three-place version sync: this constant, package.json "version", and the top
 // CHANGELOG.md heading must always match. /release keeps them locked.
-export const VERSION = '1.6.0';
+export const VERSION = '1.7.0';
 
 export { createScratchController } from './src/ScratchController.js';
 export { default as ScratchController } from './src/ScratchController.js';

package/llms.txt

@@ -78,8 +78,11 @@ Every factory takes an options bag; all options default to the shipped tuning, s
 no args reproduces the stock effect. Beyond { colors, theme } (the 14 themeable recipes) and
 count/duration, the FX_CONFIG-style knobs are: dissolve fadeSpeed (fade window as a fraction of
 duration); dragonBreath and iceBreath spread / speedMin / speedMax (spawn cone half-angle in
-radians and speed range); peel and shineWave ease (a t -> t easing function). A non-function ease
-falls back to the recipe's default curve.
+radians and speed range); burn and dragonBreath glowBudget (per-frame cap on how many particles
+paint their outer glow halo, default Infinity = unlimited; 0 = zero halos, cores only; 80 =
+game GLOW_BUDGET parity -- the core arc, physics and offscreen cull are never capped and the
+counter resets each tick, so the default output is byte-identical to earlier versions); peel and
+shineWave ease (a t -> t easing function). A non-function ease falls back to the recipe's default curve.
 
 ## Registry, metadata, extension
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-scratch-fx",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "One-shot scratch-card reveal effects on canvas. A controller scans the still-covered pixels of a scratch layer, spawns particles from them, and delegates physics and rendering to a recipe. 21 themeable recipes (burn, shatter, dissolve, glitch, gold dust, cosmic dust, and more), a registry with a register hook, zero GSAP, a zero-GC hot path, deterministic seeded RNG, and a stage that runs a grid of simultaneous reveals over one shared pool.",
   "type": "module",
   "main": "./index.js",

package/src/ScratchRecipes.js

@@ -28,7 +28,7 @@ import {resolvePalette} from './Palette.js';
 //  Spawn particles from the scratch layer's still-covered pixels and run their own physics.
 // ===========================================================================
 
-export function BurnRecipe({count = 100, duration = 200, colors, theme} = {}) {
+export function BurnRecipe({count = 100, duration = 200, glowBudget = Infinity, colors, theme} = {}) {
     let pSize, pDecay, pColorIdx;
     const palette = resolvePalette(colors, theme, ['#ff6b00', '#ff8c00', '#ffaa00', '#ff4500', '#8B0000']);
 
@@ -49,6 +49,7 @@ export function BurnRecipe({count = 100, duration = 200, colors, theme} = {}) {
             const {x, y, vx, vy, life, data, max} = engine;
             const ds = dt * 60;
             let alive = 0;
+            let g = 0;
             const progress = clamp(elapsed / duration, 0, 1);
             src.style.opacity = 1 - easeIn(progress);
 
@@ -63,10 +64,13 @@ export function BurnRecipe({count = 100, duration = 200, colors, theme} = {}) {
                 if (y[i] < -50) continue;
                 ctx.globalCompositeOperation = 'lighter';
                 ctx.fillStyle = palette[pColorIdx[p]];
-                ctx.globalAlpha = life[i] * 0.3;
-                ctx.beginPath();
-                ctx.arc(x[i], y[i], pSize[p] * 2, 0, Math.PI * 2);
-                ctx.fill();
+                if (g < glowBudget) {
+                    ctx.globalAlpha = life[i] * 0.3;
+                    ctx.beginPath();
+                    ctx.arc(x[i], y[i], pSize[p] * 2, 0, Math.PI * 2);
+                    ctx.fill();
+                    g++;
+                }
                 ctx.globalAlpha = life[i];
                 ctx.beginPath();
                 ctx.arc(x[i], y[i], pSize[p], 0, Math.PI * 2);
@@ -171,7 +175,7 @@ export function ExplodeRecipe({count = 80, duration = 750, force = 15, colors, t
 }
 
 
-export function DragonBreathRecipe({count = 200, duration = 1200, spread = 0.3, speedMin = 12, speedMax = 25, colors, theme} = {}) {
+export function DragonBreathRecipe({count = 200, duration = 1200, spread = 0.3, speedMin = 12, speedMax = 25, glowBudget = Infinity, colors, theme} = {}) {
     let pSize, pDecay, pColorIdx, r;
     const palette = resolvePalette(colors, theme, ['#FFF', '#FFD700', '#FF4500', '#8B0000', '#2F2F2F']);
 
@@ -203,6 +207,7 @@ export function DragonBreathRecipe({count = 200, duration = 1200, spread = 0.3,
             const dvy = Math.pow(0.98, ds);
             const dsz = Math.pow(1.04, ds);
             let alive = 0;
+            let g = 0;
             const fadeT = clamp((elapsed - 100) / 400, 0, 1);
             src.style.opacity = 1 - fadeT * fadeT;
 
@@ -220,10 +225,13 @@ export function DragonBreathRecipe({count = 200, duration = 1200, spread = 0.3,
                 if (y[i] < -50) continue;
                 ctx.globalCompositeOperation = 'lighter';
                 ctx.fillStyle = palette[pColorIdx[p]];
-                ctx.globalAlpha = life[i] * 0.3;
-                ctx.beginPath();
-                ctx.arc(x[i], y[i], pSize[p] * 2, 0, Math.PI * 2);
-                ctx.fill();
+                if (g < glowBudget) {
+                    ctx.globalAlpha = life[i] * 0.3;
+                    ctx.beginPath();
+                    ctx.arc(x[i], y[i], pSize[p] * 2, 0, Math.PI * 2);
+                    ctx.fill();
+                    g++;
+                }
                 ctx.globalAlpha = life[i];
                 ctx.beginPath();
                 ctx.arc(x[i], y[i], pSize[p], 0, Math.PI * 2);