Skip to content

3D engine that AI agents drive

8.1 KB
Raw Blame
import { invalidField } from './field-error.js';
import { knownKeys } from './motion-validation.js';
import { fractureMesh, MAX_FRACTURE_CELLS, MIN_FRACTURE_CELLS } from './fracture.js';
import { AGENT_SCENE_CAPABILITIES } from './agent-scene-capabilities.js';

// Recipe side of fracture: the `fragment` geometry type (one Voronoi piece of a source geometry) and the
// `fracture-node` operation that swaps a node for its pieces, bodies and breakable glue.

const DEFAULT_PHYSICS_DURATION = 3;
const FRACTURE_CACHE_SIZE = 4;
const UNSUPPORTED_NODE_FIELDS = ['instances', 'asset', 'vegetation', 'relations'];
const FRACTURE_NODE_FIELDS = ['type', 'node', 'cells', 'strength', 'seed', 'impact', 'impactRadius', 'density', 'friction'];

const fractureCache = new Map();

/** The fracture of one source and option set, kept for the few most recent so the pieces of a part share one computation. */
function cachedFracture(key, compute) {
  if (fractureCache.has(key)) return fractureCache.get(key);
  const fracture = compute();
  fractureCache.set(key, fracture);
  if (fractureCache.size > FRACTURE_CACHE_SIZE) fractureCache.delete(fractureCache.keys().next().value);
  return fracture;
}

function fractureOptions(definition) {
  return { seed: definition.seed ?? 1, cells: definition.cells, impact: definition.impact, impactRadius: definition.impactRadius };
}

/**
 * Render geometry of piece `definition.index`, in the source geometry's local space.
 * `sourceSignature` is the cache identity of the source record, so editing the source changes the pieces.
 */
export function fragmentGeometry(definition, sourceSignature, generateSource) {
  const options = fractureOptions(definition);
  const key = JSON.stringify([sourceSignature, options.seed, options.cells, options.impact ?? null, options.impactRadius ?? null]);
  const fracture = cachedFracture(key, () => fractureMesh(generateSource(), options));
  const fragment = fracture.fragments[definition.index];
  return {
    positions: fragment.positions.slice(),
    normals: fragment.normals.slice(),
    indices: fragment.indices.slice(),
  };
}

function validatedOperation(operation) {
  knownKeys(operation, FRACTURE_NODE_FIELDS, 'operation');
  if (typeof operation.node !== 'string') {
    throw invalidField('node', operation.node, 'the ID of a node to fracture, such as "wall"', TypeError);
  }
  if (!Number.isInteger(operation.cells) || operation.cells < MIN_FRACTURE_CELLS || operation.cells > MAX_FRACTURE_CELLS) {
    throw invalidField('cells', operation.cells, `a whole number of pieces from ${MIN_FRACTURE_CELLS} to ${MAX_FRACTURE_CELLS}, such as 24`);
  }
  if (!(Number.isFinite(operation.strength) && operation.strength > 0)) {
    throw invalidField('strength', operation.strength, 'the glue strength as an impulse above 0 in N s, such as 5; a body hit by more than this in one 1/60 s step breaks its glue');
  }
  for (const field of ['density', 'friction']) {
    if (operation[field] !== undefined && !(Number.isFinite(operation[field]) && operation[field] > 0)) {
      throw invalidField(field, operation[field], `a number above 0, such as ${field === 'density' ? 1 : 0.6}`);
    }
  }
  return operation;
}

function fracturableNode(candidate, nodeId) {
  const node = candidate.nodes.find(entry => entry.id === nodeId);
  if (!node) {
    throw invalidField('node', nodeId, `the ID of an existing node, one of ${candidate.nodes.slice(0, 8).map(entry => entry.id).join(', ') || 'none yet'}`);
  }
  if (node.geometry === undefined) {
    throw invalidField('node', nodeId, 'a node with a geometry to break; pick a mesh node such as "wall"');
  }
  const unsupported = UNSUPPORTED_NODE_FIELDS.find(field => node[field] !== undefined);
  if (unsupported) {
    throw invalidField('node', nodeId, `a plain mesh node; ${nodeId} uses ${unsupported}, so fracture a node without it`);
  }
  if (node.parent !== null && node.parent !== undefined) {
    throw invalidField('node', nodeId, 'a root node, with no parent, since every piece is a physics body; reparent it first with set-node');
  }
  if (candidate.nodes.some(entry => entry.parent === nodeId)) {
    throw invalidField('node', nodeId, 'a node without children; move the children to another parent with set-node first');
  }
  if ((candidate.motion?.tracks ?? []).some(track => track.id === nodeId)) {
    throw invalidField('node', nodeId, 'a node without motion tracks; the pieces are moved by physics, so remove its tracks first');
  }
  if ((candidate.physics?.bodies ?? []).some(body => body.node === nodeId)) {
    throw invalidField('node', nodeId, `a node without a physics body; the pieces get their own bodies, so drop the body of ${nodeId} with set-physics first`);
  }
  return node;
}

function claimPieceIds(candidate, nodeId, cells) {
  const ids = Array.from({ length: cells }, (_, index) => `${nodeId}-frag-${index}`);
  const taken = ids.find(id => candidate.nodes.some(entry => entry.id === id) || candidate.geometries.some(entry => entry.id === id));
  if (taken) {
    throw invalidField('node', nodeId, `a node whose piece IDs are free; ${taken} already exists, so rename it or remove it first`);
  }
  return ids;
}

function physicsWithRoom(candidate, bodiesNeeded, jointsNeeded) {
  const physics = candidate.physics ?? { duration: DEFAULT_PHYSICS_DURATION, bodies: [] };
  const { maxBodies, maxJoints } = AGENT_SCENE_CAPABILITIES.physics.limits;
  const bodyCount = physics.bodies.length + bodiesNeeded;
  const jointCount = (physics.joints?.length ?? 0) + jointsNeeded;
  if (bodyCount > maxBodies) {
    throw invalidField('cells', bodiesNeeded, `at most ${maxBodies - physics.bodies.length} pieces, since physics holds ${maxBodies} bodies and ${physics.bodies.length} are in use; use fewer cells`);
  }
  if (jointCount > maxJoints) {
    throw invalidField('cells', bodiesNeeded, `fewer pieces: ${jointsNeeded} glue joints would pass the ${maxJoints} joints physics holds (${physics.joints?.length ?? 0} in use); use fewer cells`);
  }
  return physics;
}

/**
 * The fracture-node operation. Replaces `operation.node` by `cells` piece nodes with the same transform and material,
 * adds a convex dynamic body per piece and one fixed joint with `breakImpulse: strength` per neighbouring pair. Set a
 * physics section with the ball and floor first (set-physics replaces the section), or let this create one of 3 seconds.
 */
export function fractureNode(candidate, rawOperation, generateSource) {
  const operation = validatedOperation(rawOperation);
  const node = fracturableNode(candidate, operation.node);
  const definition = { seed: operation.seed ?? 1, cells: operation.cells, impact: operation.impact, impactRadius: operation.impactRadius };
  const fracture = fractureMesh(generateSource(node.geometry), fractureOptions(definition));
  const ids = claimPieceIds(candidate, node.id, operation.cells);
  const physics = physicsWithRoom(candidate, operation.cells, fracture.glue.length);
  const scale = node.scale ?? [1, 1, 1];
  const { id: removedId, geometry: sourceGeometry, ...shared } = node;
  const pieces = ids.map(id => ({ ...structuredClone(shared), id, geometry: id }));
  candidate.geometries.push(...ids.map((id, index) => ({
    id, type: 'fragment', source: sourceGeometry, index, cells: operation.cells, seed: definition.seed,
    ...(operation.impact === undefined ? {} : { impact: operation.impact }),
    ...(operation.impactRadius === undefined ? {} : { impactRadius: operation.impactRadius }),
  })));
  const position = candidate.nodes.findIndex(entry => entry.id === removedId);
  candidate.nodes.splice(position, 1, ...pieces);
  physics.bodies.push(...ids.map(id => ({
    node: id, type: 'dynamic', shape: 'convex', density: operation.density ?? 1,
    ...(operation.friction === undefined ? {} : { friction: operation.friction }),
  })));
  physics.joints = [...(physics.joints ?? []), ...fracture.glue.map(({ a, b, anchor }) => {
    const scaledAnchor = anchor.map((value, axis) => value * scale[axis]);
    return {
      name: `${removedId}-glue-${a}-${b}`, type: 'fixed', bodyA: ids[a], bodyB: ids[b],
      anchorA: scaledAnchor, anchorB: scaledAnchor, breakImpulse: operation.strength,
    };
  })];
  candidate.physics = physics;
}