@erikwatson/snowfall 3.1.2 → 4.0.0

package/dist/snowfall.d.ts

@@ -0,0 +1,242 @@
+/**
+ * @module snowfall
+ *
+ * Lightweight, high-performance snowfall effect for the web.
+ * Fully configurable, supports multiple layers, wind, gusts, and scheduled activation.
+ *
+ * Stay cool ☃️
+ */
+import { UserConfig, UserSchedule } from './types';
+/**
+ * Starts the Snowfall simulation.
+ *
+ * @param {UserConfig} [config] - A config, possibly from the [Visual Config Editor](https://erikwatson.github.io/snowfall-editor/).
+ */
+export declare function start(config?: UserConfig): void;
+export declare function restart(config?: UserConfig): void;
+export declare function stop(): void;
+/**
+ * Starts the Snowfall simulation when today's date falls within the date range in the schedule.
+ *
+ * @param {UserSchedule} userSchedule - A schedule config, defining when the simulation should run from, and when the simulation should run to.
+ * @param {UserConfig} [config] - A config, possibly from the [Visual Config Editor](https://erikwatson.github.io/snowfall-editor/).
+ */
+export declare function schedule(userSchedule: UserSchedule, config?: UserConfig): void;
+/**
+ * Set the colour of the Snowflakes
+ * @param {string} colour - The colour to set
+ * @param {number} layer - The layer to set the colour for
+ */
+export declare function setColour(colour: string, layer: number): void;
+/**
+ * Set the density of the Snowflakes. This is the number of snowflakes on screen
+ * at a resolution of 1280 x 1080, but this number is scaled up and down at
+ * higher and lower resolutions respectively to give a consistent look when
+ * resizing.
+ *
+ * Setting this restarts the simulation.
+ *
+ * @param {number} density - A number representing the density of snowflakes.
+ * @param {number} layer - The layer to set the density for
+ */
+export declare function setDensity(density: number, layer: number): void;
+/**
+ * Set the Amplitude of the sway of the Snowflakes
+ *
+ * @param {number} amplitude - The Amplitude to set
+ * @param {number} layer - The layer to set the amplitude for
+ */
+export declare function setAmplitude(amplitude: number, layer: number): void;
+/**
+ * Set the Frequency of the sway of the Snowflakes.
+ *
+ * @param {number} frequency - The frequency to set
+ * @param {number} layer - The layer to set the frequency for
+ */
+export declare function setFrequency(frequency: number, layer: number): void;
+/**
+ * Pauses or resumes a specific layer.
+ *
+ * @param {boolean} pause - Pass true to pause the layer, false to resume
+ * @param {number} layer - The layer index
+ */
+export declare function setPaused(pause: boolean, layer: number): void;
+/**
+ * Pause/unpause the snowfall update loop for a specific layer.
+ *
+ * @param layer - The layer index to toggle
+ */
+export declare function togglePaused(layer: number): void;
+/**
+ * Set the angle and strength of the wind in the simulation.
+ *
+ * @param {number} angle - The angle of the wind, in degrees
+ * @param {number} strength - The strength of the wind
+ * @param {number} layer - The layer to set the wind for
+ */
+export declare function setWind(angle: number, strength: number, layer: number): void;
+/**
+ * Set the angle of the wind in the simulation.
+ *
+ * @param {number} angle - The angle of the wind, in degrees
+ * @param {number} layer - The layer to set the wind angle for
+ */
+export declare function setWindAngle(angle: number, layer: number): void;
+/**
+ * Set the strength of the wind in the simulation.
+ *
+ * @param {number} strength - The strength of the wind
+ * @param {number} layer    - The layer to apply the wind strength to
+ */
+export declare function setWindStrength(strength: number, layer: number): void;
+/**
+ * Set the wind gusts in the simulation.
+ * This restarts the simulation.
+ *
+ * @param {boolean} gusts - Should there be gusts in the wind?
+ * @param {number} layer - The layer to set the gusts for
+ */
+export declare function setGusts(gusts: boolean, layer: number): void;
+/**
+ * Set the angle and strength of gravity in the simulation.
+ *
+ * @param {number} angle - The angle of gravity, in degrees
+ * @param {number} strength - The strength of the gravity
+ * @param {number} layer - The layer to set the gravity for
+ */
+export declare function setGravity(angle: number, strength: number, layer: number): void;
+/**
+ * Set the angle of gravity in the simulation.
+ *
+ * @param {number} angle - The angle of gravity, in degrees
+ * @param {number} layer - The layer to set the gravity angle for
+ */
+export declare function setGravityAngle(angle: number, layer: number): void;
+/**
+ * Set the strength of gravity in the simulation.
+ *
+ * @param {number} strength - The strength of the gravity
+ * @param {number} layer - The layer to set the gravity strength for
+ */
+export declare function setGravityStrength(strength: number, layer: number): void;
+/**
+ * Set the minimum additional strength of the wind when it's coming in.
+ *
+ * @param {number} min - The minimum additional strength of the wind when it's coming in.
+ * @param {number} layer - The layer to set the wind in additional strength min for
+ * @returns {void}
+ */
+export declare function setWindInAdditionalStrengthMin(min: number, layer: number): void;
+/**
+ * Set the maximum additional strength of the wind when it's coming in.
+ *
+ * @param {number} max - The maximum additional strength of the wind when it's coming in.
+ * @param {number} layer - The layer to set the wind in additional strength max for
+ * @returns {void}
+ */
+export declare function setWindInAdditionalStrengthMax(max: number, layer: number): void;
+/**
+ * Set the minimum duration of the wind when it's coming in.
+ *
+ * @param {number} min - The minimum duration of the wind when it's coming in.
+ * @param {number} layer - The layer to set the wind in duration min for
+ * @returns {void}
+ */
+export declare function setWindInDurationMin(min: number, layer: number): void;
+/**
+ * Set the maximum duration of the wind when it's coming in.
+ *
+ * @param {number} max - The maximum duration of the wind when it's coming in.
+ * @param {number} layer - The layer to set the wind in duration max for
+ * @returns {void}
+ */
+export declare function setWindInDurationMax(max: number, layer: number): void;
+/**
+ * Set the minimum delay of the wind when it's coming in.
+ *
+ * @param {number} min - The minimum delay of the wind when it's coming in.
+ * @param {number} layer - The layer to set the wind in delay min for
+ * @returns {void}
+ */
+export declare function setWindInDelayMin(min: number, layer: number): void;
+/**
+ * Set the maximum delay of the wind when it's coming in.
+ *
+ * @param {number} max - The maximum delay of the wind when it's coming in.
+ * @param {number} layer - The layer to set the wind in delay max for
+ * @returns {void}
+ */
+export declare function setWindInDelayMax(max: number, layer: number): void;
+/**
+ * Set the minimum duration of the wind when it's going out.
+ *
+ * @param {number} min - The minimum duration of the wind when it's going out.
+ * @param {number} layer - The layer to set the wind out duration min for
+ * @returns {void}
+ */
+export declare function setWindOutDurationMin(min: number, layer: number): void;
+/**
+ * Set the maximum duration of the wind when it's going out.
+ *
+ * @param {number} max - The maximum duration of the wind when it's going out.
+ * @param {number} layer - The layer to set the wind out duration max for
+ * @returns {void}
+ */
+export declare function setWindOutDurationMax(max: number, layer: number): void;
+/**
+ * Set the minimum delay of the wind when it's going out.
+ *
+ * @param {number} min - The minimum delay of the wind when it's going out.
+ * @param {number} layer - The layer to set the wind out delay min for
+ * @returns {void}
+ */
+export declare function setWindOutDelayMin(min: number, layer: number): void;
+/**
+ * Set the maximum delay of the wind when it's going out.
+ *
+ * @param {number} max - The maximum delay of the wind when it's going out.
+ * @param {number} layer - The layer to set the wind out delay max for
+ * @returns {void}
+ */
+export declare function setWindOutDelayMax(max: number, layer: number): void;
+/**
+ * Set the chance of the wind changing direction after a gust.
+ *
+ * @param {number} chance - The chance of the wind changing direction after a gust.
+ * @param {number} layer - The layer to set the wind out change chance for
+ * @returns {void}
+ */
+export declare function setWindOutChangeChance(chance: number, layer: number): void;
+/**
+ * Set the minimum mass of the snowflakes.
+ *
+ * @param {number} min - The minimum mass of the snowflakes.
+ * @param {number} layer - The layer to set the mass min for
+ */
+export declare function setMassMin(min: number, layer: number): void;
+/**
+ * Set the maximum mass of the snowflakes.
+ *
+ * @param {number} max - The maximum mass of the snowflakes.
+ * @param {number} layer - The layer to set the mass max for
+ */
+export declare function setMassMax(max: number, layer: number): void;
+/**
+ * Set the minimum size of the snowflakes.
+ *
+ * @param {number} min - The minimum rendered size of the snowflakes.
+ * @param {number} layer - The layer to set the rendered size min for
+ */
+export declare function setSizeMin(min: number, layer: number): void;
+/**
+ * Set the maximum size of the snowflakes.
+ *
+ * @param {number} max - The maximum rendered size of the snowflakes.
+ * @param {number} layer - The layer to set the rendered size max for
+ */
+export declare function setSizeMax(max: number, layer: number): void;
+export { diff } from './config';
+export * from './defaults';
+export { clone } from './utils';
+export { isSimpleLayer } from './utils';
+export { UserSchedule, UserConfig, SimpleLayerConfig, ImageLayerConfig, CompleteUserConfig, BaseConfig, ConfigLayer, Gravity, SizeBounds, Sway, Wind, Gusts, In, Out } from './types';

package/dist/snowflake/index.d.ts

@@ -0,0 +1,2 @@
+export { addWind, addGravity, addSwayMotion, screenWrap, fadeIn, addRotation } from './move';
+export { drawLayer } from './render';

package/dist/snowflake/move.d.ts

@@ -0,0 +1,16 @@
+import { Snowflake } from '../types';
+export declare function addWind(snowflake: Snowflake, angle: number, strength: number): void;
+export declare function addRotation(snowflake: Snowflake): void;
+export declare function addGravity(snowflake: Snowflake, angle: number, strength: number): void;
+export declare function addSwayMotion(snowflake: Snowflake, gravity: {
+    angle: number;
+    strength: number;
+}, sway: {
+    frequency: number;
+    amplitude: number;
+}): void;
+export declare function fadeIn(snowflake: Snowflake): void;
+export declare function screenWrap(snowflake: Snowflake, width: number, height: number, gravity: {
+    angle: number;
+    strength: number;
+}): void;

package/dist/snowflake/render.d.ts

@@ -0,0 +1,3 @@
+import { Graphics } from '@erikwatson/bramble';
+import { Snowflake } from '../types';
+export declare function drawLayer(gfx: Graphics, snowflakes: Snowflake[], colour: string): void;

package/dist/test/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/layers/base-layer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/layers/image-layer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/layers/simple-layer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/math.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/simulation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/snowfall.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/snowflake/move.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,280 @@
+import { Graphics, Vec2 } from '@erikwatson/bramble';
+export type SizeBounds = {
+    min: number;
+    max: number;
+};
+export type In = {
+    /**
+     * The minimum and maximum strength to add to the wind gusts.
+     * @default { min: 1, max: 3 }
+     */
+    additionalStrength: SizeBounds;
+    /**
+     * The minimum and maximum duration of the wind gusts.
+     * @default { min: 1000, max: 3000 }
+     */
+    duration: SizeBounds;
+    /**
+     * The minimum and maximum delay before the wind eases off.
+     * @default { min: 5000, max: 10000 }
+     */
+    delay: SizeBounds;
+};
+export type Out = {
+    /**
+     * The minimum and maximum duration of the wind gusts.
+     * @default { min: 5000, max: 10000 }
+     */
+    duration: SizeBounds;
+    /**
+     * The minimum and maximum delay before the wind eases off.
+     * @default { min: 1000, max: 10000 }
+     */
+    delay: SizeBounds;
+};
+export type Gusts = {
+    /**
+     * Should the wind gust?
+     * @default true
+     */
+    active: boolean;
+    /**
+     * The likelihood of the wind changing direction after a gust. 0.0 is never, 1.0 is always.
+     * @default 0.25
+     */
+    changeChance: number;
+    in: In;
+    out: Out;
+};
+export type Gravity = {
+    /**
+     * The angle of gravity, in degrees.
+     * @default 90
+     */
+    angle: number;
+    /**
+     * The strength of gravity.
+     * @default 0.7
+     */
+    strength: number;
+};
+export type Sway = {
+    /**
+     * The frequency of the sway the snowflakes follow.
+     * @default 0.02
+     */
+    frequency: number;
+    /**
+     * The amplitude of the sway the snowflakes follow.
+     * @default 1.0
+     */
+    amplitude: number;
+};
+export type Wind = {
+    /**
+     * The angle of the wind, in degrees.
+     * @default 0
+     */
+    angle: number;
+    /**
+     * The strength of the wind.
+     * @default 0
+     */
+    strength: number;
+    gusts: Gusts;
+};
+export interface BaseLayerConfig {
+    /**
+     * A number representing the required density of snowflakes on screen. Note, this is not the actual number of snowflakes.
+     * @default 200
+     */
+    density: number;
+    /**
+     * The size of the snowflakes.
+     * @default { min: 1, max: 3 }
+     */
+    mass: SizeBounds;
+    size: SizeBounds;
+    sway: Sway;
+    gravity: Gravity;
+    wind: Wind;
+    opacity: SizeBounds;
+}
+export interface SimpleLayerConfig extends BaseLayerConfig {
+    mode: 'simple';
+    /**
+     * A hex string representing the colour of the snowflakes in the foreground.
+     * @default '#8d90b7'
+     */
+    colour: string;
+}
+export interface ImageLayerConfig extends BaseLayerConfig {
+    mode: 'image';
+    /**
+     * An image to render
+     */
+    image: string;
+    /**
+     * Should the snow rotate, or not?
+     * @default false
+     */
+    rotate: boolean;
+}
+export interface BaseConfig {
+    [key: string]: any;
+    /**
+     * A hex string representing the Background Colour of the canvas.
+     * @default '#0d0014'
+     */
+    /**
+     * An array of uniquely configured snowflake layers.
+     */
+    layers: ConfigLayer[];
+}
+export type ConfigLayer = SimpleLayerConfig | ImageLayerConfig;
+export interface Config extends BaseConfig {
+    /**
+     * The element to attach the simulation to.
+     * @default '#snowfall'
+     */
+    attachTo: HTMLElement;
+}
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+export interface CompleteUserConfig extends BaseConfig {
+    /**
+     * The element to attach the simulation to, as a string representing the ID.
+     */
+    attachTo: string;
+    /**
+     * A fully configured array of snowflake layers.
+     */
+    layers: ConfigLayer[];
+}
+export interface UserConfig extends Omit<Partial<CompleteUserConfig>, 'layers'> {
+    /**
+     * An optional array of uniquely configured snowflake layers,
+     * where each layer can be partially configured.
+     * @default undefined
+     */
+    layers?: DeepPartial<ConfigLayer>[];
+    /**
+     * A string that represents the ID of an element you want to attach snowfall to.
+     * @default '#snowfall'
+     */
+    attachTo?: string;
+}
+export interface UserSchedule {
+    /** The date from which to start the simulation */
+    from: {
+        /** The day of the month, starting at 1 */
+        day: number;
+        /** The month of the year, starting at 1 */
+        month: number;
+    };
+    /** The date on which to end the simulation */
+    to: {
+        /** The day of the month, starting at 1 */
+        day: number;
+        /** The month of the year, starting at 1 */
+        month: number;
+    };
+}
+export type Snowflake = {
+    position: Vec2;
+    mass: number;
+    size: number;
+    renderedSize: number;
+    noise: number;
+    time: number;
+    amplitude: number;
+    frequency: number;
+    random: number;
+    rotation: number;
+    opacity: number;
+};
+export interface Simulation {
+    start: (config: UserConfig) => void;
+    setAmplitude: (num: number, layer: number) => void;
+    setDensity: (den: number, layer: number) => void;
+    setFrequency: (freq: number, layer: number) => void;
+    setGravity: (degrees: number, strength: number, layer: number) => void;
+    setGravityAngle: (degrees: number, layer: number) => void;
+    setGravityStrength: (strength: number, layer: number) => void;
+    setPaused: (pause: boolean, layer: number) => void;
+    setWind: (degrees: number, strength: number, layer: number) => void;
+    setWindAngle: (degrees: number, layer: number) => void;
+    setWindStrength: (strength: number, layer: number) => void;
+    setGusts: (gusts: boolean, layer: number) => void;
+    togglePaused: (layer: number) => void;
+    setWindInAdditionalStrengthMin: (min: number, layer: number) => void;
+    setWindInAdditionalStrengthMax: (max: number, layer: number) => void;
+    setWindInDurationMin: (min: number, layer: number) => void;
+    setWindInDurationMax: (max: number, layer: number) => void;
+    setWindInDelayMin: (min: number, layer: number) => void;
+    setWindInDelayMax: (max: number, layer: number) => void;
+    setWindOutDurationMin: (min: number, layer: number) => void;
+    setWindOutDurationMax: (max: number, layer: number) => void;
+    setWindOutDelayMin: (min: number, layer: number) => void;
+    setWindOutDelayMax: (max: number, layer: number) => void;
+    setWindOutChangeChance: (chance: number, layer: number) => void;
+    setColour: (colour: string, layer: number) => void;
+    setMassMin: (min: number, layer: number) => void;
+    setMassMax: (max: number, layer: number) => void;
+    setSizeMin: (min: number, layer: number) => void;
+    setSizeMax: (max: number, layer: number) => void;
+    restart: (config?: UserConfig) => void;
+    stop: () => void;
+}
+export interface HasGravity {
+    setGravity(degrees: number, strength: number): void;
+    setGravityAngle(degrees: number): void;
+    setGravityStrength(strength: number): void;
+}
+export interface HasWind {
+    setWind(degrees: number, strength: number): void;
+    setWindAngle(degrees: number): void;
+    setWindStrength(strength: number): void;
+    setGusts(gusts: boolean): void;
+    setWindInAdditionalStrengthMin(min: number): void;
+    setWindInAdditionalStrengthMax(max: number): void;
+    setWindInDurationMin(min: number): void;
+    setWindInDurationMax(max: number): void;
+    setWindInDelayMin(min: number): void;
+    setWindInDelayMax(max: number): void;
+    setWindOutDurationMin(min: number): void;
+    setWindOutDurationMax(max: number): void;
+    setWindOutDelayMin(min: number): void;
+    setWindOutDelayMax(max: number): void;
+    setWindOutChangeChance(chance: number): void;
+}
+export interface HasSway {
+    setAmplitude(num: number): void;
+    setFrequency(freq: number): void;
+}
+export interface HasDensity {
+    setDensity(density: number): void;
+}
+export interface HasRender {
+    render(gfx: Graphics): void;
+}
+export interface IBaseLayer extends HasGravity, HasWind, HasSway {
+    start(): void;
+    pause(): void;
+    resume(): void;
+    restart(): void;
+    update(dt: number): void;
+    setPaused(pause: boolean): void;
+    togglePaused(): void;
+}
+export interface ISimpleLayer extends IBaseLayer, HasRender {
+    mode: 'simple';
+    config: SimpleLayerConfig;
+    setColour(colour: string): void;
+}
+export interface IImageLayer extends IBaseLayer, HasRender {
+    mode: 'image';
+    config: ImageLayerConfig;
+    setImage(image: string): void;
+}

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+import { BaseLayerConfig, ConfigLayer, ImageLayerConfig, SimpleLayerConfig, UserSchedule } from './types';
+export declare function getElementOrThrow(id: string): HTMLElement;
+export declare function withinSchedule(schedule: UserSchedule): boolean;
+export declare function requiredSnowflakes(width: number, height: number, density: number): number;
+export declare function clone(obj: any): any;
+export declare function makeSnowflakes(num: number, config: BaseLayerConfig | SimpleLayerConfig | ImageLayerConfig, width: number, height: number): {
+    position: import("@erikwatson/bramble").Vec2;
+    mass: number;
+    size: number;
+    renderedSize: number;
+    noise: number;
+    amplitude: number;
+    frequency: number;
+    random: number;
+    rotation: number;
+    time: number;
+    opacity: number;
+}[];
+export declare function isSimpleLayer(layer: ConfigLayer): layer is SimpleLayerConfig;