Skip to content

3D engine that AI agents drive

14.0 KB
Raw Blame
import { mat4, quat, vec3 } from 'gl-matrix';
import { bakeEasedKeyframes } from './animation.js';

// glTF has no easing, so an eased segment is written as this many linear pieces.
const EASING_BAKE_STEPS_PER_SEGMENT = 32;

const GLTF_PATHS = { translation: 'translation', rotation: 'rotation', scale: 'scale', weights: 'weights' };
const COMPONENTS_BY_PATH = { translation: 3, rotation: 4, scale: 3 };
const ACCESSOR_TYPE_BY_PATH = { translation: 'VEC3', rotation: 'VEC4', scale: 'VEC3', weights: 'SCALAR' };
const GLTF_STEP_INTERPOLATION = 2300;
const GLTF_LINEAR_INTERPOLATION = 2301;
const IDENTITY_ROTATION = [0, 0, 0, 1];

function transformFields(translation, rotation, scale) {
  const fields = {};
  if (translation.some(value => value !== 0)) fields.translation = Array.from(translation);
  if (rotation.some((value, index) => value !== IDENTITY_ROTATION[index])) fields.rotation = Array.from(rotation);
  if (scale.some(value => value !== 1)) fields.scale = Array.from(scale);
  return fields;
}

/**
 * Translation, rotation and scale of an affine matrix. gl-matrix's getRotation divides the wrong entries by the scale,
 * so under a non-uniform scale it returns a wrong rotation: the rotation is taken from the unit-length columns instead.
 * A mirrored matrix (negative determinant) keeps its reflection as a negative x scale, so the rotation stays proper.
 */
export function matrixFrame(matrix) {
  const translation = mat4.getTranslation(vec3.create(), matrix);
  const scale = mat4.getScaling(vec3.create(), matrix);
  if (mat4.determinant(matrix) < 0) scale[0] = -scale[0];
  const unitColumns = [0, 4, 8].flatMap((offset, column) => {
    const axisScale = scale[column] || 1;
    return [matrix[offset] / axisScale, matrix[offset + 1] / axisScale, matrix[offset + 2] / axisScale];
  });
  const rotation = quat.normalize(quat.create(), quat.fromMat3(quat.create(), unitColumns));
  return { translation, rotation, scale };
}

/** Split an affine matrix into glTF translation, rotation and scale fields. */
export function decomposeMatrix(matrix) {
  const { translation, rotation, scale } = matrixFrame(matrix);
  return transformFields(translation, rotation, scale);
}

function composeFields(record) {
  return mat4.fromRotationTranslationScale(mat4.create(), record.rotation ?? IDENTITY_ROTATION, record.translation ?? [0, 0, 0], record.scale ?? [1, 1, 1]);
}

function worldMatrixOf(index, nodes, cache) {
  if (cache.has(index)) return cache.get(index);
  const node = nodes[index];
  const local = composeFields(node);
  const world = node.parent >= 0 ? mat4.multiply(mat4.create(), worldMatrixOf(node.parent, nodes, cache), local) : local;
  cache.set(index, world);
  return world;
}

/** Hierarchy records from `options.nodes` (the `nodes` of a parsed asset, or the same fields): name, id, parent id. */
function nodesFromRecords(records) {
  const indexById = new Map(records.map((record, index) => [record.id ?? record.name, index]));
  const nodes = records.map(record => {
    if (typeof record.name !== 'string' || !record.name) throw new TypeError('GLB nodes need a name.');
    const parent = record.parent === null || record.parent === undefined ? -1 : indexById.get(record.parent);
    if (parent === undefined) throw new RangeError(`GLB node ${record.name} names a parent that is not in the node list.`);
    return { name: record.name, parent, translation: record.translation, rotation: record.rotation, scale: record.scale, meshIds: record.meshIds ?? [] };
  });
  requireNoParentLoop(nodes);
  return nodes;
}

function requireNoParentLoop(nodes) {
  for (const node of nodes) {
    let ancestor = node.parent;
    for (let step = 0; ancestor >= 0 && step < nodes.length; step++) ancestor = nodes[ancestor].parent;
    if (ancestor >= 0) throw new RangeError(`GLB node ${node.name} has a parent loop.`);
  }
}

function jointWorld(skin, joint) {
  return skin.jointWorldMatrices.subarray(joint * 16, joint * 16 + 16);
}

function requireSkinFields(skin, partName) {
  const jointCount = skin.joints?.length;
  if (!Array.isArray(skin.joints) || skin.inverseBindMatrices?.length !== jointCount * 16 || skin.jointWorldMatrices?.length !== jointCount * 16) {
    throw new TypeError(`GLB part ${partName} has a skin without joints, inverseBindMatrices and jointWorldMatrices. Use the skin that parseGltf returned, or give each joint a name and parent.`);
  }
}

/** Joint nodes derived from the skin's current joint world matrices, for skins built without a node list. */
function appendDerivedJoints(nodes, skin) {
  const indexByJoint = skin.joints.map(joint => {
    const existing = nodes.findIndex(node => node.name === joint.name);
    return existing >= 0 ? existing : -1;
  });
  skin.joints.forEach((joint, jointIndex) => {
    if (indexByJoint[jointIndex] >= 0) return;
    const parentJoint = joint.parent ?? -1;
    const world = jointWorld(skin, jointIndex);
    const parentWorld = parentJoint >= 0 ? jointWorld(skin, parentJoint) : null;
    const local = parentWorld ? mat4.multiply(mat4.create(), mat4.invert(mat4.create(), parentWorld), world) : world;
    const fields = decomposeMatrix(local);
    indexByJoint[jointIndex] = nodes.length;
    nodes.push({ name: joint.name, parent: -1, ...fields, meshIds: [], derivedParentJoint: parentJoint });
  });
  skin.joints.forEach((joint, jointIndex) => {
    const node = nodes[indexByJoint[jointIndex]];
    if (node.derivedParentJoint !== undefined) node.parent = node.derivedParentJoint >= 0 ? indexByJoint[node.derivedParentJoint] : -1;
  });
}

/**
 * The hierarchy of joint and group nodes: the records of `options.nodes` when given, otherwise one node per skin joint.
 * Each entry holds name, parent index, local TRS fields and the `mesh-N` ids it carries.
 */
export function buildHierarchy(parts, nodeRecords) {
  const nodes = nodeRecords ? nodesFromRecords(nodeRecords) : [];
  for (const part of parts) {
    if (!part.skin) continue;
    requireSkinFields(part.skin, part.name);
    const missing = part.skin.joints.find(joint => !nodes.some(node => node.name === joint.name));
    if (missing && nodeRecords) {
      throw new RangeError(`GLB skin joint ${missing.name} of part ${part.name} is not in options.nodes. Pass the nodes of the same parsed asset.`);
    }
    if (!nodeRecords) appendDerivedJoints(nodes, part.skin);
  }
  return nodes;
}

/** Where each part hangs: the hierarchy node whose meshIds lists it, with its matrix made relative to that node. */
export function hostOfPart(partIndex, hierarchy, worldCache) {
  const host = hierarchy.findIndex(node => node.meshIds.includes(`mesh-${partIndex}`));
  if (host < 0) return null;
  return { index: host, world: worldMatrixOf(host, hierarchy, worldCache) };
}

export function relativeMatrix(partMatrix, hostWorld) {
  return mat4.multiply(mat4.create(), mat4.invert(mat4.create(), hostWorld), partMatrix);
}

export function hierarchyNodeFields(node) {
  return transformFields(node.translation ?? [0, 0, 0], node.rotation ?? IDENTITY_ROTATION, node.scale ?? [1, 1, 1]);
}

/** glTF skin for a part: inverse bind matrices fold in the bind matrix, so joint world * matrix * vertex is the pose. */
export function writeSkin(writer, skin, nodeIndexByName, cache) {
  if (cache.has(skin)) return cache.get(skin);
  const count = skin.joints.length;
  const matrices = new Float32Array(count * 16);
  const bind = skin.bindMatrix ?? mat4.create();
  for (let joint = 0; joint < count; joint++) {
    const inverseBind = skin.inverseBindMatrices.subarray(joint * 16, joint * 16 + 16);
    matrices.set(mat4.multiply(mat4.create(), inverseBind, bind), joint * 16);
  }
  writer.document.skins ??= [];
  writer.document.skins.push({
    joints: skin.joints.map(joint => nodeIndexByName.get(joint.name)),
    inverseBindMatrices: writer.addAccessor(matrices, 'MAT4', undefined, { bounds: false }),
  });
  cache.set(skin, writer.document.skins.length - 1);
  return writer.document.skins.length - 1;
}

/** Skin weights as glTF wants them: four joints per vertex, summing to one. */
export function normalizedWeights(weights) {
  const result = new Float32Array(weights.length);
  for (let vertex = 0; vertex < weights.length; vertex += 4) {
    const total = weights[vertex] + weights[vertex + 1] + weights[vertex + 2] + weights[vertex + 3];
    for (let influence = 0; influence < 4; influence++) result[vertex + influence] = weights[vertex + influence] / total;
  }
  return result;
}

// A weights keyframe holds one value per morph target, so its width comes from the keyframes.
function componentCount(track) {
  if (track.property !== 'weights') return COMPONENTS_BY_PATH[track.property];
  const count = track.keyframes[0].value.length;
  const consistent = track.keyframes.every(keyframe => keyframe.value.length === count && Array.from(keyframe.value).every(Number.isFinite));
  if (!count || !consistent) {
    throw new RangeError(`GLB weights track on ${track.target} needs the same nonzero count of finite weights in every keyframe.`);
  }
  return count;
}

function trackOutput(track) {
  const zero = new Array(componentCount(track)).fill(0);
  const rows = [];
  for (const keyframe of track.keyframes) {
    const value = Array.isArray(keyframe.value) ? keyframe.value : Array.from(keyframe.value);
    if (track.interpolation === 'CUBICSPLINE') rows.push(Array.from(keyframe.inTangent), value, Array.from(keyframe.outTangent));
    // SMOOTH eases each segment with smoothstep, which is a cubic Hermite segment with zero tangents.
    else if (track.interpolation === 'SMOOTH') rows.push(zero, value, zero);
    else rows.push(value);
  }
  return Float32Array.from(rows.flat());
}

const GLTF_INTERPOLATION = { LINEAR: 'LINEAR', STEP: 'STEP', SMOOTH: 'CUBICSPLINE', CUBICSPLINE: 'CUBICSPLINE' };

// glTF needs strictly increasing finite times and finite values of the path's width; anything else makes a file loaders reject or misread.
function validateKeyframes(track) {
  const keyframes = track.keyframes;
  let previousTime = -Infinity;
  const timesValid = keyframes?.length > 0 && keyframes.every(({ time }) => time > previousTime && Number.isFinite(previousTime = time));
  const valuesValid = keyframes?.every(({ value }) => Array.from(value).every(Number.isFinite));
  if (!timesValid || !valuesValid) throw new RangeError(`GLB ${track.property} track on ${track.target} needs keyframes with finite values and strictly increasing finite times.`);
  const fixedWidth = COMPONENTS_BY_PATH[track.property];
  const width = fixedWidth ?? keyframes[0].value.length;
  const sized = (list, size) => list?.length === size && Array.from(list).every(Number.isFinite);
  const cubic = track.interpolation === 'CUBICSPLINE';
  if (!keyframes.every(({ value, inTangent, outTangent }) => (!fixedWidth || value.length === width) && (!cubic || (sized(inTangent, width) && sized(outTangent, width))))) {
    throw new RangeError(`GLB ${track.property} track on ${track.target} needs ${width} values${cubic ? ' and tangents' : ''} in every keyframe.`);
  }
}

function writeTrack(writer, animation, sourceTrack, nodeIndex) {
  validateKeyframes(sourceTrack);
  const bakedKeyframes = bakeEasedKeyframes(sourceTrack, EASING_BAKE_STEPS_PER_SEGMENT);
  const track = bakedKeyframes === sourceTrack.keyframes ? sourceTrack : { ...sourceTrack, keyframes: bakedKeyframes, interpolation: 'LINEAR' };
  const path = GLTF_PATHS[track.property];
  if (!path) {
    throw new RangeError(`GLB export cannot write ${track.property} tracks (target ${track.target}). Only translation, rotation, scale and weights tracks are exported; remove the others from the clip.`);
  }
  const times = Float32Array.from(track.keyframes, keyframe => keyframe.time);
  animation.samplers.push({
    input: writer.addAccessor(times, 'SCALAR', undefined, { bounds: true }),
    output: writer.addAccessor(trackOutput(track), ACCESSOR_TYPE_BY_PATH[track.property], undefined, { bounds: false }),
    interpolation: GLTF_INTERPOLATION[track.interpolation ?? 'LINEAR'],
  });
  animation.channels.push({ sampler: animation.samplers.length - 1, target: { node: nodeIndex, path } });
}

/** Clips in createAnimationClip form; track targets are node names. */
export function writeAnimations(writer, clips, nodeIndexByName, prepareNodeForAnimation) {
  writer.document.animations = [];
  clips.forEach((clip, clipIndex) => {
    if (!Array.isArray(clip?.tracks) || !clip.tracks.length) throw new TypeError(`GLB clip ${clipIndex} needs tracks. Build it with createAnimationClip or clipFromGltfAnimation.`);
    const animation = { name: clip.name ?? `clip ${clipIndex}`, samplers: [], channels: [] };
    for (const track of clip.tracks) {
      const nodeIndex = nodeIndexByName.get(track.target);
      if (nodeIndex === undefined) {
        throw new RangeError(`GLB clip ${animation.name} targets ${track.target}, which is no exported node. Pass options.nodes from the parsed asset, or name a part or joint.`);
      }
      prepareNodeForAnimation(nodeIndex);
      writeTrack(writer, animation, track, nodeIndex);
    }
    writer.document.animations.push(animation);
  });
}

/**
 * Morph weight tracks of an imported animation (`asset.animations[n]`) in clip form. clipFromGltfAnimation skips them,
 * because the mixer samples only fixed-size properties. Cubic weight keys fail instead of silently changing shape.
 */
export function weightTracksFromGltfAnimation(animation) {
  const tracks = [];
  for (const track of animation.tracks) {
    const separator = track.name.lastIndexOf('.');
    if (track.name.slice(separator + 1) !== 'morphTargetInfluences') continue;
    const target = track.name.slice(0, separator);
    const interpolation = track.getInterpolation?.();
    if (interpolation !== GLTF_LINEAR_INTERPOLATION && interpolation !== GLTF_STEP_INTERPOLATION) {
      throw new RangeError(`GLB export cannot write cubic morph weights on ${target}. Re-key them as linear or step.`);
    }
    const width = track.values.length / track.times.length;
    tracks.push({
      target,
      property: 'weights',
      interpolation: interpolation === GLTF_STEP_INTERPOLATION ? 'STEP' : 'LINEAR',
      keyframes: Array.from(track.times, (time, index) => ({ time, value: Array.from(track.values.subarray(index * width, (index + 1) * width)) })),
    });
  }
  return tracks;
}