Skip to content

3D engine that AI agents drive

13.0 KB
Raw Blame
// The two soft body films of docs/physics.md: a jelly cube landing and a flag lowered into folds on itself.
// Each is one recipe. The film test and the preview script both bake that recipe, so what is measured is what is rendered.
import { createHash } from 'node:crypto';
import '../tests/support/load-agent-scene-modules.mjs';
import { createAgentScene } from '../src/agent-scene.js';

export const FILM_FRAMES_PER_SECOND = 60;
const FLOOR_THICKNESS = 0.01;
const GROUND_NODE = { id: 'ground', geometry: 'floor', material: 'stone', translation: [0, -0.5, 0], scale: [8, 1, 8] };
const CAMERA = { fov: 34 };

function baseRecipe({ geometries, materials, nodes, motion, cloth, camera, floorColor = [0.55, 0.55, 0.58], environment }) {
  return {
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [...geometries, { id: 'floor', type: 'box', bevel: 0 }],
    materials: [...materials, { id: 'stone', color: floorColor }],
    nodes: [...nodes, GROUND_NODE],
    camera: { ...CAMERA, ...camera },
    motion,
    cloth,
    ...(environment ? { environment } : {}),
  };
}

/** A rounded jelly cube, 0.5 m across, dropped from 1.95 m above the floor. */
export function jellyCubeRecipe() {
  return baseRecipe({
    geometries: [{ id: 'jelly', type: 'box', bevel: 0.12, subdivisions: 3 }],
    materials: [{ id: 'gel', color: [0.25, 0.85, 0.45] }],
    nodes: [
      { id: 'cube', geometry: 'jelly', material: 'gel', translation: [0, 2.2, 0], scale: [0.5, 0.5, 0.5] },
      { id: 'clock' },
    ],
    // A recipe needs authored motion before a render job accepts a start time; the cloth bake reads the same clock.
    motion: { duration: 2, loop: false, tracks: [{ kind: 'node', id: 'clock', property: 'translation', interpolation: 'LINEAR', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: 2, value: [0, 0, 0] }] }] },
    camera: { eye: [0.45, 0.22, 1.75], target: [0, 0.3, 0] },
    cloth: {
      duration: 2,
      sheets: [{ node: 'cube', softBody: { shape: 0.15, pressure: 1 }, stiffness: 0.9, bend: 0, damping: 2 }],
      colliders: [{ node: 'ground', shape: 'box' }],
    },
  });
}

// The pole's path: a wide whip from side to side on the way down so the sheet billows and ripples, a landing at 0.8 s, then a zig-zag drag
// 2 m across the floor that pulls the cloth into a thin crumpled layer.
const POLE_KEYFRAMES = [
  { time: 0, value: [0, 2.0, 0] },
  { time: 0.15, value: [0.5, 1.85, 0.4] },
  { time: 0.3, value: [-0.5, 1.4, -0.4] },
  { time: 0.45, value: [0.4, 0.8, 0.5] },
  { time: 0.6, value: [-0.2, 0.3, -0.2] },
  { time: 0.8, value: [0, 0.012, 0] },
  { time: 1.1, value: [0.3, 0.012, 0.7] },
  { time: 1.5, value: [-0.3, 0.012, 1.1] },
  { time: 1.9, value: [0.3, 0.012, 1.5] },
  { time: 2.4, value: [0, 0.012, 1.9] },
  { time: 3, value: [0, 0.012, 2.0] },
];
export const FLAG_FILM_SECONDS = 3;
// The fine flag: a 64 by 64 grid for 4 s with dihedral bending, so the cloth folds in many soft ripples instead of one crease.
export const FINE_FLAG_FILM_SECONDS = 4;
const FINE_FLAG_SEGMENTS = 63;
const FINE_FLAG_BEND = 0.15;
// Creases stay: past 0.3 rad of bending the rest angle follows the cloth by a fifth of the excess a substep, so folds made in the fall are kept
// (without it the sheet pulls its folds flat again and ends as a smooth layer). Damping 3 calms the landing. Static friction holds a layer
// where it lies on the floor, and the pole lets go as it lands, so no corner stays pinned up like a tent and the heap is left to rest.
const FINE_FLAG_CREASE = { bendYield: 0.3, bendSet: 0.2, damping: 3, friction: 0.6, staticFriction: 1 };
const FINE_FLAG_LANDING_SECONDS = 0.8;
// The camera frames the fall from afar, then moves in over the landing so the heap fills the picture.
const FINE_FLAG_CAMERA_TRACKS = [
  { kind: 'camera', property: 'eye', interpolation: 'SMOOTH', keyframes: [{ time: 0, value: [1.5, 1.2, 3.6] }, { time: 0.7, value: [1.5, 1.2, 3.6] }, { time: 1.3, value: [0.85, 0.75, 1.55] }, { time: 4, value: [0.85, 0.75, 1.55] }] },
  { kind: 'camera', property: 'target', interpolation: 'SMOOTH', keyframes: [{ time: 0, value: [0, 0.9, 0] }, { time: 0.7, value: [0, 0.9, 0] }, { time: 1.3, value: [0, 0.03, 0] }, { time: 4, value: [0, 0.03, 0] }] },
];
// A deep red and cream striped cloth on a mid grey floor, lit by a grazing key from the side so every fold casts a shadow and bends the stripes.
const FLAG_LOOK = { lightDirection: [-0.9, 0.3, 0.45], keyIntensity: 1.5, fillIntensity: 0.12, ambientIntensity: 0.15 };
const FLAG_STRIPES = { type: 'graph', mapping: 'uv', resolution: 256, graph: { color: { layer: { base: [0.35, 0.015, 0.04], top: [0.85, 0.78, 0.62], mask: { wave: { frequency: 8, direction: 'v', shape: 'saw' } }, edge: 0.5, softness: 0.02 } } } };

/**
 * A flag hung from a pole by its top edge. The pole swings from side to side while it falls, so the sheet ripples, lands on the floor and
 * is let go there, so the cloth settles as a crumpled heap that stays put (fine only; the 38 by 38 film drags it into a ridge). The sheet sets thickness 3.5 mm, which also sets the self collision radius,
 * so layers stack 6 mm apart instead of 3.7 cm.
 */
export function foldingFlagRecipe({ selfCollision = true, fine = false } = {}) {
  const seconds = fine ? FINE_FLAG_FILM_SECONDS : FLAG_FILM_SECONDS;
  const landing = POLE_KEYFRAMES.findIndex(keyframe => keyframe.time === FINE_FLAG_LANDING_SECONDS);
  const keyframes = fine ? [...POLE_KEYFRAMES.slice(0, landing + 1), { time: seconds, value: POLE_KEYFRAMES[landing].value }] : POLE_KEYFRAMES;
  const bending = fine ? { bendModel: 'dihedral', bend: FINE_FLAG_BEND, ...FINE_FLAG_CREASE } : { bend: 0.0002 };
  return baseRecipe({
    geometries: [{ id: 'flag', type: 'grid', segments: fine ? FINE_FLAG_SEGMENTS : 38 }],
    materials: [{ id: 'fabric', color: [1, 1, 1], doubleSided: true, pattern: FLAG_STRIPES }],
    nodes: [
      { id: 'flag', geometry: 'flag', material: 'fabric', translation: [0, 1.5, 0], scale: [1.6, 1, 1] },
      { id: 'pole', translation: [0, 2.0, 0] },
    ],
    motion: { duration: seconds, loop: false, tracks: [{ kind: 'node', id: 'pole', property: 'translation', interpolation: 'LINEAR', keyframes }, ...(fine ? FINE_FLAG_CAMERA_TRACKS : [])] },
    camera: fine ? { eye: [1.5, 1.2, 3.6], target: [0, 0.9, 0], fov: 42 } : { eye: [2.2, 1.7, 5.4], target: [0, 0.6, 0.8] },
    floorColor: [0.28, 0.28, 0.3],
    environment: FLAG_LOOK,
    cloth: {
      duration: seconds,
      sheets: [{ node: 'flag', pin: ['topLeft', 'topRight'], pinTo: fine ? { node: 'pole', releaseAt: FINE_FLAG_LANDING_SECONDS } : { node: 'pole' }, selfCollision, stiffness: 0.6, damping: 1.5, friction: 0.4, ...bending, thickness: 0.002 }],
      colliders: [{ node: 'ground', shape: 'box' }],
    },
  });
}

/**
 * How far the sheet's triangles face different ways: 0 for a flat sheet, toward 1 as the normals scatter. A triangle's normal is
 * taken up to its sign (a cloth has two faces), summed, and the length of that sum over the triangle count is taken from 1.
 */
export function normalSpread(vertices, indices) {
  let sumX = 0;
  let sumY = 0;
  let sumZ = 0;
  let counted = 0;
  for (let corner = 0; corner < indices.length; corner += 3) {
    const a = indices[corner] * 3;
    const b = indices[corner + 1] * 3;
    const thirdVertexOffset = indices[corner + 2] * 3;
    const edgeOne = [vertices[b] - vertices[a], vertices[b + 1] - vertices[a + 1], vertices[b + 2] - vertices[a + 2]];
    const edgeTwo = [vertices[thirdVertexOffset] - vertices[a], vertices[thirdVertexOffset + 1] - vertices[a + 1], vertices[thirdVertexOffset + 2] - vertices[a + 2]];
    let normalX = edgeOne[1] * edgeTwo[2] - edgeOne[2] * edgeTwo[1];
    let normalY = edgeOne[2] * edgeTwo[0] - edgeOne[0] * edgeTwo[2];
    let normalZ = edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0];
    const length = Math.hypot(normalX, normalY, normalZ);
    if (length < 1e-12) continue;
    const sign = normalZ < 0 ? -1 / length : 1 / length;
    normalX *= sign;
    normalY *= sign;
    normalZ *= sign;
    sumX += normalX;
    sumY += normalY;
    sumZ += normalZ;
    counted++;
  }
  return counted === 0 ? 0 : 1 - Math.hypot(sumX, sumY, sumZ) / counted;
}

/** The cloth node's vertices at `time` in world space (the recipe nodes use translation and scale only), as a copy. */
export function clothVertices(scene, node, time) {
  scene.sampleMotion(time);
  const local = scene.parts.find(part => part.name === node.id).geometry.positions;
  const world = new Float32Array(local.length);
  for (let index = 0; index < local.length; index++) {
    world[index] = local[index] * node.scale[index % 3] + node.translation[index % 3];
  }
  return world;
}

/**
 * Bakes a recipe and samples every frame. Returns the world vertex buffer of each frame, a hash of each frame, and
 * the milliseconds of the whole bake (scene creation plus the first sample) and of every later sample, and the triangle indices of the
 * cloth node so a caller does not bake the recipe again just to read them.
 */
export function recordFilm(recipe, nodeId, frameCount) {
  const node = recipe.nodes.find(candidate => candidate.id === nodeId);
  const started = performance.now();
  const scene = createAgentScene(recipe);
  const frames = [clothVertices(scene, node, 0)];
  const bakeMilliseconds = performance.now() - started;
  const sampleMilliseconds = [];
  for (let frame = 1; frame < frameCount; frame++) {
    const sampleStarted = performance.now();
    frames.push(clothVertices(scene, node, frame / FILM_FRAMES_PER_SECOND));
    sampleMilliseconds.push(performance.now() - sampleStarted);
  }
  const hashes = frames.map(frame => createHash('sha256').update(Buffer.from(frame.buffer)).digest('hex'));
  const indices = scene.parts.find(part => part.name === node.id).geometry.indices;
  return { frames, hashes, bakeMilliseconds, sampleMilliseconds, indices };
}

/** Lowest, highest and extent of a vertex buffer along one axis (0 x, 1 y, 2 z). */
export function axisRange(vertices, axis) {
  let low = Infinity;
  let high = -Infinity;
  for (let index = axis; index < vertices.length; index += 3) {
    low = Math.min(low, vertices[index]);
    high = Math.max(high, vertices[index]);
  }
  return { low, high, extent: high - low };
}

/** The frame where the body first rests on the floor, with the dent measured from there on. */
export function measureLanding(frames, restHeight) {
  const lowest = frame => axisRange(frame, 1).low;
  const contact = frames.findIndex(frame => lowest(frame) <= FLOOR_THICKNESS + 1e-3);
  if (contact === -1) {
    throw new Error(`measureLanding: the body never reached the floor within ${frames.length} frames; pass a longer film or lower the drop.`);
  }
  let deepest = contact;
  let deepestHeight = Infinity;
  for (let frame = contact; frame < frames.length; frame++) {
    const height = axisRange(frames[frame], 1).extent;
    if (height < deepestHeight) {
      deepestHeight = height;
      deepest = frame;
    }
  }
  return { contact, maxDentFrame: deepest, maxDentDepth: restHeight - deepestHeight, restHeight };
}

/**
 * How often the sheet's height turns from rising to falling (or back) along the middle row and the middle column of its grid, ignoring
 * wiggles under `deadband` metres: the number of folds a line across the cloth crosses.
 */
export function foldCrossings(vertices, side, deadband = 0.0005) {
  const countAlong = line => {
    let crossings = 0;
    let direction = 0;
    let anchor = vertices[line[0] * 3 + 1];
    for (const vertex of line) {
      const height = vertices[vertex * 3 + 1];
      if (direction >= 0 && height < anchor - deadband) {
        if (direction === 1) crossings++;
        direction = -1;
        anchor = height;
      } else if (direction <= 0 && height > anchor + deadband) {
        if (direction === -1) crossings++;
        direction = 1;
        anchor = height;
      } else if ((direction >= 0 && height > anchor) || (direction <= 0 && height < anchor)) {
        anchor = height;
      }
    }
    return crossings;
  };
  const middle = Math.floor(side / 2);
  return {
    row: countAlong(Array.from({ length: side }, (_, column) => middle * side + column)),
    column: countAlong(Array.from({ length: side }, (_, row) => row * side + middle)),
  };
}

/** Smallest distance between two vertices that no triangle edge joins: the closest two layers of a fold come. */
export function unjoinedMinimumDistance(vertices, indices) {
  const count = vertices.length / 3;
  const joined = new Set();
  for (let corner = 0; corner < indices.length; corner += 3) {
    for (let side = 0; side < 3; side++) {
      const first = indices[corner + side];
      const second = indices[corner + (side + 1) % 3];
      joined.add(Math.min(first, second) * count + Math.max(first, second));
    }
  }
  let minimum = Infinity;
  for (let first = 0; first < count; first++) {
    for (let second = first + 1; second < count; second++) {
      if (joined.has(first * count + second)) continue;
      const distance = Math.hypot(vertices[first * 3] - vertices[second * 3], vertices[first * 3 + 1] - vertices[second * 3 + 1], vertices[first * 3 + 2] - vertices[second * 3 + 2]);
      minimum = Math.min(minimum, distance);
    }
  }
  return minimum;
}