Skip to content

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.

10.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  timeOfDay.ts
 * @brief Where the sun and the moon are at an hour of the day, and what that does to the light, the fog and the sky.
 *
 * @details The sun is placed by the astronomy that fits in four lines — an hour angle, a latitude and a declination — so a
 *          day has the right shape (a long arc in summer, a low one in winter, sunrise toward the east) with three numbers a
 *          person can understand. Everything else is the same idea as the weather: MULTIPLIERS of what the scene already
 *          says (the sun at its strength times a curve, the fog's colour times how dark it is) so the same hour fits any
 *          scene. The moon stands opposite the sun and is the directional light's aim while the sun is down.
 *
 *          The state is applied in two places, as the weather's is: to the lights (in play mode, from the weather
 *          system, which owns the lights so the two scale one number and not each other's last answer) and to the
 *          effects the volumes resolve.
 */
import type { BlendedEffect, Rgba } from './volumeBlending';
import { getEffectDef } from './effects';

export interface TimeOfDayState {
    /** The hour this is the state of, 0..24. */
    hour: number;
    /** Unit vectors toward the sun and the moon, in world space (Y up). */
    sunDir: [number, number, number];
    moonDir: [number, number, number];
    /** The sun's height above the horizon in degrees, negative below it. */
    sunElevation: number;
    /** The sun's azimuth as the effects take it: degrees from +Z toward +X. */
    sunAzimuth: number;
    /** 0 at night, 1 by day, with the dusk between. */
    daylight: number;
    /** The unit vector the key (directional) light shines FROM: the sun by day, the moon by night. */
    lightDir: [number, number, number];
    /** × the key light's strength, and what it is tinted: warm at the horizon, white overhead, blue by moonlight. */
    light: number;
    lightTint: [number, number, number];
    /** × the ambient light's strength, and its tint. */
    sky: number;
    skyTint: [number, number, number];
    /** × what baked reflection probes show, and × their colour. */
    reflection: number;
    reflectionSaturation: number;
    /** × Height Fog's colour (how lit the haze is), and the dusk colour it moves toward and how far. */
    fogBrightness: number;
    fogDusk: number;
    /** Stops added to the exposure compensation: a night is kept readable, not as bright as a day. */
    exposure: number;
}

/** What a time of day drives. A bit each, so a project can take the sky from the clock and keep its own light. */
export const TimeDrive = {
    Lights: 1,
    Sky: 2,
    Fog: 4,
    Exposure: 8,
    Reflections: 16,
    All: 31,
} as const;

const RAD = Math.PI / 180;

const smooth = (a: number, b: number, x: number): number => {
    const t = Math.min(Math.max((x - a) / (b - a), 0), 1);
    return t * t * (3 - 2 * t);
};
const mix = (a: number, b: number, t: number): number => a + (b - a) * t;
const mix3 = (a: [number, number, number], b: [number, number, number], t: number): [number, number, number] =>
    [mix(a[0], b[0], t), mix(a[1], b[1], t), mix(a[2], b[2], t)];

/** A direction from an elevation and an azimuth, both in radians, the azimuth from +Z toward +X. */
function direction(elevation: number, azimuth: number): [number, number, number] {
    const c = Math.cos(elevation);
    return [c * Math.sin(azimuth), Math.sin(elevation), c * Math.cos(azimuth)];
}

/**
 * The sun's place at an hour: its elevation and its azimuth from +Z toward +X, in radians.
 *
 * @param hour        Solar time, 0..24; 12 is noon.
 * @param latitude    Degrees; where on the planet. Positive is north.
 * @param declination Degrees, -23.5..23.5: the season. Positive is summer in the north.
 * @param north       Degrees the world is turned from compass north (+Z) toward +X.
 */
export function sunPosition(hour: number, latitude: number, declination: number, north: number): { elevation: number; azimuth: number } {
    const phi = latitude * RAD;
    const delta = declination * RAD;
    const hourAngle = (hour - 12) * 15 * RAD;
    const sinE = Math.sin(phi) * Math.sin(delta) + Math.cos(phi) * Math.cos(delta) * Math.cos(hourAngle);
    const elevation = Math.asin(Math.min(Math.max(sinE, -1), 1));
    // From north, clockwise (east is 90): mornings are east of the meridian and afternoons west of it.
    const cosA = (Math.sin(delta) - sinE * Math.sin(phi)) / Math.max(Math.cos(elevation) * Math.cos(phi), 1e-5);
    let compass = Math.acos(Math.min(Math.max(cosA, -1), 1));
    if (hourAngle > 0) compass = 2 * Math.PI - compass;
    // Compass north is +Z and east is +X until `north` turns the world; the effects count azimuth from +Z toward +X.
    return { elevation, azimuth: compass + north * RAD };
}

/** The time of day at an hour. @beta */
export function timeOfDayAt(hour: number, latitude = 40, declination = 15, north = 0): TimeOfDayState {
    const h = ((hour % 24) + 24) % 24;
    const sun = sunPosition(h, latitude, declination, north);
    const sinE = Math.sin(sun.elevation);
    const sunDir = direction(sun.elevation, sun.azimuth);
    // The moon stands opposite the sun and higher than the sun is low, so it is up for most of a night. Matches Sky Atmosphere.
    const moonEl = -sun.elevation * 0.85 + 12 * RAD;
    const moonDir = direction(moonEl, sun.azimuth + Math.PI);
    const sinM = Math.sin(moonEl);

    const daylight = smooth(-0.12, 0.28, sinE);
    const dusk = Math.exp(-sinE * sinE * 60);

    // The sun's own light: gone a little below the horizon, warm and weak while it is low.
    const sunStrength = Math.pow(smooth(-0.03, 0.3, sinE), 1.1);
    const warm = smooth(0, 0.4, sinE);
    const sunTint: [number, number, number] = [1, mix(0.55, 0.97, warm), mix(0.3, 0.94, warm)];
    // The moon's: a few hundredths of the sun's, blue, and only once the sun is well out of the way.
    const moonStrength = 0.06 * smooth(0.0, 0.12, sinM) * smooth(-0.03, -0.12, sinE);
    const sunUp = sinE > -0.03;

    const nightSky: [number, number, number] = [0.5, 0.62, 1];
    const duskSky: [number, number, number] = [1, 0.72, 0.55];
    const skyTint = mix3(mix3(nightSky, [1, 1, 1], daylight), duskSky, dusk * 0.45);

    return {
        hour: h,
        sunDir, moonDir,
        sunElevation: sun.elevation / RAD,
        sunAzimuth: ((sun.azimuth / RAD) % 360 + 360) % 360,
        daylight,
        lightDir: sunUp ? sunDir : moonDir,
        light: sunUp ? sunStrength : moonStrength,
        lightTint: sunUp ? sunTint : [0.55, 0.68, 1],
        sky: mix(0.14, 1, daylight) * mix(1, 0.8, dusk),
        skyTint,
        reflection: mix(0.12, 1, daylight),
        reflectionSaturation: mix(0.6, 1, daylight),
        fogBrightness: mix(0.035, 1, daylight),
        fogDusk: dusk * 0.5,
        exposure: (1 - daylight) * 1.1,
    };
}

/** The state the frame is under, or null when no TimeOfDay is. Set by the weather system, read by the volumes. */
let current: { state: TimeOfDayState; drive: number; lightsApplied: boolean } | null = null;

export function setCurrentTimeOfDay(state: TimeOfDayState | null, drive: number = TimeDrive.All, lightsApplied = false): void {
    current = state ? { state, drive, lightsApplied } : null;
}

/** The time of day the frame is under, or null. @beta */
export function currentTimeOfDay(): TimeOfDayState | null {
    return current ? current.state : null;
}

export function currentTimeDrive(): number {
    return current ? current.drive : 0;
}

/** Whether the scene's lights are being moved by the clock (play mode); in the editor the effects stand in for them. */
export function timeLightsApplied(): boolean {
    return current ? current.lightsApplied : false;
}

function value(effect: BlendedEffect, type: string, name: string, fallback = 0): number {
    const set = effect.uniforms.get(name);
    if (set !== undefined) return set;
    return getEffectDef(type)?.uniforms.find((u) => u.name === name)?.defaultValue ?? fallback;
}

function scaled(c: Rgba, k: number): Rgba {
    return { r: c.r * k, g: c.g * k, b: c.b * k, a: c.a };
}

/**
 * Applies the hour to what the volumes blended: the sky takes the sun's place, the fog is lit as the day is, the exposure
 * is kept readable.
 *
 * @details In the editor the scene's lights are not moved by the clock, so the effects that follow "the scene's sun" are
 *          told where the clock's sun is instead; in play they follow the light, which the clock has moved.
 */
export function applyTimeToEffects(effects: Map<string, BlendedEffect>, state: TimeOfDayState, drive: number, lightsApplied: boolean): void {
    if (drive & TimeDrive.Sky) {
        const sky = effects.get('skyAtmosphere');
        if (sky && sky.enabled) {
            // The sky always takes the sun from the clock: the key light is the moon at night, and a sky must not draw it as the sun.
            sky.uniforms.set('u_followSun', 0);
            sky.uniforms.set('u_sunAzimuth', state.sunAzimuth);
            sky.uniforms.set('u_sunElevation', state.sunElevation);
        }
    }
    if (drive & TimeDrive.Fog) {
        const fog = effects.get('heightFog');
        if (fog && fog.enabled) {
            if (!lightsApplied) {
                fog.uniforms.set('u_followSun', 0);
                fog.uniforms.set('u_sunAzimuth', state.sunAzimuth);
                fog.uniforms.set('u_sunElevation', state.sunElevation);
                // Without the light the glow has to go with the sun on its own.
                fog.uniforms.set('u_inscatter', value(fog, 'heightFog', 'u_inscatter') * smooth(-0.05, 0.2, state.sunDir[1]));
            }
            const colour = fog.colors.get('u_fogColor')
                ?? getEffectDef('heightFog')?.colors?.find((c) => c.name === 'u_fogColor')?.defaultValue;
            if (colour) {
                const dusk: [number, number, number] = [0.95, 0.55, 0.35];
                const a = state.fogDusk;
                const toward = {
                    r: colour.r * (1 - a) + dusk[0] * a, g: colour.g * (1 - a) + dusk[1] * a, b: colour.b * (1 - a) + dusk[2] * a, a: colour.a,
                };
                // The haze at night is a little blue as well as dark: the sky it is lit by is.
                const night = 1 - state.daylight;
                const blue = { r: toward.r * (1 - 0.3 * night), g: toward.g * (1 - 0.15 * night), b: toward.b, a: toward.a };
                fog.colors.set('u_fogColor', scaled(blue, state.fogBrightness));
            }
        }
    }
    if (drive & TimeDrive.Exposure) {
        const ae = effects.get('autoExposure');
        if (ae && ae.enabled) ae.uniforms.set('u_bias', value(ae, 'autoExposure', 'u_bias') + state.exposure);
        else if (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 * 1.5);
        }
    }
}