3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { mat4 } from 'gl-matrix';
import { leafTextureDescriptor } from './vegetation-textures.js';
import { SPECIES, createTree, scatterVegetation, levelForDistance } from './vegetation.js';
import { createRecipeTerrain } from './agent-terrain.js';
import { invalidField } from './field-error.js';
// Recipe vegetation: a group node with a `vegetation` field grows one tree, or scatters trees over a terrain node. The
// result reuses the placed-asset channel of agent-scene.js: generated geometries (type "asset"), materials (assetSource)
// and part nodes (assetPart), so exports and edits already skip them. Everything is a pure function of the recipe: the
// same seed grows the same trees, and levels of detail come from the recipe camera, never from the frame being drawn.
export const VEGETATION_LIMITS = Object.freeze({
maxInstances: 1000, maxVariants: 4, maxExclusions: 32, maxCandidates: 4000, maxCachedSets: 4,
});
const SCATTER_SPECIES = [...Object.keys(SPECIES), 'grass', 'flowers'];
const VEGETATION_FIELDS = ['species', 'mix', 'seed', 'height', 'leaves', 'season', 'cullDistance', 'distanceScale', 'scatter'];
const SCATTER_FIELDS = ['ground', 'density', 'slopeLimit', 'area', 'exclude', 'variants', 'scale'];
const EXCLUSION_FIELDS = ['center', 'radius', 'min', 'max', 'node'];
const GROUND_EDGE_MARGIN = 0.5;
const SEASON_TARGETS = Object.freeze([[0.35, [196, 150, 40]], [0.6, [186, 84, 26]], [0.85, [112, 66, 34]]]);
const GRASS_CARD_COLOR = [80, 128, 40];
const BARE_SEASON = 0.9;
const DECIDUOUS_SPECIES = new Set(['broadleaf', 'birch', 'bush']);
function knownKeys(value, allowed, path) {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
throw invalidField(path, value, 'an object, such as {}', TypeError);
}
for (const key of Object.keys(value)) {
if (!allowed.includes(key)) throw invalidField(`${path}.${key}`, value[key], `no such field; use one of ${allowed.join(', ')}`, TypeError);
}
}
function numberWithin(value, minimum, maximum, path) {
if (!Number.isFinite(value) || value < minimum || value > maximum) {
throw invalidField(path, value, `a number from ${minimum} to ${maximum}, such as ${Math.min(Math.max(1, minimum), maximum)}`);
}
return value;
}
function planePoint(value, path) {
if (!Array.isArray(value) || value.length !== 2 || value.some(component => !Number.isFinite(component))) {
throw invalidField(path, value, '[x, z] in metres, such as [0, 0]', TypeError);
}
return [...value];
}
function normalizeExclusion(value, path) {
knownKeys(value, EXCLUSION_FIELDS, path);
if (value.min !== undefined || value.max !== undefined) {
if (value.center !== undefined || value.radius !== undefined || value.node !== undefined) {
throw invalidField(path, value, 'either the box form "min", "max" or the circle form "center", "radius", not both');
}
const min = planePoint(value.min, `${path}.min`);
const max = planePoint(value.max, `${path}.max`);
if (max[0] <= min[0] || max[1] <= min[1]) throw invalidField(`${path}.max`, max, `[x, z] above min ${JSON.stringify(min)} on both axes`);
return { min, max };
}
const radius = numberWithin(value.radius, 0.01, 2000, `${path}.radius`);
if (value.node !== undefined) {
if (typeof value.node !== 'string' || !value.node) throw invalidField(`${path}.node`, value.node, 'a node ID, such as "pond"', TypeError);
return { node: value.node, radius };
}
return { center: planePoint(value.center, `${path}.center`), radius };
}
function normalizeScatter(value, path) {
knownKeys(value, SCATTER_FIELDS, path);
if (typeof value.ground !== 'string' || !value.ground) throw invalidField(`${path}.ground`, value.ground, 'the ID of a terrain node, such as "ground"', TypeError);
const result = {
ground: value.ground,
density: numberWithin(value.density ?? 0.012, 0.0001, 4, `${path}.density`),
slopeLimit: numberWithin(value.slopeLimit ?? 32, 0, 90, `${path}.slopeLimit`),
variants: numberWithin(value.variants ?? 3, 1, VEGETATION_LIMITS.maxVariants, `${path}.variants`),
exclude: [],
};
if (!Number.isInteger(result.variants)) throw invalidField(`${path}.variants`, result.variants, `a whole number from 1 to ${VEGETATION_LIMITS.maxVariants}, such as 3`);
if (value.exclude !== undefined) {
if (!Array.isArray(value.exclude) || value.exclude.length > VEGETATION_LIMITS.maxExclusions) {
throw invalidField(`${path}.exclude`, Array.isArray(value.exclude) ? `${value.exclude.length} areas` : value.exclude, `a list of at most ${VEGETATION_LIMITS.maxExclusions} areas, such as [{ "center": [0, 0], "radius": 5 }]`);
}
result.exclude = value.exclude.map((entry, index) => normalizeExclusion(entry, `${path}.exclude[${index}]`));
}
if (value.area !== undefined) {
knownKeys(value.area, ['min', 'max'], `${path}.area`);
result.area = { min: planePoint(value.area.min, `${path}.area.min`), max: planePoint(value.area.max, `${path}.area.max`) };
if (result.area.max[0] <= result.area.min[0] || result.area.max[1] <= result.area.min[1]) {
throw invalidField(`${path}.area.max`, result.area.max, `[x, z] above min ${JSON.stringify(result.area.min)} on both axes`);
}
}
if (value.scale !== undefined) {
if (!Array.isArray(value.scale) || value.scale.length !== 2) throw invalidField(`${path}.scale`, value.scale, '[min, max], such as [0.8, 1.2]', TypeError);
result.scale = [numberWithin(value.scale[0], 0.1, 10, `${path}.scale[0]`), numberWithin(value.scale[1], 0.1, 10, `${path}.scale[1]`)];
if (result.scale[1] < result.scale[0]) throw invalidField(`${path}.scale`, value.scale, '[min, max] with max not below min, such as [0.8, 1.2]');
}
return result;
}
/** Validate environment.wind: strength 0 to 4 (0.3) and direction in degrees (0 toward +x, 90 toward +z). */
export function normalizeWind(value) {
knownKeys(value, ['strength', 'direction'], 'environment.wind');
return {
strength: numberWithin(value.strength ?? 0.3, 0, 4, 'environment.wind.strength'),
direction: numberWithin(value.direction ?? 0, -360, 360, 'environment.wind.direction'),
};
}
// The placed-asset runtime with the vegetation maps added to it, and the report for scene_inspect.
function mergedRuntime(placed, vegetation) {
return {
...placed,
vegetation: vegetation.report,
geometryParts: new Map([...placed.geometryParts, ...vegetation.geometryParts]),
materialOutputs: new Map([...placed.materialOutputs, ...vegetation.materialOutputs]),
partExtras: new Map([...placed.partExtras, ...vegetation.partExtras]),
};
}
/** Validate the `vegetation` field of a node (`node` is the whole node, which must be a group). Returns the canonical form kept in the recipe. */
export function normalizeVegetation(value, node) {
const conflict = node && ['geometry', 'skin', 'asset'].find(field => node[field] !== undefined);
if (conflict) {
throw invalidField(conflict, node[conflict], 'nothing, because a node that grows vegetation is a group; drop geometry, material, skin and asset', TypeError);
}
knownKeys(value, VEGETATION_FIELDS, 'vegetation');
const result = {};
if ((value.species === undefined) === (value.mix === undefined)) {
throw invalidField('vegetation.species', value.species, 'exactly one of species (one tree, such as "broadleaf") or mix (a scatter, such as { "broadleaf": 3, "bush": 1 })', TypeError);
}
if (value.species !== undefined) {
if (!SCATTER_SPECIES.includes(value.species) || (!value.scatter && !SPECIES[value.species])) {
throw invalidField('vegetation.species', value.species, `one of ${(value.scatter ? SCATTER_SPECIES : Object.keys(SPECIES)).join(', ')}`);
}
result.species = value.species;
} else {
if (!value.scatter) throw invalidField('vegetation.scatter', value.scatter, 'a scatter, such as { "ground": "ground" }, because mix needs one; a single tree takes species', TypeError);
if (!value.mix || typeof value.mix !== 'object' || Array.isArray(value.mix)) throw invalidField('vegetation.mix', value.mix, 'an object that maps species to weights, such as { "broadleaf": 3, "bush": 1 }', TypeError);
result.mix = {};
for (const [name, weight] of Object.entries(value.mix)) {
if (!SCATTER_SPECIES.includes(name)) throw invalidField('vegetation.mix', name, `species names among ${SCATTER_SPECIES.join(', ')}`);
result.mix[name] = numberWithin(weight, 0, 100, `vegetation.mix.${name}`);
}
if (!Object.values(result.mix).some(weight => weight > 0)) throw invalidField('vegetation.mix', value.mix, 'at least one positive weight, such as { "broadleaf": 1 }');
}
result.seed = numberWithin(value.seed ?? 1, -2147483648, 2147483647, 'vegetation.seed');
if (value.height !== undefined) result.height = numberWithin(value.height, 0.2, 80, 'vegetation.height');
result.leaves = value.leaves ?? 'cards';
if (result.leaves !== 'cards' && result.leaves !== 'mesh') throw invalidField('vegetation.leaves', result.leaves, '"cards" or "mesh"');
result.season = numberWithin(value.season ?? 0, 0, 1, 'vegetation.season');
if (value.cullDistance !== undefined) result.cullDistance = numberWithin(value.cullDistance, 1, 100_000, 'vegetation.cullDistance');
result.distanceScale = numberWithin(value.distanceScale ?? 1, 0.1, 10, 'vegetation.distanceScale');
if (value.scatter !== undefined) result.scatter = normalizeScatter(value.scatter, 'vegetation.scatter');
return result;
}
/** A leaf colour (0 to 255 sRGB) for a season: summer keeps the species colour, then 0.35 gold, 0.6 orange and 0.85 brown. */
export function seasonLeafColor(base, season) {
const stops = [[0, base], ...SEASON_TARGETS];
if (season >= stops[stops.length - 1][0]) return [...stops[stops.length - 1][1]];
let index = 0;
while (season > stops[index + 1][0]) index++;
const [startSeason, startColor] = stops[index];
const [endSeason, endColor] = stops[index + 1];
const fraction = (season - startSeason) / (endSeason - startSeason);
return startColor.map((channel, axis) => Math.round(channel + (endColor[axis] - channel) * fraction));
}
// Cards recolour their procedural leaf sprite, because a colour factor cannot turn a green leaf orange; mesh leaves and grass blades recolour the material.
function seasonalMaterial(material, variant, species, season) {
if (material.map) {
const preset = SPECIES[species];
const kind = species === 'grass' ? 'grass' : material === variant.materials.crown ? 'clump' : preset.leaf.texture;
const base = species === 'grass' ? GRASS_CARD_COLOR : preset.leaf.color;
return { ...material, map: leafTextureDescriptor(kind, seasonLeafColor(base, season)) };
}
const base = material.color.map(channel => channel ** (1 / 2.2) * 255);
return { ...material, color: seasonLeafColor(base, season).map(channel => (channel / 255) ** 2.2) };
}
function nodeWorldMatrix(nodes, node) {
const byId = new Map(nodes.map(candidate => [candidate.id, candidate]));
let matrix = mat4.fromRotationTranslationScale(mat4.create(), node.rotation, node.translation, node.scale);
let parent = node.parent === null ? null : byId.get(node.parent);
for (let depth = 0; parent && depth < 256; depth++) {
const local = mat4.fromRotationTranslationScale(mat4.create(), parent.rotation, parent.translation, parent.scale);
matrix = mat4.multiply(mat4.create(), local, matrix);
parent = parent.parent === null ? null : byId.get(parent.parent);
}
return matrix;
}
function groundTerrain(recipe, scatter) {
const ground = recipe.nodes.find(node => node.id === scatter.ground);
const definition = ground && recipe.geometries.find(geometry => geometry.id === ground.geometry);
if (definition?.type !== 'terrain') {
throw invalidField('vegetation.scatter.ground', scatter.ground, 'the ID of a node that draws a terrain geometry, such as "ground"; give the group node the same transform as the ground');
}
return { definition, terrain: createRecipeTerrain(definition) };
}
function scatterArea(scatter, definition) {
const half = (definition.size ?? 40) / 2 - GROUND_EDGE_MARGIN;
const area = scatter.area ?? { min: [-half, -half], max: [half, half] };
const clamped = {
minX: Math.max(area.min[0], -half), maxX: Math.min(area.max[0], half),
minZ: Math.max(area.min[1], -half), maxZ: Math.min(area.max[1], half),
};
if (clamped.maxX <= clamped.minX || clamped.maxZ <= clamped.minZ) {
throw invalidField(scatter.area ? 'vegetation.scatter.area' : 'vegetation.scatter.ground', scatter.area ?? scatter.ground, `an area that overlaps the ground, which spans ${-half} to ${half} on x and z`);
}
return clamped;
}
// The [x, z] of a node in the ground's own space, which is where the scatter area and exclusions are measured.
function planePositionInGround(recipe, scatter, nodeId) {
const target = recipe.nodes.find(node => node.id === nodeId);
const ground = recipe.nodes.find(node => node.id === scatter.ground);
const inGround = mat4.multiply(mat4.create(), mat4.invert(mat4.create(), nodeWorldMatrix(recipe.nodes, ground)), nodeWorldMatrix(recipe.nodes, target));
return [inGround[12], inGround[14]];
}
function exclusionTest(recipe, scatter, terrain) {
const areas = scatter.exclude.map((entry, index) => {
if (entry.min) return (x, z) => x >= entry.min[0] && x <= entry.max[0] && z >= entry.min[1] && z <= entry.max[1];
let center = entry.center;
if (entry.node) {
const target = recipe.nodes.find(node => node.id === entry.node);
if (!target) throw invalidField(`vegetation.scatter.exclude[${index}].node`, entry.node, 'the ID of a node in the recipe, such as "pond"');
center = planePositionInGround(recipe, scatter, entry.node);
}
return (x, z) => Math.hypot(x - center[0], z - center[1]) <= entry.radius;
});
return (x, z) => terrain.isHole(x, z) || areas.some(test => test(x, z));
}
/** The options `scatterVegetation` gets for a scatter node: the same call an addon user makes, so both give the same instances. */
export function scatterOptionsFor(recipe, vegetation) {
const { scatter } = vegetation;
const { definition, terrain } = groundTerrain(recipe, scatter);
const area = scatterArea(scatter, definition);
const candidates = (area.maxX - area.minX) * (area.maxZ - area.minZ) * scatter.density;
if (candidates > VEGETATION_LIMITS.maxCandidates) {
throw invalidField('vegetation.scatter.density', scatter.density, `a density that tries at most ${VEGETATION_LIMITS.maxCandidates} trees over the area (this tries about ${Math.round(candidates)}); lower it or give a smaller area`);
}
return {
area, density: scatter.density, terrainHeight: terrain.heightAt, slopeLimit: scatter.slopeLimit,
exclusion: exclusionTest(recipe, scatter, terrain), seed: vegetation.seed, mix: vegetation.mix ?? { [vegetation.species]: 1 },
variants: scatter.variants, leaves: vegetation.leaves, ...(scatter.scale ? { scale: scatter.scale } : {}),
};
}
function grow(recipe, vegetation) {
if (!vegetation.scatter) {
const tree = createTree({ species: vegetation.species, leaves: vegetation.leaves, ...(vegetation.height ? { height: vegetation.height } : {}) }, vegetation.seed);
return { variants: [tree], instances: [{ variant: tree, matrix: mat4.create(), species: vegetation.species }] };
}
const scattered = scatterVegetation(scatterOptionsFor(recipe, vegetation));
if (scattered.instances.length > VEGETATION_LIMITS.maxInstances) {
throw invalidField('vegetation.scatter.density', vegetation.scatter.density, `a density that places at most ${VEGETATION_LIMITS.maxInstances} instances (this placed ${scattered.instances.length}); lower it or give a smaller area`);
}
return { variants: Object.values(scattered.variants).flat(), instances: scattered.instances };
}
// Where a named exclusion stands in the ground's space, or null while the node or the ground is missing (growing reports that).
function namedPlanePosition(recipe, scatter, nodeId) {
const hasNode = id => recipe.nodes.some(node => node.id === id);
return hasNode(nodeId) && hasNode(scatter.ground) ? planePositionInGround(recipe, scatter, nodeId) : null;
}
function cacheKey(recipe, node) {
const { vegetation } = node;
const ground = vegetation.scatter ? recipe.geometries.find(geometry => geometry.id === recipe.nodes.find(candidate => candidate.id === vegetation.scatter.ground)?.geometry) : null;
const named = vegetation.scatter?.exclude.filter(entry => entry.node).map(entry => namedPlanePosition(recipe, vegetation.scatter, entry.node));
const { season, cullDistance, distanceScale, ...growth } = vegetation;
return JSON.stringify([growth, ground, named]);
}
function materialJson(material) {
return {
tag: material.tag ?? 'surface', color: [...material.color], metallic: material.metallic ?? 0, roughness: material.roughness ?? 0.5,
emission: material.emission ?? 0, opacity: 1, alphaMode: material.alphaMode ?? 'opaque',
doubleSided: Boolean(material.doubleSided),
};
}
/**
* Generate the geometries, materials and part nodes of every vegetation node into a normalized recipe, in place.
* `cache` (the scene's asset output map) holds grown trees across edits, so a camera or season edit does not grow them again.
* Returns the runtime maps the scene merges with the placed-asset ones, and a report for scene_inspect.
*/
export function expandVegetation(recipe, limits, cache, placedRuntime) {
cache.serial ??= 0;
const planted = recipe.nodes.filter(node => node.vegetation);
const runtime = { geometryParts: new Map(), materialOutputs: new Map(), partExtras: new Map(), report: [] };
const generatedNodes = [];
const geometryIds = new Set();
const eye = recipe.camera?.eye ?? [0, 0, 0];
for (const node of planted) {
const { vegetation } = node;
const key = `vegetation:${cacheKey(recipe, node)}`;
if (!cache.has(key)) {
// The scene shares this map with its placed assets, so only grown sets are evicted.
const grownKeys = [...cache.keys()].filter(candidate => candidate.startsWith('vegetation:'));
if (grownKeys.length >= VEGETATION_LIMITS.maxCachedSets) cache.delete(grownKeys[0]);
cache.set(key, { serial: ++cache.serial, grown: grow(recipe, vegetation), outputs: new Map() });
}
const entry = cache.get(key);
const bare = vegetation.season >= BARE_SEASON;
const world = nodeWorldMatrix(recipe.nodes, node);
const variantIds = new Map(entry.grown.variants.map((variant, index) => [variant, index]));
const materialIds = new Map();
const bySpecies = {};
let triangles = 0;
let culled = 0;
entry.grown.instances.forEach((instance, instanceIndex) => {
const position = [instance.matrix[12], instance.matrix[13], instance.matrix[14]];
const worldPosition = [
world[0] * position[0] + world[4] * position[1] + world[8] * position[2] + world[12],
world[1] * position[0] + world[5] * position[1] + world[9] * position[2] + world[13],
world[2] * position[0] + world[6] * position[1] + world[10] * position[2] + world[14],
];
const distance = Math.hypot(eye[0] - worldPosition[0], eye[1] - worldPosition[1], eye[2] - worldPosition[2]);
const level = levelForDistance(distance, instance.variant, { distanceScale: vegetation.distanceScale, cullDistance: vegetation.cullDistance });
const counts = bySpecies[instance.species] ??= { instances: 0, levels: [] };
counts.instances++;
if (level < 0) {
culled++;
return;
}
counts.levels[level] = (counts.levels[level] ?? 0) + 1;
const leafless = bare && DECIDUOUS_SPECIES.has(instance.species);
const seasonal = DECIDUOUS_SPECIES.has(instance.species) || instance.species === 'grass';
instance.variant.levels[level].parts.forEach((part, partIndex) => {
if (leafless && part.tintable) return;
const geometryId = `vegetation:${entry.serial}:${variantIds.get(instance.variant)}:${level}:${partIndex}`;
if (!geometryIds.has(geometryId)) {
geometryIds.add(geometryId);
recipe.geometries.push({ id: geometryId, type: 'asset', vegetation: entry.serial });
runtime.geometryParts.set(geometryId, part.geometry);
}
const tinted = part.tintable && seasonal && vegetation.season > 0;
if (!materialIds.has(part.material)) materialIds.set(part.material, materialIds.size);
const materialId = `vegetation:${entry.serial}:${variantIds.get(instance.variant)}:${materialIds.get(part.material)}:${tinted ? `s${vegetation.season}` : 'plain'}`;
if (!runtime.materialOutputs.has(materialId)) {
if (!entry.outputs.has(materialId)) {
entry.outputs.set(materialId, Object.freeze(tinted ? seasonalMaterial(part.material, instance.variant, instance.species, vegetation.season) : { ...part.material }));
}
runtime.materialOutputs.set(materialId, entry.outputs.get(materialId));
recipe.materials.push({ id: materialId, ...materialJson(entry.outputs.get(materialId)), assetSource: true });
}
const partNodeId = `${node.id}/${instanceIndex}/${part.role}`;
generatedNodes.push({
id: partNodeId, parent: node.id, label: `${instance.species} ${part.role}`,
translation: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1],
geometry: geometryId, material: materialId, assetPart: { placement: node.id, index: instanceIndex, matrix: Array.from(instance.matrix) },
});
// `group` makes the growing node, not each generated part, the node that per-node lines and object IDs name.
runtime.partExtras.set(partNodeId, { group: node.id, ...(part.shadowLods ? { shadowLods: part.shadowLods } : {}) });
triangles += part.geometry.indices.length / 3;
});
});
runtime.report.push({
node: node.id, mode: vegetation.scatter ? 'scatter' : 'tree', instances: entry.grown.instances.length, culled,
season: vegetation.season, bare, triangles,
species: Object.fromEntries(Object.entries(bySpecies).map(([name, counts]) => [name, { instances: counts.instances, levels: Array.from(counts.levels, count => count ?? 0) }])),
});
}
if (recipe.nodes.length + generatedNodes.length > limits.maxNodes) {
throw invalidField('vegetation.scatter.density', `${generatedNodes.length} generated part nodes`, `a density that keeps authored plus generated nodes (${recipe.nodes.length} authored) within maxNodes ${limits.maxNodes}; lower it or cull far trees with cullDistance`);
}
recipe.nodes.push(...generatedNodes);
return mergedRuntime(placedRuntime, runtime);
}