Skip to content

3D engine that AI agents drive

39.6 KB
Raw Blame
import { mat3, mat4 } from 'gl-matrix';
import { HAIR_LIMITS, buildHairMesh, createStrandRoots } from './hair.js';
import { normalizeForceFields } from './force-fields.js';
import { PARTICLE_LIMITS, buildParticleMesh, createParticleLaunches } from './particles.js';
import { createCollisionSurface } from './particle-collision.js';
import { SPARK_DEFAULTS, SPARK_LIMITS, SPARK_VERTICES, buildSparkMesh } from './particle-sparks.js';
import { EMITTER_MESH_MODES, createMeshSource } from './particle-emitter-mesh.js';
import { invalidField } from './field-error.js';
import { bakingContext, boundedArray, finiteNumber, knownKeys, rootNodeWithGeometry, vectorOfThree } from './agent-recipe-checks.js';

const PARTICLES_FIELDS = ['gravity', 'wind', 'fields', 'systems'];
const SYSTEM_TYPES = ['emitter', 'hair', 'sparks'];
const EMITTER_SYSTEM_FIELDS = ['type', 'node', 'seed', 'count', 'rate', 'delay', 'start', 'stop', 'lifetime', 'speed', 'direction', 'spread', 'emitter', 'size', 'scale', 'drag', 'floor', 'bounce', 'friction', 'colliders', 'spin', 'color', 'alpha', 'instances', 'orient'];
const SPARK_SYSTEM_FIELDS = ['type', 'preset', 'node', 'seed', 'count', 'delay', 'lifetime', 'speed', 'direction', 'spread', 'emitter', 'position', 'size', 'drag', 'floor', 'bounce', 'temperature', 'intensity', 'shutter'];
const SPARK_PRESETS = Object.freeze({
  // A blast: a few hundred sparks thrown in every direction from a small ball, fast, light enough for drag to pull them in, living 0.5 to 2 s.
  explosion: Object.freeze({ count: 800, speed: [6, 24], spread: 180, lifetime: [0.5, 2], size: [0.006, 0.014], drag: 0.9, emitter: Object.freeze({ shape: 'sphere', radius: 0.2 }) }),
});
const HAIR_FIELDS = ['type', 'node', 'surface', 'seed', 'count', 'length', 'segments', 'width', 'droop', 'lean', 'sway', 'swayRate'];
const EMITTER_FIELDS = ['shape', 'position', 'halfExtents', 'radius', 'mesh', 'from', 'group', 'sharpAngle', 'normalSpeed', 'velocityFrom', 'velocityScale', 'groupThreshold'];
const EMITTER_SHAPES = ['point', 'box', 'sphere', 'disc', 'mesh'];
const ORIENT_MODES = ['none', 'random', 'normal'];
const SCALE_MODES = ['constant', 'shrink', 'grow'];
const DEFAULT_GRAVITY = Object.freeze([0, -9.81, 0]);
// Defaults that read as debris: a bounce keeps 30 percent of the speed (the first release of collision stuck at 0 without colliders and had no default with them), friction 0.5.
const DEBRIS_BOUNCE = 0.3;
const DEBRIS_FRICTION = 0.5;
const POSITION_LIMIT = 10000;
const MAX_SEED = 0xffffffff;

// A number stands for the range [value, value].
function rangeOf(value, path, minimum, maximum) {
  if (typeof value === 'number') {
    return [finiteNumber(value, path, minimum, maximum), value];
  }
  if (!Array.isArray(value) || value.length !== 2) {
    throw invalidField(path, value, `a number or [minimum, maximum] from ${minimum} to ${maximum}, such as [${Math.max(minimum, 0.5)}, ${Math.min(maximum, 1)}]`, TypeError);
  }
  const range = value.map((entry, index) => finiteNumber(entry, `${path}[${index}]`, minimum, maximum));
  if (range[0] > range[1]) {
    throw invalidField(path, value, `[minimum, maximum] with the minimum not above the maximum, such as [${range[1]}, ${range[0]}]`);
  }
  return range;
}

function normalizeMeshEmitter(input, emitter, context, path) {
  rootNodeWithGeometry(input.mesh, context.recipeNodes, new Set(), context.motionNodeIds, context.physicsNodeIds, `${path}.mesh`, 'particles');
  const from = input.from ?? 'surface';
  if (!EMITTER_MESH_MODES.includes(from)) {
    throw invalidField(`${path}.from`, from, `one of ${EMITTER_MESH_MODES.join(', ')}`);
  }
  emitter.mesh = input.mesh;
  emitter.from = from;
  if (input.group !== undefined) {
    if (typeof input.group !== 'string' || !input.group) {
      throw invalidField(`${path}.group`, input.group, 'the name of a vertex group on the emitter mesh, such as "edge"');
    }
    if (from === 'volume') {
      throw invalidField(`${path}.group`, input.group, `left out, because a vertex group weighs ${path}.from "surface", "vertices" or "edges", not "volume"`);
    }
    emitter.group = input.group;
  }
  if (input.sharpAngle !== undefined) {
    if (from !== 'edges') {
      throw invalidField(`${path}.sharpAngle`, input.sharpAngle, `left out unless ${path}.from is "edges"`);
    }
    emitter.sharpAngle = finiteNumber(input.sharpAngle, `${path}.sharpAngle`, 0, 180);
  }
  if (input.normalSpeed !== undefined) {
    emitter.normalSpeed = finiteNumber(input.normalSpeed, `${path}.normalSpeed`, -1000, 1000);
  }
  if (input.groupThreshold !== undefined) {
    if (!emitter.group) {
      throw invalidField(`${path}.groupThreshold`, input.groupThreshold, `left out unless ${path}.group names a vertex group, such as "spray"`);
    }
    emitter.groupThreshold = finiteNumber(input.groupThreshold, `${path}.groupThreshold`, 0, 1);
  }
  normalizeVelocitySource(input, emitter, from, path);
}

// `velocityFrom` names a "vector:<name>" point attribute of the emitter mesh (the ocean's `spray`): each particle also leaves with that velocity.
function normalizeVelocitySource(input, emitter, from, path) {
  if (input.velocityFrom === undefined) {
    if (input.velocityScale !== undefined) {
      throw invalidField(`${path}.velocityScale`, input.velocityScale, `left out unless ${path}.velocityFrom names a vector, such as "spray"`);
    }
    return;
  }
  if (typeof input.velocityFrom !== 'string' || !input.velocityFrom) {
    throw invalidField(`${path}.velocityFrom`, input.velocityFrom, 'the name of a vector on the emitter mesh, such as "spray" (an ocean edit with spray: true writes it)');
  }
  if (from !== 'surface' && from !== 'vertices') {
    throw invalidField(`${path}.velocityFrom`, input.velocityFrom, `left out, because a vector has a value at vertices and across faces, so ${path}.from is "surface" or "vertices", not "${from}"`);
  }
  emitter.velocityFrom = input.velocityFrom;
  emitter.velocityScale = input.velocityScale === undefined ? 1 : finiteNumber(input.velocityScale, `${path}.velocityScale`, -1000, 1000);
}

const DEFAULT_EMITTER_RADIUS = 0.5;

// Only a sphere and a disc are sized by a radius, so only they get the default. A box takes its size from halfExtents and
// rejects a radius, except the 0.5 earlier versions wrote into every box they stored: that one is dropped so the recipe still loads.
function assignEmitterRadius(input, emitter, shape, path) {
  if (shape === 'box') {
    if (input.radius !== undefined && input.radius !== DEFAULT_EMITTER_RADIUS) {
      throw invalidField(`${path}.radius`, input.radius, `left out on a box, sized by ${path}.halfExtents`);
    }
    return;
  }
  if (input.radius !== undefined) {
    emitter.radius = finiteNumber(input.radius, `${path}.radius`, 0, POSITION_LIMIT);
  } else if (shape === 'sphere' || shape === 'disc') {
    emitter.radius = DEFAULT_EMITTER_RADIUS;
  }
}

function normalizeEmitter(input, context, path) {
  knownKeys(input, EMITTER_FIELDS, path);
  const shape = input.shape ?? 'point';
  if (!EMITTER_SHAPES.includes(shape)) {
    throw invalidField(`${path}.shape`, shape, `one of ${EMITTER_SHAPES.join(', ')}`);
  }
  const emitter = {
    shape,
    position: input.position === undefined ? [0, 0, 0] : vectorOfThree(input.position, `${path}.position`, POSITION_LIMIT),
    halfExtents: input.halfExtents === undefined ? [0.5, 0.5, 0.5] : vectorOfThree(input.halfExtents, `${path}.halfExtents`, POSITION_LIMIT).map(Math.abs),
  };
  assignEmitterRadius(input, emitter, shape, path);
  if (shape === 'mesh') {
    normalizeMeshEmitter(input, emitter, context, path);
  } else {
    for (const field of ['mesh', 'from', 'group', 'sharpAngle', 'normalSpeed', 'velocityFrom', 'velocityScale', 'groupThreshold']) {
      if (input[field] !== undefined) throw invalidField(`${path}.${field}`, input[field], `left out unless ${path}.shape is "mesh"`);
    }
  }
  return emitter;
}

function normalizeInstances(input, system, context, path) {
  if (input.instances !== undefined) {
    const nodeIds = boundedArray(input.instances, PARTICLE_LIMITS.maxInstances, `${path}.instances`);
    if (!nodeIds.length) {
      throw invalidField(`${path}.instances`, nodeIds, 'at least one node ID, such as ["leaf"]; leave it out to repeat the system node');
    }
    // Instance nodes are only read, so several systems may share one.
    nodeIds.forEach((nodeId, index) => {
      rootNodeWithGeometry(nodeId, context.recipeNodes, new Set(), context.motionNodeIds, context.physicsNodeIds, `${path}.instances[${index}]`, 'particles');
    });
    system.instances = nodeIds;
  }
  const orient = input.orient ?? 'none';
  if (!ORIENT_MODES.includes(orient)) {
    throw invalidField(`${path}.orient`, orient, `one of ${ORIENT_MODES.join(', ')}`);
  }
  const source = system.emitter;
  if (orient === 'normal' && (source.shape !== 'mesh' || source.from === 'volume')) {
    throw invalidField(`${path}.orient`, orient, `"none" or "random", because a normal needs ${path}.emitter.shape "mesh" with from "surface", "vertices" or "edges"`);
  }
  if (source.normalSpeed && source.from === 'volume') {
    throw invalidField(`${path}.emitter.normalSpeed`, source.normalSpeed, 'left out when from is "volume", which has no surface normal');
  }
  if (orient !== 'none') system.orient = orient;
}

function normalizeCount(input, path) {
  const count = input.count ?? 100;
  if (!Number.isInteger(count) || count < 1 || count > PARTICLE_LIMITS.maxParticlesPerSystem) {
    throw invalidField(`${path}.count`, count, `a whole number from 1 to ${PARTICLE_LIMITS.maxParticlesPerSystem}, such as 100`);
  }
  return count;
}

function normalizeSeed(input, path) {
  const seed = input.seed ?? 1;
  if (!Number.isInteger(seed) || seed < 0 || seed > MAX_SEED) {
    throw invalidField(`${path}.seed`, seed, `a whole number from 0 to ${MAX_SEED}, such as 1`);
  }
  return seed;
}

function normalizeColors(value, path) {
  if (!Array.isArray(value) || value.length !== 2) {
    throw invalidField(path, value, '[start, end], each [r, g, b] from 0 to 1, such as [[1, 0.6, 0.1], [0.3, 0, 0]]', TypeError);
  }
  return value.map((color, index) => vectorOfThree(color, `${path}[${index}]`, 1000).map((channel, channelIndex) => finiteNumber(channel, `${path}[${index}][${channelIndex}]`, 0, 1000)));
}

// [start, end] over the life, in either direction; a number holds one value.
function normalizeAlpha(value, path) {
  if (typeof value === 'number') {
    return [finiteNumber(value, path, 0, 1), value];
  }
  if (!Array.isArray(value) || value.length !== 2) {
    throw invalidField(path, value, 'a number or [start, end] from 0 to 1, such as [1, 0]', TypeError);
  }
  return value.map((entry, index) => finiteNumber(entry, `${path}[${index}]`, 0, 1));
}

function normalizeColliders(value, context, path) {
  const nodeIds = boundedArray(value, PARTICLE_LIMITS.maxColliders, path);
  // Colliders are only read, so several systems may share one.
  nodeIds.forEach((nodeId, index) => {
    rootNodeWithGeometry(nodeId, context.recipeNodes, new Set(), context.motionNodeIds, context.physicsNodeIds, `${path}[${index}]`, 'particles');
  });
  return nodeIds;
}

function normalizeEmitterSystem(input, context, path) {
  knownKeys(input, EMITTER_SYSTEM_FIELDS, path);
  rootNodeWithGeometry(input.node, context.recipeNodes, context.claimedNodes, context.motionNodeIds, context.physicsNodeIds, `${path}.node`, 'particles');
  const system = {
    type: 'emitter', node: input.node, seed: normalizeSeed(input, path), count: normalizeCount(input, path),
    lifetime: rangeOf(input.lifetime ?? 1, `${path}.lifetime`, 0.01, PARTICLE_LIMITS.maxLifetime),
    speed: rangeOf(input.speed ?? 1, `${path}.speed`, 0, 1000),
    size: rangeOf(input.size ?? 0.05, `${path}.size`, 0.0001, 100),
    direction: input.direction === undefined ? [0, 1, 0] : vectorOfThree(input.direction, `${path}.direction`, 1000),
    spread: input.spread === undefined ? 30 : finiteNumber(input.spread, `${path}.spread`, 0, 180),
    emitter: normalizeEmitter(input.emitter ?? {}, context, `${path}.emitter`),
    scale: input.scale ?? 'constant',
    drag: input.drag === undefined ? 0 : finiteNumber(input.drag, `${path}.drag`, 0, 100),
  };
  if (Math.hypot(...system.direction) === 0) {
    throw invalidField(`${path}.direction`, system.direction, 'a direction that is not the zero vector, such as [0, 1, 0]');
  }
  if (!SCALE_MODES.includes(system.scale)) {
    throw invalidField(`${path}.scale`, system.scale, `one of ${SCALE_MODES.join(', ')}`);
  }
  if (input.rate !== undefined) system.rate = finiteNumber(input.rate, `${path}.rate`, 0.01, PARTICLE_LIMITS.maxParticlesPerSystem * 100);
  applyEmissionWindow(input, system, path);
  if (input.bounce !== undefined) system.bounce = finiteNumber(input.bounce, `${path}.bounce`, 0, 1);
  if (input.friction !== undefined) system.friction = finiteNumber(input.friction, `${path}.friction`, 0, 1);
  if (input.spin !== undefined) system.spin = rangeOf(input.spin, `${path}.spin`, -100000, 100000);
  if (input.color !== undefined) system.color = normalizeColors(input.color, `${path}.color`);
  if (input.alpha !== undefined) system.alpha = normalizeAlpha(input.alpha, `${path}.alpha`);
  if (input.colliders !== undefined) {
    system.colliders = normalizeColliders(input.colliders, context, `${path}.colliders`);
    if (system.colliders.includes(system.node)) {
      throw invalidField(`${path}.colliders`, system.colliders, `node IDs other than the system's own node "${system.node}"`);
    }
  }
  normalizeInstances(input, system, context, path);
  if (input.floor !== undefined) system.floor = finiteNumber(input.floor, `${path}.floor`, -POSITION_LIMIT, POSITION_LIMIT);
  return system;
}

function normalizeSparkTemperature(value, path) {
  const example = '[start, end] kelvin, such as [2500, 800]';
  if (!Array.isArray(value) || value.length !== 2) throw invalidField(path, value, example, TypeError);
  const [start, end] = value.map((entry, index) => finiteNumber(entry, `${path}[${index}]`, SPARK_LIMITS.minKelvin, SPARK_LIMITS.maxKelvin));
  if (end > start) throw invalidField(path, value, `a spark that cools, with the start at or above the end, such as [${end}, ${start}]`);
  return [start, end];
}

// The material must be unlit: an unlit surface outputs colour times vertex colour, and the vertex colour is the spark's blackbody radiance.
function checkSparkMaterial(system, recipe, path) {
  const node = recipe.nodes.find(candidate => candidate.id === system.node);
  const material = recipe.materials?.find(candidate => candidate.id === node.material);
  if (material && material.tag !== 'unlit') {
    throw invalidField(`${path}.node`, `${system.node} (material "${material.id}" has tag "${material.tag}")`, 'a node with an unlit material of colour [1, 1, 1] (tag "unlit"), whose colour times vertex colour carries the spark radiance');
  }
}

function sparkEmitterInput(input, preset, path) {
  const emitterInput = { ...(preset?.emitter ?? { shape: 'point' }), ...input.emitter };
  if (input.position !== undefined) {
    if (input.emitter?.position !== undefined) {
      throw invalidField(`${path}.position`, input.position, `left out when ${path}.emitter.position is set; give the blast point once`);
    }
    emitterInput.position = input.position;
  }
  return emitterInput;
}

function normalizeSparkSystem(input, context, path, recipe) {
  knownKeys(input, SPARK_SYSTEM_FIELDS, path);
  const presetName = input.preset;
  if (presetName !== undefined && !SPARK_PRESETS[presetName]) {
    throw invalidField(`${path}.preset`, presetName, `one of ${Object.keys(SPARK_PRESETS).join(', ')}, or left out`);
  }
  const preset = SPARK_PRESETS[presetName];
  rootNodeWithGeometry(input.node, context.recipeNodes, context.claimedNodes, context.motionNodeIds, context.physicsNodeIds, `${path}.node`, 'particles');
  const count = input.count ?? preset?.count ?? 200;
  if (!Number.isInteger(count) || count < 1 || count > SPARK_LIMITS.maxCount) {
    throw invalidField(`${path}.count`, count, `a whole number from 1 to ${SPARK_LIMITS.maxCount}, such as 800`);
  }
  const emitter = normalizeEmitter(sparkEmitterInput(input, preset, path), context, `${path}.emitter`);
  const system = {
    type: 'sparks', node: input.node, seed: normalizeSeed(input, path), count,
    lifetime: rangeOf(input.lifetime ?? preset?.lifetime ?? [0.5, 2], `${path}.lifetime`, SPARK_LIMITS.minLifetime, SPARK_LIMITS.maxLifetime),
    speed: rangeOf(input.speed ?? preset?.speed ?? [4, 12], `${path}.speed`, 0, SPARK_LIMITS.maxSpeed),
    size: rangeOf(input.size ?? preset?.size ?? 0.01, `${path}.size`, SPARK_LIMITS.minRadius, SPARK_LIMITS.maxRadius),
    direction: input.direction === undefined ? [0, 1, 0] : vectorOfThree(input.direction, `${path}.direction`, 1000),
    spread: finiteNumber(input.spread ?? preset?.spread ?? 180, `${path}.spread`, 0, 180),
    emitter,
    drag: finiteNumber(input.drag ?? preset?.drag ?? 0.5, `${path}.drag`, 0, 100),
    temperature: normalizeSparkTemperature(input.temperature ?? SPARK_DEFAULTS.temperature, `${path}.temperature`),
    intensity: finiteNumber(input.intensity ?? SPARK_DEFAULTS.intensity, `${path}.intensity`, 0, SPARK_LIMITS.maxIntensity),
    shutter: finiteNumber(input.shutter ?? SPARK_DEFAULTS.shutter, `${path}.shutter`, 0, SPARK_LIMITS.maxShutter),
  };
  if (Math.hypot(...system.direction) === 0) {
    throw invalidField(`${path}.direction`, system.direction, 'a direction that is not the zero vector, such as [0, 1, 0]');
  }
  if (input.floor !== undefined) system.floor = finiteNumber(input.floor, `${path}.floor`, -POSITION_LIMIT, POSITION_LIMIT);
  if (input.bounce !== undefined) system.bounce = finiteNumber(input.bounce, `${path}.bounce`, 0, 1);
  if (input.delay !== undefined) system.delay = finiteNumber(input.delay, `${path}.delay`, 0, 3600);
  checkSparkMaterial(system, recipe, path);
  return system;
}

function normalizeHairSystem(input, context, path) {
  knownKeys(input, HAIR_FIELDS, path);
  rootNodeWithGeometry(input.node, context.recipeNodes, context.claimedNodes, context.motionNodeIds, context.physicsNodeIds, `${path}.node`, 'particles');
  // The surface is only read, so several systems may grow from one node.
  rootNodeWithGeometry(input.surface, context.recipeNodes, new Set(), context.motionNodeIds, context.physicsNodeIds, `${path}.surface`, 'particles');
  if (input.surface === input.node) {
    throw invalidField(`${path}.surface`, input.surface, 'a node other than the hair node, such as the head mesh');
  }
  const segments = input.segments ?? 4;
  if (!Number.isInteger(segments) || segments < 1 || segments > HAIR_LIMITS.maxSegments) {
    throw invalidField(`${path}.segments`, segments, `a whole number from 1 to ${HAIR_LIMITS.maxSegments}, such as 4`);
  }
  const system = {
    type: 'hair', node: input.node, surface: input.surface, seed: normalizeSeed(input, path), count: normalizeCount(input, path), segments,
    length: rangeOf(input.length ?? 0.1, `${path}.length`, 0.001, 100),
    width: finiteNumber(input.width ?? 0.004, `${path}.width`, 0.0001, 10),
    droop: finiteNumber(input.droop ?? 0.5, `${path}.droop`, 0, 10),
    lean: finiteNumber(input.lean ?? 0.2, `${path}.lean`, 0, 2),
  };
  if (input.sway === undefined && input.swayRate !== undefined) {
    throw invalidField(`${path}.swayRate`, input.swayRate, `left out unless ${path}.sway is set`);
  }
  if (input.sway !== undefined) {
    system.sway = finiteNumber(input.sway, `${path}.sway`, 0, 10);
    system.swayRate = finiteNumber(input.swayRate ?? 0.5, `${path}.swayRate`, 0.01, 20);
  }
  return system;
}

function normalizeSystem(input, context, path, recipe) {
  const type = input?.type ?? 'emitter';
  if (!SYSTEM_TYPES.includes(type)) {
    throw invalidField(`${path}.type`, type, `one of ${SYSTEM_TYPES.join(', ')}`);
  }
  if (type === 'sparks') return normalizeSparkSystem(input, context, path, recipe);
  return type === 'hair' ? normalizeHairSystem(input, context, path) : normalizeEmitterSystem(input, context, path);
}

/** Validate a recipe particles section against its nodes. Returns the plain, bounded form stored in the recipe. */
export function normalizeAgentParticles(input, recipe) {
  if (input === null || input === undefined) {
    return null;
  }
  knownKeys(input, PARTICLES_FIELDS, 'particles');
  const context = bakingContext(recipe, ['cloth']);
  const result = {};
  result.systems = boundedArray(input.systems, PARTICLE_LIMITS.maxSystems, 'particles.systems').map((system, index) => normalizeSystem(system, context, `particles.systems[${index}]`, recipe));
  if (!result.systems.length) {
    throw invalidField('particles.systems', result.systems, 'at least one system, such as [{ "node": "sparks" }]; use particles: null to clear it');
  }
  const systemNodes = new Set(result.systems.map(system => system.node));
  for (const system of result.systems) {
    const clash = system.colliders?.find(nodeId => systemNodes.has(nodeId));
    if (clash) {
      throw invalidField('particles.systems', clash, 'colliders that are not particle system nodes, because a system replaces its own geometry with particles');
    }
  }
  const sparkTotal = result.systems.reduce((sum, system) => sum + (system.type === 'sparks' ? system.count : 0), 0);
  if (sparkTotal > SPARK_LIMITS.maxCount) {
    throw invalidField('particles.systems', `${sparkTotal} sparks in total`, `spark counts that add up to at most ${SPARK_LIMITS.maxCount}, such as a lower count in each system`);
  }
  const total = result.systems.reduce((sum, system) => sum + (system.type === 'sparks' ? 0 : system.count), 0);
  if (total > PARTICLE_LIMITS.maxParticles) {
    throw invalidField('particles.systems', `${total} particles in total`, `counts that add up to at most ${PARTICLE_LIMITS.maxParticles}, such as a lower count in each system`);
  }
  if (input.gravity !== undefined) result.gravity = vectorOfThree(input.gravity, 'particles.gravity', 1000);
  if (input.wind !== undefined) result.wind = vectorOfThree(input.wind, 'particles.wind', 100);
  if (input.fields !== undefined) result.fields = normalizeForceFields(input.fields, 'Particle force field');
  return result;
}

function nodeMatrix(node) {
  return mat4.fromRotationTranslationScale(mat4.create(), node.rotation, node.translation, node.scale);
}

// The mesh is built in world space; the part draws it through the node's own matrix, so undo that matrix here.
function worldToNodeLocal(geometry, matrix) {
  const inverse = mat4.invert(mat4.create(), matrix);
  const positions = new Float32Array(geometry.positions.length);
  const normals = new Float32Array(geometry.normals.length);
  for (let offset = 0; offset < positions.length; offset += 3) {
    const x = geometry.positions[offset];
    const y = geometry.positions[offset + 1];
    const z = geometry.positions[offset + 2];
    for (let axis = 0; axis < 3; axis++) {
      positions[offset + axis] = inverse[axis] * x + inverse[4 + axis] * y + inverse[8 + axis] * z + inverse[12 + axis];
      normals[offset + axis] = matrix[axis * 4] * geometry.normals[offset] + matrix[axis * 4 + 1] * geometry.normals[offset + 1] + matrix[axis * 4 + 2] * geometry.normals[offset + 2];
    }
    const length = Math.hypot(normals[offset], normals[offset + 1], normals[offset + 2]) || 1;
    for (let axis = 0; axis < 3; axis++) normals[offset + axis] /= length;
  }
  return Object.freeze({ ...geometry, positions, normals });
}

// `start` is a second name for `delay` (seconds before the first birth); `stop` ends the window, so a system with a `rate`
// emits only inside it.
function applyEmissionWindow(input, system, path) {
  if (input.start !== undefined && input.delay !== undefined) {
    throw invalidField(`${path}.start`, input.start, 'either start or delay, which mean the same thing (seconds before the first birth), not both');
  }
  const startField = input.start === undefined ? 'delay' : 'start';
  const startInput = input.start ?? input.delay;
  if (startInput !== undefined) system.delay = finiteNumber(startInput, `${path}.${startField}`, 0, 3600);
  if (input.stop === undefined) return;
  const stop = finiteNumber(input.stop, `${path}.stop`, 0, 3600);
  const start = system.delay ?? 0;
  if (stop <= start) {
    throw invalidField(`${path}.stop`, input.stop, `a time in seconds after the start (${start}), such as ${start + 2}`);
  }
  system.stop = stop;
}

// Most particles alive at once and the time the last one dies, counted from the launch values alone.
function lifeSummary(launches) {
  const events = [];
  for (let index = 0; index < launches.count; index++) {
    if (launches.birth[index] >= launches.stop) continue;
    events.push([launches.birth[index], 1], [launches.birth[index] + launches.life[index], -1]);
  }
  events.sort((first, second) => first[0] - second[0] || first[1] - second[1]);
  let alive = 0;
  let peak = 0;
  for (const [, change] of events) {
    alive += change;
    peak = Math.max(peak, alive);
  }
  return { maxAlive: peak, endsAt: Number(events.at(-1)[0].toFixed(4)) };
}

function surfaceInWorld(geometry, matrix) {
  const positions = new Float64Array(geometry.positions.length);
  const normals = new Float64Array(geometry.normals.length);
  const normalMatrix = mat3.normalFromMat4(mat3.create(), matrix);
  for (let offset = 0; offset < positions.length; offset += 3) {
    for (let axis = 0; axis < 3; axis++) {
      positions[offset + axis] = matrix[axis] * geometry.positions[offset] + matrix[4 + axis] * geometry.positions[offset + 1] + matrix[8 + axis] * geometry.positions[offset + 2] + matrix[12 + axis];
      normals[offset + axis] = normalMatrix[axis] * geometry.normals[offset] + normalMatrix[3 + axis] * geometry.normals[offset + 1] + normalMatrix[6 + axis] * geometry.normals[offset + 2];
    }
    // A scaled node shrinks or stretches the inverse-transpose normal; callers need unit normals for speeds and orientation.
    const length = Math.hypot(normals[offset], normals[offset + 1], normals[offset + 2]) || 1;
    for (let axis = 0; axis < 3; axis++) normals[offset + axis] /= length;
  }
  return { positions, normals };
}

// What to change when the drawn vertices pass the limit: a default box has a bevel, so each particle is 1176 vertices, not 24.
function bevelledBoxAdvice(nodeId, recipe) {
  const node = recipe.nodes.find(candidate => candidate.id === nodeId);
  const definition = (recipe.geometries ?? []).find(candidate => candidate.id === node?.geometry);
  const base = definition?.type === 'mesh' ? definition.base : definition;
  return base?.type === 'box' && base.bevel !== 0 ? '; the shape is a box with a bevel, so pass "bevel": 0 on it to make it 24 vertices' : '';
}

function checkVertexBudget(verticesPerItem, count, totalVertices, nodeId, recipe) {
  const vertices = verticesPerItem * count;
  if (vertices > PARTICLE_LIMITS.maxVertices || totalVertices > PARTICLE_LIMITS.maxVertices) {
    throw invalidField('particles.systems', `${totalVertices} vertices`, `at most ${PARTICLE_LIMITS.maxVertices} vertices drawn in total; node ${nodeId} draws ${verticesPerItem} vertices per particle times count ${count}, so use a shape with fewer vertices or a lower count${bevelledBoxAdvice(nodeId, recipe)}`);
  }
}

// The geometries a particle can be: the listed instance nodes, or else the system node's own.
function templateNodeIds(system) {
  return system.instances ?? [system.node];
}

function horizontalDirection(wind) {
  const length = Math.hypot(wind[0], wind[2]);
  return length > 1e-6 ? [wind[0] / length, 0, wind[2] / length] : [1, 0, 0];
}

function collisionSurfaceOf(system, nodes, geometries) {
  if (!system.colliders) return undefined;
  const meshes = system.colliders.map(nodeId => {
    const collider = nodes.get(nodeId);
    const geometry = geometries.get(collider.geometry);
    return { positions: surfaceInWorld(geometry, nodeMatrix(collider)).positions, indices: geometry.indices };
  });
  const surface = createCollisionSurface(meshes);
  if (surface.triangleCount > PARTICLE_LIMITS.maxColliderTriangles) {
    throw invalidField('particles.systems', `${surface.triangleCount} collider triangles for node ${system.node}`, `colliders with at most ${PARTICLE_LIMITS.maxColliderTriangles} triangles in total, such as a simpler collider mesh`);
  }
  return surface;
}

// The emitter group's weight per render vertex. A name the mesh lacks is an error that lists the groups it has.
function vertexGroupOf(emitter, geometry, emitterPath) {
  const weights = geometry.vertexGroups?.[emitter.group];
  if (!weights) {
    const known = Object.keys(geometry.vertexGroups ?? {});
    throw invalidField(`${emitterPath}.group`, emitter.group, `a vertex group of node ${emitter.mesh} (known groups: ${known.join(', ') || 'none'}); make one with a vertex_group mesh edit`);
  }
  return weights;
}

// The emitter's vector in world space, scaled by velocityScale. A name the mesh lacks is an error that lists the vectors it has.
function velocityVectorOf(emitter, geometry, matrix, emitterPath) {
  const vectors = geometry.vertexVectors?.[emitter.velocityFrom];
  if (!vectors) {
    const known = Object.keys(geometry.vertexVectors ?? {});
    throw invalidField(`${emitterPath}.velocityFrom`, emitter.velocityFrom, `a vector of node ${emitter.mesh} (known vectors: ${known.join(', ') || 'none'}); an ocean edit with spray: true writes "spray"`);
  }
  const world = new Float64Array(vectors.length);
  for (let offset = 0; offset < vectors.length; offset += 3) {
    for (let axis = 0; axis < 3; axis++) {
      world[offset + axis] = emitter.velocityScale * (matrix[axis] * vectors[offset] + matrix[4 + axis] * vectors[offset + 1] + matrix[8 + axis] * vectors[offset + 2]);
    }
  }
  return world;
}

// A sea whose oceanTime a motion track drives is sampled at the ocean time of each particle's birth, rounded to this step (seconds of ocean time).
const OCEAN_TIME_STEP = 1 / 24;
// How many steps either side of a birth to look when the sea has no spray at that moment.
const OCEAN_TIME_SEARCH_STEPS = 96;

function meshSourceFrom(emitter, geometry, sourceNode, emitterPath) {
  const world = surfaceInWorld(geometry, nodeMatrix(sourceNode));
  const weights = emitter.group ? vertexGroupOf(emitter, geometry, emitterPath) : null;
  const sharpAngle = emitter.sharpAngle ?? null;
  const vectors = emitter.velocityFrom ? velocityVectorOf(emitter, geometry, nodeMatrix(sourceNode), emitterPath) : null;
  const source = createMeshSource(world.positions, world.normals, geometry.indices, emitter.from, weights, sharpAngle, vectors, emitter.groupThreshold ?? 0);
  if (source && source.triangleCount > PARTICLE_LIMITS.maxEmitterTriangles) {
    throw invalidField(`${emitterPath}.mesh`, `${source.triangleCount} triangles on node ${emitter.mesh}`, `a mesh with at most ${PARTICLE_LIMITS.maxEmitterTriangles} triangles, such as a simpler proxy mesh`);
  }
  return source;
}

function emptySourceError(emitter, emitterPath, detail) {
  const groupNote = emitter.group ? ` and some weight in vertex group "${emitter.group}"` : '';
  return invalidField(`${emitterPath}.mesh`, emitter.mesh, `a node whose mesh has triangles with some area${groupNote}, because emitter.from is "${emitter.from}"${detail}`);
}

// The source of a sea that an oceanTime track moves: each particle takes its point from the sea as it is when the particle is born.
function followingSeaSource(emitter, sourceNode, sea, emitterPath) {
  const frames = new Map();
  const sourceAt = step => {
    if (!frames.has(step)) {
      const geometry = sea.geometryAt(sourceNode.geometry, step * OCEAN_TIME_STEP);
      frames.set(step, meshSourceFrom(emitter, geometry, sourceNode, emitterPath));
    }
    return frames.get(step);
  };
  const nearestSource = step => {
    for (let distance = 0; distance <= OCEAN_TIME_SEARCH_STEPS; distance++) {
      const source = sourceAt(step + distance) ?? sourceAt(step - distance);
      if (source) return source;
    }
    throw emptySourceError(emitter, emitterPath, `; the sea of node ${emitter.mesh} has no weight in that group at any ocean time its oceanTime track gives near the births; raise the ocean windSpeed or choppiness, lower groupThreshold, or change ocean.time and the oceanTime track`);
  };
  return Object.freeze({
    mode: emitter.from,
    triangleCount: 0,
    sample: (random, birth) => nearestSource(Math.round(sea.oceanTimeAt(sourceNode.geometry, birth) / OCEAN_TIME_STEP)).sample(random),
  });
}

function meshSourceOf(system, nodes, geometries, systemIndex, sea) {
  const emitterPath = `particles.systems[${systemIndex}].emitter`;
  const emitter = system.emitter;
  if (emitter.shape !== 'mesh') return emitter;
  const sourceNode = nodes.get(emitter.mesh);
  const followsSea = sea?.oceanTimeAt(sourceNode.geometry, 0) != null;
  if (followsSea) return { ...emitter, source: followingSeaSource(emitter, sourceNode, sea, emitterPath) };
  const source = meshSourceFrom(emitter, geometries.get(sourceNode.geometry), sourceNode, emitterPath);
  if (!source) {
    throw emptySourceError(emitter, emitterPath, emitter.group ? '; an ocean edit with spray: true has spray only on crests that rise, and that depends on its time, size, resolution and windSpeed: change them, lower groupThreshold, or animate the sea with an oceanTime track' : '');
  }
  return { ...emitter, source };
}

function prepareEmitter(system, node, templates, forces, colliders, emitter) {
  const systemForces = { ...forces, drag: system.drag, floor: system.floor, bounce: system.bounce ?? (colliders ? DEBRIS_BOUNCE : 0), friction: system.friction ?? DEBRIS_FRICTION, colliders };
  const launches = createParticleLaunches({ ...system, emitter, instanceCount: templates.length, spreadRadians: system.spread * Math.PI / 180, forces: systemForces });
  return {
    node,
    report: () => ({ node: system.node, type: 'emitter', particles: system.count, verticesPerParticle: Math.max(...templates.map(template => template.positions.length / 3)), ...lifeSummary(launches) }),
    build: time => buildParticleMesh(templates, launches, systemForces, system.scale, time, system),
  };
}

/**
 * The seeded launches, the forces and the look of a normalized spark system. The agent scene draws from this, and so do the reference
 * renders (`scripts/make-spark-spec.mjs`), so every renderer shows the same sparks. `forces` is `{ gravity, wind, fields }`.
 */
export function sparkSystemSetup(system, forces, emitter = system.emitter) {
  const systemForces = { ...forces, drag: system.drag, floor: system.floor, bounce: system.bounce ?? 0, friction: DEBRIS_FRICTION };
  const launches = createParticleLaunches({ ...system, emitter, instanceCount: 1, spreadRadians: system.spread * Math.PI / 180, forces: systemForces });
  const look = { shutter: system.shutter, temperature: system.temperature, intensity: system.intensity };
  return { launches, forces: systemForces, look };
}

function prepareSparks(system, node, forces, emitter) {
  const { launches, forces: systemForces, look } = sparkSystemSetup(system, forces, emitter);
  return {
    node,
    report: () => ({ node: system.node, type: 'sparks', particles: system.count, verticesPerParticle: SPARK_VERTICES, temperature: [...system.temperature], shutter: system.shutter, ...lifeSummary(launches) }),
    build: time => buildSparkMesh(launches, systemForces, time, look),
  };
}

function prepareHair(system, node, surfaceNode, surfaceGeometry, forces) {
  const world = surfaceInWorld(surfaceGeometry, nodeMatrix(surfaceNode));
  const strands = createStrandRoots({ ...system, spread: system.lean }, world.positions, world.normals, surfaceGeometry.indices);
  const settings = {
    segments: system.segments, width: system.width, droop: system.droop,
    fields: forces.fields,
    sway: system.sway ? { amplitude: system.sway, rate: system.swayRate, direction: horizontalDirection(forces.wind) } : undefined,
  };
  const verticesPerStrand = (system.segments + 1) * HAIR_LIMITS.ringSides;
  let staticMesh = null;
  return {
    node,
    report: () => ({ node: system.node, type: 'hair', surface: system.surface, strands: system.count, segments: system.segments, verticesPerStrand }),
    // Without sway a strand never moves, so one build serves every time.
    build: time => {
      if (settings.sway || settings.fields.some(field => field.type === 'turbulence')) return buildHairMesh(strands, settings, time);
      staticMesh ??= buildHairMesh(strands, settings, 0);
      return staticMesh;
    },
  };
}

/**
 * Prepare the particles section. The result is a pure function of time: `sample(t)` returns the geometry of each
 * system node with every particle or strand placed from its seeded values, so a seek never replays earlier times.
 */
function isOrigin(vector) {
  return !vector || vector.every(component => component === 0);
}

/**
 * A system node's own transform does not move its particles, only emitter.position does, so a node placed at the spark point
 * with a translation and no emitter.position births its particles at the world origin (#2053). A mesh emitter takes its place
 * from the mesh node, so it has nothing to ignore.
 */
function nodeTransformProblems(particles, recipe) {
  const nodesById = new Map(recipe.nodes.map(node => [node.id, node]));
  const reported = new Set();
  const problems = [];
  for (const system of particles.systems) {
    const node = nodesById.get(system.node);
    if (!node || reported.has(node.id) || isOrigin(node.translation) || system.emitter?.shape === 'mesh' || !isOrigin(system.emitter?.position)) continue;
    reported.add(node.id);
    const translation = Array.from(node.translation).map(component => Math.round(component * 1000) / 1000).join(', ');
    problems.push({
      kind: 'particle-node-transform-ignored', severity: 'warning', target: node.id,
      message: `Particle system node ${node.id} is translated to [${translation}], but a system node's transform does not move its particles, so they are born at the world origin.`,
      fix: `Set emitter.position to [${translation}] on the system with scene_apply set-particles, and leave the node translation at [0, 0, 0].`,
    });
  }
  return problems;
}

/** `sea` is `{ oceanTimeAt(geometryId, time), geometryAt(geometryId, oceanTime) }`: an emitter on a geometry that an oceanTime track drives follows that sea. */
export function bakeAgentParticles(particles, recipe, geometries, sea) {
  const nodes = new Map(recipe.nodes.map(node => [node.id, node]));
  const forces = { gravity: particles.gravity ?? DEFAULT_GRAVITY, wind: particles.wind ?? [0, 0, 0], fields: particles.fields ?? [] };
  let totalVertices = 0;
  const prepared = particles.systems.map((system, systemIndex) => {
    const node = nodes.get(system.node);
    const verticesPerItem = system.type === 'sparks' ? SPARK_VERTICES : system.type === 'hair' ? (system.segments + 1) * HAIR_LIMITS.ringSides : Math.max(...templateNodeIds(system).map(nodeId => geometries.get(nodes.get(nodeId).geometry).positions.length / 3));
    totalVertices += verticesPerItem * system.count;
    checkVertexBudget(verticesPerItem, system.count, totalVertices, system.node, recipe);
    if (system.type === 'hair') {
      const surfaceNode = nodes.get(system.surface);
      return prepareHair(system, node, surfaceNode, geometries.get(surfaceNode.geometry), forces);
    }
    if (system.type === 'sparks') return prepareSparks(system, node, forces, meshSourceOf(system, nodes, geometries, systemIndex, sea));
    const templates = templateNodeIds(system).map(nodeId => geometries.get(nodes.get(nodeId).geometry));
    return prepareEmitter(system, node, templates, forces, collisionSurfaceOf(system, nodes, geometries), meshSourceOf(system, nodes, geometries, systemIndex, sea));
  });
  return Object.freeze({
    /** Warnings for a recipe that loads but does not do what its author likely meant. */
    diagnostics() {
      return nodeTransformProblems(particles, recipe);
    },
    sample(time) {
      return new Map(prepared.map(({ node, build }) => [node.id, worldToNodeLocal(build(time), nodeMatrix(node))]));
    },
    /** Counts, vertices drawn and, for emitters, when each system peaks and ends: numbers an agent can read without a picture. */
    report() {
      return { gravity: [...forces.gravity], wind: [...forces.wind], fields: forces.fields.map(field => ({ ...field })), vertices: totalVertices, systems: prepared.map(entry => entry.report()) };
    },
  });
}