@adatechnology/game-weather 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,9 @@
 # @adatechnology/game-weather
 
 Pure, seeded weather for games: states from clear to typhoon, climates that move between them in game time, lightning with the thunder delay,
-ground wetness, what the weather means for sight, hearing and footsteps, the heat index and the day-night formula. No three.js, no audio, no
-game content; renderers and sound engines read it. Zero runtime dependencies; works in the browser and in Node.
+ground wetness, what the weather means for sight, hearing and footsteps, the heat index and the day-night formula, and the bridges that push it to
+the fluid film, the interactables, the vegetation, the effects world, the environment bus and the sound. No three.js and no game content; renderers
+read it. Depends on `game-contracts` and `game-audio` (the rain, wind and thunder recipes); works in the browser and in Node.
 
 The numbers come from the teams' pages (each state lists its `sources`): the rain, fog and lightning of the VFX Workshop, the dry and wet fog and
 the day of the game, the wind and fog of the Art Scene, the rain rules of the Vale Cinzento gallery. Cyclone, typhoon and extreme heat have no team
@@ -93,3 +94,36 @@ Arte, Galeria do Vale Cinzento); ciclone, tufão e calor intenso não têm fonte
 - Relâmpago com fluxo próprio de semente (o servidor manda a semente e todos veem o mesmo clarão); trovão `distância / 343` s depois.
 - O solo seca 180 s depois que a chuva para; `effects` entrega `sightScale`, `hearingScale`, `footstepScale`, índice de calor e estresse de calor.
 - Catálogo por registro: acrescente, troque (`patch`) ou tire estados e climas sem mexer no núcleo.
+
+## Bridges
+
+`createWeatherBridges(targets, options)` pushes one weather to whatever you give it. Every target is optional and an interface of its own, so the
+weather imports none of the packages it drives:
+
+```ts
+import { createWeatherBridges } from '@adatechnology/game-weather'
+
+const bridges = createWeatherBridges({
+  film: room.film, // game-fluids-three FilmBridge: setWeather({ rain, drying }), wash()
+  interactables: world, // game-interactables: water.setRain(mm/h), setWind(x, z)
+  vegetation, // game-vegetation: setWind({ direction, strength, gust })
+  vfx: vfxWorld, // game-vfx: setWind([x, 0, z])
+  environment: host.environment, // the EnvironmentBus
+  audio: host.audio, // rain and wind loops, thunder
+})
+bridges.bind(weather)
+// every frame, after weather.advance(dt)
+bridges.update(dt)
+```
+
+The rules are numbers you can change (`filmRainFullAt`, `washFrom`, `washBelow`, `washEvery`, `windFull`): light rain (2.5 mm/h) stops the drying and
+does not wash; heavy rain (15 mm/h) and stronger washes the fresh stain (less than half dry) once a second; extreme heat dries twice as fast; the
+vegetation's `strength` is `min(1, speed / 20)`.
+
+Sound: `WEATHER_BANK` holds `rain_loop` and `wind_loop` (art scene), `rain_hiss_game` (game) and `thunder`. `createWeatherSound` sets the rain loop
+from 0.035 (light rain) to 0.06 (heavy), the wind loop at 0.05 in the breeze and in proportion to the speed, and plays the thunder at the strike's
+bearing when it arrives (`distance / 343` s after the flash). `options.sound` changes the style (`art_scene` or `game`), the levels and the listener.
+
+The picture is `@adatechnology/game-weather-three`. The bench takes it as `visual` (a `WeatherVisualFactory`: `layers(locale)` before the room lends anything, then
+`create({ host, locale, weather })` returning `{ update(dt), setLayer(id, on), dispose() }`); with a visual the bench leaves the scene fog to it:
+`createWeatherTestModule({ visual: createWeatherVisual({ vfx: room.vfx }) })`.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { TestableModule } from '@adatechnology/game-contracts';
+import { Vec3, AudioSink, EnvironmentBus, EnvironmentState, TestableModule, ModuleLayer, ModuleHost } from '@adatechnology/game-contracts';
+import { LoopRecipe, SoundRecipe, SoundBank } from '@adatechnology/game-audio';
 
 /** Every number of a weather state; these are the values that blend between two states. */
 type StateValues = {
@@ -335,6 +336,178 @@ declare function createRng(seed: number): () => number;
 declare function streamSeed(seed: number, name: string): number;
 declare function createStream(seed: number, name: string): () => number;
 
+type WeatherSoundStyle = 'art_scene' | 'game';
+type WeatherSoundOptions = {
+    /** Which team's rain: `art_scene` (default, the kit mix) or `game` (a highpass hiss). The wind and the thunder are the same. */
+    readonly style?: WeatherSoundStyle;
+    /**
+     * Level of the rain loop. It is `light` at `lightAt` mm/h (the game's rain, 0.035) and `heavy` from `heavyAt` mm/h (the art scene's, 0.06), a straight
+     * line between, and 0 when it does not rain.
+     */
+    readonly rain?: {
+        readonly light?: number;
+        readonly heavy?: number;
+        readonly lightAt?: number;
+        readonly heavyAt?: number;
+    };
+    /** Level of the wind loop: `base` (the art scene's 0.05) at `referenceSpeed` m/s, in proportion to the speed, at most `max`. */
+    readonly wind?: {
+        readonly base?: number;
+        readonly referenceSpeed?: number;
+        readonly max?: number;
+    };
+    /** Where the listener is, to place the thunder around it (default the origin). */
+    readonly listener?: () => Vec3;
+    /** Level of the thunder (default 1). */
+    readonly thunderVolume?: number;
+    /** `false` keeps the sink's bank as it is (the host registered `WEATHER_BANK` itself). */
+    readonly register?: boolean;
+};
+declare const DEFAULT_RAIN_SOUND: {
+    readonly light: 0.035;
+    readonly heavy: 0.06;
+    readonly lightAt: 2.5;
+    readonly heavyAt: 15;
+};
+/** The art scene opens its wind at 0.05 with the breeze of its day (3.8 m/s, the `clear` state's wind): the level follows the speed from there. */
+declare const DEFAULT_WIND_SOUND: {
+    readonly base: 0.05;
+    readonly referenceSpeed: 3.8;
+    readonly max: 0.12;
+};
+/** The level of the rain loop for `rain` mm/h. */
+declare function rainVolume(rain: number, options?: WeatherSoundOptions['rain']): number;
+/** The level of the wind loop for a wind of `speed` m/s. */
+declare function windVolume(speed: number, options?: WeatherSoundOptions['wind']): number;
+/** Where a strike is, around `origin`: `bearing` is degrees clockwise from north, and north is -z. */
+declare function strikePosition(strike: Pick<Strike, 'distance' | 'bearing'>, origin?: Vec3): Vec3;
+type WeatherSound = {
+    /** Sets the level of the loops from the weather of now (opens a loop the first time it is above 0). */
+    update(sample: Pick<WeatherSample, 'rain' | 'windSpeed'>): void;
+    /** Plays a clap of thunder at the strike (call it when the thunder arrives: the weather delays it by `distance / 343`). */
+    thunder(strike: Pick<Strike, 'distance' | 'bearing'>): void;
+    dispose(): void;
+};
+/** The sound of the weather on the host's `audio`: the rain loop, the wind loop and the thunder. Without a sink (or one without loops) it does nothing. */
+declare function createWeatherSound(sink: AudioSink | undefined, options?: WeatherSoundOptions): WeatherSound;
+
+/** The shape of the film of `game-fluids-three` (`FilmBridge`) this needs: no import, so the weather does not depend on it. */
+type FilmTarget = {
+    setWeather(weather: {
+        rain: number;
+        drying?: number;
+    }): void;
+    wash?(maxDryness?: number): number;
+};
+/** The interactables world (`game-interactables`): its water takes the rain, the soft volumes the wind. */
+type InteractablesTarget = {
+    water: {
+        setRain(mmPerHour: number): void;
+    };
+    setWind(x: number, z: number): void;
+};
+/** The vegetation renderer (`game-vegetation`). `direction` is normalised by the renderer, `strength` and `gust` are 0..1. */
+type VegetationTarget = {
+    setWind(wind: {
+        direction?: [number, number];
+        strength?: number;
+        gust?: number;
+    }): void;
+};
+/** The effects world (`game-vfx`'s `VfxWorld`): smoke and dust drift with its wind. */
+type VfxTarget = {
+    setWind(wind: readonly [number, number, number]): void;
+};
+type WeatherTargets = {
+    readonly film?: FilmTarget;
+    readonly interactables?: InteractablesTarget;
+    readonly vegetation?: VegetationTarget;
+    readonly vfx?: VfxTarget;
+    /** The host's environment bus (`ModuleHost.environment`). */
+    readonly environment?: Pick<EnvironmentBus, 'set'>;
+    /** The host's sound (`ModuleHost.audio`): the rain and wind loops, and the thunder. */
+    readonly audio?: AudioSink;
+};
+/** The rules the bridges apply; every number can be replaced. */
+type WeatherBridgeRules = {
+    /** Rain in mm/h at which the film counts as fully rained on (it stops drying, spreads 1.5 times faster). Default 2.5, the light rain. */
+    readonly filmRainFullAt?: number;
+    /** Rain in mm/h from which the rain washes the fresh stain (Workshop and visor: heavy rain and stronger). Default 15; light rain does not wash. */
+    readonly washFrom?: number;
+    /** Stains less dry than this are washed (visor L13494). Default 0.5. */
+    readonly washBelow?: number;
+    /** Seconds between two washes while it pours. Default 1. */
+    readonly washEvery?: number;
+    /** Wind speed in m/s that is 1 for the vegetation (`strength = min(1, speed / this)`). Default 20. */
+    readonly windFull?: number;
+};
+type WeatherBridgeOptions = WeatherBridgeRules & {
+    readonly sound?: WeatherSoundOptions | false;
+};
+declare const DEFAULT_BRIDGE_RULES: {
+    readonly filmRainFullAt: 2.5;
+    readonly washFrom: 15;
+    readonly washBelow: 0.5;
+    readonly washEvery: 1;
+    readonly windFull: 20;
+};
+/** The weather as the environment bus holds it. */
+declare function environmentOf(sample: WeatherSample): Partial<EnvironmentState>;
+type WeatherBridges = {
+    /** Follows this weather (the one before is let go) and pushes its values at once. */
+    bind(weather: Weather): void;
+    /** Pushes the weather of now to every target; call it each frame after `weather.advance(dt)`. */
+    update(dt: number): void;
+    dispose(): void;
+};
+/**
+ * Pushes one weather to the packages that react to it, each through a small interface of its own, so the weather depends on none of them and every
+ * target is optional:
+ * - fluids film: `setWeather({ rain: min(1, rain / filmRainFullAt), drying: dryingScale })`, and `wash()` every `washEvery` seconds while the rain is at
+ *   `washFrom` or stronger (light rain stops the drying and does not wash);
+ * - interactables: `water.setRain(mm/h)` and `setWind(x, z)`;
+ * - vegetation: `setWind({ direction: [x, z], strength: min(1, speed / windFull), gust: min(1, gust / windFull) })`;
+ * - vfx: `setWind([x, 0, z])`;
+ * - the environment bus: every value of `environmentOf`;
+ * - sound: the rain and wind loops follow the weather, and each thunder that arrives plays at its bearing.
+ */
+declare function createWeatherBridges(targets: WeatherTargets, options?: WeatherBridgeOptions): WeatherBridges;
+
+/** Rain of the art scene: noise through a highpass at 600 Hz and a lowpass at 6000 Hz (cena L1314), opened at its volume. */
+declare const RAIN_LOOP: LoopRecipe;
+/** Wind of the art scene: noise through a lowpass at 320 Hz whose gain swings 0.035 at 0.07 Hz (cena L1315). */
+declare const WIND_LOOP: LoopRecipe;
+/** Rain of the game: noise through a highpass at 2500 Hz, created when the volume first passes 0.002 (jogo L62116 `chuva`). */
+declare const RAIN_HISS_GAME: LoopRecipe;
+/**
+ * Thunder. The thump is the game's boom (a sine from 70 to 28 Hz over 1.2 s); the rumble is a lowpassed noise that slides from 260 to 50 Hz over 3.2 s
+ * with a reverb send, the kit's choice (no team has a thunder). It carries much farther than a blast: `k` is 0.00001, so a strike 1 km away is still at
+ * 0.13 and one 4 km away (the farthest the weather places) at 0.009.
+ */
+declare const THUNDER: SoundRecipe;
+declare const WEATHER_BANK: SoundBank;
+declare const WEATHER_SOUNDS: readonly SoundRecipe[];
+declare const WEATHER_LOOPS: readonly LoopRecipe[];
+
+/** What a renderer of the weather (game-weather-three) gives the bench: its layers, a step per frame and the switch of each layer. */
+type WeatherVisual = {
+    update(dt: number): void;
+    setLayer(id: string, on: boolean): void;
+    dispose(): void;
+};
+/** The bench hands a visual the weather it shows (always the live one, even after the bench restarts it) and what the room lends. */
+type WeatherVisualContext = {
+    readonly host: ModuleHost;
+    readonly locale: string;
+    readonly weather: {
+        sample(): WeatherSample;
+    };
+};
+/** The bench declares its layers before the room lends anything, so the factory tells them first (`fog` is the bench's own layer and reaches the visual through `setLayer` too). */
+type WeatherVisualFactory = {
+    layers(locale: string): readonly ModuleLayer[];
+    create(context: WeatherVisualContext): WeatherVisual;
+};
 type WeatherTestModuleOptions = WeatherOptions & {
     locale?: string;
     /** Text of a state id in the game's words; without it the bench uses its own names, then the id. */
@@ -343,6 +516,12 @@ type WeatherTestModuleOptions = WeatherOptions & {
     weather?: Weather;
     /** Whether the scene fog follows the weather at first (default true; the layer can be switched either way). A room that is not about weather starts it off. */
     fog?: boolean;
+    /** The packages the weather drives besides the host's environment bus and sound (fluids film, interactables, vegetation, vfx), from the example. */
+    targets?: Omit<WeatherTargets, 'environment' | 'audio'>;
+    /** The rain, wind and thunder on the host's `audio`; `false` keeps the area silent. */
+    sound?: WeatherSoundOptions | false;
+    /** The picture of the weather (rain, fog, sky, lightning, headlights, haze), from `@adatechnology/game-weather-three`. With it the bench leaves the scene fog to the visual. */
+    visual?: WeatherVisualFactory;
 };
 /** What the scenarios use of the context the test room passes. */
 interface WeatherScenarioLike {
@@ -373,4 +552,4 @@ type WeatherBenchText = {
 };
 declare const weatherBenchTextOf: (locale: string) => WeatherBenchText;
 
-export { CLIMATES, type Climate, DAY_REAL_SECONDS, DEFAULT_DRY_OUT_SECONDS, DEFAULT_START_HOUR, DEFAULT_TIME_SCALE, DEFAULT_WET_RISE_SECONDS, DRY_VISIBILITY_METERS, type Daylight, type DeepPartial, type EffectsInput, FLASH_END_SECONDS, GAME_DAY_SECONDS, type LightningConfig, type LightningStream, NIGHT_SIGHT_LOSS, type RegistryOptions, SPEED_OF_SOUND, STATE_VALUE_KEYS, type Scheduler, type StateValueKey, type StateValues, type Strike, type TimelineOptions, WEATHER_STATES, type Weather, type WeatherBenchText, type WeatherEffects, type WeatherEventMap, type WeatherOptions, type WeatherRegistry, type WeatherSample, type WeatherScenarioLike, type WeatherState, type WeatherTestModule, type WeatherTestModuleOptions, type WeatherTimeline, type Wetness, type WetnessOptions, blendValues, createLightningStream, createRng, createScheduler, createStream, createTimeline, createWeather, createWeatherRegistry, createWeatherTestModule, createWetness, dayFractionAt, daylight, deriveEffects, flashIntensity, heatIndexC, heatStress, streamSeed, thunderDelay, valuesOf, weatherBenchTextOf };
+export { CLIMATES, type Climate, DAY_REAL_SECONDS, DEFAULT_BRIDGE_RULES, DEFAULT_DRY_OUT_SECONDS, DEFAULT_RAIN_SOUND, DEFAULT_START_HOUR, DEFAULT_TIME_SCALE, DEFAULT_WET_RISE_SECONDS, DEFAULT_WIND_SOUND, DRY_VISIBILITY_METERS, type Daylight, type DeepPartial, type EffectsInput, FLASH_END_SECONDS, type FilmTarget, GAME_DAY_SECONDS, type InteractablesTarget, type LightningConfig, type LightningStream, NIGHT_SIGHT_LOSS, RAIN_HISS_GAME, RAIN_LOOP, type RegistryOptions, SPEED_OF_SOUND, STATE_VALUE_KEYS, type Scheduler, type StateValueKey, type StateValues, type Strike, THUNDER, type TimelineOptions, type VegetationTarget, type VfxTarget, WEATHER_BANK, WEATHER_LOOPS, WEATHER_SOUNDS, WEATHER_STATES, WIND_LOOP, type Weather, type WeatherBenchText, type WeatherBridgeOptions, type WeatherBridgeRules, type WeatherBridges, type WeatherEffects, type WeatherEventMap, type WeatherOptions, type WeatherRegistry, type WeatherSample, type WeatherScenarioLike, type WeatherSound, type WeatherSoundOptions, type WeatherSoundStyle, type WeatherState, type WeatherTargets, type WeatherTestModule, type WeatherTestModuleOptions, type WeatherTimeline, type WeatherVisual, type WeatherVisualContext, type WeatherVisualFactory, type Wetness, type WetnessOptions, blendValues, createLightningStream, createRng, createScheduler, createStream, createTimeline, createWeather, createWeatherBridges, createWeatherRegistry, createWeatherSound, createWeatherTestModule, createWetness, dayFractionAt, daylight, deriveEffects, environmentOf, flashIntensity, heatIndexC, heatStress, rainVolume, streamSeed, strikePosition, thunderDelay, valuesOf, weatherBenchTextOf, windVolume };