Skip to content

3D engine that AI agents drive

12.7 KB
Raw Blame
import { quat } from 'gl-matrix';
import { invalidField } from './field-error.js';
import { bounded, knownKeys } from './motion-validation.js';

// The bake-motion operation: sample the live local transform of chosen nodes (tracks, IK, constraints, drivers and
// physics all included), write it back as keyframe tracks and drop the live sources, so the motion plays from keys alone.

export const BAKE_LIMITS = Object.freeze({ maxNodes: 32, maxSamples: 512, maxKeysPerTrack: 64, defaultStep: 1 / 30, minimumStep: 1 / 120 });
const DEFAULT_TOLERANCE = Object.freeze({ position: 0.001, angle: 0.1 });
const MAX_MOTION_DURATION = 30;
const BAKED_PROPERTIES = ['translation', 'rotation', 'scale'];
const REST_VALUES = { translation: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };
// Float noise below this is no movement: a node the bake leaves where it was gets no track.
const STEADY_EPSILON = 1e-6;
const RADIANS_PER_DEGREE = Math.PI / 180;

function roundTime(seconds) {
  return Math.round(seconds * 1e6) / 1e6;
}

function normalizedTolerance(input) {
  if (input === undefined) return null;
  knownKeys(input, ['position', 'angle', 'scale'], 'tolerance');
  const position = bounded(input.position ?? DEFAULT_TOLERANCE.position, 0, 10, 'tolerance.position');
  const angleDegrees = bounded(input.angle ?? DEFAULT_TOLERANCE.angle, 0, 45, 'tolerance.angle');
  const scale = bounded(input.scale ?? position, 0, 10, 'tolerance.scale');
  return { translation: position, rotation: angleDegrees * RADIANS_PER_DEGREE, scale };
}

function normalizedNodeIds(input, candidate) {
  const known = new Map(candidate.nodes.map(node => [node.id, node]));
  const example = JSON.stringify([candidate.nodes.find(node => !node.assetPart)?.id ?? 'crate']);
  if (!Array.isArray(input) || input.length < 1 || input.length > BAKE_LIMITS.maxNodes) {
    throw invalidField('nodes', Array.isArray(input) ? `${input.length} IDs` : input, `a list of 1 to ${BAKE_LIMITS.maxNodes} node IDs, such as ${example}`, Array.isArray(input) ? RangeError : TypeError);
  }
  input.forEach((id, position) => {
    const node = known.get(id);
    if (!node || node.assetPart) {
      throw invalidField(`nodes[${position}]`, id, `the ID of a node you placed, such as ${example}; scene_inspect lists them`);
    }
    if (input.indexOf(id) !== position) {
      throw invalidField(`nodes[${position}]`, id, 'each node ID once');
    }
  });
  return input;
}

/** Validate a bake-motion operation against the scene. `source` describes what the committed scene can sample. */
function normalizedBake(operation, candidate, source) {
  knownKeys(operation, ['type', 'nodes', 'start', 'end', 'step', 'tolerance'], 'operation');
  const ids = normalizedNodeIds(operation.nodes, candidate);
  if (!source.animated) {
    throw invalidField('nodes', ids, 'a scene that already moves: add motion or physics first, since there is nothing to sample yet');
  }
  const naturalEnd = Math.max(source.motionDuration, source.physicsDuration);
  const start = bounded(operation.start ?? 0, 0, MAX_MOTION_DURATION, 'start');
  const end = roundTime(bounded(operation.end ?? Math.min(naturalEnd, MAX_MOTION_DURATION), 0, MAX_MOTION_DURATION, 'end'));
  if (end <= start) {
    throw invalidField('end', end, `a time after start ${start}, up to ${MAX_MOTION_DURATION} seconds, such as ${roundTime(start + 1)}`);
  }
  const step = bounded(operation.step ?? BAKE_LIMITS.defaultStep, BAKE_LIMITS.minimumStep, 1, 'step');
  const sampleCount = Math.ceil((end - start) / step - 1e-9) + 1;
  if (sampleCount > BAKE_LIMITS.maxSamples) {
    throw invalidField('step', step, `a step that gives at most ${BAKE_LIMITS.maxSamples} samples over ${roundTime(end - start)} seconds, so at least ${roundTime((end - start) / (BAKE_LIMITS.maxSamples - 1))}, or a shorter start to end range`);
  }
  return { ids, start, end, step, sampleCount, tolerance: normalizedTolerance(operation.tolerance), toleranceInput: operation.tolerance };
}

function sampleTimes({ start, end, step, sampleCount }) {
  return Array.from({ length: sampleCount }, (_, index) => (index === sampleCount - 1 ? end : roundTime(start + index * step)));
}

/** Per node and property, the values at every sample time. Quaternions keep one sign so interpolation takes the short way. */
function sampledValues(options, source) {
  const times = sampleTimes(options);
  const series = new Map(options.ids.map(id => [id, { translation: [], rotation: [], scale: [] }]));
  for (const time of times) {
    const transforms = source.sampleLocalTransforms(time, options.ids);
    for (const id of options.ids) {
      const transform = transforms.get(id);
      const target = series.get(id);
      for (const property of BAKED_PROPERTIES) {
        const value = Array.from(transform[property]);
        const previous = target[property].at(-1);
        if (property === 'rotation' && previous && quat.dot(previous, value) < 0) {
          value.forEach((component, index) => { value[index] = -component; });
        }
        target[property].push(value);
      }
    }
  }
  return { times, series };
}

function distance(first, second) {
  return Math.hypot(...first.map((component, index) => component - second[index]));
}

function rotationAngle(first, second) {
  return 2 * Math.acos(Math.min(1, Math.abs(quat.dot(first, second))));
}

function difference(property, first, second) {
  return property === 'rotation' ? rotationAngle(first, second) : distance(first, second);
}

function interpolated(property, first, second, progress) {
  if (property === 'rotation') return Array.from(quat.slerp(new Float64Array(4), first, second, progress));
  return first.map((component, index) => component + (second[index] - component) * progress);
}

/** Ramer-Douglas-Peucker over time: keep the sample the kept neighbours miss most until none misses by more than the tolerance. */
function keptIndices(property, times, values, tolerance) {
  const kept = new Set([0, values.length - 1]);
  const pending = [[0, values.length - 1]];
  while (pending.length) {
    const [first, last] = pending.pop();
    let worstIndex = -1;
    let worstError = tolerance;
    for (let index = first + 1; index < last; index++) {
      const progress = (times[index] - times[first]) / (times[last] - times[first]);
      const error = difference(property, interpolated(property, values[first], values[last], progress), values[index]);
      if (error > worstError) {
        worstError = error;
        worstIndex = index;
      }
    }
    if (worstIndex >= 0) {
      kept.add(worstIndex);
      pending.push([first, worstIndex], [worstIndex, last]);
    }
  }
  return [...kept].sort((left, right) => left - right);
}

/** The keyframes of one property, or null when it stays at the node's rest value. */
function keyframesFor(property, times, values, restValue, tolerance) {
  const limit = Math.max(tolerance?.[property] ?? 0, STEADY_EPSILON);
  const steady = values.every(value => difference(property, value, values[0]) <= limit);
  if (steady) {
    return difference(property, values[0], restValue) <= limit ? null : [{ time: times[0], value: values[0] }];
  }
  const indices = tolerance ? keptIndices(property, times, values, limit) : values.map((_, index) => index);
  return indices.map(index => ({ time: times[index], value: values[index] }));
}

function bakedTracks(options, series, times, candidate) {
  const nodes = new Map(candidate.nodes.map(node => [node.id, node]));
  const tracks = [];
  for (const id of options.ids) {
    for (const property of BAKED_PROPERTIES) {
      const restValue = nodes.get(id)[property] ?? REST_VALUES[property];
      const keyframes = keyframesFor(property, times, series.get(id)[property], restValue, options.tolerance);
      if (!keyframes) continue;
      if (keyframes.length > BAKE_LIMITS.maxKeysPerTrack) {
        const advice = options.tolerance ? 'a larger tolerance' : 'a tolerance such as { "position": 0.005, "angle": 0.5 }';
        throw invalidField('tolerance', options.toleranceInput ?? null, `${advice}, or a larger step, since a track holds at most ${BAKE_LIMITS.maxKeysPerTrack} keys and ${id} ${property} needs ${keyframes.length}`);
      }
      tracks.push({ kind: 'node', id, property, interpolation: 'LINEAR', keyframes });
    }
  }
  return tracks;
}

function solverJoints(solver, nodes) {
  if (solver.type === 'two-bone') return [solver.root, solver.middle, solver.end];
  if (solver.type === 'aim') return solver.joints;
  if (solver.chain) return solver.chain;
  const path = [];
  for (let id = solver.end; id !== null && id !== undefined; id = nodes.get(id)?.parent) {
    path.push(id);
    if (id === solver.root) break;
  }
  return path;
}

function physicsNodeIds(physics, candidate) {
  const ids = (physics.bodies ?? []).map(body => body.node);
  if (physics.ragdoll) {
    ids.push(...candidate.nodes.filter(node => node.armature === physics.ragdoll.armature && node.id !== node.armature).map(node => node.id));
  }
  return ids;
}

/** A solver or a physics world moves its nodes together, so a bake that takes some of them must take all. */
function requireWholeGroup(group, kind, remedy, ids) {
  const missing = group.filter(id => !ids.has(id));
  if (missing.length) {
    throw invalidField('nodes', [...ids], `every node the ${kind} moves, so also ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? ' and more' : ''}; ${remedy}`);
  }
}

/** Remove what drove the baked nodes, so the keys are not applied on top of the live source. */
function dropLiveSources(candidate, idList) {
  const ids = new Set(idList);
  const nodes = new Map(candidate.nodes.map(node => [node.id, node]));
  const { motion, physics } = candidate;
  if (physics) {
    const group = physicsNodeIds(physics, candidate);
    if (group.some(id => ids.has(id))) {
      requireWholeGroup(group, 'physics world', 'bodies collide, so they bake together', ids);
      delete candidate.physics;
    }
  }
  if (!motion) return;
  const solvers = (motion.ik ?? []).filter(solver => {
    const joints = solverJoints(solver, nodes);
    if (!joints.some(id => ids.has(id))) return true;
    requireWholeGroup(joints, `${solver.type} IK solver`, 'its joints bake together', ids);
    return false;
  });
  const springs = bakedSprings(motion.springs, ids);
  const remaining = {
    ik: solvers,
    constraints: (motion.constraints ?? []).filter(constraint => !ids.has(constraint.node)),
    drivers: (motion.drivers ?? []).filter(driver => !(driver.target.kind === 'node' && ids.has(driver.target.id))),
  };
  for (const [field, list] of Object.entries(remaining)) {
    if (list.length) motion[field] = list;
    else delete motion[field];
  }
  if (springs) motion.springs = springs;
  else delete motion.springs;
}

/** The spring chains that stay live. A chain moves its bones together, so a bake that takes one must take all of them. */
function bakedSprings(springs, ids) {
  if (!springs) return null;
  const chains = springs.chains.filter(chain => {
    if (!chain.bones.some(id => ids.has(id))) return true;
    requireWholeGroup(chain.bones, 'spring chain', 'its bones bake together', ids);
    return false;
  });
  if (!chains.length) return null;
  const used = new Set(chains.flatMap(chain => chain.colliders));
  return { chains, colliders: springs.colliders.filter(collider => used.has(collider.id)) };
}

function motionHasContent(motion) {
  return Boolean(motion.tracks.length || motion.layers?.length || motion.ik?.length || motion.springs || motion.constraints?.length || motion.drivers?.length || motion.drive);
}

/**
 * Apply one bake-motion operation to a candidate recipe. `source` gives { animated, motionDuration, physicsDuration,
 * sampleLocalTransforms(time, ids) } for the committed scene. Returns { tracks, keyframes } counts for the report.
 */
export function bakeMotion(candidate, operation, source) {
  const options = normalizedBake(operation, candidate, source);
  if (candidate.motion?.loop && options.end > candidate.motion.duration) {
    throw invalidField('end', options.end, `at most the looping motion duration ${candidate.motion.duration}, since a longer bake would change the loop; set the motion loop to false first`);
  }
  dropLiveSources(candidate, options.ids);
  const { times, series } = sampledValues(options, source);
  const tracks = bakedTracks(options, series, times, candidate);
  const baked = new Set(options.ids);
  const motion = candidate.motion ?? { duration: Math.max(options.end, 0.1), loop: false, tracks: [] };
  motion.duration = Math.max(motion.duration, options.end);
  motion.tracks = [
    ...motion.tracks.filter(track => !(track.kind === 'node' && baked.has(track.id) && BAKED_PROPERTIES.includes(track.property))),
    ...tracks,
  ];
  if (motionHasContent(motion)) candidate.motion = motion;
  else delete candidate.motion;
  return { tracks: tracks.length, keyframes: tracks.reduce((total, track) => total + track.keyframes.length, 0) };
}