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.

44.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    waterPlugin.ts
 * @brief   Bodies of water, the zone they are baked into, the one surface drawn from it, and the surface they answer questions about.
 *
 * @details A `WaterBody` says what water is where: an ocean, a lake inside an outline, a river along a Spline, each with the height its waves
 *          stand to and how far in from its shore they calm. It is not drawn on its own: the bodies are inputs to a zone (zone.ts), which bakes
 *          them over its region into one field (the surface's height, the shore, the waves' height, the current) where rivers run into lakes and
 *          lakes into the sea with no seam. One mesh of rings following the camera reads the field and is every body's surface; the zone's
 *          `WaterZone` component (or, without one, a zone over every lake and river with its defaults) says where, how fine, the waves every
 *          body shares and the material.
 *
 *          The waves are the ones the Water shader draws: `waves.ts` is the same formula, and {@link Waters.sample} answers from the same field, so
 *          a floating object, a camera under the surface and a splash all read the surface that is on the screen.
 */
import type { WaterQueryData } from './waterQuery';
import { riverBedModifiers } from './riverBed';
import type { App, Plugin } from '../app/app';
import { defineSystem, Schedule } from '../ecs/system';
import { defineResource, Time } from '../ecs/resource';
import {
    defineComponent, Camera, MeshRenderer, Transform,
    type ComponentDef, type CameraData, type MeshRendererData, type TransformData,
} from '../ecs/component';
import { Assets } from '../asset/AssetPlugin';
import type { MaterialShaderSource } from '../asset/loaders/MaterialShaderAssetLoader';
import { Material, MATERIAL_FORMAT_VERSION } from '../render/material';
import { createTextureFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';
import { getResourceManager, provideTextureContent, withdrawTextureContent } from '../wasm/resourceManager';
import { TextureContent } from '../wasm';
import { TerrainsRes } from '../terrain/terrainPlugin';
import { BlendMode } from '../render/blend';
import { log } from '../util/logger';
import { bakesOf } from '../runtime/bakes';
import type { Entity } from '../types';
import { surfHeight, waveHeight, waveSlope, WAVE_SET_SIZE, type WaveParams } from './waves';
import { buildOceanMesh, oceanReach, oceanSnap } from './waterMesh';
import { installWaterfalls } from './waterfall';
import { worldUnitsPerMeter } from '../ecs/worldUnits';
import { type Point2 } from './shore';
import { Spline, type SplineData } from '../spline/splinePlugin';
import { SplineCurve } from '../spline/curve';
import { RippleField } from './ripples';
import {
    WaterField, WaterZone, currentShare,
    type RiverStation, type WaterZoneData, type ZoneBody, type ZoneGrid, type ZoneGround,
} from './zone';
import { Quality } from '../render/qualityRuntime';
import { currentWeather, currentWeatherDrive, WeatherDrive } from '../postprocess/weather';
import { defaultQualityProfile, type QualityProfile } from '../render/quality';
import { isMiniGame } from '../platform';

/** What a body of water is. A river follows the `Spline` on its own entity. */
export const WaterForm = { Ocean: 0, Lake: 1, River: 2 } as const;

/** The fields of the `WaterBody` component. @experimental */
export interface WaterBodyData {
    /** {@link WaterForm}. */
    form: number;
    /** What the game calls the body, the same in every session (an entity's number is not): what a query names the water by. */
    bodyId: string;
    /** A lake's extent along x and z, centred on its entity, when it has no outline of its own. An ocean has none: it goes on past the zone. */
    sizeX: number;
    sizeZ: number;
    /** A lake's outline: three points or more round it on its own xz plane (x, y is x, z). Empty is the rectangle of `sizeX` by `sizeZ`. */
    boundary: Point2[];
    /** How far in from the shore, and how deep, the waves take to come to full height; 0 leaves them whole to the edge. */
    shoreWidth: number;
    /** A river's current, in world units a second where the river is as wide as its widest; a narrower reach runs faster. */
    flowSpeed: number;
    /** The height of the tallest wave, in world units. Their length, speed and heading are the zone's, which every body shares. */
    waveHeight: number;
    /** How deep a river cuts its bed into the terrain under its surface, at its middle; 0 leaves the ground as it is. */
    bedDepth: number;
}

/**
 * A body of water. Presence is the opt-in; it is drawn as part of its zone's surface.
 *
 * @experimental
 */
export const WaterBody: ComponentDef<WaterBodyData> = /* @__PURE__ */ defineComponent<WaterBodyData>('WaterBody', {
    // Lengths at the engine's reference of 100 units a metre (ecs/worldUnits.ts): a 100 m lake with 30 cm waves in any project.
    form: WaterForm.Lake, bodyId: '', sizeX: 10000, sizeZ: 10000, boundary: [] as Point2[], shoreWidth: 300, flowSpeed: 200, waveHeight: 30, bedDepth: 0,
}, {
    worldUnitFields: ['sizeX', 'sizeZ', 'shoreWidth', 'flowSpeed', 'waveHeight', 'bedDepth'],
    fields: {
        form: { enum: [{ label: 'Ocean', value: WaterForm.Ocean }, { label: 'Lake', value: WaterForm.Lake }, { label: 'River', value: WaterForm.River }], category: 'Shape', tooltip: 'An ocean is without edge: everywhere at its height where the ground is lower; a lake is a rectangle or an outline of its own; a river follows the Spline on the same entity.' },
        bodyId: { category: 'Shape', tooltip: 'What the game calls this body, the same in every session: what a query names the water by. Empty is named by its entity.' },
        sizeX: { min: 1, category: 'Shape', tooltip: 'A lake\'s size along x.', shownWhen: { field: 'form', values: [WaterForm.Lake] } },
        sizeZ: { min: 1, category: 'Shape', tooltip: 'A lake\'s size along z.', shownWhen: { field: 'form', values: [WaterForm.Lake] } },
        boundary: { category: 'Shape', tooltip: 'The outline of a lake: points round it on its own xz plane. Empty is the rectangle of its size.', shownWhen: { field: 'form', values: [WaterForm.Lake] } },
        shoreWidth: { min: 0, category: 'Shape', tooltip: 'How far in from the shore, and how deep, the waves take to come to full height. 0 leaves them whole to the edge.' },
        flowSpeed: { min: 0, max: 5000, category: 'Waves', tooltip: 'A river\'s current, in world units a second where it is as wide as its widest. A narrower reach runs faster.', shownWhen: { field: 'form', values: [WaterForm.River] } },
        bedDepth: { min: 0, category: 'Shape', tooltip: 'How deep the river cuts its bed into the terrain under its surface, at its middle, its banks blending back into the ground. 0 leaves the ground as it is.', shownWhen: { field: 'form', values: [WaterForm.River] } },
        waveHeight: { min: 0, max: 800, category: 'Waves', tooltip: 'The height of the tallest wave, in world units. Their length, speed and heading are the zone\'s.' },
    },
});

/** What {@link Waters.sample} answers. */
export interface WaterSample {
    /** The entity of the body that holds the most of the water there, and what the game calls it (its `bodyId`). */
    entity: Entity;
    bodyId: string;
    /** How far the point is above the surface (negative under it), in world units. */
    depth: number;
    /** The surface's normal at the point, in world space. */
    normal: [number, number, number];
    /** How the water moves there, in world units a second (a river's current; still water is zero). */
    flow: [number, number, number];
    /** The world position of the surface above or below the point. */
    surface: [number, number, number];
    /** Whether the point is over water: always, for an answer that is not null. */
    inside: boolean;
}

/** What the quality level lets water spend: waves summed, the ripple grid's side, whether waves lift the geometry, the mirror from below, the sun's light through it. */
export interface WaterQuality {
    waves: number;
    rippleCells: number;
    displacement: boolean;
    mirror: boolean;
    caustics: boolean;
}

/** Everything on: a project with no quality policy, off a minigame. */
export const FULL_WATER: WaterQuality = { waves: WAVE_SET_SIZE, rippleCells: 256, displacement: true, mirror: true, caustics: true };

/**
 * What water is allowed: the active quality profile when the project has a quality policy running; else the low profile on a minigame, which has the least to spend and
 * gets the lite water (flat geometry, no mirror, no web of light) without anyone asking; else everything.
 */
export function waterQualityOf(profile: Readonly<QualityProfile> | null, miniGame: boolean): WaterQuality {
    const p = profile ?? (miniGame ? defaultQualityProfile('low') : null);
    if (!p) return FULL_WATER;
    return { waves: p.waterWaves, rippleCells: p.waterRippleCells, displacement: p.waterDisplacement, mirror: p.waterMirror, caustics: p.waterCaustics };
}

/** The zone a scene without a `WaterZone` is given: the component's defaults, over every lake and river. */
/** The zone's defaults in the project's units: asked each time, since a project says what a unit is before its scene loads. */
const zoneDefaults = (): WaterZoneData => ({ ...WaterZone._default });

/** Run-time access to the water: where its surface is at a point, for what floats on it or swims in it. */
export class Waters {
    /** @internal */ app_: App | null = null;
    /** What the quality level allows now; the plugin refreshes it each frame, and what is drawn and what is answered both follow it. */
    quality: WaterQuality = FULL_WATER;
    /** The baked water, and the zone it was baked by. @internal */
    field_: WaterField | null = null;
    /** @internal */ zone_: WaterZoneData = zoneDefaults();
    /** The ripples the zone keeps, where it asks for them. @internal */
    ripples_: RippleField | null = null;
    /** The material instance the surface is drawn with, for what draws the same water (the underwater effect). @internal */
    instance_ = 0;
    /** Bumped each time a new bake lands, so what is placed by the water (plants kept out of it) knows to place again. @internal */
    revision_ = 0;
    /** Whether a bake is in hand: what is placed by the water waits for it. */
    baking = false;

    /** The baked water as data a worker can answer `depthAt` and `shoreAt` from, or null where none is baked. */
    queryData(): WaterQueryData | null {
        return this.field_?.query().data ?? null;
    }

    /**
     * Whether there is no water to ask about: nothing is baked, so `depthAt` answers null everywhere. A world laid out with no water at
     * all is laid out the same here and on a worker, which "no data to hand over" alone does not say.
     */
    get empty(): boolean {
        return this.field_ === null;
    }

    /** How deep the water stands at rest over the world height `y` at (x, z): above zero under water, null where there is none. */
    depthAt(x: number, z: number, y: number): number | null {
        return this.field_?.query().depthAt(x, z, y) ?? null;
    }

    /**
     * The surface over or under `(x, y, z)`: how far above it the point is (negative under), the surface's normal, the current, and the point
     * on it straight above or below. Null where there is no water. The waves are read at the instant of the frame.
     */
    sample(x: number, y: number, z: number): WaterSample | null {
        const field = this.field_;
        if (!field || !this.app_) return null;
        const s = field.sample(x, z);
        if (!s) return null;
        const time = this.app_.getResource(Time).elapsed;
        const params = this.waves(s.amp, s.exposure);
        const zone = this.zone_;
        const still = s.still;
        // Surf is swell come in from open water: sheltered water has as little of it as it is sheltered.
        const surf = surfHeight(s.shore, zone.surf * grown(s.exposure) * s.swell * s.exposure * still, zone.surfLength, zone.waveSpeed, time, s.surf);
        // The lite water is flat: its waves are in the shading, so the height code reads is the rest plane's.
        const h = s.height + (this.quality.displacement ? waveHeight(params, x, z, time) + surf : 0) + (this.ripples_?.heightAt(x, z) ?? 0);
        const [sx, sz] = waveSlope(params, x, z, time);
        const len = Math.hypot(sx, 1, sz);
        return {
            entity: s.key as Entity, bodyId: this.bodyIdOf(s.key as Entity), depth: y - h, normal: [-sx / len, 1 / len, -sz / len], flow: [s.flowX, 0, s.flowZ], surface: [x, h, z], inside: true,
        };
    }

    /**
     * Disturbs the water at the world point (x, y, z): a bump of `strength` world units (negative is a dip) over `radius`, which spreads as a ring and leaves foam.
     * Does nothing where there is no water or where the zone keeps no ripples.
     */
    disturb(x: number, y: number, z: number, radius: number, strength: number): boolean {
        if (!this.ripples_ || !this.field_?.sample(x, z)) return false;
        this.ripples_.disturb(x, z, radius, strength);
        return true;
    }

    /** The height the ripples add to the surface at the world point, where the zone keeps them; 0 elsewhere. */
    rippleAt(x: number, _y: number, z: number): number {
        return this.ripples_?.heightAt(x, z) ?? 0;
    }

    /**
     * The body of water at (x, z) and its surface at rest, or null where there is none: which water a place belongs to, for what a game
     * keeps per body (a fishing spot, a level it raises) and a placement that keeps by the shore.
     */
    bodyAt(x: number, z: number): { entity: Entity; bodyId: string; form: number; level: number } | null {
        const s = this.field_?.sample(x, z);
        const world = this.app_?.world;
        if (!s || !world || s.key < 0) return null;
        const entity = s.key as Entity;
        const body = world.valid(entity) && world.has(entity, WaterBody) ? world.get(entity, WaterBody) as WaterBodyData : null;
        return { entity, bodyId: body?.bodyId || `entity:${entity}`, form: body?.form ?? WaterForm.Ocean, level: s.height };
    }

    /**
     * How far (x, z) is from the water's edge, across the ground: above zero on dry land (how far to the nearest water), below it on the
     * water (how far in from its shore). Past the zone's region it is the open sea's, deep in; null where no water is baked at all.
     */
    shoreAt(x: number, z: number): number | null {
        return this.field_?.query().shoreAt(x, z) ?? null;
    }

    private bodyIdOf(entity: Entity): string {
        const world = this.app_?.world;
        const body = world?.valid(entity) && world.has(entity, WaterBody) ? world.get(entity, WaterBody) as WaterBodyData : null;
        return body?.bodyId || `entity:${entity}`;
    }

    /** The world height of the surface above or below (x, z), or null where there is none. */
    heightAt(x: number, z: number): number | null {
        return this.sample(x, 0, z)?.surface[1] ?? null;
    }

    /** The waves as they stand where the zone says they are `amp` high: the zone's, at that height, raised by the weather as far as the water is open to it. */
    private waves(amp: number, exposure = 1): WaveParams {
        return { ...waveParamsOf(this.zone_), height: amp * grown(exposure), count: this.quality.waves };
    }
}

/** The resource the plugin installs. @experimental */
export const WatersRes = /* @__PURE__ */ defineResource<Waters>(/* @__PURE__ */ new Waters(), 'Waters');

/** The outline of a lake: its own boundary when it has three points or more, else the rectangle of its size. */
function outlineOf(d: WaterBodyData): Point2[] {
    if (d.boundary.length >= 3) return d.boundary.map((p) => ({ x: p.x, y: p.y }));
    const hx = d.sizeX / 2, hz = d.sizeZ / 2;
    return [{ x: -hx, y: -hz }, { x: hx, y: -hz }, { x: hx, y: hz }, { x: -hx, y: hz }];
}

/** × the waves' height the weather asks for now: 1 with no weather, or one that does not drive the wind. */
function weatherWaves(): number {
    const w = currentWeather();
    return w && (currentWeatherDrive() & WeatherDrive.Wind) ? w.waves : 1;
}

/** How far the weather raises the waves of water `exposure` open to the wind: all the way on open sea, little on a sheltered pond. */
/** @internal */
export function grown(exposure: number): number {
    return 1 + (weatherWaves() - 1) * Math.min(Math.max(exposure, 0), 1);
}

/**
 * How open a body is to the wind, 0 to 1: wind waves grow with the water they blow over (their fetch), so the weather raises them fully
 * on the sea and the more on a lake the wider it is, against eight of the zone's wave lengths; a river's fetch is its width.
 */
/** @internal */
export function exposureOf(body: ZoneBody, waveLength: number): number {
    if (body.kind === 'ocean') return 1;
    let fetch: number;
    if (body.kind === 'lake') {
        let minX = Infinity, minZ = Infinity, maxX = -Infinity, maxZ = -Infinity;
        for (const p of body.outline) {
            const [x, z] = body.toWorld(p.x, p.y);
            minX = Math.min(minX, x); maxX = Math.max(maxX, x); minZ = Math.min(minZ, z); maxZ = Math.max(maxZ, z);
        }
        fetch = Math.min(maxX - minX, maxZ - minZ);
    } else {
        fetch = body.stations.reduce((n, s) => n + s.half * 2, 0) / Math.max(body.stations.length, 1);
    }
    return Math.min(Math.max(fetch / Math.max(waveLength * 8, 1e-6), 0.1), 1);
}

/** How hard it rains on the water now (the weather's rain level), 0 with none or one that does not drive the rain. */
function weatherRain(): number {
    const w = currentWeather();
    return w && (currentWeatherDrive() & WeatherDrive.Rain) ? w.rain : 0;
}

/** The zone's waves at unit height, scaled by the weather: what is drawn and what the surface answers both read this, times each place's height. */
export function waveParamsOf(zone: Pick<WaterZoneData, 'waveLength' | 'waveSpeed' | 'waveDirection'>): WaveParams {
    return { height: weatherWaves(), length: zone.waveLength, speed: zone.waveSpeed, direction: zone.waveDirection };
}

/**
 * How hard it rains on the water: the weather's rain, which the Water shader rings out as drops on the surface (`u_rain`). Rain is
 * drawn, not simulated: it puts nothing in the ripples a zone keeps, and no foam.
 */
export function rainOnWater(): number {
    return weatherRain();
}

type Quat = { x: number; y: number; z: number; w: number };

/** `v` turned by `q`. */
function rotate(q: Quat, vx: number, vy: number, vz: number): [number, number, number] {
    const tx = 2 * (q.y * vz - q.z * vy), ty = 2 * (q.z * vx - q.x * vz), tz = 2 * (q.x * vy - q.y * vx);
    return [vx + q.w * tx + (q.y * tz - q.z * ty), vy + q.w * ty + (q.z * tx - q.x * tz), vz + q.w * tz + (q.x * ty - q.y * tx)];
}

function toLocal(t: TransformData, x: number, y: number, z: number, scale: number): [number, number, number] {
    const inv = { x: -t.worldRotation.x, y: -t.worldRotation.y, z: -t.worldRotation.z, w: t.worldRotation.w };
    const r = rotate(inv, x - t.worldPosition.x, y - t.worldPosition.y, z - t.worldPosition.z);
    return [r[0] / scale, r[1] / scale, r[2] / scale];
}

function fromLocal(t: TransformData, x: number, y: number, z: number, scale: number): [number, number, number] {
    const r = rotate(t.worldRotation, x * scale, y * scale, z * scale);
    return [r[0] + t.worldPosition.x, r[1] + t.worldPosition.y, r[2] + t.worldPosition.z];
}

/** A river's stations in the world: a few to its narrowest width along its curve, each with its height, half its width, its heading and its current. */
export function riverStations(curve: SplineCurve, flowSpeed: number, toWorld: (x: number, y: number, z: number) => [number, number, number],
    turn: (x: number, y: number, z: number) => [number, number, number], scale: number): RiverStation[] {
    let widest = 0, narrowest = Infinity;
    for (let i = 0; i <= 64; i++) {
        const w = curve.width((i / 64) * curve.length);
        widest = Math.max(widest, w);
        narrowest = Math.min(narrowest, w);
    }
    const step = Math.max(narrowest / 3, curve.length / 1024, 1e-3);
    const count = Math.max(2, Math.ceil(curve.length / step) + 1);
    const stations: RiverStation[] = [];
    for (let i = 0; i < count; i++) {
        const s = (i / (count - 1)) * curve.length;
        const [px, py, pz] = curve.position(s);
        const [x, y, z] = toWorld(px, py, pz);
        const tangent = curve.tangent(s);
        const [tx, , tz] = turn(tangent[0], 0, tangent[2]);
        const run = Math.hypot(tx, tz) || 1;
        const width = curve.width(s);
        stations.push({ x, y, z, half: (width / 2) * scale, dx: tx / run, dz: tz / run, speed: flowSpeed * currentShare(width, widest) * 2 * scale });
    }
    return stations;
}

/** A river whose bed is cut into the terrain. */
interface Bed { key: number; stations: readonly RiverStation[]; depth: number }

/** Everything the zone is baked from, as the scene says it now. */
interface Inputs {
    beds: Bed[];
    bodies: ZoneBody[];
    grid: ZoneGrid;
    zone: WaterZoneData;
    /** What, changed, rebakes the field. */
    key: string;
}

/** The surface the plugin draws: its mesh, its material instance and the textures it reads the field and the ripples from. */
interface Surface {
    entity: Entity;
    mesh: number;
    meshKey: string;
    instance: number;
    material: number;
    heights: number;
    field: number;
    exposure: number;
    /** Which bake the textures hold. */
    baked: WaterField | null;
    ripple: number;
    rippleBytes: Uint8Array | null;
    epoch: number;
    pending: boolean;
}

export class WaterPlugin implements Plugin {
    name = 'water';
    /** Nothing to bake, carve or draw without a body or a zone; the frame after the last one goes still runs, and lets go. */
    readonly activeWhen = [WaterBody, WaterZone];

    /** The stock material the surface is an instance of when the zone names none, made once from the Water shader. */
    private stock_ = 0;
    /** The resource this plugin installed. */
    private waters_: Waters = new Waters();
    private key_ = '';
    private surface_: Surface | null = null;
    private epoch_ = 0;
    /** The bake in hand, for the inputs `key` names; the field drawn until it lands is the last one baked. */
    private baking_: { key: string; cancel: () => void } | null = null;
    /** The beds cut into the terrain, by river: what they were cut from, and the ids of their modifiers. */
    private beds_ = new Map<number, { signature: string; ids: string[] }>();

    build(app: App): void {
        const waters = new Waters();
        this.waters_ = waters;
        waters.app_ = app;
        app.insertResource(WatersRes, waters);
        installWaterfalls(app);

        app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
            const policy = app.hasResource(Quality) ? app.getResource(Quality) : null;
            waters.quality = waterQualityOf(policy && policy.enabled ? policy.profile : null, isMiniGame());
            // What the water IS (the baked field) needs no renderer: it is baked here whether or not anything is drawn, so a server or a test
            // that never draws can still ask the surface where it is. What is DRAWN waits for the asset layer.
            const inputs = this.gather(app);
            this.carve(app, inputs.beds);
            waters.zone_ = inputs.zone;
            if (inputs.bodies.length === 0) {
                this.baking_?.cancel();
                this.baking_ = null;
                waters.baking = false;
                waters.field_ = null;
                this.key_ = '';
                this.dropRipples();
                this.dropSurface(app);
                return;
            }
            if (inputs.key !== this.key_ && this.baking_?.key !== inputs.key) {
                // A big zone is a second or more of work: it is spread over frames and shown while it runs.
                this.baking_?.cancel();
                const key = inputs.key;
                const job = bakesOf(app).run('Baking the water', WaterField.baking(inputs.grid, inputs.bodies, this.ground(app), inputs.zone.surfLength));
                this.baking_ = { key, cancel: job.cancel };
                waters.baking = true;
                void job.done.then((field) => {
                    if (this.baking_?.key !== key) return;
                    this.baking_ = null;
                    waters.baking = false;
                    this.key_ = key;
                    waters.field_ = field;
                    waters.revision_++;
                }, (e) => { log.error('water', 'baking the water failed', e); });
            }
            if (!waters.field_) return;
            const eye = this.eye(app);
            this.ripple(app, inputs.zone, eye, app.getResource(Time).delta);
            if (!app.hasResource(Assets)) return;
            const surface = this.surface(app, inputs.zone);
            if (surface.instance && surface.entity) this.update(app, surface, inputs.zone, eye ?? this.middle(inputs.grid));
        }, { name: 'WaterSystem' }));
    }

    cleanup(app?: App): void {
        if (app) this.carve(app, []);
        if (!app?.hasResource(WatersRes)) return;
        this.baking_?.cancel();
        this.baking_ = null;
        app.getResource(WatersRes).baking = false;
        this.dropRipples();
        this.dropSurface(app);
        const waters = app.getResource(WatersRes);
        waters.field_ = null;
        this.key_ = '';
        if (this.stock_) Material.release(this.stock_);
        this.stock_ = 0;
    }

    /** The world position of the active camera, or null where there is none (the editor's scene view has no entity). */
    private eye(app: App): [number, number, number] | null {
        for (const entity of app.world.getEntitiesWithComponents([Camera, Transform])) {
            const camera = app.world.get(entity, Camera) as CameraData;
            if (!camera.isActive) continue;
            const t = app.world.get(entity, Transform) as TransformData;
            return [t.worldPosition.x, t.worldPosition.y, t.worldPosition.z];
        }
        return null;
    }

    /** The middle of the zone's region: where the surface and the ripples stay without a camera to follow. */
    private middle(grid: ZoneGrid): [number, number, number] {
        return [grid.minX + grid.sizeX / 2, 0, grid.minZ + grid.sizeZ / 2];
    }

    /**
     * The bodies as the zone takes them, in the world, the zone's settings, and the region they are baked over: the `WaterZone`'s, or without
     * one a region round every lake and river with a margin for their shores.
     */
    private gather(app: App): Inputs {
        const bodies: ZoneBody[] = [];
        const beds: Bed[] = [];
        const keyParts: unknown[] = [];
        for (const entity of app.world.getEntitiesWithComponents([WaterBody, Transform])) {
            const d = app.world.get(entity, WaterBody) as WaterBodyData;
            const t = app.world.get(entity, Transform) as TransformData;
            const scale = t.worldScale.y || 1;
            const key = entity as number;
            if (d.form === WaterForm.Ocean) {
                bodies.push({ kind: 'ocean', key, level: t.worldPosition.y, waveHeight: d.waveHeight, shoreWidth: d.shoreWidth });
                keyParts.push([key, d.form, t.worldPosition.y, d.waveHeight, d.shoreWidth]);
            } else if (d.form === WaterForm.Lake) {
                const outline = outlineOf(d);
                bodies.push({
                    kind: 'lake', key, level: t.worldPosition.y, waveHeight: d.waveHeight, shoreWidth: d.shoreWidth * scale, outline,
                    toLocal: (x, z) => { const q = toLocal(t, x, t.worldPosition.y, z, scale); return [q[0], q[2]]; },
                    toWorld: (x, z) => { const w = fromLocal(t, x, 0, z, scale); return [w[0], w[2]]; },
                });
                keyParts.push([key, d.form, outline, d.waveHeight, d.shoreWidth, t.worldPosition, t.worldRotation, scale]);
            } else if (d.form === WaterForm.River) {
                const spline = app.world.tryGet(entity, Spline) as SplineData | null;
                if (!spline || spline.points.length < 2) continue;
                const curve = new SplineCurve(spline.points, spline.closed);
                const stations = riverStations(curve, d.flowSpeed, (x, y, z) => fromLocal(t, x, y, z, scale), (x, y, z) => rotate(t.worldRotation, x, y, z), scale);
                bodies.push({ kind: 'river', key, waveHeight: d.waveHeight, shoreWidth: d.shoreWidth * scale, stations });
                if (d.bedDepth > 0) beds.push({ key, stations, depth: d.bedDepth * scale });
                keyParts.push([key, d.form, spline.points, spline.closed, d.flowSpeed, d.waveHeight, d.shoreWidth, t.worldPosition, t.worldRotation, scale]);
            }
        }
        let zone = zoneDefaults();
        let grid: ZoneGrid | null = null;
        for (const entity of app.world.getEntitiesWithComponents([WaterZone, Transform])) {
            zone = app.world.get(entity, WaterZone) as WaterZoneData;
            const t = app.world.get(entity, Transform) as TransformData;
            grid = gridOver(t.worldPosition.x - zone.sizeX / 2, t.worldPosition.z - zone.sizeZ / 2, zone.sizeX, zone.sizeZ, zone.resolution);
            break;
        }
        if (!grid) {
            grid = implicitGrid(bodies, zone);
            // The surface without a zone of its own reaches over the whole region from wherever the camera is in it: its cells grow with the region.
            const reach = oceanReach(zone.cells, zone.rings, zone.cellSize), need = Math.max(grid.sizeX, grid.sizeZ);
            if (reach < need) zone = { ...zone, cellSize: zone.cellSize * (need / reach) };
        }
        for (const b of bodies) b.exposure = exposureOf(b, zone.waveLength);
        const terrain = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
        const ground = terrain && terrain.built_.size > 0 ? terrain.revision_ : -1;
        return { bodies, beds, grid, zone, key: JSON.stringify([keyParts, grid, ground, zone.surfLength, zone.waveLength]) };
    }

    /**
     * Cuts each river's bed into the terrain, and gives the ground back where a river stops cutting or is gone. A bed is laid again only
     * when the river it is cut from changes: the water baked over the cut ground does not cut it again.
     */
    private carve(app: App, beds: readonly Bed[]): void {
        if (beds.length === 0 && this.beds_.size === 0) return;
        const terrains = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
        const seen = new Set<number>();
        for (const bed of beds) {
            seen.add(bed.key);
            const signature = JSON.stringify([bed.depth, bed.stations]);
            const had = this.beds_.get(bed.key);
            if (had?.signature === signature || !terrains) continue;
            for (const id of had?.ids ?? []) terrains.deleteModifier(id);
            const modifiers = riverBedModifiers(`river-bed:${bed.key}:`, bed.stations, bed.depth);
            for (const m of modifiers) terrains.setModifier(m);
            this.beds_.set(bed.key, { signature, ids: modifiers.map((m) => m.id) });
        }
        for (const [key, had] of this.beds_) {
            if (seen.has(key)) continue;
            if (terrains) for (const id of had.ids) terrains.deleteModifier(id);
            this.beds_.delete(key);
        }
    }

    /** The world height of the ground, where a terrain is built. */
    private ground(app: App): ZoneGround | undefined {
        if (!app.hasResource(TerrainsRes)) return undefined;
        const terrains = app.getResource(TerrainsRes);
        if (terrains.built_.size === 0) return undefined;
        return (x, z) => terrains.heightAt(x, z);
    }

    /** The material the surface is an instance of when the zone names none: the Water shader, compiled once. */
    private async stock(app: App): Promise<number> {
        if (this.stock_) return this.stock_;
        const assets = app.getResource(Assets);
        const source = await assets.load<MaterialShaderSource>('material-shader', 'builtin:water');
        const shader = source.compile([]);
        if (this.stock_) return this.stock_;
        this.stock_ = Material.createFromAsset({
            version: MATERIAL_FORMAT_VERSION, type: 'material', shader: 'builtin:water', blendMode: BlendMode.Normal,
            depthTest: true, depthWrite: true, cull: 0, properties: {},
        }, shader);
        return this.stock_;
    }

    /** The surface, made (or remade, where its mesh or its material changed) as the zone asks. */
    private surface(app: App, zone: WaterZoneData): Surface {
        const meshKey = JSON.stringify([zone.cells, zone.rings, zone.cellSize]);
        let s = this.surface_;
        if (s && (s.meshKey !== meshKey || s.material !== zone.material)) { this.dropSurface(app); s = null; }
        if (!s) {
            s = { entity: 0 as Entity, mesh: 0, meshKey, instance: 0, material: zone.material, heights: 0, field: 0, exposure: 0, baked: null, ripple: 0, rippleBytes: null, epoch: ++this.epoch_, pending: false };
            this.surface_ = s;
        }
        if (!s.entity && !s.pending) void this.build_(app, s, zone);
        return s;
    }

    private async build_(app: App, s: Surface, zone: WaterZoneData): Promise<void> {
        s.pending = true;
        const epoch = s.epoch;
        try {
            const source = zone.material || await this.stock(app);
            if (s.epoch !== epoch || this.surface_ !== s) return;
            const assets = app.getResource(Assets);
            // The rings are where the waves are; past them a flat apron carries the sea to the horizon (80 km, further than a camera a
            // kilometre up can see), so an ocean does not end in a straight line where its mesh does.
            const mesh = assets.createMesh(buildOceanMesh(zone.cells, zone.rings, zone.cellSize, 80000 * worldUnitsPerMeter()));
            if (mesh === 0) { log.warn('water', 'the engine refused the water geometry'); return; }
            const instance = Material.createInstance(source);
            if (instance === 0) { assets.releaseBuiltMesh(mesh); log.warn('water', 'the water material could not be instanced'); return; }
            s.mesh = mesh;
            s.instance = instance;
            this.waters_.instance_ = instance;
            const entity = app.world.spawn('Water');
            app.world.insert(entity, Transform, { position: { x: 0, y: 0, z: 0 } });
            app.world.insert(entity, MeshRenderer, {
                // Light goes through water: the sun lights what is under it, through the caustics, and no shadow of the surface.
                mesh, material: instance, lit: true, opaque: false, cullBackfaces: false, castShadows: false, color: { r: 1, g: 1, b: 1, a: 1 },
            } as Partial<MeshRendererData>);
            s.entity = entity;
        } catch (e) {
            log.error('water', 'building the water failed', e);
        } finally {
            s.pending = false;
        }
    }

    /** Puts the baked field where the shader reads it: the heights texel by texel, the rest filtered. */
    private upload(app: App, s: Surface, field: WaterField): void {
        this.dropFieldTextures(s);
        const ranges = field.ranges(this.waters_.zone_.surfLength * 4);
        const { heights, field: rest, exposure } = field.encode(ranges);
        const { nx, nz, minX, minZ, sizeX, sizeZ } = field.grid;
        const empty = nx < 2 || nz < 2;
        const w = empty ? 2 : nx, h = empty ? 2 : nz;
        s.heights = createTextureFromPixels(app.wasmModule, { width: w, height: h, pixels: empty ? new Uint8Array(16) : heights }, TextureContent.Retained, false,
            { filterMode: 'nearest', wrapMode: 'clamp', srgb: false });
        s.field = createTextureFromPixels(app.wasmModule, { width: w, height: h, pixels: empty ? new Uint8Array(16) : rest }, TextureContent.Retained, false,
            { filterMode: 'linear', wrapMode: 'clamp', srgb: false });
        s.exposure = createTextureFromPixels(app.wasmModule, { width: w, height: h, pixels: empty ? new Uint8Array(16).fill(255) : exposure }, TextureContent.Retained, false,
            { filterMode: 'linear', wrapMode: 'clamp', srgb: false });
        s.baked = field;
        const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(s.instance, name, value); };
        set('u_zoneHeights', Material.tex(s.heights));
        set('u_zoneField', Material.tex(s.field));
        set('u_zoneExposure', Material.tex(s.exposure));
        // A region of nothing is put where no point is: everything is past it, which is the ocean.
        set('u_zoneOrigin', empty ? { x: 1e9, y: 1e9 } : { x: minX, y: minZ });
        set('u_zoneSize', empty ? { x: 1e-4, y: 1e-4 } : { x: sizeX, y: sizeZ });
        set('u_zoneHeight', { x: ranges.heightMin, y: ranges.heightSpan });
        set('u_zoneRange', { x: ranges.shore, y: ranges.amp, z: ranges.flow, w: ranges.depth });
        set('u_zoneOn', 1);
    }

    /** Writes the zone into the instance, and moves the surface to the camera on the lattice its rings line up on. */
    private update(app: App, s: Surface, zone: WaterZoneData, eye: [number, number, number]): void {
        const field = this.waters_.field_!;
        if (s.baked !== field) this.upload(app, s, field);
        const snap = oceanSnap(zone.rings, zone.cellSize);
        const ox = Math.round(eye[0] / snap) * snap, oz = Math.round(eye[2] / snap) * snap;
        const t = app.world.get(s.entity, Transform) as TransformData;
        if (t.position.x !== ox || t.position.z !== oz) app.world.insert(s.entity, Transform, { ...t, position: { x: ox, y: 0, z: oz } });
        const set = (name: string, value: number | { x: number; y: number }): void => { Material.setUniform(s.instance, name, value); };
        const q = this.waters_.quality;
        const ocean = field.ocean;
        const waves = waveParamsOf(zone);
        set('u_waveCount', q.waves);
        set('u_mirror', q.mirror ? 1 : 0);
        set('u_causticOn', q.caustics ? 1 : 0);
        set('u_waveSpace', 1);
        set('u_origin', { x: ox, y: oz });
        set('u_cellSize', zone.cellSize);
        set('u_geoWaves', q.displacement ? 1 : 0);
        set('u_waveHeight', waves.height);
        set('u_rain', rainOnWater());
        set('u_waveLength', waves.length);
        set('u_waveSpeed', waves.speed);
        set('u_waveDirection', waves.direction);
        set('u_oceanOn', ocean ? 1 : 0);
        set('u_oceanLevel', ocean ? ocean.level : 0);
        set('u_oceanWaves', ocean ? ocean.waveHeight : 0);
        set('u_surfHeight', zone.surf);
        set('u_surfLength', zone.surfLength);
        set('u_surfSpeed', zone.waveSpeed);
    }

    /**
     * Keeps the zone's ripples: makes the grid when `ripples` asks for one, moves its window to the camera, steps it, and (where drawn) puts it where the shader reads it.
     * It runs headless too, so the surface a test or a server asks about has them.
     */
    private ripple(app: App, zone: WaterZoneData, eye: [number, number, number] | null, dt: number): void {
        const waters = this.waters_;
        if (zone.ripples <= 0 || waters.quality.rippleCells <= 0) { this.dropRipples(); return; }
        // The level holds the grid to its own side; a zone that asks for more gets the level's.
        const n = Math.max(8, Math.floor(Math.min(zone.ripples, waters.quality.rippleCells))), size = Math.max(zone.rippleSize, 1e-3);
        if (!waters.ripples_ || waters.ripples_.n !== n || waters.ripples_.size !== size) {
            this.dropRipples();
            waters.ripples_ = new RippleField(n, size);
            const grid = waters.field_!.grid;
            waters.ripples_.recenter(grid.minX + grid.sizeX / 2, grid.minZ + grid.sizeZ / 2);
        }
        const field = waters.ripples_;
        if (eye) field.recenter(eye[0], eye[2]);
        const step = Math.min(Math.max(dt, 0), 0.1);
        field.step(step, zone.rippleSpeed, zone.rippleDamping, zone.foamFade);
        const s = this.surface_;
        if (!s || !s.instance || !app.hasResource(Assets)) return;
        // The height the grid holds and its encoding spans either side of rest: twice the tallest waves, or a fiftieth of the window where the water is calm.
        const range = Math.max((waters.field_ ? waters.field_.ranges().amp : 0) * weatherWaves() * 2, zone.rippleSize * 0.02);
        field.limit = range;
        const bytes = field.encode(range, s.rippleBytes ?? undefined);
        s.rippleBytes = bytes;
        if (!s.ripple) {
            s.ripple = createTextureFromPixels(app.wasmModule, { width: n, height: n, pixels: bytes }, TextureContent.Retained, false,
                { filterMode: 'linear', wrapMode: 'clamp', srgb: false });
            const handle = s.ripple;
            provideTextureContent(handle, () => {
                if (s.ripple !== handle || !s.rippleBytes) return false;
                updateTextureSubregion(app.wasmModule, handle, 0, 0, n, n, s.rippleBytes);
                return true;
            });
            Material.setUniform(s.instance, 'u_rippleMap', Material.tex(handle));
        } else {
            updateTextureSubregion(app.wasmModule, s.ripple, 0, 0, n, n, bytes);
        }
        const set = (name: string, value: number | { x: number; y: number }): void => { Material.setUniform(s.instance, name, value); };
        set('u_rippleOn', 1);
        set('u_rippleOrigin', { x: field.originX, y: field.originZ });
        set('u_rippleSize', field.size);
        set('u_rippleTexel', 1 / n);
        set('u_rippleRange', range);
    }

    private dropRipples(): void {
        const s = this.surface_;
        if (s?.ripple) {
            withdrawTextureContent(s.ripple);
            getResourceManager()?.releaseTexture(s.ripple);
        }
        if (s) {
            s.ripple = 0;
            s.rippleBytes = null;
            if (s.instance) Material.setUniform(s.instance, 'u_rippleOn', 0);
        }
        this.waters_.ripples_ = null;
    }

    private dropFieldTextures(s: Surface): void {
        const rm = getResourceManager();
        if (s.heights) rm?.releaseTexture(s.heights);
        if (s.field) rm?.releaseTexture(s.field);
        if (s.exposure) rm?.releaseTexture(s.exposure);
        s.heights = 0;
        s.field = 0;
        s.exposure = 0;
        s.baked = null;
    }

    private dropSurface(app: App): void {
        const s = this.surface_;
        if (!s) return;
        s.epoch = ++this.epoch_;
        this.surface_ = null;
        if (s.entity && app.world.valid(s.entity)) app.world.despawn(s.entity);
        if (s.ripple) { withdrawTextureContent(s.ripple); getResourceManager()?.releaseTexture(s.ripple); }
        this.waters_.ripples_ = null;
        this.dropFieldTextures(s);
        if (s.instance) Material.release(s.instance);
        if (s.mesh && app.hasResource(Assets)) app.getResource(Assets).releaseBuiltMesh(s.mesh);
        this.waters_.instance_ = 0;
    }
}

/** A region from (minX, minZ), `sizeX` by `sizeZ`, with `resolution` texels along its longer side. */
function gridOver(minX: number, minZ: number, sizeX: number, sizeZ: number, resolution: number): ZoneGrid {
    const longer = Math.max(sizeX, sizeZ, 1e-3);
    const res = Math.max(2, Math.round(resolution));
    return { minX, minZ, sizeX, sizeZ, nx: Math.max(2, Math.round((res * sizeX) / longer)), nz: Math.max(2, Math.round((res * sizeZ) / longer)) };
}

/**
 * The region a scene without a `WaterZone` is baked over: round every lake and river, with a margin of their shores and a few texels, at half
 * the surface's finest cell to a texel (no finer than 32 texels along its longer side, no coarser than 1024). None, when there is only an ocean.
 */
function implicitGrid(bodies: readonly ZoneBody[], zone: WaterZoneData): ZoneGrid {
    let minX = Infinity, minZ = Infinity, maxX = -Infinity, maxZ = -Infinity, margin = 0;
    for (const b of bodies) {
        if (b.kind === 'ocean') continue;
        margin = Math.max(margin, b.shoreWidth);
        if (b.kind === 'river') {
            for (const s of b.stations) {
                minX = Math.min(minX, s.x - s.half); maxX = Math.max(maxX, s.x + s.half);
                minZ = Math.min(minZ, s.z - s.half); maxZ = Math.max(maxZ, s.z + s.half);
            }
        } else {
            for (const p of b.outline) {
                const [x, z] = b.toWorld(p.x, p.y);
                minX = Math.min(minX, x); maxX = Math.max(maxX, x);
                minZ = Math.min(minZ, z); maxZ = Math.max(maxZ, z);
            }
        }
    }
    if (!Number.isFinite(minX)) return { minX: 0, minZ: 0, sizeX: 0, sizeZ: 0, nx: 0, nz: 0 };
    const longer = Math.max(maxX - minX, maxZ - minZ);
    const res = Math.min(1024, Math.max(32, Math.ceil(longer / Math.max(zone.cellSize * 0.5, 1e-3))));
    const pad = margin + (longer / res) * 4;
    return gridOver(minX - pad, minZ - pad, maxX - minX + pad * 2, maxZ - minZ + pad * 2, res);
}

export const waterPlugin: Plugin = /* @__PURE__ */ new WaterPlugin();