Terrain foliage

import { Camera, InstancedMeshRenderer, Terrain, terrain, terrainAssetFromDefinition, TerrainScatter } from "ignifx";import { bootExample } from "../_kit/boot.ts";import { thousands, wholeMetres } from "../_kit/format.ts";import { fadeToHorizon } from "../_kit/horizon.ts";import { attachOrbit } from "../_kit/orbit.ts";import { bind, readout, slider } from "../_kit/panel.ts";import { createSky } from "../_kit/sky.ts";import { createApron, easedEdgeHeights, grassCard, keepOrbitAbove } from "../_kit/terrain.ts";import { conifer, foliageMaterials, GRASS_COLOR, MEADOW, WIND } from "./meadow.ts";import type { PanelBinding } from "../_kit/panel.ts";/** * Grass and trees on a terrain: two `TerrainScatter` components and no model file. * * ## Where an instance is allowed to stand * * A scatter walks a jittered grid over the field — `density` instances per square metre, capped by * `maxInstances` — and keeps a candidate only if its slope, its height and the terrain's **splat * weight** for the named layers all accept it. Every random number is an integer hash of the cell * and the seed, never a running generator, so the same seed places the same forest in a headless * test and on a device. Placement runs **once**, not per frame; a changed rule needs * `regenerate()`, and a sculpt triggers one by itself. `maxInstances` also sizes the GPU instance * buffer, which is fixed when the app starts, so each scatter is sized for the top of its slider. * * ## What draws them * * Each scatter owns an `InstancedMeshRenderer` with `gpuCulling` on, so Babylon Lite's compute * culling drops the instances behind the camera before the vertex stage, and a `lodMesh` partner * that takes over past `lodDistance`. One material draws every instance of a kind. * * ## Why foliage is a shader material and not PBR * * `createFoliageMaterial` builds a `"shader"` material that owns its vertex stage, because that is * the only way the wind can read the clock: Babylon Lite declares a material plugin's uniforms * fragment-visible only, so a `displace` surface hook has no time to sway with. The price is * stated plainly — the cards cast shadows but receive none, and get no image-based lighting or fog, * which is why the fog here begins past the farthest blade the camera can see. * * A card casts as the solid quad it is, not as the blades cut out of it: the shadow pass has no * alpha test. A tree's cone hides that, but a meadow of grass cards at this density would lay a * grey sheet over the ground it stands on, so only the trees cast here. *//** The sky the meadow stands against, in sRGB. */const SKY = { r: 0.6, g: 0.78, b: 1, a: 1 } as const;/** The density sliders' tops, in instances per square metre; the instance buffers are sized for them. */const MAX_DENSITY = { grass: 3, trees: 0.06 } as const;/** The opening shot: low and close, so the near grass reads as blades. */const SHOT = { yaw: 28, pitch: 11, distance: 30, x: 0, z: 10, lift: 3 } as const;bootExample({  title: "Terrain foliage",  extensions: [terrain()],  settings: {    rendering: { clearColor: SKY, msaaSamples: 4, features: { shadows: true } },    time: { fixedDeltaTime: 1 / 60 },  },  async setup({ app, panel }) {    // The field's last 40 m ease down to the level of the apron that continues it.    const meadow = await terrainAssetFromDefinition(app, MEADOW, { heights: easedEdgeHeights(MEADOW, 40) });    const area = meadow.value.field.width * meadow.value.field.depth;    const materials = await foliageMaterials(app);    createSky(app, {      sky: SKY,      ground: { r: 0.26, g: 0.3, b: 0.2, a: 1 },      sunPosition: { x: -34, y: 48, z: -28 },      sunIntensity: 3.1,      skyIntensity: 0.95,      shadows: { mapSize: 2048, maxDistance: 90, darkness: 0.35 },    });    const groundEntity = app.world.createEntity("Meadow");    const ground = groundEntity.addComponent(Terrain, { definition: meadow });    const grass = groundEntity.addComponent(TerrainScatter, {      mesh: grassCard(app, "foliage/grass-cross", 2),      lodMesh: grassCard(app, "foliage/grass-card", 1),      lodDistance: 26,      material: materials.grass,      density: 1.4,      layers: ["grass"],      slope: { x: 0, y: 24 },      scale: { x: 0.7, y: 1.5 },      seed: 3,      maxInstances: Math.ceil(area * MAX_DENSITY.grass),    });    // The scatter turns casting on when it attaches; a card's shadow is the whole card, so at 1.4    // per square metre the grass would shade most of the ground grey. The trees keep theirs.    groundEntity.requireComponent(InstancedMeshRenderer).castShadows = false;    // A second kind of foliage goes on a **child**: one `TerrainScatter` per entity, and a scatter    // finds the terrain on itself or on any ancestor.    const trees = app.world.createEntity("Conifers", { parent: groundEntity }).addComponent(TerrainScatter, {      mesh: conifer(app, "foliage/conifer", 7),      // Five sides and not four: a square cone is a different silhouette, and a tree changing shape      // as the idle orbit carries it across the threshold is what a level of detail must not show.      lodMesh: conifer(app, "foliage/conifer-far", 5),      // Past the shadow's 90 m reach, so a swap never redraws a shadow, and far enough that a tree      // there is a few dozen pixels tall; the field's far side is still past it from most shots.      lodDistance: 110,      material: materials.trees,      density: 0.022,      layers: ["grass"],      slope: { x: 0, y: 20 },      scale: { x: 0.75, y: 1.45 },      seed: 9,      maxInstances: Math.ceil(area * MAX_DENSITY.trees),    });    const eye = app.world.createEntity("Main Camera");    eye.addComponent(Camera, { near: 0.3, far: 600, fov: 55 });    const orbit = attachOrbit(app, eye, {      yaw: SHOT.yaw,      pitch: SHOT.pitch,      distance: SHOT.distance,      // Framed on the ground rather than on a fixed height: the field is noise, so the only honest      // way to stand the camera above the grass is to ask the height field where the grass is.      target: { x: SHOT.x, y: meadow.value.field.heightAt(SHOT.x, SHOT.z) + SHOT.lift, z: SHOT.z },      minDistance: 6,      maxDistance: 70,      idleDegreesPerSecond: 4,    });    keepOrbitAbove(app, orbit, ground);    // Foliage is never fogged, so the fog begins past the farthest blade the camera can see.    const fade = fadeToHorizon(app, { start: 190, end: 380 });    createApron(app, { size: fade.groundSize, hole: meadow.value.field.width, color: GRASS_COLOR });    // Kept in a field so the Wind slider can read it back.    const wind: { strength: number } = { strength: WIND.strength };    /**     * Binds a density slider; placement runs once, so a new density needs `regenerate()`.     *     * @param scatter - The scatter whose density the slider sets.     * @returns The binding.     */    function density(scatter: TerrainScatter): PanelBinding<number> {      return {        ...bind(scatter, "density"),        change: (value: number): void => {          scatter.density = value;          scatter.regenerate();        },      };    }    panel({      title: "Terrain foliage",      groups: [        {          label: "Scatter",          controls: [            slider(              "Grass density",              {                min: 0.1,                max: MAX_DENSITY.grass,                step: 0.1,                commit: "release",                format: (v): string => `${v.toFixed(1)}/m²`,              },              density(grass),            ),            slider(              "Tree density",              {                min: 0,                max: MAX_DENSITY.trees,                step: 0.002,                commit: "release",                format: (v): string => `${v.toFixed(3)}/m²`,              },              density(trees),            ),            readout("Grass instances", (): string => thousands(grass.count)),            readout("Trees", (): string => thousands(trees.count)),          ],        },        {          label: "Wind and detail",          controls: [            slider(              "Wind",              { min: 0, max: 0.8, step: 0.02, format: (v): string => `${v.toFixed(2)} m` },              {                ...bind(wind, "strength"),                change: (value: number): void => {                  wind.strength = value;                  materials.grass.value.setUniform("windStrength", value);                  materials.trees.value.setUniform("windStrength", value * WIND.treeShare);                },              },            ),            // `lodDistance` is live: the scatter hands it to its renderer's LOD pairing each frame.            slider("Grass LOD distance", { min: 6, max: 90, step: 2, format: wholeMetres }, bind(grass, "lodDistance")),            readout("Chunks drawn", (): string => `${String(ground.visibleChunks)} of ${String(ground.chunkCount)}`),            readout("Frame draws", (): string => String(app.renderer.drawCalls)),          ],        },      ],    });  },});