Skip to content

3D engine that AI agents drive

16.3 KB
Raw Blame
// A grass field made of real blade geometry, in the style of the Ghost of Tsushima grass talk and the open
// GodotGrass and Quick_Grass ports: curved tapered blades, clumps from cellular noise that share height, facing
// and lean, rounded normals, a dark base fading to a bright tip, dry patches, and tiles whose level of detail
// keeps a stable subset of the same blades. Wind lives in the vertex shader (`grass` tag).

import './world-material-shader.js';
import {
  FULL_TURN, WORLD_UP, clamp, createMeshBuilder, createRandom, crossProduct, lerp, lerpVectors, normalized, valueNoise,
} from './vegetation-geometry.js';
import { createTileField, hashTile, tileMatrix } from './tile-field.js';
import { requireSeed } from './seeded-random.js';
import { requireFiniteInRange } from './modeling-limits.js';

export const GRASS_LEVELS = Object.freeze([
  Object.freeze({ distance: 10, keep: 1, segments: 4, widthScale: 1 }),
  Object.freeze({ distance: 26, keep: 0.35, segments: 2, widthScale: 2 }),
  Object.freeze({ distance: 60, keep: 0.12, segments: 1, widthScale: 4.5 }),
]);

export const GRASS_PRESETS = Object.freeze({
  meadow: Object.freeze({ height: [0.25, 0.6], width: 0.022, density: 260, clumpSize: 0.55, clumpStrength: 0.55, dryness: 0.25, patchiness: 0.55, stalks: 0.012, bend: [0.18, 0.6], base: [0.012, 0.03, 0.006], tip: [0.15, 0.27, 0.045], dry: [0.36, 0.29, 0.1] }),
  lawn: Object.freeze({ height: [0.07, 0.14], width: 0.012, density: 900, clumpSize: 0.3, clumpStrength: 0.25, dryness: 0.05, patchiness: 0.2, stalks: 0, bend: [0.05, 0.25], base: [0.01, 0.035, 0.006], tip: [0.11, 0.26, 0.04], dry: [0.3, 0.3, 0.09] }),
  savanna: Object.freeze({ height: [0.45, 0.95], width: 0.018, density: 170, clumpSize: 0.8, clumpStrength: 0.7, dryness: 0.75, patchiness: 0.65, stalks: 0.035, bend: [0.25, 0.8], base: [0.04, 0.035, 0.01], tip: [0.36, 0.3, 0.1], dry: [0.5, 0.39, 0.15] }),
  wild: Object.freeze({ height: [0.3, 0.9], width: 0.026, density: 200, clumpSize: 0.7, clumpStrength: 0.65, dryness: 0.35, patchiness: 0.75, stalks: 0.025, bend: [0.25, 0.75], base: [0.012, 0.028, 0.008], tip: [0.14, 0.24, 0.05], dry: [0.4, 0.32, 0.12] }),
});

const MAXIMUM_BLADES_PER_TILE = 40000;
const ROUNDING_TILT = 0.55;
const CANOPY_BLEND = 0.3;
// Share of blades that fold over at the middle, as trampled or overgrown grass does.
const FOLDED_SHARE = 0.06;
// A seed stalk is this much thinner than a blade below its head; the head swells to HEAD_WIDTH past HEAD_START.
const STALK_WIDTH = 0.22;
const HEAD_START = 0.7;
const HEAD_WIDTH = 0.75;

/**
 * Field-scale entropy at (x, z): `height` and `density` multipliers and a `lush` shade, from two octaves of value noise
 * (about 8 m and 25 m). With `patchiness` 0 the field is uniform; at 1 some patches are short and thin, others tall and dense.
 */
function fieldPatch(x, z, settings) {
  const amount = settings.patchiness;
  const broad = valueNoise(x * 0.04, z * 0.04, settings.seed + 57);
  const local = valueNoise(x * 0.13, z * 0.13, settings.seed + 83);
  const growth = broad * 0.6 + local * 0.4;
  return {
    height: lerp(1, lerp(0.45, 1.35, growth), amount),
    density: lerp(1, smoothstep(0.28, 0.62, growth), amount * 0.85),
    lush: lerp(1, lerp(0.68, 1.2, valueNoise(x * 0.07, z * 0.07, settings.seed + 97)), amount),
  };
}

// Independent value in [0, 1) per clump cell; `salt` picks which property it is.
function cellHash(column, row, seed, salt) {
  return hashTile(seed + salt * 1013, column, row) / 4294967296;
}

/** Nearest jittered clump centre around (x, z): cellular noise, as the clumping in the Ghost of Tsushima talk. */
function nearestClump(x, z, clumpSize, seed) {
  const cellColumn = Math.floor(x / clumpSize);
  const cellRow = Math.floor(z / clumpSize);
  let best = null;
  for (let offsetRow = -1; offsetRow <= 1; offsetRow++) {
    for (let offsetColumn = -1; offsetColumn <= 1; offsetColumn++) {
      const column = cellColumn + offsetColumn;
      const row = cellRow + offsetRow;
      const centerX = (column + cellHash(column, row, seed, 1)) * clumpSize;
      const centerZ = (row + cellHash(column, row, seed, 2)) * clumpSize;
      const distance = Math.hypot(x - centerX, z - centerZ);
      if (!best || distance < best.distance) best = { centerX, centerZ, distance, column, row };
    }
  }
  return {
    ...best,
    heightScale: lerp(0.72, 1.28, cellHash(best.column, best.row, seed, 3)),
    facing: cellHash(best.column, best.row, seed, 4) * FULL_TURN,
    shade: lerp(0.82, 1.15, cellHash(best.column, best.row, seed, 5)),
    bendScale: lerp(0.7, 1.3, cellHash(best.column, best.row, seed, 6)),
  };
}

function smoothstep(edgeLow, edgeHigh, value) {
  const amount = clamp((value - edgeLow) / (edgeHigh - edgeLow), 0, 1);
  return amount * amount * (3 - 2 * amount);
}

/** Every blade of one tile at full density, in a stable order; each level keeps the blades whose `keepKey` is below its share. */
function planTileBlades(column, row, settings, keepLimit) {
  const { tileSize, origin, seed, terrainHeight, mask, density } = settings;
  const random = createRandom(hashTile(seed, column, row));
  const count = Math.min(MAXIMUM_BLADES_PER_TILE, Math.round(density * tileSize * tileSize));
  const blades = [];
  for (let index = 0; index < count; index++) {
    let x = origin[0] + (column + random()) * tileSize;
    let z = origin[1] + (row + random()) * tileSize;
    const keepKey = random();
    const maskRoll = random();
    const shapeRolls = [random(), random(), random(), random(), random(), random(), random(), random()];
    // Every roll is drawn before skipping, so a blade keeps its shape whatever share of the tile is built.
    if (keepKey >= keepLimit) continue;
    const coverage = mask ? clamp(mask(x, z), 0, 1) : 1;
    const patch = fieldPatch(x, z, settings);
    if (maskRoll >= coverage * patch.density) continue;
    const clump = nearestClump(x, z, settings.clumpSize, seed);
    const pull = settings.clumpStrength * 0.35;
    x = lerp(x, clump.centerX, pull);
    z = lerp(z, clump.centerZ, pull);
    const awayX = x - clump.centerX;
    const awayZ = z - clump.centerZ;
    const awayLength = Math.hypot(awayX, awayZ) || 1;
    const randomLean = shapeRolls[0] * FULL_TURN;
    const leanX = lerp(Math.cos(randomLean), awayX / awayLength, settings.clumpStrength);
    const leanZ = lerp(Math.sin(randomLean), awayZ / awayLength, settings.clumpStrength);
    const leanLength = Math.hypot(leanX, leanZ) || 1;
    // One roll picks the blade kind: a seed stalk at the low end, a folded blade at the high end, a plain blade between.
    const stalk = shapeRolls[7] < settings.stalks;
    const folded = !stalk && shapeRolls[7] > 1 - FOLDED_SHARE;
    const bladeHeight = lerp(settings.height[0], settings.height[1], shapeRolls[1]) * clump.heightScale * patch.height;
    // Stalks rise above the sward around them but stay under 1.5 times the tallest blade.
    const stalkHeight = Math.min(bladeHeight * lerp(1.3, 1.6, shapeRolls[3]), settings.height[1] * 1.5);
    const height = (stalk ? stalkHeight : bladeHeight) * coverage ** 0.35;
    const dryPatch = smoothstep(0.45, 0.8, valueNoise(x * 0.09, z * 0.09, seed + 31)) * settings.dryness;
    const bend = lerp(settings.bend[0], settings.bend[1], shapeRolls[3]) * clump.bendScale;
    blades.push({
      x, z, y: terrainHeight(x, z), keepKey, height, stalk,
      yaw: lerp(shapeRolls[2] * FULL_TURN, clump.facing, settings.clumpStrength * 0.6),
      leanX: leanX / leanLength, leanZ: leanZ / leanLength,
      bend: stalk ? bend * 0.35 : (folded ? Math.min(1.6, bend * 2.4 + 0.5) : bend),
      shade: clump.shade * patch.lush * lerp(0.85, 1.12, shapeRolls[4]),
      hue: shapeRolls[6] * 2 - 1,
      dryness: clamp(dryPatch + (shapeRolls[5] < settings.dryness * 0.25 ? 0.6 : 0), 0, 1),
    });
  }
  return blades;
}

/** Point and tangent on the blade's quadratic curve: straight up at the base, bending over toward its lean at the tip. */
function bladeCurve(blade, progress) {
  const rise = blade.height * (1 - blade.bend * 0.45);
  const reach = blade.height * blade.bend;
  const control = [0, blade.height * 0.75, 0];
  const tip = [blade.leanX * reach, rise, blade.leanZ * reach];
  const inverse = 1 - progress;
  const point = [0, 1, 2].map(axis => 2 * inverse * progress * control[axis] + progress * progress * tip[axis]);
  const tangent = normalized([0, 1, 2].map(axis => 2 * inverse * control[axis] + 2 * progress * (tip[axis] - control[axis])));
  return { point, tangent };
}

function bladeColor(blade, progress, settings) {
  if (blade.stalk) {
    // Green stem ripening to a straw seed head.
    const stem = lerpVectors(settings.base, lerpVectors(settings.tip, settings.dry, 0.35), progress ** 0.6);
    const head = settings.dry.map(channel => channel * 0.5);
    const colour = lerpVectors(stem, head, smoothstep(HEAD_START - 0.08, HEAD_START + 0.05, progress));
    return colour.map(channel => channel * blade.shade * lerp(0.4, 1, smoothstep(0, 0.3, progress)));
  }
  const green = lerpVectors(settings.base, settings.tip, progress ** 0.75);
  const dryTip = lerpVectors(settings.base.map(channel => channel * 1.6), settings.dry, progress ** 0.6);
  const mixed = lerpVectors(green, dryTip, blade.dryness);
  const occlusion = lerp(0.3, 1, smoothstep(0, 0.45, progress));
  // Hue drift per blade: some lean yellow, some blue-green, as in a real sward.
  const hue = [1 + blade.hue * 0.14, 1, 1 - blade.hue * 0.2];
  return mixed.map((channel, index) => channel * occlusion * blade.shade * hue[index]);
}

/** Width of a seed stalk along its length: a thin stem, then a spindle-shaped head that closes at the tip. */
function stalkProfile(progress) {
  if (progress <= HEAD_START) return STALK_WIDTH;
  return STALK_WIDTH + HEAD_WIDTH * Math.sin(Math.PI * (progress - HEAD_START) / (1 - HEAD_START));
}

function addBlade(builder, blade, tileX, tileZ, level, settings) {
  const right = [Math.cos(blade.yaw), 0, Math.sin(blade.yaw)];
  const width = settings.width * level.widthScale * (0.7 + 0.6 * blade.height / settings.height[1]);
  const base = [blade.x - tileX, blade.y, blade.z - tileZ];
  const rows = [];
  for (let segment = 0; segment <= level.segments; segment++) {
    const progress = segment / level.segments;
    const { point, tangent } = bladeCurve(blade, progress);
    const center = [base[0] + point[0], base[1] + point[1], base[2] + point[2]];
    const faceNormal = normalized(crossProduct(right, tangent));
    const halfWidth = width * 0.5 * (blade.stalk ? stalkProfile(progress) : 1 - progress ** 1.7);
    const color = bladeColor(blade, progress, settings);
    const vertexFor = (side) => {
      // Rounded normals: each edge tilts outward, so a flat blade shades like a curved leaf.
      const tilted = normalized(faceNormal.map((component, axis) => component + right[axis] * side * ROUNDING_TILT));
      const shading = normalized(tilted.map((component, axis) => component * (1 - CANOPY_BLEND) + WORLD_UP[axis] * CANOPY_BLEND));
      const position = center.map((component, axis) => component + right[axis] * side * halfWidth);
      return builder.addVertex(position, shading, (side + 1) / 2, 1 - progress, color);
    };
    if (segment === level.segments) {
      const tipNormal = normalized(faceNormal.map((component, axis) => component * (1 - CANOPY_BLEND) + WORLD_UP[axis] * CANOPY_BLEND));
      rows.push([builder.addVertex(center, tipNormal, 0.5, 0, color)]);
    } else {
      rows.push([vertexFor(-1), vertexFor(1)]);
    }
  }
  for (let segment = 0; segment < level.segments; segment++) {
    const [left, rightIndex] = rows[segment];
    const next = rows[segment + 1];
    if (next.length === 1) {
      builder.addTriangle(left, rightIndex, next[0]);
    } else {
      builder.addTriangle(left, rightIndex, next[0]);
      builder.addTriangle(rightIndex, next[1], next[0]);
    }
  }
}

function resolveSettings(options) {
  const preset = GRASS_PRESETS[options.preset ?? 'meadow'];
  if (!preset) throw new RangeError(`Unknown grass preset: ${options.preset}. Use ${Object.keys(GRASS_PRESETS).join(', ')}.`);
  const settings = { ...preset, ...Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined)) };
  const { area } = settings;
  if (!area || ![area.minX, area.maxX, area.minZ, area.maxZ].every(Number.isFinite) || area.maxX <= area.minX || area.maxZ <= area.minZ) {
    throw new TypeError('Grass area needs finite minX < maxX and minZ < maxZ.');
  }
  if (!(settings.density > 0)) throw new RangeError('Grass density must be a positive number of blades per square metre.');
  requireFiniteInRange('createGrass', 'tileSize', settings.tileSize, 1e-3, 1e6);
  if (!Array.isArray(settings.height) || !(settings.height[0] > 0) || !(settings.height[1] >= settings.height[0]) || !(settings.height[1] < Infinity)) throw new RangeError('Grass height must be finite [minimum, maximum] in metres, such as [0.25, 0.6].');
  requireFiniteInRange('createGrass', 'width', settings.width, 1e-6, 1e3);
  requireFiniteInRange('createGrass', 'clumpSize', settings.clumpSize, 1e-3, 1e6);
  if (!Array.isArray(settings.bend) || settings.bend.length !== 2 || !(settings.bend[1] >= settings.bend[0])) throw new RangeError('Grass bend must be [minimum, maximum], such as [0.18, 0.6].');
  requireFiniteInRange('createGrass', 'bend', settings.bend, 0, 10);
  for (const name of ['patchiness', 'stalks', 'dryness', 'clumpStrength']) {
    if (!(settings[name] >= 0 && settings[name] <= 1)) throw new RangeError(`Grass ${name} must be between 0 and 1.`);
  }
  if (settings.mask !== undefined && typeof settings.mask !== 'function') throw new TypeError('Grass mask must be a function (x, z) => 0..1.');
  if (typeof settings.terrainHeight !== 'function') throw new TypeError('Grass terrainHeight must be a function (x, z) => y.');
  for (const name of ['base', 'tip', 'dry']) {
    if (!Array.isArray(settings[name]) || settings[name].length !== 3 || !settings[name].every(Number.isFinite)) throw new TypeError(`Grass ${name} colour must be three linear RGB numbers.`);
  }
  settings.levels = settings.levels ?? GRASS_LEVELS;
  settings.cullDistance = settings.cullDistance ?? settings.levels.at(-1).distance;
  settings.origin = [area.minX, area.minZ];
  return settings;
}

/**
 * Builds a grass field over `area` ({ minX, maxX, minZ, maxZ }) in tiles of `tileSize` metres.
 * Options: `preset` ('meadow', 'lawn', 'savanna', 'wild'), `terrainHeight(x, z)`, `mask(x, z)` (0..1 coverage),
 * `density` (blades per square metre near the camera), `height` [min, max], `width`, `clumpSize`, `clumpStrength`,
 * `bend` [min, max], `dryness`, `patchiness` (0..1 field-scale height and density patches), `stalks` (share of seed
 * stalks), linear `base`, `tip` and `dry` colours, `castShadow`, `levels`, `cullDistance`, `seed`, `eye`.
 * Returns `{ parts, update(eye), material, stats(), groundColor }`; tint the ground under the grass with `groundColor`. `update` returns true when tiles changed level; then call
 * `renderer.replaceParts([...otherParts, ...grass.parts])`. Grass parts are rigid and untextured, so they stream.
 */
export function createGrass(options = {}) {
  const settings = resolveSettings({ tileSize: 4, seed: 1, terrainHeight: () => 0, castShadow: false, ...options });
  requireSeed(settings.seed, 'grass seed');
  const material = { tag: 'grass', color: [1, 1, 1], roughness: 0.8, metallic: 0, emission: 0, doubleSided: true };

  function buildParts(tile, levelIndex) {
    const level = settings.levels[levelIndex];
    if (!tile.cache.blades || tile.cache.plannedKeep < level.keep) {
      tile.cache.blades = planTileBlades(tile.column, tile.row, settings, level.keep);
      tile.cache.plannedKeep = level.keep;
    }
    const builder = createMeshBuilder({ withColors: true });
    for (const blade of tile.cache.blades) {
      if (blade.keepKey < level.keep) addBlade(builder, blade, tile.tileX, tile.tileZ, level, settings);
    }
    if (builder.vertexCount === 0) return [];
    return [{ name: `Grass tile ${tile.column},${tile.row}`, geometry: builder.build(), matrix: tileMatrix(tile), material, castShadow: settings.castShadow }];
  }

  const field = createTileField({ ...settings, buildParts });
  field.update(settings.eye ?? [(settings.area.minX + settings.area.maxX) / 2, 2, (settings.area.minZ + settings.area.maxZ) / 2]);
  // Colour for the ground under the blades: gaps then read as shaded grass instead of bare soil.
  const groundColor = lerpVectors(settings.base, settings.tip, 0.3);
  return { get parts() { return field.parts; }, update: field.update, material, stats: field.stats, settings, groundColor };
}