3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// Ground clutter: pebbles, rocks, twigs and fallen leaves scattered over terrain in streamable tiles.
// Stones are noise-displaced spheres cut by a few random planes, so rocks get flat chipped faces while pebbles stay
// round. They sink into the ground and darken underneath and near the soil line. Rocks carry the renderer's moss layer
// (its own rough, sheened material with cushion relief), so moss is shaded as moss rather than painted on.
// Everything is vertex-coloured and untextured, so tiles stream with `renderer.replaceParts`.
import './world-material-shader.js';
import {
FULL_TURN, addTube, 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';
// Rocks draw their keep key below this value and everything else above it, so the farthest level keeps only rocks.
const ROCK_KEY_LIMIT = 0.04;
export const CLUTTER_LEVELS = Object.freeze([
Object.freeze({ distance: 12, keep: 1, detail: 1 }),
Object.freeze({ distance: 30, keep: 0.2, detail: 0 }),
Object.freeze({ distance: 70, keep: ROCK_KEY_LIMIT, detail: 0 }),
]);
/** Items per square metre near the camera. */
export const CLUTTER_PRESETS = Object.freeze({
meadow: Object.freeze({ pebbles: 0.8, rocks: 0.03, twigs: 0.08, leaves: 0.3, moss: 0.4 }),
forest: Object.freeze({ pebbles: 0.5, rocks: 0.06, twigs: 1.2, leaves: 16, moss: 0.8 }),
riverbed: Object.freeze({ pebbles: 14, rocks: 0.6, twigs: 0.15, leaves: 0.1, moss: 0.15 }),
scree: Object.freeze({ pebbles: 12, rocks: 1.4, twigs: 0, leaves: 0, moss: 0.05 }),
});
const DEFAULTS = Object.freeze({
pebbleSize: [0.012, 0.05],
rockSize: [0.08, 0.38],
stoneColor: [0.13, 0.125, 0.11],
mossColor: [0.06, 0.09, 0.025],
soilColor: [0.07, 0.055, 0.04],
twigColor: [0.11, 0.075, 0.045],
leafColors: [[0.2, 0.1, 0.035], [0.32, 0.19, 0.05], [0.1, 0.065, 0.03], [0.14, 0.12, 0.04]],
clumping: 0.6,
});
const KINDS = Object.freeze(['pebbles', 'rocks', 'twigs', 'leaves']);
const MAXIMUM_ITEMS_PER_KIND = 20000;
// Sphere resolution per detail level (index 0 far, 1 near). Pebbles are small and many, so they get coarser spheres,
// down to an octahedron far away, where one covers a pixel or two.
const ROCK_DETAIL = Object.freeze([Object.freeze({ segments: 6, rings: 4 }), Object.freeze({ segments: 12, rings: 7 })]);
const PEBBLE_DETAIL = Object.freeze([Object.freeze({ segments: 4, rings: 2 }), Object.freeze({ segments: 6, rings: 4 })]);
function smoothstep(edgeLow, edgeHigh, value) {
const amount = clamp((value - edgeLow) / (edgeHigh - edgeLow), 0, 1);
return amount * amount * (3 - 2 * amount);
}
function groundNormal(terrainHeight, x, z) {
const step = 0.25;
const slopeX = terrainHeight(x + step, z) - terrainHeight(x - step, z);
const slopeZ = terrainHeight(x, z + step) - terrainHeight(x, z - step);
return normalized([-slopeX, 2 * step, -slopeZ]);
}
/**
* Right-handed frame on the ground: `up` is the terrain normal and `forward` follows `yaw` across it. Local x, y
* and z map to forward, up and side; a mirrored frame would turn every stone inside out.
*/
function groundFrame(up, yaw) {
const heading = [Math.cos(yaw), 0, Math.sin(yaw)];
const side = normalized(crossProduct(heading, up));
const forward = normalized(crossProduct(up, side));
return { up, forward, side };
}
function placeInFrame(frame, origin, local) {
return [0, 1, 2].map(axis => origin[axis] + frame.forward[axis] * local[0] + frame.up[axis] * local[1] + frame.side[axis] * local[2]);
}
/** Field-scale clumping: items gather into patches of about 7 m instead of spreading evenly. */
function clumpWeight(x, z, settings, salt) {
const patch = smoothstep(0.3, 0.75, valueNoise(x * 0.15, z * 0.15, settings.seed + salt));
return lerp(1, patch * 2, settings.clumping);
}
function planTileItems(tile, settings) {
const items = [];
KINDS.forEach((kind, kindIndex) => {
const density = settings[kind];
if (!(density > 0)) return;
const random = createRandom(hashTile(settings.seed + kindIndex * 7907, tile.column, tile.row));
// Twice the candidates, each accepted with half its clump weight, so the mean density matches `density`.
const candidates = Math.min(MAXIMUM_ITEMS_PER_KIND, Math.round(density * settings.tileSize * settings.tileSize * 2));
for (let index = 0; index < candidates; index++) {
const x = tile.tileX + random() * settings.tileSize;
const z = tile.tileZ + random() * settings.tileSize;
const acceptRoll = random();
const keepRoll = random();
const shapeRolls = [random(), random(), random(), random(), random(), random()];
const coverage = settings.mask ? clamp(settings.mask(x, z), 0, 1) || 0 : 1; // a NaN mask value means no coverage, not full
if (acceptRoll * 2 >= clumpWeight(x, z, settings, 131 + kindIndex * 17) * coverage) continue;
const keepKey = kind === 'rocks' ? keepRoll * ROCK_KEY_LIMIT : lerp(ROCK_KEY_LIMIT, 1, keepRoll);
items.push({ kind, x, z, keepKey, shapeRolls });
}
});
return items;
}
/** Radius multiplier of a stone along `direction`: smooth noise, then flat chipped faces from cutting planes. */
function stoneRadius(direction, stone) {
const [x, y, z] = direction;
const phases = stone.phases;
let radius = 1 + stone.roughness * (
Math.sin(x * 2.6 + phases[0]) * Math.sin(y * 2.6 + phases[1])
+ 0.5 * Math.sin(z * 4.4 + phases[2]) * Math.cos(x * 3.4 + phases[3])
);
for (const plane of stone.planes) {
const facing = x * plane.normal[0] + y * plane.normal[1] + z * plane.normal[2];
if (facing > 0.05) radius = Math.min(radius, plane.distance / facing);
}
return radius;
}
function stoneColor(normal, localPoint, heightAboveGround, stone, vertexIndex, settings) {
const underside = lerp(0.45, 1, smoothstep(-0.6, 0.7, normal[1]));
const speckle = lerp(0.82, 1.12, (hashTile(stone.colorSeed, vertexIndex, 3) & 1023) / 1023);
// Blotches and veins across the surface, in the stone's own space so they stay put as it turns.
const blotch = valueNoise(localPoint[0] * stone.grain + localPoint[1] * 0.7 * stone.grain, localPoint[2] * stone.grain, stone.colorSeed);
const stain = lerp(0.6, 1.25, blotch);
let color = stone.base.map(channel => channel * underside * speckle * stain);
// Soil clings to the stone where it meets the ground.
const soil = 1 - smoothstep(0, stone.height * 0.35, heightAboveGround);
return lerpVectors(color, settings.soilColor, soil * 0.7);
}
function addStone(builder, item, tileOrigin, settings, detail) {
const isRock = item.kind === 'rocks';
const { segments, rings } = (isRock ? ROCK_DETAIL : PEBBLE_DETAIL)[detail];
const rolls = item.shapeRolls;
const sizeRange = isRock ? settings.rockSize : settings.pebbleSize;
// Most stones are small: a power curve leaves a few large ones.
const radius = lerp(sizeRange[0], sizeRange[1], rolls[0] ** 2.5);
const random = createRandom(hashTile(settings.seed, Math.floor(item.x * 977), Math.floor(item.z * 977)));
const stone = {
roughness: isRock ? 0.16 : 0.08,
phases: [random() * FULL_TURN, random() * FULL_TURN, random() * FULL_TURN, random() * FULL_TURN],
planes: [],
colorSeed: hashTile(settings.seed + 17, Math.floor(item.x * 977), Math.floor(item.z * 977)),
height: radius * lerp(0.45, 0.75, rolls[1]),
};
if (isRock) {
for (let plane = 0; plane < 4; plane++) {
const theta = random() * FULL_TURN;
const lift = random() * 1.6 - 0.4;
stone.planes.push({ normal: normalized([Math.cos(theta), lift, Math.sin(theta)]), distance: lerp(0.68, 0.9, random()) });
}
}
// Each stone gets its own tone and hue, from blue-grey to rust, as a mixed riverbed has.
const tone = lerp(0.55, 1.45, rolls[2]);
const warmth = rolls[3] * 2 - 1;
stone.base = settings.stoneColor.map((channel, index) => channel * tone * [1 + warmth * 0.25, 1 + warmth * 0.04, 1 - warmth * 0.3][index]);
stone.grain = lerp(2.5, 5, random());
const scale = [radius * lerp(0.75, 1.1, rolls[4]), stone.height, radius * lerp(0.7, 1, rolls[5])];
const ground = settings.terrainHeight(item.x, item.z);
const frame = groundFrame(groundNormal(settings.terrainHeight, item.x, item.z), rolls[5] * FULL_TURN);
// Sink a third to a half of the stone so it sits in the ground instead of resting on it.
const sink = lerp(0.3, 0.5, rolls[1]);
const center = [item.x - tileOrigin[0], ground + stone.height * (1 - 2 * sink), item.z - tileOrigin[1]];
const directions = [[0, 1, 0]];
for (let ring = 1; ring < rings; ring++) {
const polar = Math.PI * ring / rings;
for (let segment = 0; segment < segments; segment++) {
const azimuth = FULL_TURN * segment / segments;
directions.push([Math.sin(polar) * Math.cos(azimuth), Math.cos(polar), Math.sin(polar) * Math.sin(azimuth)]);
}
}
directions.push([0, -1, 0]);
const localPoints = directions.map(direction => {
const distance = stoneRadius(direction, stone);
return direction.map((component, axis) => component * distance * scale[axis]);
});
const triangles = [];
const ringStart = ring => 1 + (ring - 1) * segments;
const bottom = directions.length - 1;
for (let segment = 0; segment < segments; segment++) {
const next = (segment + 1) % segments;
triangles.push([0, ringStart(1) + next, ringStart(1) + segment]);
for (let ring = 1; ring < rings - 1; ring++) {
const upper = ringStart(ring);
const lower = ringStart(ring + 1);
triangles.push([upper + segment, upper + next, lower + segment]);
triangles.push([upper + next, lower + next, lower + segment]);
}
const last = ringStart(rings - 1);
triangles.push([last + segment, last + next, bottom]);
}
// Smooth normals from the faces around each vertex; the sphere has no seam, so none show.
const localNormals = localPoints.map(() => [0, 0, 0]);
for (const [first, second, third] of triangles) {
const edgeOne = [0, 1, 2].map(axis => localPoints[second][axis] - localPoints[first][axis]);
const edgeTwo = [0, 1, 2].map(axis => localPoints[third][axis] - localPoints[first][axis]);
const face = crossProduct(edgeOne, edgeTwo);
for (const vertex of [first, second, third]) for (let axis = 0; axis < 3; axis++) localNormals[vertex][axis] += face[axis];
}
const firstVertex = builder.vertexCount;
localPoints.forEach((point, index) => {
const position = placeInFrame(frame, center, point);
const normal = normalized(placeInFrame(frame, [0, 0, 0], normalized(localNormals[index])));
const color = stoneColor(normal, point.map((component, axis) => component / scale[axis]), position[1] - ground, stone, index, settings);
builder.addVertex(position, normal, 0, 0, color);
});
for (const [first, second, third] of triangles) builder.addTriangle(firstVertex + first, firstVertex + second, firstVertex + third);
}
function addTwig(builder, item, tileOrigin, settings, detail) {
const rolls = item.shapeRolls;
const length = lerp(0.1, 0.45, rolls[0] ** 1.5);
const thickness = lerp(0.003, 0.011, rolls[1]) * (0.6 + length);
const yaw = rolls[2] * FULL_TURN;
const bend = (rolls[3] - 0.5) * 0.6;
const pointCount = detail ? 4 : 2;
const points = [];
const radii = [];
for (let index = 0; index < pointCount; index++) {
const progress = index / (pointCount - 1);
const angle = yaw + bend * progress;
const along = (progress - 0.5) * length;
const x = item.x + Math.cos(angle) * along;
const z = item.z + Math.sin(angle) * along;
const radius = thickness * lerp(1, 0.45, progress);
points.push([x - tileOrigin[0], settings.terrainHeight(x, z) + radius * 0.7, z - tileOrigin[1]]);
radii.push(radius);
}
const color = settings.twigColor.map(channel => channel * lerp(0.7, 1.3, rolls[4]));
addTube(builder, points, radii, detail ? 5 : 3, 1, color);
}
function addLeaf(builder, item, tileOrigin, settings, detail) {
const rolls = item.shapeRolls;
const length = lerp(0.04, 0.1, rolls[0]);
const width = length * lerp(0.4, 0.65, rolls[1]);
const curl = width * lerp(0.05, 0.45, rolls[2]);
const palette = settings.leafColors;
const base = palette[Math.floor(rolls[3] * palette.length) % palette.length];
const color = base.map(channel => channel * lerp(0.75, 1.25, rolls[4]));
const ground = settings.terrainHeight(item.x, item.z);
const frame = groundFrame(groundNormal(settings.terrainHeight, item.x, item.z), rolls[5] * FULL_TURN);
const origin = [item.x - tileOrigin[0], ground + 0.004, item.z - tileOrigin[1]];
const rows = detail ? 3 : 2;
const grid = [];
for (let row = 0; row < rows; row++) {
const progress = row / (rows - 1);
const halfWidth = width * 0.5 * Math.sin(Math.PI * lerp(0.08, 1, progress)) ** 0.8;
const rowVertices = [];
for (let across = -1; across <= 1; across++) {
// Edges curl up and the leaf lies cupped; the midrib is a little darker.
const lift = curl * across * across;
const local = [(progress - 0.5) * length, lift, across * halfWidth];
const normal = normalized(placeInFrame(frame, [0, 0, 0], [0, 1, -across * curl / Math.max(halfWidth, 1e-4)]));
const shade = across === 0 ? 0.82 : 1;
rowVertices.push(builder.addVertex(placeInFrame(frame, origin, local), normal, (across + 1) / 2, progress, color.map(channel => channel * shade)));
}
grid.push(rowVertices);
}
for (let row = 0; row < rows - 1; row++) {
for (let column = 0; column < 2; column++) {
// Counter-clockwise from above, so the upper face is the front and keeps its sky-facing normal.
builder.addTriangle(grid[row][column], grid[row][column + 1], grid[row + 1][column]);
builder.addTriangle(grid[row][column + 1], grid[row + 1][column + 1], grid[row + 1][column]);
}
}
}
function requireRange(value, name) {
if (!Array.isArray(value) || value.length !== 2 || !(value[0] > 0) || !(value[1] >= value[0]) || !(value[1] < Infinity)) throw new RangeError(`Clutter ${name} must be finite [minimum, maximum] in metres, such as [0.01, 0.05].`);
}
function requireColor(value, name) {
if (!Array.isArray(value) || value.length !== 3 || !value.every(Number.isFinite)) throw new TypeError(`Clutter ${name} must be three linear RGB numbers.`);
}
function resolveSettings(options) {
const preset = CLUTTER_PRESETS[options.preset ?? 'meadow'];
if (!preset) throw new RangeError(`Unknown clutter preset: ${options.preset}. Use ${Object.keys(CLUTTER_PRESETS).join(', ')}.`);
const defined = Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));
const settings = { tileSize: 4, seed: 1, terrainHeight: () => 0, castShadow: true, ...DEFAULTS, ...preset, ...defined };
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('Clutter area needs finite minX < maxX and minZ < maxZ.');
}
for (const kind of KINDS) {
if (!(settings[kind] >= 0)) throw new RangeError(`Clutter ${kind} must be a non-negative count per square metre.`);
}
for (const name of ['moss', 'clumping']) {
if (!(settings[name] >= 0 && settings[name] <= 1)) throw new RangeError(`Clutter ${name} must be between 0 and 1.`);
}
requireFiniteInRange('createClutter', 'tileSize', settings.tileSize, 1e-3, 1e6);
requireSeed(settings.seed, 'Clutter seed');
requireRange(settings.pebbleSize, 'pebbleSize');
requireRange(settings.rockSize, 'rockSize');
for (const name of ['stoneColor', 'mossColor', 'soilColor', 'twigColor']) requireColor(settings[name], name);
if (!Array.isArray(settings.leafColors) || settings.leafColors.length === 0) throw new TypeError('Clutter leafColors must be a non-empty list of colours.');
settings.leafColors.forEach((color, index) => requireColor(color, `leafColors[${index}]`));
if (typeof settings.terrainHeight !== 'function') throw new TypeError('Clutter terrainHeight must be a function (x, z) => y.');
if (settings.mask !== undefined && typeof settings.mask !== 'function') throw new TypeError('Clutter mask must be a function (x, z) => 0..1.');
settings.levels = settings.levels ?? CLUTTER_LEVELS;
settings.cullDistance = settings.cullDistance ?? settings.levels.at(-1).distance;
return settings;
}
/**
* Scatters pebbles, rocks, twigs and fallen leaves over `area` ({ minX, maxX, minZ, maxZ }).
* Options: `preset` ('meadow', 'forest', 'riverbed', 'scree'), `terrainHeight(x, z)`, `mask(x, z)` (0..1),
* counts per square metre `pebbles`, `rocks`, `twigs`, `leaves`, `pebbleSize` and `rockSize` radius ranges,
* `moss` (0..1), `clumping` (0..1), linear `stoneColor`, `mossColor`, `soilColor`, `twigColor` and `leafColors`,
* `castShadow` (stones only), `tileSize`, `levels`, `cullDistance`, `seed`, `eye`.
* Returns `{ parts, update(eye), stats(), materials, settings }`. When `update` returns true, call
* `renderer.replaceParts([...otherParts, ...clutter.parts])`.
*/
export function createClutter(options = {}) {
const settings = resolveSettings(options);
const materials = {
rock: { color: [1, 1, 1], roughness: 0.88, metallic: 0, emission: 0, moss: settings.moss, mossColor: settings.mossColor },
pebble: { color: [1, 1, 1], roughness: 0.8, metallic: 0, emission: 0 },
litter: { color: [1, 1, 1], roughness: 0.8, metallic: 0, emission: 0, doubleSided: true },
};
function buildParts(tile, levelIndex) {
const level = settings.levels[levelIndex];
tile.cache.items ??= planTileItems(tile, settings);
const tileOrigin = [tile.tileX, tile.tileZ];
const rocks = createMeshBuilder({ withColors: true });
const pebbles = createMeshBuilder({ withColors: true });
const litter = createMeshBuilder({ withColors: true });
for (const item of tile.cache.items) {
if (item.keepKey >= level.keep) continue;
if (item.kind === 'rocks') addStone(rocks, item, tileOrigin, settings, level.detail);
else if (item.kind === 'pebbles') addStone(pebbles, item, tileOrigin, settings, level.detail);
else if (item.kind === 'twigs') addTwig(litter, item, tileOrigin, settings, level.detail);
else addLeaf(litter, item, tileOrigin, settings, level.detail);
}
const parts = [];
const matrix = tileMatrix(tile);
if (rocks.vertexCount > 0) parts.push({ name: `Clutter rocks ${tile.column},${tile.row}`, geometry: rocks.build(), matrix, material: materials.rock, castShadow: settings.castShadow });
if (pebbles.vertexCount > 0) parts.push({ name: `Clutter pebbles ${tile.column},${tile.row}`, geometry: pebbles.build(), matrix, material: materials.pebble, castShadow: settings.castShadow });
if (litter.vertexCount > 0) parts.push({ name: `Clutter litter ${tile.column},${tile.row}`, geometry: litter.build(), matrix, material: materials.litter, castShadow: false });
return parts;
}
const field = createTileField({ ...settings, buildParts });
field.update(settings.eye ?? [(settings.area.minX + settings.area.maxX) / 2, 2, (settings.area.minZ + settings.area.maxZ) / 2]);
return { get parts() { return field.parts; }, update: field.update, stats: field.stats, materials, settings };
}