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.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    foliagePlugin.ts
 * @brief   Grass and trees across an area, drawn a cell at a time and swaying in the wind.
 *
 * @details The `Foliage` component says what grows where; this grows it. The entity stays as authored and the cells are its children.
 *          The cells are a layer of procedural chunks (residency/chunks.ts): grown round the streaming sources (or the eye) out to
 *          `drawDistance`, nearest first within the frame's budget, let go with their meshes past it, and grown again when a field or
 *          the ground changes, each old cell staying until its new one replaces it, so nothing is baked and nothing blinks out.
 *          Each cell is a MeshRenderer with a LODGroup (see builder.ts for what each level is), so culling and the choice of level are
 *          the engine's. If there is a Terrain, plants stand on it, avoid what is too steep and wait for it to be built.
 */
import type { App, Plugin } from '../app/app';
import { defineSystem, Schedule } from '../ecs/system';
import { defineResource } from '../ecs/resource';
import {
    defineComponent, getComponent, MeshRenderer, Transform,
    type ComponentDef, type MeshRendererData, type TransformData,
} from '../ecs/component';
import { Assets } from '../asset/AssetPlugin';
import type { MeshData } from '../asset/meshFormat';
import { log } from '../util/logger';
import { chunksOf, ProceduralChunksRes, type ChunkLayerStatus } from '../residency/chunks';
import type { Entity } from '../types';
import { TerrainsRes } from '../terrain/terrainPlugin';
import { Material } from '../render/material';
import { holdShaderWarmup } from '../render/shaderWarmup';
import { currentWeather, currentWeatherDrive, WeatherDrive } from '../postprocess/weather';
import { isEditor, isPlayMode } from '../ecs/env';
import type { Zones } from '../worldgen/zones';
import { installFoliageContacts } from './foliageContacts';
import { lodCullSizeWithin, lodSizeAtDistance, lodSphereRadius } from '../render/lodDistance';
import { buildFoliageCell, type CellSurroundings, type DensityMap, type FoliageCellSpec } from './cellBuild';
import { imagePixelsAt } from '../terrain/layerArrays';
import { bakesOf } from '../runtime/bakes';
import { firstSend, forgetSent, planPool } from '../runtime/planPool';
import type { FoliageCellRequest, FoliageSurroundingsSpec } from '../worldgen/planWorker';

/**
 * How many cells an area is cut into along x and z: as many as it takes for none to be wider than `cellSize`, however large the area.
 * Only those near the eye are ever grown, so the count costs nothing; a cap on it would leave each cell wider than the plants scattered in it.
 */
export function foliageCellsAcross(sizeX: number, sizeZ: number, cellSize: number): { x: number; z: number } {
    const side = Math.max(1, cellSize);
    return { x: Math.max(1, Math.ceil(sizeX / side)), z: Math.max(1, Math.ceil(sizeZ / side)) };
}

/** The fields of the `Foliage` component. @experimental */
export interface FoliageData {
    /** The plant to scatter. Empty grows grass, blades made here. */
    mesh: number;
    /** A material on the Foliage shader, which makes the wind. Empty draws the plants in their own colours, still. */
    material: number;
    /** An image over the area whose red says how many of the plants stand where: none at 0, all the field asks at white. Empty grows them everywhere. */
    densityMap: number;
    /** An image over the area whose red says how large the plants stand where: full size at white, none at black. */
    scaleMap: number;
    /** A picture over the area that colours the plants by where they stand, mixed in by its alpha (the material's shader reads it). */
    colorMap: number;
    /** How much of the colour map is mixed in where its alpha is whole. */
    colorMapStrength: number;
    /** A strip of colours each plant takes the colour of its top from, by a number of its own: as wide a share of the strip, as many of the plants. */
    palette: number;
    /** How many far versions a cell has, 1 to 3: each is the same plants, fewer and larger, and takes over `farStep` times further out than the last. */
    farLevels: number;
    /** The share of its plants each far version keeps of the one before. They thin to it plant by plant before it takes over, so nothing jumps. */
    farKeep: number;
    /** How many times further out each far version takes over than the one before: the first at `lodDistance`. */
    farStep: number;
    /** The most a plant kept in a far version is grown by, to cover the ground the ones left out did. */
    farGrow: number;
    /** The share of that growth a mesh plant's height takes, 0 to 1: at 0 it grows across the ground only, at 1 the same every way. Grass grows broader, never higher. */
    farGrowUp: number;
    /** How far the top of a mesh plant is tipped over in its far versions, in degrees, each plant its own way round. */
    farTilt: number;
    /** How far the head of a mesh plant turns to face the eye, 0 to 1: at the eye, and half the draw distance away. */
    faceEyeNear: number;
    faceEye: number;
    /** A mesh's far version is crossed cards of its texture (a tree). Off, it is the plant itself, fewer and larger (a flower). */
    farCards: boolean;
    /** How far up a plant the colour map begins: 0 colours it whole, 0.6 only its top (a flower's head, on a mesh whose red rises to it). */
    colorMapFrom: number;
    /** The area, centred on the entity, and the side of the cells it is cut into. */
    sizeX: number;
    sizeZ: number;
    cellSize: number;
    /** Plants per cell. */
    count: number;
    seed: number;
    minScale: number;
    maxScale: number;
    /** The least a place may face up (0 to 1) and still grow something: lower lets plants onto slopes. */
    minUp: number;
    /** The band of heights, in world units, plants grow in. */
    heightMin: number;
    heightMax: number;
    /** How deep under water, in world units, a plant may stand: 0 keeps them on dry ground; reeds stand in the shallows. */
    waterDepth: number;
    /** Grass: how tall and how wide a blade is, at scale 1. */
    bladeHeight: number;
    bladeWidth: number;
    /** How far a blade's tip is thrown over, as a share of its height. */
    bladeLean: number;
    /** Distance past which a cell is drawn as its far version, and past which it is not drawn. */
    lodDistance: number;
    drawDistance: number;
    /** Whether the generated cells cast shadows. Disable for dense short grass; it still receives lighting and shadows. */
    castShadows: boolean;
    /** WorldGen world whose zones reserve roads and buildings. Empty uses its first world; no WorldGen leaves the field unchanged. */
    zoneWorld: string;
    /** Extra comma-separated exclusion tags, in addition to foliage and grass/tree. */
    zoneTags: string;
    /** Additional world-space clearance from a zone's boundary. */
    zonePadding: number;
    /** A tree's far version is two crossed cards showing this rectangle of its texture, as uv: left, bottom, right, top. */
    cardU0: number;
    cardV0: number;
    cardU1: number;
    cardV1: number;
    /** 1 draws a far tree's cards as tents (a conifer's outline) rather than rectangles. */
    cardTent: number;
}

/**
 * Plants across an area. Presence is the opt-in; its children are the cells that draw them.
 *
 * @experimental
 */
export const Foliage: ComponentDef<FoliageData> = defineComponent<FoliageData>('Foliage', {
    mesh: 0, material: 0, densityMap: 0, scaleMap: 0, colorMap: 0, colorMapStrength: 1, colorMapFrom: 0, palette: 0,
    farLevels: 1, farKeep: 0.34, farStep: 2, farGrow: 2, farGrowUp: 0, farTilt: 0, faceEyeNear: 0, faceEye: 0, farCards: true,
    sizeX: 400, sizeZ: 400, cellSize: 40, count: 500, seed: 1,
    minScale: 0.8, maxScale: 1.25, minUp: 0.7, heightMin: -100000, heightMax: 100000, waterDepth: 0,
    bladeHeight: 14, bladeWidth: 1.6, bladeLean: 0.12, lodDistance: 140, drawDistance: 420, castShadows: true,
    zoneWorld: '', zoneTags: '', zonePadding: 0,
    cardU0: 0, cardV0: 0, cardU1: 1, cardV1: 1, cardTent: 0,
}, {
    assetFields: [{ field: 'mesh', type: 'mesh' }, { field: 'material', type: 'material' }, { field: 'densityMap', type: 'texture' }, { field: 'scaleMap', type: 'texture' }, { field: 'colorMap', type: 'texture' }, { field: 'palette', type: 'texture' }],
    fields: {
        mesh: { tooltip: 'The plant to scatter. Empty grows grass.', category: 'Plant' },
        material: { tooltip: 'A material on the Foliage shader, which makes the wind. Empty draws the plants still, in their own colours.', category: 'Plant' },
        densityMap: { tooltip: 'An image over the area whose red says how many of the plants stand where: none at black, all of them at white. Its Use is Data. Empty grows them everywhere.', category: 'Placement' },
        scaleMap: { tooltip: 'An image over the area whose red says how large the plants stand where: full size at white, smaller toward black, none at black. A sward that shrinks to nothing has a soft edge where one that only thins has a ragged one. Its Use is Data. Empty leaves every plant its own size.', category: 'Placement' },
        colorMap: { tooltip: 'A picture over the area that colours the plants by where they stand, mixed in by its alpha. Needs a material.', category: 'Plant' },
        colorMapStrength: { min: 0, max: 1, step: 0.01, slider: true, category: 'Plant', tooltip: 'How much of the colour map is mixed in where its alpha is whole.' },
        palette: { tooltip: 'A strip of colours each plant takes the colour of its top from, by a number of its own: as wide a share of the strip, as many of the plants. Needs a material; the top begins at its Tip From.', category: 'Plant' },
        colorMapFrom: { min: 0, max: 1, step: 0.01, slider: true, category: 'Plant', tooltip: 'How far up a plant the colour map begins: 0 colours it whole, higher only its top.' },
        sizeX: { min: 1, category: 'Area', tooltip: 'World size along x, centred on this entity.' },
        sizeZ: { min: 1, category: 'Area', tooltip: 'World size along z, centred on this entity.' },
        cellSize: { min: 4, category: 'Area', tooltip: 'Side of the cells the area is cut into. Each is one mesh, culled whole.' },
        count: { min: 0, step: 1, category: 'Area', tooltip: 'Plants per cell.' },
        seed: { step: 1, category: 'Area', tooltip: 'Another seed grows the same plants in other places.' },
        minScale: { min: 0.01, category: 'Plant' },
        maxScale: { min: 0.01, category: 'Plant' },
        minUp: { min: 0, max: 1, step: 0.01, category: 'Placement', tooltip: 'The least a place may face up and still grow something. Lower lets plants onto slopes.' },
        heightMin: { category: 'Placement', tooltip: 'The lowest world height plants grow at.' },
        heightMax: { category: 'Placement', tooltip: 'The highest world height plants grow at.' },
        waterDepth: { min: 0, category: 'Placement', tooltip: 'How deep under water a plant may stand. 0 keeps them on dry ground; reeds stand in the shallows.' },
        bladeHeight: { min: 0.1, category: 'Grass', tooltip: 'Height of a blade at scale 1.' },
        bladeWidth: { min: 0.01, category: 'Grass', tooltip: 'Width of a blade at its base, at scale 1.' },
        bladeLean: { min: 0, max: 2, step: 0.01, slider: true, category: 'Grass', tooltip: 'How far a blade’s tip is thrown over, as a share of its height, each blade its own way. Upright blades are needles with the ground between them; blades that lie over cover it.' },
        farLevels: { min: 1, max: 3, step: 1, category: 'Distance', tooltip: 'How many far versions a cell has: each is the same plants, fewer and larger, and takes over further out than the last.' },
        farKeep: { min: 0.1, max: 1, step: 0.01, slider: true, category: 'Distance', tooltip: 'The share of its plants each far version keeps of the one before. They thin to it plant by plant before it takes over.' },
        farStep: { min: 1.2, max: 4, step: 0.05, category: 'Distance', tooltip: 'How many times further out each far version takes over than the one before. The first takes over at the LOD distance.' },
        farGrow: { min: 1, max: 6, step: 0.1, category: 'Distance', tooltip: 'The most a plant kept in a far version is grown by, to cover the ground the ones left out did.' },
        farGrowUp: { min: 0, max: 1, step: 0.01, slider: true, category: 'Distance', tooltip: 'The share of that growth the height of a mesh plant takes: at 0 it grows across the ground only (a clump of flowers is no taller than a flower), at 1 the same every way.' },
        farTilt: { min: 0, max: 90, step: 1, slider: true, category: 'Distance', tooltip: 'How far the top of a mesh plant is tipped over in its far versions, each plant its own way round. A flat flower is edge on to a low eye a field away; tipped, half the field shows its face.' },
        faceEyeNear: { min: 0, max: 1, step: 0.01, slider: true, category: 'Distance', tooltip: 'How far the head of a mesh plant (the last tenth of its height) is turned to face the eye, close to. Needs a material.' },
        faceEye: { min: 0, max: 1, step: 0.01, slider: true, category: 'Distance', tooltip: 'How far it is turned to face the eye half the draw distance away and beyond: a far flower stands for a clump, and a clump shows its colour from the side. Needs a material.' },
        farCards: { category: 'Far version', tooltip: 'A mesh\'s far version is crossed cards of its texture (a tree). Off, it is the plant itself, fewer and larger (a flower).' },
        lodDistance: { min: 1, category: 'Distance', tooltip: 'Past this a cell is drawn as its far version: fewer, broader blades, or a tree as crossed cards.' },
        drawDistance: { min: 1, category: 'Distance', tooltip: 'Past this a cell is not drawn.' },
        castShadows: { category: 'Distance', tooltip: 'Generated cells cast shadows. Turn off for dense short grass to avoid drawing every cell again into each shadow cascade. Lighting and received shadows remain.' },
        zoneWorld: { category: 'Placement', tooltip: 'WorldGen world whose building and road exclusion zones this field respects. Empty uses the first world.' },
        zoneTags: { category: 'Placement', tooltip: 'Extra comma-separated tags used by zone exclusions. foliage and grass (or tree for a mesh) are included automatically.' },
        zonePadding: { min: 0, category: 'Placement', tooltip: 'Extra world-space clearance from building and road zones.' },
        cardU0: { label: 'Card left', category: 'Far version', tooltip: 'The part of the plant\'s texture a far tree shows (left, bottom, right, top).' },
        cardV0: { label: 'Card bottom', category: 'Far version' },
        cardU1: { label: 'Card right', category: 'Far version' },
        cardV1: { label: 'Card top', category: 'Far version' },
        cardTent: { label: 'Card shape', category: 'Far version', enum: [{ label: 'Rectangle', value: 0 }, { label: 'Tent (conifer)', value: 1 }], tooltip: 'The outline of the cards a far tree is drawn as.' },
    },
});

interface BuiltFoliage {
    signature: string;
    data: FoliageData;
    source: MeshData | null;
    /** The field's own instance of its material (0 with none): what its cells are drawn with and where everything the field itself says is written, so two fields on one material do not write over each other. */
    instance: number;
    /** The density map's red, read once; null where the field has none. */
    density: { width: number; height: number; values: Uint8Array } | null;
    scale: { width: number; height: number; values: Uint8Array } | null;
    loading: boolean;
    epoch: number;
    /** What its cells are being grown for now: a cell that lands for an earlier one is not put in the world. */
    generation?: string;
    /** Its cells' geometry made on the workers, for the surroundings `key` names; null where they cannot be given those. */
    away?: { key: string; grow: ((cell: FoliageCellSpec) => Promise<MeshData[]>) | null };
}

/** One grown cell: its entity (none where nothing grew) and the meshes it owns. */
interface GrownCell { entity: Entity | null; handles: number[] }

/** The water, as foliage asks it (the water module is optional: read by name, not imported). */
interface WaterQuery {
    depthAt(x: number, z: number, y: number): number | null; revision_: number; baking: boolean;
    /** The water as data a worker can answer from, and whether there is none at all. */
    queryData?(): FoliageSurroundingsSpec['water']; readonly empty?: boolean;
}

function waterOf(app: App): WaterQuery | null {
    const w = (app as unknown as { getResourceByName?: (name: string) => unknown }).getResourceByName?.('Waters') as Partial<WaterQuery> | undefined;
    return w && typeof w.depthAt === 'function' ? w as WaterQuery : null;
}

/** Optional world generation: querying zones must not pull that module into a foliage-only game. */
function zonesOf(app: App, world: string | undefined): Zones | null {
    const gens = app.getResourceByName?.('WorldGens') as { zones?(world?: string): Zones } | undefined;
    return gens?.zones?.(world || undefined) ?? null;
}

/** The chunk layer a Foliage's cells are. */
/** The most far versions a cell has. */
const FAR_LEVELS = 3;
/** A field's layer of cells; with `level`, the layer of one version of them (0 the near one). */
const layerOf = (entity: Entity, level = 0): string => (level === 0 ? `foliage:${entity}` : `foliage:${entity}:${level}`);
/**
 * Whether a field's versions are layers of their own, each grown only as far out as it is drawn and told apart by the shader: what a
 * material makes possible, for grass and for a mesh whose far version is itself. Else a cell holds its versions and a LODGroup picks one.
 */
const farLevelsOf = (data: FoliageData, mesh: boolean): number =>
    (data.material && (!mesh || !data.farCards) ? Math.min(Math.max(Math.floor(data.farLevels), 1), FAR_LEVELS) : 0);
/** Where far version `level` (1 on) takes over from the one before. */
const takesOverAt = (data: FoliageData, level: number): number => data.lodDistance * Math.pow(Math.max(data.farStep, 1.01), level - 1);

/** Run-time facts about the foliage the plugin has grown. */
export class FoliageField {
    /** @internal */ readonly built_ = new Map<Entity, BuiltFoliage>();
    /** @internal The u_windStrength each material had before the weather's wind scaled it, to put back. */
    readonly authoredWind_ = new Map<number, number>();
    /** Instances of materials no field draws with any more, let go once the cells grown with them are gone. */
    readonly retired_: { instance: number; frames: number }[] = [];

    /** @internal */ app_: App | null = null;

    /** @internal Cells whose geometry has come back from a worker and is waiting to be put in the world, a few a frame. */
    readonly landed_: (() => void)[] = [];

    /** How many cells near enough to be drawn, across every field, are still waiting to be grown. */
    get pending(): number {
        let n = 0;
        for (const [entity, b] of this.built_) {
            for (let level = 0; level <= FAR_LEVELS; level++) n += this.statusOf_(entity, level)?.pending ?? 0;
            if (b.loading) n++;
        }
        return n;
    }

    /** How many cells are grown and standing now, across every field. */
    get cellCount(): number {
        let n = 0;
        for (const entity of this.built_.keys()) {
            for (let level = 0; level <= FAR_LEVELS; level++) {
                const s = this.statusOf_(entity, level);
                if (s) n += s.ready + s.stale;
            }
        }
        return n;
    }

    private statusOf_(entity: Entity, level = 0): ChunkLayerStatus | null {
        const app = this.app_;
        return app?.hasResource(ProceduralChunksRes) ? app.getResource(ProceduralChunksRes).status(layerOf(entity, level)) : null;
    }
}

/** The resource the plugin installs. @experimental */
export const FoliageRes = defineResource<FoliageField>(new FoliageField(), 'Foliage');

export class FoliagePlugin implements Plugin {
    name = 'foliage';
    /** No foliage, no work; the frame after the last one goes still runs its sweep. */
    readonly activeWhen = [Foliage];
    private clearContacts_: (() => void) | null = null;

    build(app: App): void {
        const field = new FoliageField();
        field.app_ = app;
        app.insertResource(FoliageRes, field);
        // Cells still to be grown, or grown and not yet put in the world, draw with shaders nothing has asked for yet.
        holdShaderWarmup(app, () => (app.hasResource(Assets) ? field.pending + field.landed_.length : 0));
        this.clearContacts_ = installFoliageContacts(app);

        app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
            if (!app.hasResource(Assets)) return;
            const terrains = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
            this.sweep(app, field);
            this.blow(app, field);
            // Cells made on the workers are put in the world here, within the frame's budget: making them cost the frame nothing, and
            // a dozen landing at once must not cost it a dozen uploads.
            const bakes = bakesOf(app);
            for (let first = true; field.landed_.length > 0 && (first || bakes.hasTime(field)); first = false) field.landed_.shift()!();
            bakes.mark(field, 'Growing the plants', field.landed_.length === 0 ? 1 : 0.5);
            // Plants are grown again when the ground they stand on or the water they keep out of changes, and wait while either is
            // being made: a plant placed before its terrain is read would stand on nothing.
            const water = waterOf(app);
            const revision = (terrains?.revision_ ?? 0) * 100003 + (water?.revision_ ?? 0);
            const waiting = !!terrains?.loading || !!water?.baking;
            for (const entity of app.world.getEntitiesWithComponents([Foliage, Transform])) {
                const data = app.world.get(entity, Foliage) as FoliageData;
                // The colour map is read by the material each frame: changing it grows nothing again.
                const { colorMap: _c, colorMapStrength: _s, colorMapFrom: _f, palette: _p, ...grown } = data;
                const signature = JSON.stringify(grown);
                let built = field.built_.get(entity);
                if (!built || built.signature !== signature) {
                    // The instance outlives a rebuild on the same material; one on a material no longer the field's is let go once its old cells are.
                    const kept = built && built.data.material === data.material ? built.instance : 0;
                    if (built && built.instance && !kept) field.retired_.push({ instance: built.instance, frames: 600 });
                    const instance = kept || (data.material ? Material.createInstance(data.material) : 0);
                    built = { signature, data: { ...data }, source: null, instance, density: null, scale: null, loading: true, epoch: (built?.epoch ?? 0) + 1 };
                    field.built_.set(entity, built);
                    void this.start(app, built);
                }
                built.data = { ...data };
                this.wash(app, entity, built);
                const zones = zonesOf(app, data.zoneWorld);
                this.layer(app, entity, built, `${revision}:${zones?.revision ?? 0}`, waiting);
            }
        }, { name: 'FoliageSystem' }));
    }

    /**
     * The weather's wind on the plants: each Foliage material's u_windStrength is its authored strength times the weather's `wind`, and is
     * put back when the weather is taken away or stops driving the wind. Only while the game runs, as the weather's lights are: in the
     * editor a material asset is left as authored, so previewing a storm never saves one.
     */
    private blow(app: App, field: FoliageField): void {
        const w = currentWeather();
        const playing = !isEditor() || isPlayMode();
        const wind = w && playing && (currentWeatherDrive() & WeatherDrive.Wind) ? w.wind : 1;
        const materials = new Set<number>();
        if (wind !== 1) {
            for (const entity of app.world.getEntitiesWithComponents([Foliage])) {
                const material = (app.world.get(entity, Foliage) as FoliageData).material;
                if (material) materials.add(material);
            }
        }
        for (const material of materials) {
            let authored = field.authoredWind_.get(material);
            if (authored === undefined) {
                const value = Material.getUniform(material, 'u_windStrength');
                if (typeof value !== 'number') continue;
                authored = value;
                field.authoredWind_.set(material, authored);
            }
            Material.setUniform(material, 'u_windStrength', authored * wind);
        }
        // What the weather no longer blows goes back to its own strength, once; the material is the author's again from then on.
        for (const [material, authored] of field.authoredWind_) {
            if (materials.has(material)) continue;
            Material.setUniform(material, 'u_windStrength', authored);
            field.authoredWind_.delete(material);
        }
    }

    cleanup(app?: App): void {
        this.clearContacts_?.();
        this.clearContacts_ = null;
        if (!app?.hasResource(FoliageRes)) return;
        const field = app.getResource(FoliageRes);
        for (const entity of field.built_.keys()) {
            if (app.hasResource(ProceduralChunksRes)) for (let level = 0; level <= FAR_LEVELS; level++) app.getResource(ProceduralChunksRes).remove(layerOf(entity, level));
        }
        for (const built of field.built_.values()) if (built.instance) Material.release(built.instance);
        for (const r of field.retired_) Material.release(r.instance);
        field.retired_.length = 0;
        field.built_.clear();
        // What had come back and not landed is let go with the field: its cells are no longer anyone's.
        field.landed_.length = 0;
    }

    /** Reads the plant's geometry, if it has one; the cells wait for it. */
    private async start(app: App, built: BuiltFoliage): Promise<void> {
        const data = built.data;
        try {
            if (data.mesh) {
                built.source = await app.getResource(Assets).readMeshData(data.mesh);
                if (!built.source) log.warn('foliage', `the geometry of mesh ${data.mesh} cannot be read, so its plants are grass instead`);
            }
            // A map of numbers over the area, its red: what an image the field reads on the CPU is.
            const numbers = async (handle: number, what: string, without: string): Promise<BuiltFoliage['density']> => {
                const path = app.getResource(Assets).pathForHandle('texture', handle);
                const image = path ? await imagePixelsAt(app, path) : null;
                if (!image) { log.warn('foliage', `the ${what} (texture ${handle}) cannot be read, so its plants ${without}`); return null; }
                const values = new Uint8Array(image.width * image.height);
                for (let i = 0; i < values.length; i++) values[i] = image.pixels[i * 4]!;
                return { width: image.width, height: image.height, values };
            };
            if (data.densityMap) built.density = await numbers(data.densityMap, 'density map', 'grow everywhere');
            if (data.scaleMap) built.scale = await numbers(data.scaleMap, 'scale map', 'keep their own size');
        } catch (e) {
            log.error('foliage', 'growing the foliage failed', e);
        } finally {
            built.loading = false;
        }
    }

    /**
     * The field's cells as a layer of chunks: the area's grid, wanted out to `drawDistance` round the streaming sources, grown again
     * (each old cell kept till its new one stands) when a field, the ground or the water changes.
     */
    private layer(app: App, entity: Entity, built: BuiltFoliage, revision: string, waiting: boolean): void {
        const t = app.world.get(entity, Transform) as TransformData;
        const data = built.data, cells = this.cellsAcross(data);
        const sx = t.worldScale.x || 1, sz = t.worldScale.z || 1;
        const assets = app.getResource(Assets);
        const generation = `${built.epoch}:${revision}:${t.worldPosition.x}:${t.worldPosition.y}:${t.worldPosition.z}:${sx}:${sz}`;
        built.generation = generation;
        const away = waiting || built.loading ? null : this.awayFor(app, entity, built, revision, t.worldPosition.y);
        const far = farLevelsOf(data, !!built.source);
        const side = Math.max(1, data.cellSize);
        for (let level = 0; level <= FAR_LEVELS; level++) {
            if (level > far) { chunksOf(app).remove(layerOf(entity, level)); continue; }
            // A version is grown as far out as it is drawn: to where the next takes over, and the last to the draw distance.
            const reach = far === 0 || level === far ? data.drawDistance : Math.min(takesOverAt(data, level + 1) + side, data.drawDistance);
            const only = far === 0 ? null : level;
            chunksOf(app).set<GrownCell>(layerOf(entity, level), {
                label: 'Growing the plants',
                // Made on the workers where they can be: the layer then takes none of the frame's budget to make, only to land.
                async: away !== null,
                originX: t.worldPosition.x - data.sizeX / 2 * sx, originZ: t.worldPosition.z - data.sizeZ / 2 * sz,
                sizeX: data.sizeX / cells.x * sx, sizeZ: data.sizeZ / cells.z * sz,
                extent: [0, 0, cells.x, cells.z],
                loadRadius: reach,
                unloadRadius: reach + side * 1.5,
                generation,
                // Plants stand on the ground and keep out of the water: while either is still being made, they wait.
                make: (cx, cz, signal) => (waiting || built.loading ? null : this.grow(app, entity, built, cx, cz, away, generation, signal, only)),
                publish: (_cx, _cz, cell) => { if (cell.entity !== null) app.world.setParent(cell.entity, entity); },
                release: (_cx, _cz, cell) => {
                    if (cell.entity !== null && app.world.valid(cell.entity)) app.world.despawn(cell.entity);
                    for (const handle of cell.handles) assets.releaseBuiltMesh(handle);
                },
            });
        }
    }

    /** The field's density map where it lies in the world: over the whole area. */
    private densityOf(app: App, entity: Entity, built: BuiltFoliage): DensityMap | null {
        return this.mapOf(app, entity, built, built.density);
    }

    /** The same for its scale map. */
    private scaleOf(app: App, entity: Entity, built: BuiltFoliage): DensityMap | null {
        return this.mapOf(app, entity, built, built.scale);
    }

    private mapOf(app: App, entity: Entity, built: BuiltFoliage, map: BuiltFoliage['density']): DensityMap | null {
        const t = app.world.tryGet(entity, Transform) as TransformData | null;
        if (!map || !t) return null;
        const sizeX = built.data.sizeX * (t.worldScale.x || 1), sizeZ = built.data.sizeZ * (t.worldScale.z || 1);
        return { ...map, originX: t.worldPosition.x - sizeX / 2, originZ: t.worldPosition.z - sizeZ / 2, sizeX, sizeZ };
    }

    /** Writes the colour map and the palette to the field's instance of its material. */
    private wash(app: App, entity: Entity, built: BuiltFoliage): void {
        const material = built.instance, data = built.data;
        if (!material) return;
        const t = app.world.tryGet(entity, Transform) as TransformData | null;
        const strength = data.colorMap && t ? data.colorMapStrength : 0;
        if (strength > 0 && t) {
            const sizeX = data.sizeX * (t.worldScale.x || 1), sizeZ = data.sizeZ * (t.worldScale.z || 1);
            Material.setUniform(material, 'u_colorMap', Material.tex(data.colorMap));
            Material.setUniform(material, 'u_colorMapArea', { x: t.worldPosition.x - sizeX / 2, y: t.worldPosition.z - sizeZ / 2, z: sizeX, w: sizeZ });
            Material.setUniform(material, 'u_colorMapFrom', data.colorMapFrom);
        }
        Material.setUniform(material, 'u_colorMapStrength', strength);
        if (data.palette) Material.setUniform(material, 'u_palette', Material.tex(data.palette));
        Material.setUniform(material, 'u_paletteOn', data.palette ? 1 : 0);
    }

    private cellsAcross(data: FoliageData): { x: number; z: number } {
        return foliageCellsAcross(data.sizeX, data.sizeZ, data.cellSize);
    }

    /**
     * What makes a Foliage's cells on the workers, when what they are grown against can be handed over as data: no terrain (a flat
     * area) or one a worker can rebuild, water that is baked or absent, and the zones, which are data already. Null when it cannot,
     * and the cells are made here. Worked out again only when the ground, the water or the zones change.
     */
    private awayFor(app: App, entity: Entity, built: BuiltFoliage, revision: string, flatY: number): ((cell: FoliageCellSpec) => Promise<MeshData[]>) | null {
        const key = `foliage:${entity}:${built.epoch}:${revision}:${flatY}`;
        if (built.away?.key === key) return built.away.grow;
        const none = (): null => { built.away = { key, grow: null }; return null; };
        const pool = planPool();
        if (!pool) return none();
        const terrains = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
        const hasTerrain = !!terrains && terrains.built_.size > 0;
        const ground = hasTerrain ? terrains!.groundData() : null;
        if (hasTerrain && !ground) return none();
        const water = waterOf(app);
        const waterData = water?.queryData?.() ?? null;
        if (water && !waterData && !water.empty) return none();
        const zones = zonesOf(app, built.data.zoneWorld);
        const density = this.densityOf(app, entity, built), scale = this.scaleOf(app, entity, built);
        const around = (): FoliageSurroundingsSpec => ({ ground, flatY, water: waterData, zones: zones ? [...zones.all()] : [], density, scale });
        const source = built.source;
        const sourceKey = source ? `${key}:mesh` : undefined;
        const grow = (cell: FoliageCellSpec): Promise<MeshData[]> => {
            // Cells are spread over the workers by where they are, as the world's squares are.
            const worker = Math.abs((Math.floor(cell.centerX / 256) * 73856093) ^ (Math.floor(cell.centerZ / 256) * 19349663)) % pool.size;
            const first = firstSend(worker, key);
            const request: FoliageCellRequest = {
                id: 0, type: 'foliageCell', key, cell,
                ...(first ? { around: around() } : {}),
                ...(sourceKey ? { sourceKey, ...(first ? { source: source! } : {}) } : {}),
            };
            return pool.run<MeshData[]>(worker, request as unknown as Record<string, unknown>).catch((e: unknown) => {
                forgetSent(worker, key);
                throw e;
            });
        };
        built.away = { key, grow };
        return grow;
    }

    /**
     * Grows cell (cx, cz): its plants, their meshes and the entity that draws them, not yet in the world (its parent is set on publishing).
     * The geometry is made on a worker where `away` can make it, and the cell lands a frame or two later; else it is made here.
     */
    private grow(app: App, parent: Entity, built: BuiltFoliage, cx: number, cz: number,
                 away: ((cell: FoliageCellSpec) => Promise<MeshData[]>) | null = null, generation?: string, signal?: AbortSignal,
                 only: number | null = null): GrownCell | Promise<GrownCell | null> | null {
        const world = app.world;
        if (!world.valid(parent)) return null;
        const data = built.data;
        const terrains = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
        const t = world.tryGet(parent, Transform) as TransformData | null;
        if (!t) return null;
        const side = Math.max(1, data.cellSize);
        const cells = this.cellsAcross(data);
        // The cell's centre in the entity's own space, then in the world's (the ground is answered in the world's).
        const localX = -data.sizeX / 2 + (cx + 0.5) * (data.sizeX / cells.x);
        const localZ = -data.sizeZ / 2 + (cz + 0.5) * (data.sizeZ / cells.z);
        const sx = t.worldScale.x || 1, sz = t.worldScale.z || 1;
        const worldX = t.worldPosition.x + localX * sx, worldZ = t.worldPosition.z + localZ * sz;
        const hasTerrain = !!terrains && terrains.built_.size > 0;
        // The cell stands on the ground under its centre, not at the entity's height: how far a cell is (what thins its plants) is
        // measured from where they are. On a hill a cell at the entity's height was a hill's height away with the eye in the grass.
        const groundY = (hasTerrain ? terrains!.heightAt(worldX, worldZ) : null) ?? t.worldPosition.y;
        const lift = (groundY - t.worldPosition.y) / (t.worldScale.y || 1);
        // Plants thin, each by its own number, to what the next far version keeps before it takes over, and to none at the draw distance.
        if (built.instance) {
            const thins = !built.source || !data.farCards;
            Material.setUniform(built.instance, 'u_thinLevels', farLevelsOf(data, !!built.source));
            Material.setUniform(built.instance, 'u_bladeWidth', built.source ? 0 : data.bladeWidth);
            Material.setUniform(built.instance, 'u_thinGrow', Math.max(data.farGrow, 1));
            Material.setUniform(built.instance, 'u_thinDistance', thins ? data.lodDistance : 0);
            Material.setUniform(built.instance, 'u_thinKeep', Math.min(Math.max(data.farKeep, 0.01), 1));
            Material.setUniform(built.instance, 'u_thinStep', Math.max(data.farStep, 1.01));
            Material.setUniform(built.instance, 'u_thinEnd', thins ? data.drawDistance : 0);
            Material.setUniform(built.instance, 'u_faceEyeNear', Math.min(Math.max(data.faceEyeNear ?? 0, 0), 1));
            Material.setUniform(built.instance, 'u_faceEye', Math.min(Math.max(data.faceEye ?? 0, 0), 1));
            Material.setUniform(built.instance, 'u_faceEyeBy', Math.max(data.drawDistance * 0.5, 1e-3));
        }
        const spec: FoliageCellSpec = {
            centerX: worldX, centerZ: worldZ, size: Math.min(side, data.sizeX / cells.x), count: Math.floor(data.count), seed: data.seed,
            cellKey: cz * 1000 + cx, minScale: data.minScale, maxScale: data.maxScale, minUp: data.minUp,
            heightMin: data.heightMin, heightMax: data.heightMax,
            waterDepth: data.waterDepth, zonePadding: data.zonePadding ?? 0,
            tags: ['foliage', data.mesh ? 'tree' : 'grass', ...(data.zoneTags ?? '').split(',').map((s) => s.trim()).filter(Boolean)],
            baseY: groundY,
            seats: !!built.source && !!built.instance && (data.faceEye > 0 || data.faceEyeNear > 0),
            paint: data.material ? null : { base: [0.14, 0.3, 0.08], tip: [0.55, 0.72, 0.25] },
            far: { levels: data.farLevels, keep: data.farKeep, grow: data.farGrow, cards: data.farCards, only, up: data.farGrowUp, tilt: (data.farTilt ?? 0) * Math.PI / 180 },
            look: built.source
                ? { kind: 'mesh', card: { u0: data.cardU0, v0: data.cardV0, u1: data.cardU1, v1: data.cardV1 }, tent: data.cardTent === 1 }
                : { kind: 'grass', bladeHeight: data.bladeHeight, bladeWidth: data.bladeWidth, bladeLean: data.bladeLean ?? 0.12 },
        };
        const here = (): MeshData[] => {
            const around: CellSurroundings = {
                ground: hasTerrain ? terrains! : null, flatY: t.worldPosition.y, water: waterOf(app), zones: zonesOf(app, data.zoneWorld),
                density: this.densityOf(app, parent, built), scale: this.scaleOf(app, parent, built),
            };
            return buildFoliageCell(spec, around, built.source);
        };
        if (away) {
            const field = app.getResource(FoliageRes);
            // A worker that fails a cell does not leave a hole in the field: that cell is made here, and so are the ones after it.
            const made = away(spec).catch((e: unknown) => {
                if (built.away?.grow) log.warn('foliage', 'the workers failed a cell; this field grows its cells on the main thread from here', e);
                if (built.away) built.away = { key: built.away.key, grow: null };
                return null;
            });
            return made.then((meshes) => new Promise<GrownCell | null>((resolve, reject) => {
                // Put in the world on a later frame, within its budget; not at all if the field has moved on while it was being made.
                field.landed_.push(() => {
                    if (signal?.aborted || built.generation !== generation || !app.world.valid(parent)) { resolve(null); return; }
                    try { resolve(this.land(app, built, cx, cz, localX, lift, localZ, meshes ?? here(), only !== null)); } catch (e) { reject(e); }
                });
            }));
        }
        return this.land(app, built, cx, cz, localX, lift, localZ, here(), only !== null);
    }

    /** Puts a cell's geometry in the world: its meshes on the GPU and the entity that draws them (its parent is set on publishing). */
    private land(app: App, built: BuiltFoliage, cx: number, cz: number, localX: number, lift: number, localZ: number, meshes: MeshData[], banded = false): GrownCell {
        if (meshes.length === 0) return { entity: null, handles: [] };
        const world = app.world, data = built.data;
        const assets = app.getResource(Assets);
        const handles: number[] = [];
        for (const mesh of meshes) {
            const handle = assets.createMesh(mesh);
            if (handle === 0) {
                log.warn('foliage', `the engine refused the geometry of cell ${cx},${cz}`);
                for (const h of handles) assets.releaseBuiltMesh(h);
                throw new Error(`the engine refused the geometry of cell ${cx},${cz}`);
            }
            handles.push(handle);
        }

        const cell = world.spawn(`FoliageCell ${cx},${cz}`);
        world.insert(cell, Transform, { position: { x: localX, y: lift, z: localZ } });
        world.insert(cell, MeshRenderer, {
            mesh: handles[0]!, material: built.instance || data.material, lit: true, opaque: true, cullBackfaces: false,
            castShadows: data.castShadows !== false,
            color: { r: 1, g: 1, b: 1, a: 1 },
        } as Partial<MeshRendererData>);
        // A version that is a layer of its own is drawn in its band by its shader and let go with its layer: nothing picks among versions.
        const lodDef = banded ? null : getComponent('LODGroup');
        if (lodDef) {
            // The component's distances as the screen sizes the engine compares, on the sphere it will measure: the one round the
            // plants this cell grew, not round the cell — a cell with a few plants at one edge is a fraction of its own square.
            const radius = lodSphereRadius(handles.length > 1 ? meshes : [meshes[0]]);
            const step = Math.max(data.farStep, 1.01);
            const sizeAt = (level: number): number => (handles[level] ? lodSizeAtDistance(radius, data.lodDistance * Math.pow(step, level - 1)) : 0);
            world.insert(cell, lodDef, {
                lod1: handles[1] ?? 0, lod2: handles[2] ?? 0, lod3: handles[3] ?? 0,
                lod1Size: sizeAt(1), lod2Size: sizeAt(2), lod3Size: sizeAt(3),
                cullSize: lodCullSizeWithin(radius, data.drawDistance), hysteresis: 0.1, enabled: true,
            });
        }
        return { entity: cell, handles };
    }

    private sweep(app: App, field: FoliageField): void {
        for (const [entity, built] of field.built_) {
            if (app.world.valid(entity) && app.world.has(entity, Foliage)) continue;
            if (app.hasResource(ProceduralChunksRes)) for (let level = 0; level <= FAR_LEVELS; level++) app.getResource(ProceduralChunksRes).remove(layerOf(entity, level));
            if (built.instance) field.retired_.push({ instance: built.instance, frames: 2 });
            field.built_.delete(entity);
        }
        for (let i = field.retired_.length - 1; i >= 0; i--) {
            if (--field.retired_[i]!.frames > 0) continue;
            Material.release(field.retired_[i]!.instance);
            field.retired_.splice(i, 1);
        }
    }
}

export const foliagePlugin: Plugin = new FoliagePlugin();