Skip to content

3D engine that AI agents drive

15.6 KB
Raw Blame
import { mat4, quat } from 'gl-matrix';
import { easedProgress, normalizeKeyframeEasing } from './easing.js';

const PROPERTY_SIZES = { translation: 3, rotation: 4, scale: 3, value: 1, emission: 1, metallic: 1, roughness: 1 };
const INTERPOLATIONS = new Set(['LINEAR', 'STEP', 'SMOOTH', 'CUBICSPLINE']);
const MATERIAL_PROPERTIES = new Set(['emission', 'metallic', 'roughness']);
const MINIMUM_POSITIVE_VALUE = 1e-8;
const isolatedMaterials = new WeakMap();

/** Share one isolated target material across source-internal animation bindings. */
export function retainAnimationMaterial(part, candidate = { ...part.material }) {
  const retained = isolatedMaterials.get(part);
  const material = retained && retained === part.material ? retained : candidate;
  part.material = material;
  isolatedMaterials.set(part, material);
  return material;
}

function normalizedTangent(property, tangent) {
  const size = PROPERTY_SIZES[property];
  if (size === 1) {
    if (!Number.isFinite(tangent)) throw new TypeError('Spline tangents must be finite numbers.');
    return tangent;
  }
  if ((!Array.isArray(tangent) && !ArrayBuffer.isView(tangent)) || tangent.length !== size || !Array.from(tangent).every(Number.isFinite)) {
    throw new TypeError(`${property} tangents need ${size} finite values.`);
  }
  return Object.freeze(Array.from(tangent));
}

function normalizedValue(property, value) {
  const size = PROPERTY_SIZES[property];
  if (size === 1) {
    if (!Number.isFinite(value)) throw new TypeError('Numeric keyframes must be finite.');
    if (property === 'emission' && value < 0) throw new RangeError('Emission keyframes cannot be negative.');
    if (['metallic', 'roughness'].includes(property) && (value > 1 || value < 0 || property === 'roughness' && value === 0)) {
      throw new RangeError(`${property} keyframes must stay within their material range.`);
    }
    return value;
  }
  if ((!Array.isArray(value) && !ArrayBuffer.isView(value)) || value.length !== size || !Array.from(value).every(Number.isFinite)) {
    throw new TypeError(`${property} keyframes need ${size} finite values.`);
  }
  const result = Array.from(value);
  if (property === 'rotation') {
    const length = Math.hypot(...result);
    if (!Number.isFinite(length) || length < 1e-8) throw new RangeError('Rotation keyframes need a finite nonzero quaternion length.');
    return Object.freeze(result.map(component => component / length));
  }
  if (property === 'scale' && result.some(component => component < 0)) throw new RangeError('Scale keyframes cannot be negative. Zero is allowed and hides the node.');
  return Object.freeze(result);
}

/** Keyframes are absolute local transforms. Input order does not affect sampling. */
export function createAnimationClip({ duration, loop = false, tracks = [] } = {}) {
  if (!Number.isFinite(duration) || duration <= 0) throw new RangeError('Clip duration must be positive and finite.');
  if (typeof loop !== 'boolean' || !Array.isArray(tracks)) throw new TypeError('Clip loop must be boolean and tracks must be an array.');
  const properties = new Set();
  const compiled = tracks.map(track => {
    if (!track || typeof track.target !== 'string' || !track.target.trim()) throw new TypeError('Every track needs a target name.');
    if (!Object.hasOwn(PROPERTY_SIZES, track.property)) throw new RangeError(`Unknown animation property: ${track.property}`);
    const identity = `${track.target}\u0000${track.property}`;
    if (properties.has(identity)) throw new RangeError('Each target property can have only one track.');
    properties.add(identity);
    const interpolation = track.interpolation ?? 'LINEAR';
    if (!INTERPOLATIONS.has(interpolation)) throw new RangeError(`Unknown interpolation: ${interpolation}`);
    if (!Array.isArray(track.keyframes) || !track.keyframes.length) throw new RangeError('Tracks need at least one keyframe.');
    if (interpolation === 'CUBICSPLINE' && track.keyframes.length < 2) throw new RangeError('Spline tracks need at least two keyframes.');
    const keyframes = track.keyframes.map(keyframe => {
      if (!keyframe || !Number.isFinite(keyframe.time) || keyframe.time < 0 || keyframe.time > duration) {
        throw new RangeError('Keyframe times must be within the clip duration.');
      }
      const compiledKeyframe = { time: keyframe.time, value: normalizedValue(track.property, keyframe.value) };
      const easing = normalizeKeyframeEasing(keyframe);
      if (easing && interpolation !== 'LINEAR' && interpolation !== 'SMOOTH') {
        throw new RangeError(`Keyframe easing needs LINEAR or SMOOTH interpolation, not ${interpolation}.`);
      }
      Object.assign(compiledKeyframe, easing);
      if (interpolation === 'CUBICSPLINE') {
        compiledKeyframe.inTangent = normalizedTangent(track.property, keyframe.inTangent);
        compiledKeyframe.outTangent = normalizedTangent(track.property, keyframe.outTangent);
      }
      return Object.freeze(compiledKeyframe);
    }).sort((first, second) => first.time - second.time);
    for (let index = 1; index < keyframes.length; index++) {
      if (keyframes[index].time === keyframes[index - 1].time) throw new RangeError('Keyframe times must be distinct.');
    }
    const effects = track.extrapolation === undefined && track.modifiers === undefined ? null : trackEffects?.normalize(track);
    if (effects === undefined) throw new Error('Import animation-modifiers.js.');
    return Object.freeze({ target: track.target, property: track.property, interpolation, keyframes: Object.freeze(keyframes), ...(effects ? { effects } : {}) });
  });
  return Object.freeze({ duration, loop, tracks: Object.freeze(compiled) });
}

function constrainSample(property, value) {
  if (!Number.isFinite(value)) throw new RangeError('Animation output must be finite. Reduce the values or tangents.');
  if (property === 'scale') return Math.max(MINIMUM_POSITIVE_VALUE, value);
  if (property === 'emission') return Math.max(0, value);
  if (property === 'metallic') return Math.max(0, Math.min(1, value));
  if (property === 'roughness') return Math.max(MINIMUM_POSITIVE_VALUE, Math.min(1, value));
  return value;
}

function copySample(output, value) {
  if (typeof value === 'number') output[0] = value;
  else output.set(value);
  return output;
}

function sampleTrackInto(track, time, output) {
  const keyframes = track.keyframes;
  const first = keyframes[0];
  const last = keyframes[keyframes.length - 1];
  if (time <= first.time) return copySample(output, first.value);
  if (time >= last.time) return copySample(output, last.value);
  let lower = 0;
  let upper = keyframes.length - 1;
  while (upper - lower > 1) {
    const middle = Math.floor((lower + upper) / 2);
    if (keyframes[middle].time <= time) lower = middle;
    else upper = middle;
  }
  const start = keyframes[lower];
  const end = keyframes[upper];
  if (time === start.time || track.interpolation === 'STEP') return copySample(output, start.value);
  const interval = end.time - start.time;
  let progress = (time - start.time) / interval;
  if (track.interpolation === 'CUBICSPLINE') {
    const squared = progress * progress;
    const cubed = squared * progress;
    const startWeight = 2 * cubed - 3 * squared + 1;
    const endWeight = -2 * cubed + 3 * squared;
    const outgoingWeight = (cubed - 2 * squared + progress) * interval;
    const incomingWeight = (cubed - squared) * interval;
    for (let axis = 0; axis < output.length; axis++) {
      const scalar = output.length === 1;
      const startValue = scalar ? start.value : start.value[axis];
      const endValue = scalar ? end.value : end.value[axis];
      const outgoing = scalar ? start.outTangent : start.outTangent[axis];
      const incoming = scalar ? end.inTangent : end.inTangent[axis];
      output[axis] = constrainSample(track.property,
        startWeight * startValue + outgoingWeight * outgoing + endWeight * endValue + incomingWeight * incoming);
    }
    if (track.property === 'rotation') {
      const length = Math.hypot(output[0], output[1], output[2], output[3]);
      if (!Number.isFinite(length) || length === 0) throw new RangeError('Spline produced an invalid quaternion. Adjust the rotation tangents.');
      for (let axis = 0; axis < 4; axis++) output[axis] /= length;
    }
    return output;
  }
  if (start.easing !== undefined) progress = easedProgress(start, progress);
  else if (track.interpolation === 'SMOOTH') progress = progress * progress * (3 - 2 * progress);
  if (track.property === 'rotation') return quat.slerp(output, start.value, end.value, progress);
  for (let axis = 0; axis < output.length; axis++) {
    const startValue = output.length === 1 ? start.value : start.value[axis];
    const endValue = output.length === 1 ? end.value : end.value[axis];
    output[axis] = startValue + (endValue - startValue) * progress;
  }
  return output;
}

let trackEffects = null;

/** Called by animation-modifiers.js when it loads, so the modifier code stays out of bundles that never use it. */
export function registerTrackEffects(handlers) {
  trackEffects = handlers;
}

function sampleTrack(track, time, output) {
  return track.effects ? trackEffects.sample(track, time, output, sampleTrackInto, constrainSample) : sampleTrackInto(track, time, output);
}

/**
 * Linear keyframes that trace a track with eased segments, for formats with no easing (glTF). Each segment gets
 * `stepsPerSegment` linear pieces; a track without easing comes back unchanged.
 */
export function bakeEasedKeyframes(track, stepsPerSegment) {
  if (!track.keyframes.some(keyframe => keyframe.easing !== undefined)) return track.keyframes;
  const size = PROPERTY_SIZES[track.property];
  const baked = [];
  for (let index = 0; index < track.keyframes.length; index++) {
    const start = track.keyframes[index];
    baked.push({ time: start.time, value: start.value });
    const end = track.keyframes[index + 1];
    if (!end) break;
    for (let step = 1; step < stepsPerSegment; step++) {
      const time = start.time + (end.time - start.time) * step / stepsPerSegment;
      const output = sampleTrackInto(track, time, new Float64Array(size));
      baked.push({ time, value: size === 1 ? output[0] : Array.from(output) });
    }
  }
  return baked;
}

// A frame time such as 9 / 30 = 0.3 sits a hair under the third cycle of a 0.1 s clip; it belongs to the cycle that starts there.
// Well under the 1e-9 s that rig.js reads before a loop end to bake the end pose.
const CYCLE_EDGE_TOLERANCE = 1e-10;

/** Splits a time offset into whole cycles and the time inside the cycle, snapping a time a hair before a cycle start to that start. */
export function splitIntoCycles(offset, length) {
  let cycle = Math.floor(offset / length);
  let local = Math.max(0, offset - cycle * length);
  if (length - local <= CYCLE_EDGE_TOLERANCE) {
    cycle += 1;
    local = 0;
  }
  return { cycle, local };
}

function normalizedTime(clip, time) {
  if (!Number.isFinite(time)) throw new TypeError('Animation time must be finite.');
  // A clip that does not loop passes the time through: keyframes lie within the duration, so tracks hold their ends anyway, and extrapolation and cycles need the time past them.
  if (!clip.loop) return time;
  return splitIntoCycles(time, clip.duration).local;
}

export function sampleAnimationClip(clip, time) {
  const clipTime = normalizedTime(clip, time);
  return clip.tracks.map(track => {
    const output = sampleTrack(track, clipTime, new Float64Array(PROPERTY_SIZES[track.property]));
    const value = output.length === 1 ? output[0] : Array.from(output);
    return { target: track.target, property: track.property, value };
  });
}

/** Internal compiled sampler for retained mixer buffers; not a package entry point. */
export function compileAnimationSampler(clip) {
  const tracks = clip.tracks.map(track => ({
    target: track.target,
    property: track.property,
    output: new Float64Array(PROPERTY_SIZES[track.property]),
  }));
  return {
    tracks,
    sample(time) {
      const clipTime = normalizedTime(clip, time);
      for (let index = 0; index < tracks.length; index++) {
        sampleTrack(clip.tracks[index], clipTime, tracks[index].output);
      }
      return tracks;
    },
  };
}

/** Bind once before playback. Matrix identities and untracked initial components stay stable. */
export function createAnimationPlayer(clip, parts) {
  const namedParts = new Map();
  for (const part of parts) {
    if (namedParts.has(part.name)) throw new RangeError(`Duplicate animated part name: ${part.name}`);
    namedParts.set(part.name, part);
  }
  const bindings = new Map();
  const compiledTracks = [];
  for (const track of clip.tracks) {
    const part = namedParts.get(track.target);
    if (!part) throw new RangeError(`Animation target was not found: ${track.target}`);
    if (track.property === 'value') throw new RangeError('Value tracks are sampled directly, rather than bound to parts.');
    if (!bindings.has(track.target)) {
      if (!(part.matrix instanceof Float32Array) || part.matrix.length !== 16 || !Array.from(part.matrix).every(Number.isFinite)) {
        throw new TypeError('Animated parts need a finite Float32Array matrix.');
      }
      const translation = mat4.getTranslation(new Float64Array(3), part.matrix);
      const scale = mat4.getScaling(new Float64Array(3), part.matrix);
      if (Array.from(scale).some(value => value < Math.fround(MINIMUM_POSITIVE_VALUE))) throw new RangeError('Animated matrices must have nonzero scale.');
      const rotationMatrix = mat4.clone(part.matrix);
      for (let column = 0; column < 3; column++) {
        for (let row = 0; row < 3; row++) rotationMatrix[column * 4 + row] /= scale[column];
      }
      if (mat4.determinant(rotationMatrix) < 0.9999) throw new RangeError('Animated matrices must use rotation and positive scale without shear.');
      const rotation = quat.normalize(new Float64Array(4), mat4.getRotation(new Float64Array(4), rotationMatrix));
      bindings.set(track.target, { part, translation, scale, rotation, matrix: mat4.create(), hasTransform: false, material: null });
    }
    const binding = bindings.get(track.target);
    const materialTrack = MATERIAL_PROPERTIES.has(track.property);
    if (materialTrack && !binding.material) {
      const retained = isolatedMaterials.get(part);
      binding.material = retained && retained === part.material ? retained : { ...part.material };
    }
    if (!materialTrack) binding.hasTransform = true;
    const output = materialTrack ? new Float64Array(1) : binding[track.property];
    compiledTracks.push({ track, binding, output, materialTrack });
  }
  const compiledBindings = Array.from(bindings.values());
  for (const binding of compiledBindings) {
    if (binding.material) {
      binding.material = retainAnimationMaterial(binding.part, binding.material);
    }
  }
  return {
    clip,
    apply(time) {
      const clipTime = normalizedTime(clip, time);
      for (const compiled of compiledTracks) {
        sampleTrack(compiled.track, clipTime, compiled.output);
      }
      for (const binding of compiledBindings) {
        if (binding.hasTransform) {
          mat4.fromRotationTranslationScale(binding.matrix, binding.rotation, binding.translation, binding.scale);
          for (let index = 0; index < 16; index++) {
            if (!Number.isFinite(binding.matrix[index])) throw new RangeError('Animated matrix exceeds the finite float range. Reduce the transform values.');
          }
        }
      }
      // Commit only after every sample and composed matrix is valid.
      for (const compiled of compiledTracks) {
        if (compiled.materialTrack) compiled.binding.material[compiled.track.property] = compiled.output[0];
      }
      for (const binding of compiledBindings) {
        if (binding.hasTransform) binding.part.matrix.set(binding.matrix);
      }
      return parts;
    },
  };
}