A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file cellBuild.ts
* @brief One cell of a Foliage, from where its plants may stand to the geometry of them: the part that is only computation.
*
* @details Growing a cell is two things. Working out where its plants stand and what they look like — a few thousand questions of the
* ground, then tens of thousands of vertices — is arithmetic on data, 4 to 12 ms of it a cell. Putting the result in the world
* (two meshes on the GPU and an entity) is the engine's, and quick.
*
* The first is here, as one function of plain data, so it runs the same wherever it is called: on a worker, which is where it
* belongs, or on the main thread where a worker cannot be given the ground (a terrain with modifiers laid on it, a game's own
* provider). One implementation is also why the two cannot come to disagree about a cell.
*/
import type { MeshData } from '../asset/meshFormat';
import { buildBillboardMesh, buildGrassMesh, rankedPlants, buildInstancedMesh, scatterCell, type Ground, type Plant } from './builder';
/** The ground a cell's plants stand on, as the terrain answers it. */
export interface CellGround {
heightAt(x: number, z: number): number | null;
normalAt(x: number, z: number): readonly [number, number, number] | null;
}
/** What a cell is grown against: the ground (or a flat height where there is none), the water, the zones that keep plants out. */
export interface CellSurroundings {
ground: CellGround | null;
/** The height of the ground where there is no terrain: the Foliage entity's own. */
flatY: number;
water: { depthAt(x: number, z: number, y: number): number | null } | null;
zones: { excluding(x: number, z: number, radius: number, tags: readonly string[], seed: number): unknown } | null;
density?: DensityMap | null;
/** How large a plant stands by where it is, 0 to 1 of its own size: read as the density map is. */
scale?: DensityMap | null;
}
/** A blade's or a plant's own colours, where no material paints it. */
export type CellPaint = { base: [number, number, number]; tip: [number, number, number] } | null;
/** One cell to grow: plain data, so it can be sent to a worker as it is. */
export interface FoliageCellSpec {
/** The cell's centre and side in the world, and how many plants are tried in it. */
centerX: number;
centerZ: number;
size: number;
count: number;
seed: number;
cellKey: number;
minScale: number;
maxScale: number;
minUp: number;
heightMin: number;
heightMax: number;
/** The deepest water a plant may stand in. */
waterDepth: number;
/** How far from a zone's edge a plant is kept, and what it is kept out as. */
zonePadding: number;
tags: string[];
/** The Foliage entity's height: the plants carry the ground's height relative to it. */
baseY: number;
/** The copies of a mesh carry, in a second uv, where each vertex of a head sits from its plant's axis: what a shader turns the head about. */
seats?: boolean;
paint: CellPaint;
/**
* The far versions: how many there are (1 to 3), the share of its plants each keeps of the one before, the most a kept plant is
* grown by, and whether a mesh's far version is cards (a tree) or the plant itself, fewer and larger. With `only`, the cell is that one
* version alone (0 the near one), marked with its band: each version is then a layer of cells of its own, grown only as far out as it is drawn.
*/
far: { levels: number; keep: number; grow: number; cards: boolean; only?: number | null; up?: number; tilt?: number };
/** Grass, as blades of this size; or copies of a mesh, with the card its far version is drawn as. */
look: { kind: 'grass'; bladeHeight: number; bladeWidth: number; bladeLean?: number }
| { kind: 'mesh'; card: { u0: number; v0: number; u1: number; v1: number }; tent: boolean };
}
/** How densely plants stand over an area, read from an image's red: 0 none, 255 as many as the field asks. Nothing grows off it. */
export interface DensityMap {
width: number;
height: number;
values: Uint8Array;
/** The corner and the size of what the image covers, in the world. */
originX: number;
originZ: number;
sizeX: number;
sizeZ: number;
}
/** The share of plants that stand at (x, z), 0 to 1: the four texels about it blended. */
export function densityAt(map: DensityMap, x: number, z: number): number {
const u = (x - map.originX) / map.sizeX, v = (z - map.originZ) / map.sizeZ;
if (!(u >= 0 && u <= 1 && v >= 0 && v <= 1)) return 0;
const fx = Math.min(u * map.width - 0.5, map.width - 1), fz = Math.min(v * map.height - 0.5, map.height - 1);
const x0 = Math.max(Math.floor(fx), 0), z0 = Math.max(Math.floor(fz), 0);
const x1 = Math.min(x0 + 1, map.width - 1), z1 = Math.min(z0 + 1, map.height - 1);
const tx = Math.min(Math.max(fx - x0, 0), 1), tz = Math.min(Math.max(fz - z0, 0), 1);
const at = (ix: number, iz: number): number => map.values[iz * map.width + ix]!;
return ((at(x0, z0) * (1 - tx) + at(x1, z0) * tx) * (1 - tz) + (at(x0, z1) * (1 - tx) + at(x1, z1) * tx) * tz) / 255;
}
/** A number from 0 to 1 that is a place's own, whichever cell or thread asks: which plants a density thins out. */
function lot(x: number, z: number, seed: number): number {
let h = Math.imul(Math.floor(x * 64) | 0, 374761393) ^ Math.imul(Math.floor(z * 64) | 0, 668265263) ^ Math.imul(seed | 0, 2246822519);
h = Math.imul(h ^ (h >>> 13), 1274126177);
return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
}
/** Where a plant may stand in a cell, as `scatterCell` asks it. */
export function cellGround(spec: FoliageCellSpec, around: CellSurroundings): Ground {
return (x, z) => {
if (around.zones?.excluding(x, z, Math.max(0, spec.zonePadding), spec.tags, spec.seed)) return null;
if (around.density && lot(x, z, spec.seed) >= densityAt(around.density, x, z)) return null;
// With a terrain, a plant stands where there is ground and nowhere else; with none, the area is flat at the entity's height.
const y = around.ground ? around.ground.heightAt(x, z) : around.flatY;
if (y === null) return null;
// Nor under water deeper than it may stand in.
const depth = around.water?.depthAt(x, z, y);
if (depth != null && depth > spec.waterDepth) return null;
if (!around.ground) return { y, up: 1 };
const n = around.ground.normalAt(x, z);
return { y, up: n ? n[1] : 1 };
};
}
/** A plant under this share of its own size is not there. */
const LEAST_SIZE = 0.03;
/** The plants at the size the scale map gives each where it stands (their places are from the cell's centre), without those it takes to nothing. */
export function plantsSized(plants: readonly Plant[], map: DensityMap, centerX: number, centerZ: number): Plant[] {
const out: Plant[] = [];
for (const p of plants) {
const share = densityAt(map, centerX + p.x, centerZ + p.z);
if (share >= LEAST_SIZE) out.push(share >= 1 ? p : { ...p, scale: p.scale * share });
}
return out;
}
/**
* The geometry of a cell: its near mesh and its far one, or none where nothing grows in it. `source` is the plant's own mesh for a
* cell of copies, and not read for grass.
*/
export function buildFoliageCell(spec: FoliageCellSpec, around: CellSurroundings, source: MeshData | null): MeshData[] {
const plants = scatterCell({
centerX: spec.centerX, centerZ: spec.centerZ, size: spec.size, count: spec.count, seed: spec.seed, cellKey: spec.cellKey,
minScale: spec.minScale, maxScale: spec.maxScale, minUp: spec.minUp, heightMin: spec.heightMin, heightMax: spec.heightMax,
}, cellGround(spec, around));
if (plants.length === 0) return [];
// The cell stands at its centre, on the entity's own base height; the plants carry the ground's height relative to that.
for (const p of plants) p.y -= spec.baseY;
const sized = around.scale ? plantsSized(plants, around.scale, spec.centerX, spec.centerZ) : plants;
if (sized.length === 0) return [];
const levels = Math.min(Math.max(Math.floor(spec.far.levels), 1), 3);
const share = (level: number): number => Math.pow(Math.min(Math.max(spec.far.keep, 0.01), 1), level);
// Where each version is a layer of its own the shader widens every blade as its neighbours thin, at any distance; here a far blade is made wider once.
const wider = (level: number): number => (spec.far.only != null ? 1 : Math.min(Math.sqrt(1 / share(level)), Math.max(spec.far.grow, 1)));
const only = spec.far.only ?? null;
const band = only === null ? undefined : only;
const copies = (level: number): MeshData | null => {
const kept = level === 0 ? sized : rankedPlants(sized, share(level), spec.far.grow, undefined, spec.far.up ?? 0, spec.far.tilt ?? 0);
return kept.length === 0 ? null : buildInstancedMesh(source!, kept, spec.paint, band, !!spec.seats);
};
// A far blade is one quad, a little taller and as much wider as covers the ground of the ones left out: grass grows broader, not higher.
const blades = (level: number): MeshData | null => {
if (spec.look.kind !== 'grass') return null;
const blade = { height: spec.look.bladeHeight, width: spec.look.bladeWidth, lean: spec.look.bladeLean, paint: spec.paint, band };
if (level === 0) return buildGrassMesh(sized, { ...blade, segments: 3, thin: 1 });
const kept = rankedPlants(sized, share(level), 1);
return kept.length === 0 ? null : buildGrassMesh(kept, { ...blade, height: blade.height * 1.1, width: blade.width * wider(level), segments: 1, thin: 1 });
};
if (spec.look.kind === 'mesh' && !source) throw new Error('a cell of copies needs the mesh it copies');
const version = spec.look.kind === 'mesh' ? copies : blades;
if (only !== null) {
const mesh = version(Math.min(Math.max(Math.floor(only), 0), levels));
return mesh ? [mesh] : [];
}
if (spec.look.kind === 'mesh' && spec.far.cards) {
const width = Math.max(source!.aabbMax[0] - source!.aabbMin[0], source!.aabbMax[2] - source!.aabbMin[2]);
return [copies(0)!, buildBillboardMesh(sized, width, source!.aabbMax[1] - source!.aabbMin[1], spec.look.card, spec.paint, spec.look.tent)];
}
// A far version with no plant left is the end of them: past the last, the cell draws nothing.
const out: MeshData[] = [];
for (let level = 0; level <= levels; level++) {
const mesh = version(level);
if (!mesh) break;
out.push(mesh);
}
return out;
}
/** The buffers of a cell's meshes, to hand them between threads without a copy. */
export function cellTransfers(meshes: readonly MeshData[]): ArrayBuffer[] {
const out: ArrayBuffer[] = [];
for (const m of meshes) out.push(m.vertices.buffer as ArrayBuffer, m.indices.buffer as ArrayBuffer);
return out;
}