@basmilius/sparkle 2.1.0 → 2.2.0

package/src/petals/layer.ts

@@ -1,20 +1,28 @@
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { MULBERRY, PETAL_COLORS } from './consts';
-import type { PetalSimulationConfig } from './simulation';
 import type { Petal } from './types';
 
-export class PetalLayer extends SimulationLayer {
+export interface PetalsConfig {
+    readonly count?: number;
+    readonly colors?: string[];
+    readonly size?: number;
+    readonly speed?: number;
+    readonly wind?: number;
+    readonly scale?: number;
+}
+
+export class Petals extends Effect<PetalsConfig> {
     readonly #scale: number;
     readonly #size: number;
-    readonly #speed: number;
-    readonly #wind: number;
+    #speed: number;
+    #wind: number;
     readonly #colors: string[];
     #maxCount: number;
     #time: number = 0;
     #petals: Petal[] = [];
     #sprites: HTMLCanvasElement[] = [];
 
-    constructor(config: PetalSimulationConfig = {}) {
+    constructor(config: PetalsConfig = {}) {
         super();
 
         this.#scale = config.scale ?? 1;
@@ -35,14 +43,23 @@ export class PetalLayer extends SimulationLayer {
         }
     }
 
+    configure(config: Partial<PetalsConfig>): void {
+        if (config.speed !== undefined) {
+            this.#speed = config.speed;
+        }
+        if (config.wind !== undefined) {
+            this.#wind = config.wind;
+        }
+    }
+
     tick(dt: number, _width: number, height: number): void {
         const speedFactor = (height / 540) / this.#speed;
 
         this.#time += 0.012 * dt;
 
         const globalWind = Math.sin(this.#time * 0.4) * 0.3
-                         + Math.sin(this.#time * 1.1 + 1.5) * 0.15
-                         + Math.sin(this.#time * 2.7) * 0.08;
+            + Math.sin(this.#time * 1.1 + 1.5) * 0.15
+            + Math.sin(this.#time * 2.7) * 0.08;
 
         for (let index = 0; index < this.#petals.length; index++) {
             const petal = this.#petals[index];
@@ -78,11 +95,10 @@ export class PetalLayer extends SimulationLayer {
             const py = petal.y * height;
             const displaySize = petal.size * petal.depth;
             const scaleX = Math.cos(petal.flipAngle);
+            const cos = Math.cos(petal.rotation);
+            const sin = Math.sin(petal.rotation);
 
-            ctx.save();
-            ctx.translate(px, py);
-            ctx.rotate(petal.rotation);
-            ctx.scale(scaleX, 1);
+            ctx.setTransform(cos * scaleX, sin * scaleX, -sin, cos, px, py);
             ctx.globalAlpha = 0.4 + petal.depth * 0.6;
             ctx.drawImage(
                 this.#sprites[petal.colorIndex % this.#sprites.length],
@@ -91,9 +107,9 @@ export class PetalLayer extends SimulationLayer {
                 displaySize,
                 displaySize
             );
-            ctx.restore();
         }
 
+        ctx.resetTransform();
         ctx.globalAlpha = 1;
     }
 

package/src/plasma/index.ts

@@ -1,4 +1,10 @@
-export { PlasmaLayer } from './layer';
-export { PlasmaSimulation } from './simulation';
-export type { PlasmaSimulationConfig } from './simulation';
+import { Plasma } from './layer';
+import type { PlasmaConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createPlasma(config?: PlasmaConfig): Effect<PlasmaConfig> {
+    return new Plasma(config);
+}
+
+export type { PlasmaConfig };
 export type { PlasmaColor } from './types';

package/src/plasma/layer.ts

@@ -1,7 +1,13 @@
-import { SimulationLayer } from '../layer';
-import type { PlasmaSimulationConfig } from './simulation';
+import { Effect } from '../effect';
 import type { PlasmaColor } from './types';
 
+export interface PlasmaConfig {
+    readonly speed?: number;
+    readonly scale?: number;
+    readonly resolution?: number;
+    readonly palette?: PlasmaColor[];
+}
+
 const DEFAULT_PALETTE: PlasmaColor[] = [
     {r: 0, g: 255, b: 255},
     {r: 255, g: 0, b: 255},
@@ -10,9 +16,9 @@ const DEFAULT_PALETTE: PlasmaColor[] = [
     {r: 0, g: 255, b: 100}
 ];
 
-export class PlasmaLayer extends SimulationLayer {
-    readonly #speed: number;
-    readonly #scale: number;
+export class Plasma extends Effect<PlasmaConfig> {
+    #speed: number;
+    #scale: number;
     readonly #resolution: number;
     readonly #palette: PlasmaColor[];
     #time: number = 0;
@@ -20,7 +26,7 @@ export class PlasmaLayer extends SimulationLayer {
     #offscreenCtx: CanvasRenderingContext2D | null = null;
     #imageData: ImageData | null = null;
 
-    constructor(config: PlasmaSimulationConfig = {}) {
+    constructor(config: PlasmaConfig = {}) {
         super();
 
         this.#speed = config.speed ?? 1;
@@ -29,6 +35,15 @@ export class PlasmaLayer extends SimulationLayer {
         this.#palette = config.palette ?? DEFAULT_PALETTE;
     }
 
+    configure(config: Partial<PlasmaConfig>): void {
+        if (config.speed !== undefined) {
+            this.#speed = config.speed;
+        }
+        if (config.scale !== undefined) {
+            this.#scale = config.scale;
+        }
+    }
+
     tick(dt: number, _width: number, _height: number): void {
         this.#time += 0.02 * dt * this.#speed;
     }

package/src/rain/index.ts

@@ -1,6 +1,12 @@
-export { RainLayer } from './layer';
+import { Rain } from './layer';
+import type { RainConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createRain(config?: RainConfig): Effect<RainConfig> {
+    return new Rain(config);
+}
+
 export { RaindropParticle, SplashParticle } from './particle';
-export { RainSimulation } from './simulation';
+export type { RainConfig };
 export type { RaindropParticleConfig, SplashParticleConfig } from './particle';
-export type { RainSimulationConfig } from './simulation';
 export type { Raindrop, RainVariant, Splash } from './types';

package/src/rain/layer.ts

@@ -1,21 +1,31 @@
 import { parseColor } from '../color';
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { MULBERRY } from './consts';
-import type { RainSimulationConfig } from './simulation';
 import type { Raindrop, RainVariant, Splash } from './types';
 
-const VARIANT_PRESETS: Record<RainVariant, {drops: number; speed: number; wind: number; splashes: boolean}> = {
+export interface RainConfig {
+    readonly variant?: RainVariant;
+    readonly drops?: number;
+    readonly wind?: number;
+    readonly speed?: number;
+    readonly splashes?: boolean;
+    readonly color?: string;
+    readonly groundLevel?: number;
+    readonly scale?: number;
+}
+
+const VARIANT_PRESETS: Record<RainVariant, { drops: number; speed: number; wind: number; splashes: boolean }> = {
     drizzle: {drops: 70, speed: 0.55, wind: 0.1, splashes: false},
     downpour: {drops: 200, speed: 0.85, wind: 0.25, splashes: true},
     thunderstorm: {drops: 300, speed: 1, wind: 0.4, splashes: true}
 };
 
-export class RainLayer extends SimulationLayer {
+export class Rain extends Effect<RainConfig> {
     readonly #scale: number;
-    readonly #speed: number;
-    readonly #wind: number;
+    #speed: number;
+    #wind: number;
     readonly #groundLevel: number;
-    readonly #enableSplashes: boolean;
+    #enableSplashes: boolean;
     readonly #colorR: number;
     readonly #colorG: number;
     readonly #colorB: number;
@@ -23,7 +33,7 @@ export class RainLayer extends SimulationLayer {
     #drops: Raindrop[] = [];
     #splashes: Splash[] = [];
 
-    constructor(config: RainSimulationConfig = {}) {
+    constructor(config: RainConfig = {}) {
         super();
 
         const variant = config.variant ?? 'downpour';
@@ -50,6 +60,18 @@ export class RainLayer extends SimulationLayer {
         }
     }
 
+    configure(config: Partial<RainConfig>): void {
+        if (config.speed !== undefined) {
+            this.#speed = config.speed;
+        }
+        if (config.wind !== undefined) {
+            this.#wind = config.wind;
+        }
+        if (config.splashes !== undefined) {
+            this.#enableSplashes = config.splashes;
+        }
+    }
+
     tick(dt: number, width: number, height: number): void {
         // Update raindrops
         let aliveDrops = 0;

package/src/sandstorm/index.ts

@@ -1,4 +1,10 @@
-export { SandstormLayer } from './layer';
-export { SandstormSimulation } from './simulation';
-export type { SandstormSimulationConfig } from './simulation';
+import { Sandstorm } from './layer';
+import type { SandstormConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createSandstorm(config?: SandstormConfig): Effect<SandstormConfig> {
+    return new Sandstorm(config);
+}
+
+export type { SandstormConfig };
 export type { SandGrain } from './types';

package/src/sandstorm/layer.ts

@@ -1,12 +1,20 @@
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { MULBERRY } from './consts';
-import type { SandstormSimulationConfig } from './simulation';
 import type { SandGrain } from './types';
 
-export class SandstormLayer extends SimulationLayer {
+export interface SandstormConfig {
+    readonly count?: number;
+    readonly wind?: number;
+    readonly turbulence?: number;
+    readonly color?: string;
+    readonly hazeOpacity?: number;
+    readonly scale?: number;
+}
+
+export class Sandstorm extends Effect<SandstormConfig> {
     readonly #scale: number;
-    readonly #wind: number;
-    readonly #turbulence: number;
+    #wind: number;
+    #turbulence: number;
     readonly #colorR: number;
     readonly #colorG: number;
     readonly #colorB: number;
@@ -15,7 +23,7 @@ export class SandstormLayer extends SimulationLayer {
     #time: number = 0;
     #grains: SandGrain[] = [];
 
-    constructor(config: SandstormSimulationConfig = {}) {
+    constructor(config: SandstormConfig = {}) {
         super();
 
         this.#scale = config.scale ?? 1;
@@ -38,12 +46,21 @@ export class SandstormLayer extends SimulationLayer {
         }
     }
 
+    configure(config: Partial<SandstormConfig>): void {
+        if (config.wind !== undefined) {
+            this.#wind = config.wind;
+        }
+        if (config.turbulence !== undefined) {
+            this.#turbulence = config.turbulence;
+        }
+    }
+
     tick(dt: number, width: number, height: number): void {
         this.#time += 0.02 * dt;
 
         const gustX = Math.sin(this.#time * 0.3) * 0.5
-                     + Math.sin(this.#time * 0.8 + 1) * 0.3
-                     + Math.sin(this.#time * 2.1) * 0.2;
+            + Math.sin(this.#time * 0.8 + 1) * 0.3
+            + Math.sin(this.#time * 2.1) * 0.2;
 
         const gustY = Math.sin(this.#time * 0.5 + 2) * 0.15;
 
@@ -107,7 +124,7 @@ export class SandstormLayer extends SimulationLayer {
         }
     }
 
-    #parseColor(color: string): {r: number; g: number; b: number} {
+    #parseColor(color: string): { r: number; g: number; b: number } {
         const canvas = document.createElement('canvas');
         canvas.width = 1;
         canvas.height = 1;

package/src/scene.ts

@@ -0,0 +1,201 @@
+import { LimitedFrameRateCanvas } from './canvas';
+import { applyEdgeFade } from './fade';
+import type { SimulationLayer } from './layer';
+
+/**
+ * Internal canvas runner that drives all layers in a Scene.
+ */
+class SceneCanvas extends LimitedFrameRateCanvas {
+    readonly #layers: SimulationLayer[];
+    readonly #contextOptions: CanvasRenderingContext2DSettings;
+    #offscreen: HTMLCanvasElement | null = null;
+    #offscreenCtx: CanvasRenderingContext2D | null = null;
+
+    constructor(canvas: HTMLCanvasElement, layers: SimulationLayer[], frameRate: number, options: CanvasRenderingContext2DSettings) {
+        super(canvas, frameRate, options);
+        this.#layers = layers;
+        this.#contextOptions = options;
+
+        canvas.style.position = 'absolute';
+        canvas.style.top = '0';
+        canvas.style.left = '0';
+        canvas.style.height = '100%';
+        canvas.style.width = '100%';
+    }
+
+    start(): void {
+        for (const layer of this.#layers) {
+            layer.onMount(this.canvas);
+        }
+        super.start();
+    }
+
+    destroy(): void {
+        for (const layer of this.#layers) {
+            layer.onUnmount(this.canvas);
+        }
+        super.destroy();
+    }
+
+    draw(): void {
+        this.canvas.height = this.height;
+        this.canvas.width = this.width;
+
+        const ctx = this.context;
+        ctx.clearRect(0, 0, this.width, this.height);
+
+        for (const layer of this.#layers) {
+            if (layer.fade) {
+                const offCtx = this.#getOffscreenCtx(this.width, this.height);
+                offCtx.clearRect(0, 0, this.width, this.height);
+                layer.draw(offCtx, this.width, this.height);
+                applyEdgeFade(offCtx, this.width, this.height, layer.fade);
+                ctx.drawImage(this.#offscreen!, 0, 0);
+            } else {
+                ctx.save();
+                layer.draw(ctx, this.width, this.height);
+                ctx.restore();
+            }
+        }
+    }
+
+    tick(): void {
+        const dt = (this.delta > 0 && this.delta < 200 ? this.delta / (1000 / 60) : 1) * this.speed * LimitedFrameRateCanvas.globalSpeed;
+
+        for (const layer of this.#layers) {
+            layer.tick(dt, this.width, this.height);
+        }
+    }
+
+    onResize(): void {
+        super.onResize();
+
+        if (this.#offscreen) {
+            this.#offscreen.width = this.width;
+            this.#offscreen.height = this.height;
+        }
+
+        for (const layer of this.#layers) {
+            layer.onResize(this.width, this.height);
+        }
+    }
+
+    #getOffscreenCtx(width: number, height: number): CanvasRenderingContext2D {
+        if (!this.#offscreen) {
+            this.#offscreen = document.createElement('canvas');
+            this.#offscreen.width = width;
+            this.#offscreen.height = height;
+            this.#offscreenCtx = this.#offscreen.getContext('2d', this.#contextOptions)!;
+        }
+
+        return this.#offscreenCtx!;
+    }
+}
+
+/**
+ * Composable canvas that renders multiple Effect layers in order (first = bottom, last = top).
+ *
+ * @example
+ * const scene = new Scene()
+ *     .mount(canvas)
+ *     .layer(new Aurora({ bands: 5 }))
+ *     .layer(new Stars().withFade({ bottom: 0.4 }))
+ *     .start();
+ */
+export class Scene {
+    readonly #layers: SimulationLayer[] = [];
+    readonly #frameRate: number;
+    readonly #defaultOptions: CanvasRenderingContext2DSettings;
+    #runner: SceneCanvas | null = null;
+
+    constructor(frameRate: number = 60, options: CanvasRenderingContext2DSettings = {colorSpace: 'display-p3'}) {
+        this.#frameRate = frameRate;
+        this.#defaultOptions = options;
+    }
+
+    /**
+     * Mount the scene to a canvas element or CSS selector.
+     */
+    mount(canvas: HTMLCanvasElement | string, options?: CanvasRenderingContext2DSettings): this {
+        if (typeof canvas === 'string') {
+            const el = document.querySelector<HTMLCanvasElement>(canvas);
+
+            if (!el) {
+                throw new Error(`Scene.mount(): no element found for selector "${canvas}".`);
+            }
+
+            canvas = el;
+        }
+
+        this.#runner?.destroy();
+        this.#runner = new SceneCanvas(canvas, this.#layers, this.#frameRate, options ?? this.#defaultOptions);
+        return this;
+    }
+
+    /**
+     * Add an effect layer. Layers are rendered in the order they are added.
+     * If the scene is already running, the layer is mounted immediately.
+     */
+    layer(effect: SimulationLayer): this {
+        this.#layers.push(effect);
+
+        if (this.#runner?.isTicking) {
+            effect.onMount(this.#runner.canvas);
+        }
+
+        return this;
+    }
+
+    /**
+     * Start the render loop.
+     */
+    start(): this {
+        this.#runner?.start();
+        return this;
+    }
+
+    /**
+     * Pause rendering without destroying state. Use resume() to continue.
+     */
+    pause(): this {
+        this.#runner?.pause();
+        return this;
+    }
+
+    /**
+     * Resume rendering after pause().
+     */
+    resume(): this {
+        this.#runner?.resume();
+        return this;
+    }
+
+    /**
+     * Stop and destroy all layers.
+     */
+    destroy(): void {
+        this.#runner?.destroy();
+        this.#runner = null;
+    }
+
+    get speed(): number {
+        return this.#runner?.speed ?? 1;
+    }
+
+    set speed(value: number) {
+        if (this.#runner) {
+            this.#runner.speed = value;
+        }
+    }
+
+    get isTicking(): boolean {
+        return this.#runner?.isTicking ?? false;
+    }
+}
+
+/**
+ * Factory alternative to `new Scene()`. Call .mount() and .layer() on the returned instance.
+ */
+export function createScene(frameRate?: number, options?: CanvasRenderingContext2DSettings): Scene {
+    return new Scene(frameRate, options);
+}

package/src/shooting-stars/system.ts

@@ -11,7 +11,6 @@ export interface ShootingStarSystemConfig {
     readonly alphaRange?: number;
     readonly decayMin?: number;
     readonly decayRange?: number;
-    readonly verticalFade?: [number, number];
 }
 
 export class ShootingStarSystem {
@@ -25,10 +24,8 @@ export class ShootingStarSystem {
     readonly #alphaRange: number;
     readonly #decayMin: number;
     readonly #decayRange: number;
-    readonly #verticalFade: [number, number] | null;
     readonly #rng: () => number;
     #cooldown: number;
-    #height: number = 0;
     #stars: ShootingStar[] = [];
 
     constructor(config: ShootingStarSystemConfig, rng: () => number) {
@@ -42,13 +39,11 @@ export class ShootingStarSystem {
         this.#alphaRange = config.alphaRange ?? 0.3;
         this.#decayMin = config.decayMin ?? 0.008;
         this.#decayRange = config.decayRange ?? 0.01;
-        this.#verticalFade = config.verticalFade ?? null;
         this.#rng = rng;
         this.#cooldown = this.#interval[0] + this.#rng() * (this.#interval[1] - this.#interval[0]);
     }
 
     tick(dt: number, width: number, height: number): void {
-        this.#height = height;
         this.#cooldown -= dt;
 
         if (this.#cooldown <= 0) {
@@ -61,10 +56,17 @@ export class ShootingStarSystem {
         for (let i = 0; i < this.#stars.length; i++) {
             const star = this.#stars[i];
 
-            star.trail.push({x: star.x, y: star.y});
-
-            if (star.trail.length > this.#trailLength) {
-                star.trail.shift();
+            const trail = star.trail;
+            const maxLen = this.#trailLength;
+
+            if (trail.length < maxLen) {
+                trail.push({x: star.x, y: star.y});
+                star.trailHead = trail.length - 1;
+            } else {
+                const next = (star.trailHead + 1) % maxLen;
+                trail[next].x = star.x;
+                trail[next].y = star.y;
+                star.trailHead = next;
             }
 
             star.x += star.vx * this.#speed * dt;
@@ -72,9 +74,8 @@ export class ShootingStarSystem {
             star.alpha -= star.decay * dt;
 
             const inBounds = star.alpha > 0 && star.x > -50 && star.x < width + 50 && star.y < height + 50;
-            const fullyFaded = this.#verticalFade !== null && star.y / height >= this.#verticalFade[1];
 
-            if (inBounds && !fullyFaded) {
+            if (inBounds) {
                 this.#stars[alive++] = star;
             }
         }
@@ -88,30 +89,30 @@ export class ShootingStarSystem {
         ctx.globalCompositeOperation = 'lighter';
 
         for (const star of this.#stars) {
-            let fadeFactor = 1;
-
-            if (this.#verticalFade && this.#height > 0) {
-                const [fadeStart, fadeEnd] = this.#verticalFade;
-                fadeFactor = 1 - Math.max(0, Math.min(1, (star.y / this.#height - fadeStart) / (fadeEnd - fadeStart)));
-            }
-
-            for (let t = 0; t < star.trail.length; t++) {
-                const progress = t / star.trail.length;
-                const trailAlpha = star.alpha * progress * this.#trailAlphaFactor * fadeFactor;
+            const trail = star.trail;
+            const trailLen = trail.length;
+            const isFull = trailLen === this.#trailLength;
+            const oldest = isFull ? (star.trailHead + 1) % trailLen : 0;
+
+            for (let t = 0; t < trailLen; t++) {
+                const progress = t / trailLen;
+                const trailAlpha = star.alpha * progress * this.#trailAlphaFactor;
                 const trailSize = star.size * progress * this.#scale;
 
                 if (trailAlpha < 0.01) {
                     continue;
                 }
 
+                const idx = (oldest + t) % trailLen;
+
                 ctx.globalAlpha = trailAlpha;
                 ctx.beginPath();
-                ctx.arc(star.trail[t].x, star.trail[t].y, trailSize, 0, Math.PI * 2);
+                ctx.arc(trail[idx].x, trail[idx].y, trailSize, 0, Math.PI * 2);
                 ctx.fillStyle = `rgb(${cr}, ${cg}, ${cb})`;
                 ctx.fill();
             }
 
-            const alpha = star.alpha * fadeFactor;
+            const alpha = star.alpha;
             const headSize = star.size * 2 * this.#scale;
             const glow = ctx.createRadialGradient(star.x, star.y, 0, star.x, star.y, headSize);
             glow.addColorStop(0, `rgba(${cr}, ${cg}, ${cb}, ${alpha})`);
@@ -143,7 +144,8 @@ export class ShootingStarSystem {
             alpha: this.#alphaMin + this.#rng() * this.#alphaRange,
             size: 1.5 + this.#rng() * 2,
             decay: this.#decayMin + this.#rng() * this.#decayRange,
-            trail: []
+            trail: [],
+            trailHead: 0
         };
     }
 }

package/src/shooting-stars/types.ts

@@ -6,5 +6,6 @@ export type ShootingStar = {
     alpha: number;
     size: number;
     decay: number;
-    trail: {x: number; y: number}[];
+    trail: { x: number; y: number }[];
+    trailHead: number;
 };