minimojs 1.0.0-alpha.21 → 1.0.0-alpha.23

package/dist/minimo-ambient.d.ts

@@ -0,0 +1,299 @@
+import { Game, Sprite } from "./minimo.js";
+/**
+ * The weather and light of an {@link Ambient}.
+ *
+ * Every number runs from `0` to `1`, except {@link AmbientState.wind}, which
+ * runs from `-1` to `1`. Change it with {@link Ambient.set},
+ * {@link Ambient.to}, or {@link Ambient.preset}; read it from
+ * {@link Ambient.state}.
+ */
+export interface AmbientState {
+    /** Wind direction and strength: `1` is strong wind to the right, `-1` to the left. */
+    wind: number;
+    /** How irregularly the wind blows around {@link AmbientState.wind}. */
+    gusts: number;
+    /** Rain intensity. Rain splashes on the ambient's surfaces. */
+    rain: number;
+    /** Snow intensity. With {@link Ambient.snowSettles}, snow builds up on surfaces. */
+    snow: number;
+    /** Fog: drifting bands of mist and a haze over the scene. */
+    fog: number;
+    /** Lightning frequency. Flashes never exceed the safe rate, whatever the value. */
+    storm: number;
+    /** How dark the scene is: `1` is deep night. */
+    darkness: number;
+    /** How strongly {@link AmbientState.tintColor} colors the scene: `1` lays it at 50% over it. */
+    tint: number;
+    /** How many stars show in the sky. Clouds from rain, snow, and fog hide them. */
+    stars: number;
+    /** Hex color of the tint, such as `"#1b2a55"`. Interpolated in RGB by {@link Ambient.to}. */
+    tintColor: string;
+}
+/** The numeric fields of {@link AmbientState}. */
+export type AmbientField = Exclude<keyof AmbientState, "tintColor">;
+/** A partial state for {@link Ambient.set} and {@link Ambient.to}. */
+export type AmbientChange = Partial<AmbientState>;
+/**
+ * A named weather for {@link Ambient.preset}. Presets are geometric only, so
+ * every one works in any game without art.
+ */
+export type AmbientPreset = "clear" | "drizzle" | "rain" | "storm" | "snow" | "blizzard" | "mist" | "windy";
+/** A horizontal line in world space that rain splashes on and snow settles on. */
+export interface AmbientLine {
+    /** World X of the line's left end. */
+    left: number;
+    /** World X of the line's right end. */
+    right: number;
+    /** World Y of the line. */
+    y: number;
+}
+/** A rectangle in world space where no rain, snow, or falling drift is drawn. */
+export interface AmbientRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Something rain splashes on and snow settles on. A sprite counts by the top
+ * edge of its collision body, and is followed if it moves.
+ */
+export type AmbientSurface = Sprite | AmbientLine;
+/**
+ * A covered area, such as a cave, a roof, or an awning. A sprite counts by its
+ * collision body, and is followed if it moves.
+ */
+export type AmbientShelter = Sprite | AmbientRect;
+/** Options for {@link Ambient}. Every field is optional. */
+export interface AmbientOptions {
+    /** Sprite layer of the surface drawn behind the play field. Default `5`. */
+    backLayer?: number;
+    /**
+     * Sprite layer of the surface drawn in front of the play field: the nearest
+     * particles, splashes, settled snow, haze, darkness, and flashes. Put the
+     * HUD above it. Default `900`.
+     */
+    frontLayer?: number;
+    /** Share of particles that are nearer than the play field and drawn in front of it. Default `0.25`. */
+    front?: number;
+    /** Seed for reproducible weather. Omit it for different weather on every load. */
+    seed?: number;
+    /** Hard cap on rain, snow, and drift particles together. Lowered on weak devices. Default `900`. */
+    maxParticles?: number;
+    /** Wind speed in pixels per second at `wind: 1`. Default `600`. */
+    windStrength?: number;
+    /** Initial {@link Ambient.surfaces}. */
+    surfaces?: AmbientSurface[];
+    /** Initial {@link Ambient.shelters}. */
+    shelters?: AmbientShelter[];
+    /** Initial {@link Ambient.snowSettles}. Default `false`. */
+    snowSettles?: boolean;
+    /** Deepest settled snow, in pixels. Default `16`. */
+    maxSnowDepth?: number;
+    /** Hex color of the fog. Default `"#dde5ee"`; a sand color makes a sandstorm. */
+    fogColor?: string;
+    /** Hex color of rain. Default `"#c8d6ea"`. */
+    rainColor?: string;
+    /** Hex color of snow, falling and settled. Default `"#ffffff"`. */
+    snowColor?: string;
+    /**
+     * Forces reduced motion on or off. By default it follows the player's
+     * `prefers-reduced-motion` setting: fewer particles and softer lightning.
+     */
+    reducedMotion?: boolean;
+    /** Initial state. Fields left out start at `0`, and `tintColor` at `"#1b2a55"`. */
+    state?: AmbientChange;
+}
+/** A lightning strike, passed to {@link Ambient.onLightning}. */
+export interface AmbientStrike {
+    /** `0` is overhead, `1` is far away. Use it to delay and soften the thunder. */
+    distance: number;
+    /** Screen X of the bolt, in pixels. */
+    x: number;
+}
+/** A glowing dot, the art of a drift that uses no image: fireflies, embers, dust. */
+export interface AmbientDot {
+    /** Hex color of the dot, such as `"#fff6a0"`. */
+    color: string;
+    /** Radius of the solid core, in pixels. Default `2`. */
+    radius?: number;
+    /** Radius of the soft halo around the core, in pixels. Default `0`. */
+    glow?: number;
+}
+/**
+ * How a drift moves.
+ *
+ * - `"fall"`: sways and tumbles downward, like leaves, petals, or ash. Rests a
+ *   moment where it lands on a surface.
+ * - `"rise"`: floats upward, like embers or bubbles.
+ * - `"hover"`: wanders slowly in place, like fireflies or dust.
+ */
+export type AmbientDriftMotion = "fall" | "rise" | "hover";
+/** Options for {@link Ambient.addDrift}. Give either `images` or `dot`. */
+export interface AmbientDriftOptions {
+    /** How the drift moves. */
+    motion: AmbientDriftMotion;
+    /** Image keys the game loaded or created; each particle picks one. */
+    images?: string[];
+    /** A glowing dot, for drifts that need no image. */
+    dot?: AmbientDot;
+    /** Density from `0` to `1`, like the state fields. Default `0.5`. */
+    amount?: number;
+    /**
+     * Size of an image particle, as the pixel length of its longest side, or a
+     * `[min, max]` range. Nearer particles are drawn larger. Default `[16, 32]`.
+     * Ignored for dots, which use their own radius.
+     */
+    size?: number | [number, number];
+    /** Speed multiplier. Default `1`. */
+    speed?: number;
+    /** How much images tumble and turn: `0` keeps them upright. Default `1` for `"fall"`, `0` otherwise. */
+    spin?: number;
+    /** Side-to-side swing. Default `1`. */
+    sway?: number;
+    /** How much the wind carries the drift, `0` for none, as underwater. Default `1` for `"fall"`, `0.5` otherwise. */
+    wind?: number;
+    /** Brightness flicker from `0` to `1`. Default `0`. */
+    twinkle?: number;
+    /**
+     * Draw the drift above the darkness, so it glows at night. Default `true`
+     * for a dot with a glow, `false` otherwise.
+     */
+    lit?: boolean;
+    /** Fade out while rising instead of leaving through the top. Default `true` for dots, `false` for images. */
+    fade?: boolean;
+}
+/**
+ * A stream of leaves, petals, embers, bubbles, fireflies, or dust, created by
+ * {@link Ambient.addDrift}. It shares the ambient's wind and parallax.
+ */
+export declare class AmbientDrift {
+    /** How the drift moves. */
+    get motion(): AmbientDriftMotion;
+    /** Density from `0` to `1`. Setting it stops a running {@link AmbientDrift.to}. */
+    get amount(): number;
+    set amount(value: number);
+    /**
+     * Changes the density over `durationMs` milliseconds. The promise resolves
+     * when the amount arrives, or when a later change takes over.
+     */
+    to(amount: number, durationMs: number): Promise<void>;
+}
+/**
+ * Weather and atmosphere for a game: rain, snow, wind, fog, lightning,
+ * drifting leaves or fireflies, and the light of the hour.
+ *
+ * One shared state of intensities drives every effect, and every effect reads
+ * the same wind. All particles are painted into two canvas-sized surfaces, one
+ * behind the play field and one in front of it, so the module adds two sprites
+ * to the game whatever the weather.
+ *
+ * The ambient never moves a game sprite. The wind reaches the game only through
+ * {@link Ambient.windX}, which the game applies where it wants.
+ *
+ * Call {@link Ambient.update} once per frame. An ambient survives
+ * {@link Game.reset}: it puts its surfaces back on its next update and keeps
+ * its weather, so one ambient can serve every scene. Creating a new one in a
+ * scene's `onCreate` also works.
+ *
+ * @example
+ * ```ts
+ * const ambient = new Ambient(game, { surfaces: [ground], seed: 7 });
+ * ambient.preset("rain");
+ *
+ * // in onUpdate(dt)
+ * ambient.update(dt);
+ *
+ * // later: a storm rolls in over four seconds
+ * await ambient.to({ rain: 1, storm: 0.6, wind: 0.5 }, 4000);
+ * ```
+ */
+export declare class Ambient {
+    /**
+     * Things rain splashes on and snow settles on: sprites, by the top of their
+     * collision body, or {@link AmbientLine}s in world space.
+     */
+    surfaces: AmbientSurface[];
+    /**
+     * Covered areas where no rain, snow, or falling drift is drawn: sprites, by
+     * their collision body, or {@link AmbientRect}s in world space.
+     */
+    shelters: AmbientShelter[];
+    /** When `true`, snow builds up on surfaces while it snows and melts when it stops. */
+    snowSettles: boolean;
+    /** Softer lightning and fewer particles. Follows the player's system setting unless the game sets it. */
+    reducedMotion: boolean;
+    /**
+     * Called on every lightning strike, for thunder, a camera shake, or a
+     * gameplay reaction.
+     */
+    onLightning: ((strike: AmbientStrike) => void) | null;
+    /**
+     * Creates an ambient and adds its two surfaces to the game.
+     *
+     * @param game - The game to draw into.
+     * @param options - Layers, surfaces, shelters, seed, colors, and initial state.
+     */
+    constructor(game: Game, options?: AmbientOptions);
+    /** The current state. Read-only: change it with {@link Ambient.set}, {@link Ambient.to}, or {@link Ambient.preset}. */
+    get state(): Readonly<AmbientState>;
+    /**
+     * The wind at this frame, gusts included, in pixels per second. Positive
+     * blows right. This is the only way the weather reaches the game's sprites:
+     *
+     * ```ts
+     * player.vx += ambient.windX * 0.3 * dt;
+     * ```
+     */
+    get windX(): number;
+    /** `true` while any {@link Ambient.to} or {@link Ambient.preset} transition is running. */
+    get isTransitioning(): boolean;
+    /** Changes state fields at once. Fields left out keep their value. */
+    set(change: AmbientChange): void;
+    /**
+     * Changes state fields over `durationMs` milliseconds with an ease in and
+     * out. Fields left out keep their value and any transition they are in.
+     *
+     * A field that is already moving starts from wherever it is, so a new call
+     * can interrupt an old one without a jump. The promise resolves when every
+     * field arrives, or when later calls have taken all of them over.
+     */
+    to(change: AmbientChange, durationMs: number): Promise<void>;
+    /**
+     * Moves to a named weather. The preset's fields are set, and the other
+     * weather fields (`wind`, `gusts`, `rain`, `snow`, `fog`, `storm`) go to `0`.
+     * Light fields are left alone, because weather and time of day are
+     * independent.
+     *
+     * @param name - The preset.
+     * @param durationMs - Transition length in milliseconds. `0`, the default, changes at once.
+     */
+    preset(name: AmbientPreset, durationMs?: number): Promise<void>;
+    /**
+     * Adds a stream of drifting things: leaves, petals, embers, bubbles,
+     * fireflies, or dust. Images must already be loaded or created.
+     *
+     * @example
+     * ```ts
+     * const leaves = ambient.addDrift({ images: ["leaf-red", "leaf-gold"], motion: "fall", amount: 0.5 });
+     * const fireflies = ambient.addDrift({ dot: { color: "#fff6a0", glow: 8 }, motion: "hover", twinkle: 1 });
+     * ```
+     */
+    addDrift(options: AmbientDriftOptions): AmbientDrift;
+    /** Removes a drift at once. Fade it out first with `drift.to(0, ms)` for a gentle exit. */
+    removeDrift(drift: AmbientDrift): void;
+    /** Removes all settled snow at once. */
+    clearSnow(): void;
+    /**
+     * Depth of settled snow in pixels on a surface at world X, `0` where there
+     * is none. Useful for footprints, or for slowing a player in deep snow.
+     */
+    snowDepthAt(surface: AmbientSurface, worldX: number): number;
+    /**
+     * Advances the weather by `dt` seconds. Call it once per frame from the
+     * scene's `onUpdate`. Transition promises resolve from here.
+     */
+    update(dt: number): void;
+    /** Removes both surfaces from the game and resolves every pending transition. The ambient does nothing afterwards. */
+    destroy(): void;
+}