@basmilius/sparkle 2.0.0 → 2.2.0

package/src/fireworks/create-explosion.ts

@@ -0,0 +1,237 @@
+import type { Point } from '../point';
+import { Explosion } from './explosion';
+import { EXPLOSION_CONFIGS, type ExplosionType, type FireworkVariant } from './types';
+
+function between(rng: () => number, min: number, max: number): number {
+    return min + rng() * (max - min);
+}
+
+/**
+ * Creates an array of {@link Explosion} particles for the given firework variant.
+ * Use this to fire a fully formed explosion burst in your own render loop without
+ * needing a {@link Fireworks} instance.
+ *
+ * @param variant - The firework variant to create.
+ * @param position - The center position of the explosion in canvas pixels.
+ * @param hue - Base hue in degrees (0–360).
+ * @param options - Optional overrides for `lineWidth` (default `5`) and `scale` (default `1`).
+ * @param rng - RNG function returning values in [0, 1). Defaults to `Math.random`.
+ */
+export function createExplosion(
+    variant: FireworkVariant,
+    position: Point,
+    hue: number,
+    options: { lineWidth?: number; scale?: number } = {},
+    rng: () => number = Math.random
+): Explosion[] {
+    const lineWidth = options.lineWidth ?? 5;
+    const scale = options.scale ?? 1;
+    const explosions: Explosion[] = [];
+
+    switch (variant) {
+        case 'saturn':
+            createSaturn(explosions, position, hue, lineWidth, scale, rng);
+            break;
+        case 'dahlia':
+            createDahlia(explosions, position, hue, lineWidth, scale, rng);
+            break;
+        case 'heart':
+            createHeart(explosions, position, hue, lineWidth, scale, rng);
+            break;
+        case 'spiral':
+            createSpiral(explosions, position, hue, lineWidth, scale, rng);
+            break;
+        case 'flower':
+            createFlower(explosions, position, hue, lineWidth, scale, rng);
+            break;
+        case 'concentric':
+            createConcentric(explosions, position, hue, lineWidth, scale, rng);
+            break;
+        default: {
+            const type: ExplosionType = variant;
+            const config = EXPLOSION_CONFIGS[type];
+            const count = Math.floor(between(rng, config.particleCount[0], config.particleCount[1]));
+            const effectiveHue = type === 'brocade' ? between(rng, 35, 50) : hue;
+
+            for (let i = 0; i < count; i++) {
+                let angle: number | undefined;
+                let speed: number | undefined;
+
+                if (type === 'ring') {
+                    angle = (i / count) * Math.PI * 2;
+                    speed = between(rng, config.speed[0], config.speed[1]) * 0.5 + config.speed[0] * 0.5;
+                } else if (type === 'palm' || type === 'horsetail') {
+                    const spread = type === 'horsetail' ? Math.PI / 8 : Math.PI / 5;
+                    angle = -Math.PI / 2 + between(rng, -spread, spread);
+                }
+
+                explosions.push(new Explosion(position, effectiveHue, lineWidth, type, scale, angle, speed));
+            }
+        }
+    }
+
+    return explosions;
+}
+
+function createSaturn(explosions: Explosion[], position: Point, hue: number, lineWidth: number, scale: number, rng: () => number): void {
+    const velocity = between(rng, 4, 6);
+    const shellCount = Math.floor(between(rng, 25, 35));
+
+    for (let i = 0; i < shellCount; i++) {
+        const rad = (i / shellCount) * Math.PI * 2;
+
+        explosions.push(new Explosion(
+            position, hue, lineWidth, 'peony', scale,
+            rad + between(rng, -0.05, 0.05),
+            velocity + between(rng, -0.25, 0.25)
+        ));
+    }
+
+    const fillCount = Math.floor(between(rng, 40, 60));
+
+    for (let i = 0; i < fillCount; i++) {
+        explosions.push(new Explosion(
+            position, hue, lineWidth, 'peony', scale,
+            between(rng, 0, Math.PI * 2),
+            velocity * between(rng, 0, 1)
+        ));
+    }
+
+    const ringRotation = between(rng, 0, Math.PI * 2);
+    const ringCount = Math.floor(between(rng, 40, 55));
+    const ringVx = velocity * between(rng, 2, 3);
+    const ringVy = velocity * 0.6;
+
+    for (let i = 0; i < ringCount; i++) {
+        const rad = (i / ringCount) * Math.PI * 2;
+        const cx = Math.cos(rad) * ringVx + between(rng, -0.25, 0.25);
+        const cy = Math.sin(rad) * ringVy + between(rng, -0.25, 0.25);
+        const cosR = Math.cos(ringRotation);
+        const sinR = Math.sin(ringRotation);
+        const vx = cx * cosR - cy * sinR;
+        const vy = cx * sinR + cy * cosR;
+        const vz = Math.sin(rad) * velocity * 0.8;
+
+        explosions.push(new Explosion(
+            position, hue + 60, lineWidth, 'ring', scale,
+            Math.atan2(vy, vx),
+            Math.sqrt(vx * vx + vy * vy),
+            vz
+        ));
+    }
+}
+
+function createDahlia(explosions: Explosion[], position: Point, hue: number, lineWidth: number, scale: number, rng: () => number): void {
+    const petalCount = Math.floor(between(rng, 6, 9));
+    const particlesPerPetal = Math.floor(between(rng, 8, 12));
+
+    for (let petal = 0; petal < petalCount; petal++) {
+        const baseAngle = (petal / petalCount) * Math.PI * 2;
+        const petalHue = hue + (petal % 2 === 0 ? 25 : -25);
+
+        for (let i = 0; i < particlesPerPetal; i++) {
+            explosions.push(new Explosion(
+                position, petalHue, lineWidth, 'dahlia', scale,
+                baseAngle + between(rng, -0.3, 0.3)
+            ));
+        }
+    }
+}
+
+function createHeart(explosions: Explosion[], position: Point, hue: number, lineWidth: number, scale: number, rng: () => number): void {
+    const velocity = between(rng, 3, 5);
+    const count = Math.floor(between(rng, 60, 80));
+    const rotation = between(rng, -0.3, 0.3);
+    const cosR = Math.cos(rotation);
+    const sinR = Math.sin(rotation);
+
+    for (let i = 0; i < count; i++) {
+        const t = (i / count) * Math.PI * 2;
+        const hx = 16 * Math.pow(Math.sin(t), 3);
+        const hy = -(13 * Math.cos(t) - 5 * Math.cos(2 * t) - 2 * Math.cos(3 * t) - Math.cos(4 * t));
+        const s = velocity / 16;
+        const vx = hx * s;
+        const vy = hy * s;
+        const rvx = vx * cosR - vy * sinR;
+        const rvy = vx * sinR + vy * cosR;
+
+        explosions.push(new Explosion(
+            position, hue, lineWidth, 'heart', scale,
+            Math.atan2(rvy, rvx),
+            Math.max(0.1, Math.sqrt(rvx * rvx + rvy * rvy) + between(rng, -0.15, 0.15))
+        ));
+    }
+}
+
+function createSpiral(explosions: Explosion[], position: Point, hue: number, lineWidth: number, scale: number, rng: () => number): void {
+    const arms = Math.floor(between(rng, 3, 5));
+    const particlesPerArm = Math.floor(between(rng, 15, 20));
+    const twist = between(rng, 2, 3.5);
+    const baseRotation = between(rng, 0, Math.PI * 2);
+
+    for (let arm = 0; arm < arms; arm++) {
+        const baseAngle = baseRotation + (arm / arms) * Math.PI * 2;
+        const armHue = hue + arm * (360 / arms / 3);
+
+        for (let i = 0; i < particlesPerArm; i++) {
+            const progress = i / particlesPerArm;
+
+            explosions.push(new Explosion(
+                position, armHue, lineWidth, 'spiral', scale,
+                baseAngle + progress * twist,
+                2 + progress * 8 + between(rng, -0.3, 0.3)
+            ));
+        }
+    }
+}
+
+function createFlower(explosions: Explosion[], position: Point, hue: number, lineWidth: number, scale: number, rng: () => number): void {
+    const velocity = between(rng, 4, 7);
+    const count = Math.floor(between(rng, 70, 90));
+    const petals = Math.floor(between(rng, 2, 4));
+    const rotation = between(rng, 0, Math.PI * 2);
+
+    for (let i = 0; i < count; i++) {
+        const t = (i / count) * Math.PI * 2;
+        const r = Math.abs(Math.cos(petals * t));
+        const speed = velocity * r;
+
+        if (speed < 0.3) {
+            continue;
+        }
+
+        explosions.push(new Explosion(
+            position, hue + between(rng, -15, 15), lineWidth, 'flower', scale,
+            t + rotation,
+            speed + between(rng, -0.2, 0.2)
+        ));
+    }
+}
+
+function createConcentric(explosions: Explosion[], position: Point, hue: number, lineWidth: number, scale: number, rng: () => number): void {
+    const outerCount = Math.floor(between(rng, 35, 50));
+    const outerSpeed = between(rng, 7, 10);
+
+    for (let i = 0; i < outerCount; i++) {
+        const angle = (i / outerCount) * Math.PI * 2;
+
+        explosions.push(new Explosion(
+            position, hue, lineWidth, 'ring', scale,
+            angle + between(rng, -0.05, 0.05),
+            outerSpeed + between(rng, -0.25, 0.25)
+        ));
+    }
+
+    const innerCount = Math.floor(between(rng, 25, 35));
+    const innerSpeed = between(rng, 3, 5);
+
+    for (let i = 0; i < innerCount; i++) {
+        const angle = (i / innerCount) * Math.PI * 2;
+
+        explosions.push(new Explosion(
+            position, hue + 120, lineWidth, 'ring', scale,
+            angle + between(rng, -0.05, 0.05),
+            innerSpeed + between(rng, -0.25, 0.25)
+        ));
+    }
+}

package/src/fireworks/explosion.ts

@@ -77,7 +77,7 @@ export class Explosion {
             return false;
         }
 
-        if (this.#alpha <= this.#decay * 3) {
+        if (this.#alpha <= 0.4) {
             this.#hasCrackled = true;
             return true;
         }
@@ -147,21 +147,21 @@ export class Explosion {
         ctx.restore();
     }
 
-    tick(): void {
+    tick(dt: number): void {
         this.#trail.pop();
         this.#trail.unshift({...this.#position});
 
-        this.#speed *= this.#config.friction;
-        this.#vz *= this.#config.friction;
+        this.#speed *= Math.pow(this.#config.friction, dt);
+        this.#vz *= Math.pow(this.#config.friction, dt);
 
-        this.#position.x += Math.cos(this.#angle) * this.#speed;
-        this.#position.y += Math.sin(this.#angle) * this.#speed + this.#config.gravity;
-        this.#z += this.#vz;
+        this.#position.x += Math.cos(this.#angle) * this.#speed * dt;
+        this.#position.y += (Math.sin(this.#angle) * this.#speed + this.#config.gravity) * dt;
+        this.#z += this.#vz * dt;
 
         this.#depthScale = PERSPECTIVE / (PERSPECTIVE + this.#z);
 
-        this.#alpha -= this.#decay;
-        this.#sparkleTimer++;
+        this.#alpha -= this.#decay * dt;
+        this.#sparkleTimer += dt;
     }
 
     #drawShape(ctx: CanvasRenderingContext2D, ds: number, alpha: number): void {

package/src/fireworks/firework.ts

@@ -87,18 +87,18 @@ export class Firework extends EventTarget {
         ctx.restore();
     }
 
-    tick(): void {
+    tick(dt: number): void {
         this.#trail.pop();
         this.#trail.unshift({...this.#position});
 
-        this.#speed *= this.#acceleration;
+        this.#speed *= Math.pow(this.#acceleration, dt);
 
         const vx = Math.cos(this.#angle) * this.#speed;
         const vy = Math.sin(this.#angle) * this.#speed;
 
         this.#distanceTraveled = distance(this.#startPosition, {
-            x: this.#position.x + vx,
-            y: this.#position.y + vy
+            x: this.#position.x + vx * dt,
+            y: this.#position.y + vy * dt
         });
 
         if (this.#distanceTraveled >= this.#distance) {
@@ -106,12 +106,13 @@ export class Firework extends EventTarget {
             return;
         }
 
-        this.#position.x += vx;
-        this.#position.y += vy;
+        this.#position.x += vx * dt;
+        this.#position.y += vy * dt;
 
-        this.#sparkTimer++;
+        this.#sparkTimer += dt;
 
-        if (this.#sparkTimer % 3 === 0) {
+        if (this.#sparkTimer >= 3) {
+            this.#sparkTimer -= 3;
             this.#pendingSparks.push(new Spark(
                 this.#position,
                 this.#hue,

package/src/fireworks/index.ts

@@ -1,3 +1,19 @@
-export * from './simulation';
-export { FIREWORK_VARIANTS } from './types';
-export type { ExplosionType, FireworkSimulationConfig, FireworkVariant, ParticleShape } from './types';
+import { Fireworks } from './layer';
+import type { FireworksConfig, FireworkVariant } from './types';
+import type { Point } from '../point';
+import type { Effect } from '../effect';
+
+export interface FireworksInstance extends Effect<FireworksConfig> {
+    launch(variant: FireworkVariant, position?: Point): void;
+}
+
+export function createFireworks(config?: FireworksConfig): FireworksInstance {
+    return new Fireworks(config) as FireworksInstance;
+}
+
+export { createExplosion } from './create-explosion';
+export { Explosion } from './explosion';
+export { Firework } from './firework';
+export { Spark } from './spark';
+export { EXPLOSION_CONFIGS, FIREWORK_VARIANTS } from './types';
+export type { ExplosionConfig, ExplosionType, FireworksConfig, FireworkVariant, ParticleShape } from './types';

package/src/fireworks/layer.ts

@@ -0,0 +1,203 @@
+import { Effect } from '../effect';
+import type { Point } from '../point';
+import { MULBERRY } from './consts';
+import { createExplosion } from './create-explosion';
+import { Explosion } from './explosion';
+import { Firework } from './firework';
+import { Spark } from './spark';
+import { FIREWORK_VARIANTS, type FireworksConfig, type FireworkVariant } from './types';
+
+export class Fireworks extends Effect<FireworksConfig> {
+    #explosions: Explosion[] = [];
+    #fireworks: Firework[] = [];
+    #sparks: Spark[] = [];
+    #hue: number = 120;
+    #spawnTimer: number = 0;
+    #positionRandom = MULBERRY.fork();
+    #autoSpawn: boolean;
+    #variants: FireworkVariant[];
+    readonly #baseSize: number;
+    #scale: number;
+    readonly #tailWidth: number;
+    #width: number = 960;
+    #height: number = 540;
+
+    constructor(config: FireworksConfig = {}) {
+        super();
+
+        const scale = config.scale ?? 1;
+        this.#autoSpawn = config.autoSpawn ?? true;
+        this.#variants = config.variants?.length ? [...config.variants] : [...FIREWORK_VARIANTS];
+        this.#baseSize = 5 * scale;
+        this.#scale = scale;
+        this.#tailWidth = 2 * scale;
+    }
+
+    onResize(width: number, height: number): void {
+        this.#width = width;
+        this.#height = height;
+    }
+
+    launch(variant: FireworkVariant, position?: Point): void {
+        const pos = position ?? {x: this.#width / 2, y: this.#height * 0.4};
+        this.#hue = MULBERRY.nextBetween(0, 360);
+        this.#spawnExplosion(pos, this.#hue, variant);
+    }
+
+    configure(config: Partial<FireworksConfig>): void {
+        if (config.scale !== undefined) {
+            this.#scale = config.scale;
+        }
+        if (config.autoSpawn !== undefined) {
+            this.#autoSpawn = config.autoSpawn;
+        }
+        if (Array.isArray(config.variants) && config.variants.length > 0) {
+            this.#variants = [...config.variants];
+        }
+    }
+
+    tick(dt: number, width: number, height: number): void {
+        this.#width = width;
+        this.#height = height;
+        this.#spawnTimer += dt;
+
+        const isSmall = innerWidth < 991;
+        const spawnInterval = isSmall ? 60 : 30;
+
+        if (this.#autoSpawn && this.#fireworks.length < 6 && this.#spawnTimer >= spawnInterval) {
+            this.#spawnTimer -= spawnInterval;
+            let count = MULBERRY.nextBetween(1, 100) < 10 ? 2 : 1;
+
+            while (count--) {
+                this.#hue = MULBERRY.nextBetween(0, 360);
+                this.#createFirework();
+            }
+        }
+
+        for (const firework of this.#fireworks) {
+            firework.tick(dt);
+            const collected = firework.collectSparks();
+            for (let i = 0; i < collected.length; i++) {
+                this.#sparks.push(collected[i]);
+            }
+        }
+
+        for (const explosion of this.#explosions) {
+            explosion.tick(dt);
+        }
+
+        for (const spark of this.#sparks) {
+            spark.tick(dt);
+        }
+
+        const newExplosions: Explosion[] = [];
+        const newSparks: Spark[] = [];
+
+        for (const explosion of this.#explosions) {
+            if (explosion.checkSplit()) {
+                for (let i = 0; i < 4; i++) {
+                    const angle = explosion.angle + (Math.PI / 2) * i + Math.PI / 4;
+
+                    newExplosions.push(new Explosion(
+                        explosion.position,
+                        explosion.hue,
+                        this.#baseSize * 0.6,
+                        'peony',
+                        this.#scale,
+                        angle,
+                        MULBERRY.nextBetween(3, 6)
+                    ));
+                }
+            }
+
+            if (explosion.checkCrackle()) {
+                for (let j = 0; j < 14; j++) {
+                    const angle = MULBERRY.nextBetween(0, Math.PI * 2);
+                    const speed = MULBERRY.nextBetween(3, 8);
+
+                    newSparks.push(new Spark(
+                        explosion.position,
+                        explosion.hue + MULBERRY.nextBetween(-30, 30),
+                        Math.cos(angle) * speed,
+                        Math.sin(angle) * speed
+                    ));
+                }
+            }
+        }
+
+        this.#explosions.push(...newExplosions);
+        this.#sparks.push(...newSparks);
+
+        let aliveExplosions = 0;
+        for (let i = 0; i < this.#explosions.length; i++) {
+            if (!this.#explosions[i].isDead) {
+                this.#explosions[aliveExplosions++] = this.#explosions[i];
+            }
+        }
+        this.#explosions.length = aliveExplosions;
+
+        let aliveSparks = 0;
+        for (let i = 0; i < this.#sparks.length; i++) {
+            if (!this.#sparks[i].isDead) {
+                this.#sparks[aliveSparks++] = this.#sparks[i];
+            }
+        }
+        this.#sparks.length = aliveSparks;
+    }
+
+    draw(ctx: CanvasRenderingContext2D, width: number, height: number): void {
+        if (ctx.canvas.width !== width || ctx.canvas.height !== height) {
+            ctx.canvas.width = width;
+            ctx.canvas.height = height;
+        }
+
+        ctx.globalCompositeOperation = 'lighter';
+
+        for (const spark of this.#sparks) {
+            spark.draw(ctx);
+        }
+
+        for (const explosion of this.#explosions) {
+            explosion.draw(ctx);
+        }
+
+        for (const firework of this.#fireworks) {
+            firework.draw(ctx);
+        }
+
+        ctx.globalCompositeOperation = 'source-over';
+    }
+
+    #spawnExplosion(position: Point, hue: number, variant?: FireworkVariant): void {
+        const selected = variant ?? this.#pickVariant();
+        const rng = () => MULBERRY.nextBetween(0, 1);
+        this.#explosions.push(...createExplosion(selected, position, hue, {lineWidth: this.#baseSize, scale: this.#scale}, rng));
+    }
+
+    #createFirework(position?: Point): void {
+        const hue = this.#hue;
+        const targetX = position?.x || this.#positionRandom.nextBetween(this.#width * .1, this.#width * .9);
+        const targetY = position?.y || this.#height * .1 + this.#positionRandom.nextBetween(0, this.#height * .5);
+        const startX = this.#width * 0.3 + this.#positionRandom.nextBetween(0, this.#width * 0.4);
+
+        const firework = new Firework(
+            {x: startX, y: this.#height},
+            {x: targetX, y: targetY},
+            hue,
+            this.#tailWidth,
+            this.#baseSize
+        );
+
+        firework.addEventListener('remove', () => {
+            this.#fireworks.splice(this.#fireworks.indexOf(firework), 1);
+            this.#spawnExplosion(firework.position, hue);
+        }, {once: true});
+
+        this.#fireworks.push(firework);
+    }
+
+    #pickVariant(): FireworkVariant {
+        const index = Math.floor(MULBERRY.nextBetween(0, this.#variants.length));
+        return this.#variants[index];
+    }
+}

package/src/fireworks/spark.ts

@@ -8,7 +8,7 @@ export class Spark {
     readonly #size: number;
     readonly #decay: number;
     readonly #friction: number = 0.94;
-    readonly #gravity: number = 0.6;
+    readonly #gravity: number = 0.3;
     #alpha: number = 1;
 
     get isDead(): boolean {
@@ -26,7 +26,7 @@ export class Spark {
         this.#decay = MULBERRY.nextBetween(0.03, 0.08);
         this.#velocity = {
             x: velocityX + MULBERRY.nextBetween(-1.5, 1.5),
-            y: velocityY + MULBERRY.nextBetween(-2, 0.5)
+            y: velocityY + MULBERRY.nextBetween(-2, 2)
         };
     }
 
@@ -37,14 +37,14 @@ export class Spark {
         ctx.fill();
     }
 
-    tick(): void {
-        this.#velocity.x *= this.#friction;
-        this.#velocity.y *= this.#friction;
-        this.#velocity.y += this.#gravity;
+    tick(dt: number): void {
+        this.#velocity.x *= Math.pow(this.#friction, dt);
+        this.#velocity.y *= Math.pow(this.#friction, dt);
+        this.#velocity.y += this.#gravity * dt;
 
-        this.#position.x += this.#velocity.x;
-        this.#position.y += this.#velocity.y;
+        this.#position.x += this.#velocity.x * dt;
+        this.#position.y += this.#velocity.y * dt;
 
-        this.#alpha -= this.#decay;
+        this.#alpha -= this.#decay * dt;
     }
 }

package/src/fireworks/types.ts

@@ -21,10 +21,10 @@ export interface ExplosionConfig {
     readonly glowSize: number;
 }
 
-export interface FireworkSimulationConfig {
+export interface FireworksConfig {
     readonly scale?: number;
     readonly autoSpawn?: boolean;
-    readonly canvasOptions?: CanvasRenderingContext2DSettings;
+    readonly variants?: FireworkVariant[];
 }
 
 export const FIREWORK_VARIANTS: FireworkVariant[] = [

package/src/glitter/consts.ts

@@ -0,0 +1,13 @@
+import { type Mulberry32, mulberry32 } from '@basmilius/utils';
+
+export const MULBERRY: Mulberry32 = mulberry32(13);
+
+export const GLITTER_COLORS: string[] = [
+    '#ffd700', // gold
+    '#c0c0c0', // silver
+    '#ff69b4', // pink
+    '#00bfff', // sky blue
+    '#ff4500', // orange-red
+    '#7fff00', // chartreuse
+    '#9370db'  // medium purple
+];

package/src/glitter/index.ts

@@ -0,0 +1,9 @@
+import { Glitter } from './layer';
+import type { GlitterConfig } from './types';
+import type { Effect } from '../effect';
+
+export function createGlitter(config?: GlitterConfig): Effect<GlitterConfig> {
+    return new Glitter(config);
+}
+
+export type { GlitterConfig, FallingGlitter, SettledGlitter } from './types';