A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file weather.ts
* @brief What a weather IS — a handful of scales and levels — and how it reaches the picture.
*
* @details A weather is not a set of effect parameters: a project's fog density is in its own units and its sun is as
* bright as its author made it. A preset therefore speaks in MULTIPLIERS of what the scene already says (the sun
* at a quarter of its strength, the fog five times as thick) and in a few absolute levels where a number means
* the same everywhere (how hard it rains, how wet the ground is). The same preset then fits any scene.
*
* The state is blended between two presets by a transition's progress, and applied in two places: to the lights
* (the component's own, in play mode only — see weatherSystem) and, after the volumes have blended, to the
* effects that result.
*/
import type { BlendedEffect, Rgba } from './volumeBlending';
import { getEffectDef, uniformInUnits } from './effects';
export interface WeatherState {
/** × the directional lights' strength. */
sun: number;
/** × the ambient light's strength. */
sky: number;
/** × the directional light's colour. */
sunTint: [number, number, number];
/** How soft its shadows are, in suns: 1 leaves them as authored, 8 makes the source eight times wider across the
* sky — an overcast sky's shadows are barely there, and the ones that are fade into the ground. */
shadowSoftness: number;
/** × how dark the light's shadows are. */
shadowStrength: number;
/** × Height Fog's density. */
fogDensity: number;
/** The colour fog moves toward, and how far (0 = its own colour). */
fogTint: [number, number, number];
fogTintAmount: number;
/** × Height Fog's sun glow and the shafts it carries. */
fogGlow: number;
/** × Height Fog's sky haze, capped at 1. */
skyFog: number;
/** × Colour Grade's saturation and contrast. */
saturation: number;
contrast: number;
/** Stops added to Auto Exposure's compensation. */
exposure: number;
/** The rain effect's strength, and the wetness and puddles it leaves. Absolute. */
rain: number;
wetness: number;
puddles: number;
/** How much snow lies, 0..1. Absolute. */
snow: number;
/** × Screen Space Reflections' strength. */
ssr: number;
/** × what baked reflection probes show, and × their colour (1 keeps it, 0 is grey): a probe was baked under
* whatever sky the scene had then. */
reflection: number;
reflectionSaturation: number;
/** How overcast the sky is, 0 clear .. 1 grey: what Sky Atmosphere draws no sun, moon or stars through. */
overcast: number;
/** How loud the rain on the soundtrack is, 0..2. */
sound: number;
/** × the wind: how far plants sway (a Foliage material's u_windStrength). */
wind: number;
/** × the waves' height on every body of water, in what is drawn and in what the surface answers. */
waves: number;
}
export type WeatherPreset = Partial<WeatherState>;
const NEUTRAL: WeatherState = {
sun: 1, sky: 1, sunTint: [1, 1, 1], shadowSoftness: 1, shadowStrength: 1,
fogDensity: 1, fogTint: [0.7, 0.72, 0.76], fogTintAmount: 0, fogGlow: 1, skyFog: 1,
saturation: 1, contrast: 1, exposure: 0,
rain: 0, wetness: 0, puddles: 0, snow: 0, ssr: 1,
reflection: 1, reflectionSaturation: 1, overcast: 0, sound: 0, wind: 1, waves: 1,
};
/** The presets every project has. Their ids are the dropdown's values, so they only ever grow. */
export const WEATHER_CLEAR = 0;
export const WEATHER_MIST = 1;
export const WEATHER_OVERCAST = 2;
export const WEATHER_RAIN = 3;
export const WEATHER_STORM = 4;
export const WEATHER_SNOW = 5;
/** What `target` says when there is nothing to move toward. */
export const WEATHER_NONE = -1;
const registry = new Map<number, { name: string; state: WeatherState }>();
const byName = new Map<string, number>();
let nextCustomId = 100;
function fill(preset: WeatherPreset): WeatherState {
return {
...NEUTRAL, ...preset,
sunTint: preset.sunTint ?? NEUTRAL.sunTint,
fogTint: preset.fogTint ?? NEUTRAL.fogTint,
};
}
function define(id: number, name: string, preset: WeatherPreset): void {
registry.set(id, { name, state: fill(preset) });
byName.set(name, id);
}
define(WEATHER_CLEAR, 'clear', {});
define(WEATHER_MIST, 'mist', {
sun: 0.45, sky: 0.9, shadowSoftness: 3, shadowStrength: 0.8, fogDensity: 8, fogTint: [0.86, 0.86, 0.84], fogTintAmount: 0.7, fogGlow: 1.8, skyFog: 1.7,
saturation: 0.86, contrast: 0.94, exposure: 0.2, wetness: 0.2, puddles: 0.1, ssr: 1.3, reflection: 0.85,
reflectionSaturation: 0.9, overcast: 0.55, wind: 0.4, waves: 0.6,
});
define(WEATHER_OVERCAST, 'overcast', {
sun: 0.25, sky: 0.85, sunTint: [0.9, 0.93, 1], shadowSoftness: 8, shadowStrength: 0.5, fogDensity: 3, fogTint: [0.62, 0.66, 0.72], fogTintAmount: 0.5,
fogGlow: 0.3, skyFog: 1.4, saturation: 0.85, contrast: 0.96, exposure: 0.25, wetness: 0.1, ssr: 1.2,
reflection: 0.7, reflectionSaturation: 0.7, overcast: 0.95, wind: 1.5, waves: 1.3,
});
define(WEATHER_RAIN, 'rain', {
sun: 0.04, sky: 0.75, sunTint: [0.8, 0.86, 1], shadowSoftness: 10, shadowStrength: 0.3, fogDensity: 5.5, fogTint: [0.58, 0.63, 0.7], fogTintAmount: 0.8,
fogGlow: 0, skyFog: 1.7, saturation: 0.73, contrast: 0.93, exposure: 0.45, rain: 1.1, wetness: 1, puddles: 0.6,
ssr: 2.6, reflection: 0.55, reflectionSaturation: 0.5, overcast: 0.9, sound: 1, wind: 1.9, waves: 1.5,
});
define(WEATHER_SNOW, 'snow', {
sun: 0.7, sky: 1.05, sunTint: [0.92, 0.95, 1], shadowSoftness: 2, shadowStrength: 0.7, fogDensity: 1.8, fogTint: [0.82, 0.85, 0.9], fogTintAmount: 0.5,
skyFog: 1.3, saturation: 0.85, contrast: 0.96, exposure: 0.1, snow: 0.85, overcast: 0.75, wind: 0.8,
});
define(WEATHER_STORM, 'storm', {
sun: 0.02, sky: 0.5, sunTint: [0.7, 0.78, 1], shadowSoftness: 10, shadowStrength: 0.2, fogDensity: 8, fogTint: [0.4, 0.44, 0.5], fogTintAmount: 0.9,
fogGlow: 0, skyFog: 1.8, saturation: 0.6, contrast: 0.9, exposure: 0.8, rain: 2.2, wetness: 1, puddles: 1,
ssr: 3, reflection: 0.4, reflectionSaturation: 0.35, overcast: 1, sound: 1.6, wind: 3.2, waves: 2.4,
});
/**
* Adds a weather of the project's own, and returns the id it answers to.
*
* @details A preset names only what it changes; the rest is neutral. Registering a name again replaces it, so a
* project can retune a built-in one. A custom id is for code (`weatherTo`, a component's `preset` value) — the
* Inspector's dropdown lists the built-ins.
*
* @beta
*/
export function registerWeatherPreset(name: string, preset: WeatherPreset): number {
const existing = byName.get(name);
const id = existing ?? nextCustomId++;
define(id, name, preset);
return id;
}
/** The id a preset answers to, or undefined. @beta */
export function weatherPresetId(name: string): number | undefined {
return byName.get(name);
}
/** Every preset, built-in first. @beta */
export function weatherPresetNames(): string[] {
return [...registry.entries()].sort((a, b) => a[0] - b[0]).map(([, v]) => v.name);
}
const ease = (t: number): number => t * t * (3 - 2 * t);
const mix = (a: number, b: number, t: number): number => a + (b - a) * t;
/**
* The weather `progress` of the way from one preset to another, eased so a transition starts and ends gently.
*
* @beta
*/
export function blendWeather(from: number, to: number, progress: number): WeatherState {
const a = (registry.get(from) ?? registry.get(WEATHER_CLEAR)!).state;
if (to === WEATHER_NONE || progress <= 0) return { ...a, sunTint: [...a.sunTint], fogTint: [...a.fogTint] };
const b = (registry.get(to) ?? registry.get(WEATHER_CLEAR)!).state;
const t = ease(Math.min(Math.max(progress, 0), 1));
const out = {} as WeatherState;
for (const key of Object.keys(a) as (keyof WeatherState)[]) {
const x = a[key];
const y = b[key];
(out as unknown as Record<string, unknown>)[key] = Array.isArray(x)
? x.map((v, i) => mix(v, (y as number[])[i], t))
: mix(x as number, y as number, t);
}
return out;
}
// What a Weather component drives. A bit each, so a project can take the fog from the weather and keep its own light.
export const WeatherDrive = {
Lights: 1,
Fog: 2,
Rain: 4,
Grade: 8,
Exposure: 16,
Reflections: 32,
Sound: 64,
/** The plants' sway and the waves' height. */
Wind: 128,
All: 255,
} as const;
/** The state the frame is under, or null when no Weather component is. Set by the weather system, read by the volumes. */
let current: { state: WeatherState; drive: number } | null = null;
export function setCurrentWeather(state: WeatherState | null, drive: number = WeatherDrive.All): void {
current = state ? { state, drive } : null;
}
/** @beta */
export function currentWeather(): WeatherState | null {
return current ? current.state : null;
}
/** The bits of {@link WeatherDrive} the current weather has been asked to apply. */
export function currentWeatherDrive(): number {
return current ? current.drive : 0;
}
/** What an effect's uniform is now: the scene's word if it said one, the effect's own default if it did not. */
function value(effect: BlendedEffect, type: string, name: string, fallback = 0): number {
const set = effect.uniforms.get(name);
if (set !== undefined) return set;
// In the project's units: a fog the weather makes from nothing is as thick per metre as one a volume left unset.
const u = getEffectDef(type)?.uniforms.find((d) => d.name === name);
return u ? uniformInUnits(u).defaultValue : fallback;
}
function entry(effects: Map<string, BlendedEffect>, type: string): BlendedEffect {
let e = effects.get(type);
if (!e) {
e = { enabled: true, uniforms: new Map(), textures: new Map(), colors: new Map() };
effects.set(type, e);
}
return e;
}
const towards = (c: Rgba, tint: [number, number, number], amount: number): Rgba => ({
r: c.r * (1 - amount) + tint[0] * amount,
g: c.g * (1 - amount) + tint[1] * amount,
b: c.b * (1 - amount) + tint[2] * amount,
a: c.a,
});
/**
* Applies the weather to what the volumes blended: the effects the scene authored are scaled and tinted, and the
* ones a weather brings with it (rain, and the grade a weather implies) are added when the scene has none.
*
* @details Multipliers act on whatever the scene resolved — the authored density, the authored saturation — so a scene
* that fogs itself thinly stays thinner than one that fogs itself thickly in the same rain.
*/
export function applyWeatherToEffects(effects: Map<string, BlendedEffect>, state: WeatherState, drive: number): void {
if (drive & WeatherDrive.Fog) {
const fog = effects.get('heightFog');
if (fog && fog.enabled) {
fog.uniforms.set('u_density', value(fog, 'heightFog', 'u_density') * state.fogDensity);
fog.uniforms.set('u_inscatter', value(fog, 'heightFog', 'u_inscatter') * state.fogGlow);
fog.uniforms.set('u_volumetric', value(fog, 'heightFog', 'u_volumetric') * state.fogGlow);
fog.uniforms.set('u_skyFog', Math.min(value(fog, 'heightFog', 'u_skyFog') * state.skyFog, 1));
const colour = fog.colors.get('u_fogColor')
?? getEffectDef('heightFog')?.colors?.find((c) => c.name === 'u_fogColor')?.defaultValue;
if (colour && state.fogTintAmount > 0) fog.colors.set('u_fogColor', towards(colour, state.fogTint, state.fogTintAmount));
}
}
if (drive & WeatherDrive.Fog) {
// A 2D scene's mist is an opacity, not an exponent: the weather's multiplier is taken as a logarithm so a rain
// thickens it without clamping straight to opaque, and it spreads a little as it thickens (more of the ground under it, not only denser banks).
const mist = effects.get('mist2d');
if (mist && mist.enabled) {
mist.uniforms.set('u_density', Math.min(value(mist, 'mist2d', 'u_density') * (1 + 0.25 * Math.log(Math.max(state.fogDensity, 1))), 1));
mist.uniforms.set('u_coverage', Math.min(value(mist, 'mist2d', 'u_coverage') * (1 + 0.04 * (state.fogDensity - 1)), 1));
mist.uniforms.set('u_glow', value(mist, 'mist2d', 'u_glow') * Math.min(state.fogGlow, 1.2));
const colour = mist.colors.get('u_fogColor')
?? getEffectDef('mist2d')?.colors?.find((c) => c.name === 'u_fogColor')?.defaultValue;
if (colour && state.fogTintAmount > 0) mist.colors.set('u_fogColor', towards(colour, state.fogTint, state.fogTintAmount));
}
}
if (drive & WeatherDrive.Fog) {
const sky = effects.get('skyAtmosphere');
if (sky && sky.enabled) sky.uniforms.set('u_overcast', Math.max(value(sky, 'skyAtmosphere', 'u_overcast'), state.overcast));
}
if (drive & WeatherDrive.Rain) {
if (state.rain > 0.001 || state.wetness > 0.001) {
// A rain the scene authored is a floor the weather rises above; one the weather brings is exactly its own.
// A 2D scene's rain is the one that reads no depth; the weather raises it, and brings no second rain beside it.
const flat = effects.get('rain2d');
const type = flat && flat.enabled ? 'rain2d' : 'rain';
const authored = effects.has(type);
const rain = entry(effects, type);
const pick = (name: string, level: number): number => authored ? Math.max(value(rain, type, name), level) : level;
rain.uniforms.set('u_intensity', pick('u_intensity', state.rain));
rain.uniforms.set('u_wetness', pick('u_wetness', state.wetness));
rain.uniforms.set('u_puddles', pick('u_puddles', state.puddles));
}
const ssr = effects.get('ssr');
if (ssr && ssr.enabled) {
ssr.uniforms.set('u_intensity', value(ssr, 'ssr', 'u_intensity') * state.ssr);
ssr.uniforms.set('u_wetness', Math.max(value(ssr, 'ssr', 'u_wetness'), state.wetness));
ssr.uniforms.set('u_puddles', Math.max(value(ssr, 'ssr', 'u_puddles'), state.puddles));
}
}
if ((drive & WeatherDrive.Rain) && (state.snow > 0.001 || effects.has('snowCover'))) {
const authored = effects.has('snowCover');
const snow = entry(effects, 'snowCover');
snow.uniforms.set('u_amount', authored ? Math.max(value(snow, 'snowCover', 'u_amount'), state.snow) : state.snow);
}
if (drive & WeatherDrive.Grade) {
const neutral = Math.abs(state.saturation - 1) < 1e-3 && Math.abs(state.contrast - 1) < 1e-3;
const grade = effects.get('colorGrade');
if (grade && grade.enabled) {
grade.uniforms.set('u_saturation', value(grade, 'colorGrade', 'u_saturation', 1) * state.saturation);
grade.uniforms.set('u_contrast', value(grade, 'colorGrade', 'u_contrast', 1) * state.contrast);
} else if (!neutral) {
const added = entry(effects, 'colorGrade');
added.uniforms.set('u_saturation', state.saturation);
added.uniforms.set('u_contrast', state.contrast);
}
}
if (drive & WeatherDrive.Exposure) {
const ae = effects.get('autoExposure');
if (ae && ae.enabled) ae.uniforms.set('u_bias', value(ae, 'autoExposure', 'u_bias') + state.exposure);
else if (Math.abs(state.exposure) > 1e-3) {
const grade = effects.get('colorGrade');
if (grade && grade.enabled) grade.uniforms.set('u_exposure', value(grade, 'colorGrade', 'u_exposure') + state.exposure);
}
}
}