Skip to content

3D engine that AI agents drive

57.1 KB
Raw Blame
import { mat4, quat, vec3 } from 'gl-matrix';
import { compileAnimationSampler, createAnimationClip } from './animation.js';
import { updateSkinPose } from './skinning.js';
import { eulerFromQuaternion, quaternionFromEuler } from './rotation-euler.js';
import {
  bindSourceTracks, computeWorldPose, createPoseState, createRigFromSkin, mapHumanoidBones, prepareRigGeometry, validateRigJoints,
} from './retarget.js';

// Layered skeletal poses with inverse kinematics. Each apply(time) rebuilds the whole pose from the rest pose, in order:
// clip layers, then IK solvers. Nothing carries over between calls, so seeking backward gives the same pose as playing
// forward. Quaternions are XYZW; IK targets and poles are in the rig's world space.

const NEAR_ZERO = 1e-9;
// A two-bone target closer to the root than this fraction of the limb's length warns that it sits on the root.
const ROOT_TARGET_FRACTION = 1e-3;
const TO_RADIANS =Math.PI / 180;
const IDENTITY_ROTATION = Object.freeze([0, 0, 0, 1]);

function jointResolver(rig, prepared) {
  const names = rig.joints.map(joint => joint.name);
  const canonical = rig.mapping ?? mapHumanoidBones(names).mapping;
  return function resolveJoint(name, label) {
    const jointName = prepared.indexByName.has(name) ? name : canonical[name];
    const index = prepared.indexByName.get(jointName);
    if (index === undefined) {
      const shown = names.slice(0, 12).join(', ');
      throw new RangeError(`${label}: joint ${name} is not in the rig. Use a joint name or a humanoid bone such as leftUpperArm. Joints: ${shown}${names.length > 12 ? ', ...' : ''}`);
    }
    return index;
  };
}

function descendantsOf(prepared, roots) {
  const inside = new Uint8Array(prepared.joints.length);
  for (const root of roots) inside[root] = 1;
  for (const index of prepared.order) {
    const parent = prepared.joints[index].parent;
    if (parent >= 0 && inside[parent]) inside[index] = 1;
  }
  return inside;
}

/** Per-joint layer weights from { joints, descendants = true, exclude }. Without a mask every joint counts fully. */
function maskWeights(prepared, resolveJoint, mask) {
  const weights = new Float64Array(prepared.joints.length);
  if (!mask) return weights.fill(1);
  if (!Array.isArray(mask.joints) || !mask.joints.length) throw new TypeError('A layer mask needs joints: a non-empty list of joint or bone names.');
  const included = mask.joints.map(name => resolveJoint(name, 'Layer mask'));
  if (mask.descendants === false) {
    for (const index of included) weights[index] = 1;
  } else {
    weights.set(descendantsOf(prepared, included));
  }
  if (mask.exclude) {
    const removed = descendantsOf(prepared, mask.exclude.map(name => resolveJoint(name, 'Layer mask exclude')));
    removed.forEach((flag, index) => {
      if (flag) weights[index] = 0;
    });
  }
  return weights;
}

function weightFunction(value, label) {
  if (typeof value === 'function') return value;
  if (!Number.isFinite(value) || value < 0 || value > 1) throw new RangeError(`${label} must be from 0 to 1, or a function of time.`);
  return () => value;
}

function checkedWeight(weight, time, label) {
  const value = weight(time);
  if (!Number.isFinite(value) || value < 0 || value > 1) throw new RangeError(`${label} returned ${value} at time ${time}; it must be from 0 to 1.`);
  return value;
}

function checkedReferenceTime(reference, label) {
  const referenceTime = reference ?? 0;
  if (!Number.isFinite(referenceTime)) throw new RangeError(`${label} reference must be a clip time in seconds.`);
  return referenceTime;
}

function createLayer(definition, position, prepared, resolveJoint) {
  const label = `Layer ${position}`;
  if (!definition?.clip) throw new TypeError(`${label} needs a clip from createAnimationClip.`);
  const sampler = compileAnimationSampler(definition.clip);
  const bindings = bindSourceTracks(sampler, prepared);
  if (!bindings.length) throw new RangeError(`${label}: no clip track names a joint of this rig.`);
  const additive = definition.additive === true;
  const referenceTime = checkedReferenceTime(definition.reference, label);
  let references = [];
  if (additive) {
    sampler.sample(referenceTime);
    references = bindings.map(binding => Float64Array.from(binding.output));
  }
  const speed = definition.speed ?? 1;
  const offset = definition.offset ?? 0;
  if (!Number.isFinite(speed) || !Number.isFinite(offset)) throw new RangeError(`${label} speed and offset must be finite.`);
  if (definition.clipTime !== undefined && typeof definition.clipTime !== 'function') throw new TypeError(`${label} clipTime must be a function from motion time to clip time.`);
  return {
    label, sampler, bindings, additive, references, speed, offset, clipTime: definition.clipTime,
    weight: weightFunction(definition.weight ?? 1, `${label} weight`),
    mask: maskWeights(prepared, resolveJoint, definition.mask),
  };
}

const scratchDelta = new Float64Array(4);
const scratchInverse = new Float64Array(4);

function applyAdditiveRotation(rotation, sample, reference, weight) {
  // delta = inverse(reference) * sample, applied in the joint's own frame: local = local * delta.
  quat.multiply(scratchDelta, quat.invert(scratchInverse, reference), sample);
  quat.slerp(scratchDelta, IDENTITY_ROTATION, scratchDelta, weight);
  quat.normalize(rotation, quat.multiply(rotation, rotation, scratchDelta));
}

/** Clip time of a layer: its `clipTime(time)` when it has one (a strip), else `time * speed + offset`. */
function layerClipTime(layer, time) {
  const clipTime = layer.clipTime ? layer.clipTime(time) : time * layer.speed + layer.offset;
  if (!Number.isFinite(clipTime)) throw new RangeError(`${layer.label} clip time must be finite at time ${time}.`);
  return clipTime;
}

function applyLayer(layer, time, localRotations, localTranslations) {
  const layerWeight = checkedWeight(layer.weight, time, `${layer.label} weight`);
  if (layerWeight === 0) return;
  layer.sampler.sample(layerClipTime(layer, time));
  layer.bindings.forEach((binding, slot) => {
    const weight = layerWeight * layer.mask[binding.index];
    if (weight === 0) return;
    if (binding.property === 'rotation') {
      const rotation = localRotations[binding.index];
      if (layer.additive) {
        applyAdditiveRotation(rotation, binding.output, layer.references[slot], weight);
      } else {
        quat.normalize(rotation, quat.slerp(rotation, rotation, binding.output, weight));
      }
      return;
    }
    const translation = localTranslations[binding.index];
    for (let axis = 0; axis < 3; axis++) {
      if (layer.additive) {
        translation[axis] += (binding.output[axis] - layer.references[slot][axis]) * weight;
      } else {
        translation[axis] += (binding.output[axis] - translation[axis]) * weight;
      }
    }
  });
}

function isDescendant(prepared, index, ancestor) {
  let current = prepared.joints[index].parent;
  while (current >= 0) {
    if (current === ancestor) return true;
    current = prepared.joints[current].parent;
  }
  return false;
}

function checkedVector(value, label) {
  if (value?.length !== 3 || !Number.isFinite(value[0]) || !Number.isFinite(value[1]) || !Number.isFinite(value[2])) {
    throw new RangeError(`${label} must be three finite numbers.`);
  }
  return value;
}

/** A direction as a unit vector. A zero vector has no direction, so it is refused rather than turned into a silent no-op. */
function checkedDirection(value, label) {
  const direction = vec3.normalize(new Float64Array(3), checkedVector(value, label));
  if (vec3.squaredLength(direction) === 0) throw new RangeError(`${label} must not be the zero vector. Pass a direction such as [0, 0, 1].`);
  return direction;
}

const LIMIT_AXES = ['x', 'y', 'z'];
// The solver stops just short of full stretch (a 2 to 3 degree bend), so a locked limb reads as about 177 degrees.
const HYPEREXTENSION_ANGLE = 175 * TO_RADIANS;
const MIN_BEND_FRACTION = 0.01;
const MIN_REST_BEND_FRACTION = 0.02;

/**
 * Joint limits from { root: { x: [min, max], y, z }, middle: {...} } in degrees. Angles are the joint's turn away from its
 * rest rotation, in its own axes, as Euler XYZ (the order Blender uses). An axis left out is free.
 */
function createJointLimits(definition, label, jointIndices, prepared, roleHint = 'root or middle') {
  if (definition === undefined) return [];
  if (!definition || typeof definition !== 'object' || Array.isArray(definition)) throw new TypeError(`${label} limits must be { ${roleHint} } with an x, y or z range each.`);
  return Object.entries(definition).map(([role, axes]) => {
    if (!Object.hasOwn(jointIndices, role)) throw new RangeError(`${label} limits: ${role} must be ${roleHint}.`);
    const unknownAxis = Object.keys(axes ?? {}).find(axis => !LIMIT_AXES.includes(axis));
    if (unknownAxis !== undefined) throw new RangeError(`${label} limits ${role}: ${unknownAxis} must be x, y or z.`);
    const ranges = LIMIT_AXES.map(axis => {
      const range = axes[axis];
      if (range === undefined) return null;
      if (!Array.isArray(range) || range.length !== 2 || !range.every(Number.isFinite) || range[0] > range[1] || range[0] < -180 || range[1] > 180) {
        throw new RangeError(`${label} limits ${role}.${axis} must be [min, max] degrees within -180 and 180, min first.`);
      }
      return range.map(degrees => degrees * TO_RADIANS);
    });
    const index = jointIndices[role];
    return { index, name: prepared.joints[index].name, ranges };
  });
}

function resolveChainJoints(definition, label, prepared, resolveJoint) {
  let joints;
  let names;
  if (definition.chain !== undefined) {
    if (!Array.isArray(definition.chain) || definition.chain.length < 2 || definition.chain.length > 64) {
      throw new RangeError(`${label} chain must list 2 to 64 joints from base to end.`);
    }
    names = definition.chain;
    joints = names.map(name => resolveJoint(name, label));
    joints.slice(1).forEach((joint, slot) => {
      if (!isDescendant(prepared, joint, joints[slot])) {
        throw new RangeError(`${label}: each chain joint must descend from the one before it.`);
      }
    });
  } else if (definition.root !== undefined && definition.end !== undefined) {
    const root = resolveJoint(definition.root, label);
    const end = resolveJoint(definition.end, label);
    if (!isDescendant(prepared, end, root)) {
      throw new RangeError(`${label}: end must descend from root.`);
    }
    const chain = [];
    let current = end;
    while (current >= 0) {
      chain.push(current);
      if (current === root) break;
      current = prepared.joints[current].parent;
    }
    joints = chain.reverse();
    names = joints.map(index => prepared.joints[index].name);
  } else {
    throw new TypeError(`${label} needs chain (or root and end).`);
  }
  const segmentChildren = [];
  for (let slot = 0; slot < joints.length - 1; slot++) {
    const indices = [];
    let current = joints[slot + 1];
    while (current !== joints[slot]) {
      indices.push(current);
      current = prepared.joints[current].parent;
    }
    segmentChildren.push(indices);
  }
  return { joints, names, segmentChildren, stretchIndices: segmentChildren.flat() };
}

function normalizeStretch(value, defaultValue, label) {
  if (value === undefined) return defaultValue;
  if (typeof value === 'boolean') return value ? 1 : 0;
  if (!Number.isFinite(value) || value < 0 || value > 1) {
    throw new RangeError(`${label} stretch must be a boolean or a number from 0 to 1.`);
  }
  return value;
}

function checkedCurvePoints(points, label) {
  if (!Array.isArray(points) || points.length < 2 || points.length > 64) {
    throw new RangeError(`${label} curve must be 2 to 64 [x, y, z] points.`);
  }
  return points.map((point, index) => checkedVector(point, `${label} curve[${index}]`));
}

function roundedDegrees(radians) {
  return Number((radians / TO_RADIANS).toFixed(4));
}

/** Clamp each limited joint's local rotation. Returns one { joint, axis, requested, applied } (degrees) per change. */
function applyJointLimits(limits, prepared, localRotations) {
  const changes = [];
  for (const limit of limits) {
    const rest = prepared.restRotations[limit.index];
    const delta = quat.multiply(new Float64Array(4), quat.invert(new Float64Array(4), rest), localRotations[limit.index]);
    const angles = eulerFromQuaternion(delta);
    let changed = false;
    angles.forEach((angle, axis) => {
      const range = limit.ranges[axis];
      if (!range) return;
      const clamped = Math.min(range[1], Math.max(range[0], angle));
      if (Math.abs(clamped - angle) < 1e-9) return;
      changes.push({ joint: limit.name, axis: LIMIT_AXES[axis], requested: roundedDegrees(angle), applied: roundedDegrees(clamped) });
      angles[axis] = clamped;
      changed = true;
    });
    if (!changed) continue;
    quaternionFromEuler(delta, angles[0], angles[1], angles[2]);
    quat.normalize(localRotations[limit.index], quat.multiply(localRotations[limit.index], rest, delta));
  }
  return changes;
}

/** How far the middle joint sits off the straight line from root to end, as a vector. */
function bendVector(rootPosition, middlePosition, endPosition) {
  const line = vec3.subtract(new Float64Array(3), endPosition, rootPosition);
  const toMiddle = vec3.subtract(new Float64Array(3), middlePosition, rootPosition);
  const lineLengthSquared = vec3.squaredLength(line);
  if (lineLengthSquared < NEAR_ZERO) return toMiddle;
  return vec3.scaleAndAdd(toMiddle, toMiddle, line, -vec3.dot(toMiddle, line) / lineLengthSquared);
}

/** The side the limb bent toward at rest, in the frame of the joint above the root. Null when the rest limb is straight. */
function restBendInParentFrame(prepared, root, middle, end) {
  const { positions, rotations } = prepared.restWorld;
  const bend = bendVector(positions[root], positions[middle], positions[end]);
  const chainLength = vec3.distance(positions[root], positions[middle]) + vec3.distance(positions[middle], positions[end]);
  if (vec3.length(bend) < chainLength * MIN_REST_BEND_FRACTION) return null;
  const parent = prepared.joints[root].parent;
  const parentRotation = parent >= 0 ? rotations[parent] : prepared.rootRotation;
  return vec3.transformQuat(new Float64Array(3), bend, quat.invert(new Float64Array(4), parentRotation));
}

/** Sanity checks on a solved limb: locked straight, or bent the opposite way to its natural direction. */
function bendWarnings(solver, state, prepared) {
  const warnings = [];
  const rootPosition = state.positions[solver.root];
  const middlePosition = state.positions[solver.middle];
  const endPosition = state.positions[solver.end];
  const interiorAngle = vec3.angle(vec3.subtract(new Float64Array(3), rootPosition, middlePosition), vec3.subtract(new Float64Array(3), endPosition, middlePosition));
  if (interiorAngle > HYPEREXTENSION_ANGLE) {
    warnings.push({ code: 'hyperextended', message: `${prepared.joints[solver.middle].name} is locked straight (${roundedDegrees(interiorAngle)} degrees). The target is at or beyond the limb's reach, so a real joint would hyperextend.` });
  }
  let expected = solver.bendToward;
  if (!expected && solver.restBend) {
    const parent = prepared.joints[solver.root].parent;
    expected = vec3.transformQuat(new Float64Array(3), solver.restBend, parent >= 0 ? state.rotations[parent] : prepared.rootRotation);
  }
  if (!expected) return warnings;
  const bend = bendVector(rootPosition, middlePosition, endPosition);
  const chainLength = vec3.distance(rootPosition, middlePosition) + vec3.distance(middlePosition, endPosition);
  if (vec3.length(bend) >= chainLength * MIN_BEND_FRACTION && vec3.dot(bend, expected) < 0) {
    warnings.push({ code: 'wrong-bend', message: `${prepared.joints[solver.middle].name} bends away from its natural direction. Move the pole to the other side, or set bendToward.` });
  }
  return warnings;
}

/** A NaN or zero-quaternion rest value poses its joint and everything below as NaN, with no error. */
function checkRestValues(joints) {
  joints.forEach(({ name, translation, rotation, scale }) => {
    const finite = values => Array.from(values ?? []).every(Number.isFinite);
    if (!finite(translation) || !finite(rotation) || !finite(scale?.slice(0, 1)) || !Math.hypot(...rotation)) {
      throw new RangeError(`Pose rig joint ${name} needs finite translation and scale and a nonzero rotation, such as [0, 0, 0, 1].`);
    }
  });
}

function checkedCustomSolver(created, jointCount, label) {
  const validJoints = Array.isArray(created?.joints) && created.joints.every(index => index >= 0 && index < jointCount);
  if (!validJoints || typeof created.solve !== 'function') throw new TypeError(`${label} create must return { joints, solve } with rig joint indices.`);
  return created;
}

function createSolver(definition, position, prepared, resolveJoint) {
  const label = `IK ${position}`;
  if (!definition || typeof definition !== 'object') throw new TypeError(`${label} must be an object with a type.`);
  const weight = weightFunction(definition?.weight ?? 1, `${label} weight`);
  if (definition?.type === 'custom') {
    if (typeof definition.create !== 'function') throw new TypeError(`${label} type custom needs create(prepared, resolveJoint, label) => { joints, solve(time, context, weight) }.`);
    return { type: 'custom', label, weight, ...checkedCustomSolver(definition.create(prepared, resolveJoint, label), prepared.joints.length, label) };
  }
  const solverType = definition?.type === 'ik' ? 'chain' : definition?.type === 'spline_ik' ? 'spline' : definition?.type;
  if (solverType !== 'spline' && typeof definition?.target !== 'function') checkedVector(definition?.target, `${label} target`);
  if (definition.type === 'two-bone') {
    const root = resolveJoint(definition.root, label);
    const middle = resolveJoint(definition.middle, label);
    const end = resolveJoint(definition.end, label);
    if (!isDescendant(prepared, middle, root) || !isDescendant(prepared, end, middle)) {
      throw new RangeError(`${label}: end must descend from middle, and middle from root.`);
    }
    if (definition.pole !== undefined && typeof definition.pole !== 'function') checkedVector(definition.pole, `${label} pole`);
    const limits = createJointLimits(definition.limits, label, { root, middle }, prepared);
    const bendToward = definition.bendToward === undefined ? null : checkedDirection(definition.bendToward, `${label} bendToward`);
    if (definition.groundNormal !== undefined && typeof definition.groundNormal !== 'function') checkedVector(definition.groundNormal, `${label} groundNormal`);
    return {
      type: 'two-bone', label, weight, root, middle, end, target: definition.target, pole: definition.pole, limits, bendToward,
      groundNormal: definition.groundNormal,
      // A foot's sole faces up at rest, so this is where "up" sits in the end joint's own frame.
      endUp: vec3.transformQuat(new Float64Array(3), [0, 1, 0], quat.invert(new Float64Array(4), prepared.restWorld.rotations[end])),
      restBend: restBendInParentFrame(prepared, root, middle, end),
      keepEndRotation: definition.keepEndRotation !== false,
    };
  }
  if (definition.type === 'aim') {
    const names = definition.joints ?? (definition.joint === undefined ? [] : [definition.joint]);
    if (!Array.isArray(names)) throw new TypeError(`${label} joints must be a list of joint names.`);
    if (!names.length) throw new TypeError(`${label} needs joint, or joints listed from the base of the chain to the aiming joint.`);
    const joints = names.map(name => resolveJoint(name, label));
    joints.slice(1).forEach((joint, slot) => {
      if (!isDescendant(prepared, joint, joints[slot])) throw new RangeError(`${label}: list joints from the base of the chain to the aiming joint.`);
    });
    if (definition.forward !== undefined && definition.worldForward !== undefined) throw new TypeError(`${label} takes forward or worldForward, not both.`);
    const forward = checkedDirection(definition.forward ?? definition.worldForward ?? [0, 0, 1], `${label} forward`);
    if (definition.worldForward !== undefined) {
      // Bone axes differ by rig, but which way a character faces at rest does not: bring that direction into the joint.
      const restRotation = prepared.restWorld.rotations[joints[joints.length - 1]];
      vec3.transformQuat(forward, forward, quat.invert(new Float64Array(4), restRotation));
    }
    const maxAngle = definition.maxAngle ?? 180;
    if (!Number.isFinite(maxAngle) || maxAngle <= 0) throw new RangeError(`${label} maxAngle must be a positive number of degrees.`);
    return { type: 'aim', label, weight, joints, forward, maxRadians: maxAngle * TO_RADIANS, target: definition.target };
  }
  if (solverType === 'chain') {
    const { joints, names, segmentChildren, stretchIndices } = resolveChainJoints(definition, label, prepared, resolveJoint);
    if (definition.pole !== undefined && typeof definition.pole !== 'function') checkedVector(definition.pole, `${label} pole`);
    const poleAngle = definition.poleAngle ?? 0;
    if (!Number.isFinite(poleAngle) || poleAngle < -180 || poleAngle > 180) {
      throw new RangeError(`${label} poleAngle must be degrees from -180 to 180.`);
    }
    const stretch = normalizeStretch(definition.stretch, 0, label);
    const iterations = definition.iterations ?? 16;
    if (!Number.isInteger(iterations) || iterations < 1 || iterations > 64) {
      throw new RangeError(`${label} iterations must be a whole number from 1 to 64.`);
    }
    const limitJoints = {};
    joints.slice(0, -1).forEach((index, slot) => {
      limitJoints[names[slot]] = index;
      limitJoints[prepared.joints[index].name] = index;
    });
    const limits = createJointLimits(definition.limits, label, limitJoints, prepared, 'a joint in the chain');
    return {
      type: 'chain', label, weight, joints, segmentChildren, stretchIndices,
      target: definition.target, pole: definition.pole, poleRadians: poleAngle * TO_RADIANS,
      stretch, iterations, limits, keepEndRotation: definition.keepEndRotation !== false,
    };
  }
  if (solverType === 'spline') {
    const { joints, segmentChildren, stretchIndices } = resolveChainJoints(definition, label, prepared, resolveJoint);
    if (typeof definition.curve !== 'function') checkedCurvePoints(definition.curve, label);
    const stretch = normalizeStretch(definition.stretch, 1, label);
    return {
      type: 'spline', label, weight, joints, segmentChildren, stretchIndices,
      curve: definition.curve, stretch,
    };
  }
  throw new RangeError(`${label} type must be two-bone, aim, chain or spline.`);
}

function resolvedPoint(value, time, reference, label) {
  return checkedVector(typeof value === 'function' ? value(time, Array.from(reference)) : value, label);
}

function perpendicularTo(direction) {
  const reference = Math.abs(direction[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];
  return vec3.normalize(new Float64Array(3), vec3.cross(new Float64Array(3), direction, reference));
}

function createSolverContext(prepared, state, localRotations, localTranslations) {
  const update = () => computeWorldPose(prepared, state, localRotations, localTranslations);
  const scratch = new Float64Array(4);
  // Give a joint a new world rotation, faded in by weight against the local rotation it has now.
  function setWorldRotation(index, worldRotation, weight) {
    const parent = prepared.joints[index].parent;
    const parentRotation = parent >= 0 ? state.rotations[parent] : prepared.rootRotation;
    quat.multiply(scratch, quat.invert(new Float64Array(4), parentRotation), worldRotation);
    quat.normalize(localRotations[index], quat.slerp(localRotations[index], localRotations[index], scratch, weight));
    update();
  }
  return { state, prepared, localRotations, localTranslations, update, setWorldRotation };
}

/**
 * Analytic two-bone IK. Places the middle joint in the plane of the target and the pole (or of the current bend), then
 * turns the two upper joints with the shortest rotations, so twist already in the pose survives.
 */
function solveTwoBone(solver, time, context) {
  const { state, prepared, localRotations, update, setWorldRotation } = context;
  const weight = checkedWeight(solver.weight, time, `${solver.label} weight`);
  const endPosition = state.positions[solver.end];
  const target = resolvedPoint(solver.target, time, endPosition, `${solver.label} target`);
  if (weight === 0) return { reached: true, error: 0, warnings: [], limited: [] };
  const rootPosition = Float64Array.from(state.positions[solver.root]);
  const middlePosition = Float64Array.from(state.positions[solver.middle]);
  const startEnd = Float64Array.from(endPosition);
  const endRotation = Float64Array.from(state.rotations[solver.end]);
  const upperLength = vec3.distance(rootPosition, middlePosition);
  const lowerLength = vec3.distance(middlePosition, startEnd);
  const toTarget = vec3.subtract(new Float64Array(3), target, rootPosition);
  const targetDistance = vec3.length(toTarget);
  if (upperLength < NEAR_ZERO || lowerLength < NEAR_ZERO) {
    return { reached: false, error: vec3.distance(startEnd, target), warnings: [], limited: [] };
  }
  const direction = targetDistance < NEAR_ZERO
    ? foldDirection(rootPosition, middlePosition, startEnd)
    : vec3.scale(new Float64Array(3), toTarget, 1 / targetDistance);
  // Stop just short of the limits: a fully straight limb has no defined bend plane for the next frame.
  const margin = (upperLength + lowerLength) * 1e-4;
  const reachLimit = upperLength + lowerLength - margin;
  const reach = Math.min(reachLimit, Math.max(Math.abs(upperLength - lowerLength) + margin, targetDistance));
  const bendReference = solver.pole === undefined
    ? vec3.subtract(new Float64Array(3), middlePosition, rootPosition)
    : vec3.subtract(new Float64Array(3), resolvedPoint(solver.pole, time, middlePosition, `${solver.label} pole`), rootPosition);
  const alongTarget = vec3.dot(bendReference, direction);
  const bend = vec3.scaleAndAdd(new Float64Array(3), bendReference, direction, -alongTarget);
  if (vec3.length(bend) < NEAR_ZERO * Math.max(1, upperLength)) {
    vec3.copy(bend, perpendicularTo(direction));
  } else {
    vec3.normalize(bend, bend);
  }
  const alongLimb = (upperLength * upperLength - lowerLength * lowerLength + reach * reach) / (2 * reach);
  const height = Math.sqrt(Math.max(0, upperLength * upperLength - alongLimb * alongLimb));
  const newMiddle = vec3.scaleAndAdd(new Float64Array(3), rootPosition, direction, alongLimb);
  vec3.scaleAndAdd(newMiddle, newMiddle, bend, height);
  const newEnd = vec3.scaleAndAdd(new Float64Array(3), rootPosition, direction, reach);

  const upperFrom = vec3.normalize(new Float64Array(3), vec3.subtract(new Float64Array(3), middlePosition, rootPosition));
  const upperTo = vec3.normalize(new Float64Array(3), vec3.subtract(new Float64Array(3), newMiddle, rootPosition));
  const rootTurn = quat.rotationTo(new Float64Array(4), upperFrom, upperTo);
  const endAfterRoot = vec3.transformQuat(new Float64Array(3), vec3.subtract(new Float64Array(3), startEnd, rootPosition), rootTurn);
  vec3.add(endAfterRoot, endAfterRoot, rootPosition);
  const lowerFrom = vec3.normalize(new Float64Array(3), vec3.subtract(new Float64Array(3), endAfterRoot, newMiddle));
  const lowerTo = vec3.normalize(new Float64Array(3), vec3.subtract(new Float64Array(3), newEnd, newMiddle));
  const middleTurn = quat.rotationTo(new Float64Array(4), lowerFrom, lowerTo);

  const newRootRotation = quat.multiply(new Float64Array(4), rootTurn, state.rotations[solver.root]);
  const newMiddleRotation = quat.multiply(new Float64Array(4), middleTurn, quat.multiply(new Float64Array(4), rootTurn, state.rotations[solver.middle]));
  setWorldRotation(solver.root, newRootRotation, weight);
  setWorldRotation(solver.middle, newMiddleRotation, weight);
  const limited = applyJointLimits(solver.limits, prepared, localRotations);
  if (limited.length) update();
  if (solver.keepEndRotation) setWorldRotation(solver.end, endRotation, weight);
  if (solver.groundNormal !== undefined) {
    // Turn the end joint so its sole lies on the ground: its up axis goes to the normal by the shortest rotation.
    const normal = vec3.normalize(new Float64Array(3), resolvedPoint(solver.groundNormal, time, [0, 1, 0], `${solver.label} groundNormal`));
    const upNow = vec3.transformQuat(new Float64Array(3), solver.endUp, state.rotations[solver.end]);
    const turn = quat.rotationTo(new Float64Array(4), upNow, normal);
    setWorldRotation(solver.end, quat.multiply(new Float64Array(4), turn, state.rotations[solver.end]), weight);
  }
  const error = vec3.distance(state.positions[solver.end], target);
  const warnings = bendWarnings(solver, state, prepared);
  const rootTargetDistance = (upperLength + lowerLength) * ROOT_TARGET_FRACTION;
  if (targetDistance < rootTargetDistance) {
    warnings.unshift({ code: 'target-at-root', message: `The target is ${Number(targetDistance.toFixed(6))} m from ${prepared.joints[solver.root].name}, so the limb folds with no direction from the target. Move the target at least ${Number(rootTargetDistance.toFixed(4))} m off ${prepared.joints[solver.root].name}.` });
  }
  return { reached: error <= margin * 2 + NEAR_ZERO, error, warnings, limited };
}

/** Where a limb folds when the target sits on its root: along the way the end already points, else toward the middle joint. */
function foldDirection(rootPosition, middlePosition, endPosition) {
  const toEnd = vec3.subtract(new Float64Array(3), endPosition, rootPosition);
  if (vec3.length(toEnd) >= NEAR_ZERO) return vec3.normalize(toEnd, toEnd);
  const toMiddle = vec3.subtract(new Float64Array(3), middlePosition, rootPosition);
  return vec3.normalize(toMiddle, toMiddle);
}

/** Turn a joint, or a chain sharing the turn evenly, so its forward axis points at the target. */
function solveAim(solver, time, context) {
  const { state, setWorldRotation } = context;
  const weight = checkedWeight(solver.weight, time, `${solver.label} weight`);
  const aiming = solver.joints[solver.joints.length - 1];
  const target = resolvedPoint(solver.target, time, state.positions[aiming], `${solver.label} target`);
  if (weight === 0) return { reached: true, error: 0 };
  const forwardNow = () => vec3.transformQuat(new Float64Array(3), solver.forward, state.rotations[aiming]);
  const toTarget = vec3.subtract(new Float64Array(3), target, state.positions[aiming]);
  if (vec3.length(toTarget) < NEAR_ZERO) return { reached: false, error: Math.PI };
  vec3.normalize(toTarget, toTarget);
  const start = forwardNow();
  const totalTurn = quat.rotationTo(new Float64Array(4), start, toTarget);
  const totalAngle = 2 * Math.acos(Math.min(1, Math.abs(totalTurn[3])));
  // maxAngle limits the whole turn, so the chain ends up pointing along this direction when the target is too far around.
  const allowed = totalAngle > solver.maxRadians ? solver.maxRadians / totalAngle : 1;
  const limitedTurn = quat.slerp(new Float64Array(4), IDENTITY_ROTATION, totalTurn, allowed);
  const goal = vec3.transformQuat(new Float64Array(3), start, limitedTurn);
  solver.joints.forEach((joint, slot) => {
    const remaining = solver.joints.length - slot;
    const turn = quat.rotationTo(new Float64Array(4), forwardNow(), goal);
    quat.slerp(turn, IDENTITY_ROTATION, turn, 1 / remaining);
    setWorldRotation(joint, quat.multiply(new Float64Array(4), turn, state.rotations[joint]), weight);
  });
  const finalForward = forwardNow();
  const direct = vec3.subtract(new Float64Array(3), target, state.positions[aiming]);
  const error = vec3.angle(finalForward, direct);
  // A chain's own joints move as it turns, so about a degree is as close as one pass gets.
  return { reached: error < 0.02, error };
}

function sampleCatmullRomCurve(points, parameter) {
  const count = points.length;
  if (count === 2) return vec3.lerp(new Float64Array(3), points[0], points[1], parameter);
  const scaled = Math.max(0, Math.min(1, parameter)) * (count - 1);
  const segment = Math.min(count - 2, Math.floor(scaled));
  const localT = scaled - segment;
  const localT2 = localT * localT;
  const localT3 = localT2 * localT;
  const p1 = points[segment];
  const p2 = points[segment + 1];
  const p0 = segment > 0 ? points[segment - 1] : [2 * p1[0] - p2[0], 2 * p1[1] - p2[1], 2 * p1[2] - p2[2]];
  const p3 = segment + 2 < count ? points[segment + 2] : [2 * p2[0] - p1[0], 2 * p2[1] - p1[1], 2 * p2[2] - p1[2]];
  const out = new Float64Array(3);
  for (let axis = 0; axis < 3; axis++) {
    const a0 = -0.5 * p0[axis] + 1.5 * p1[axis] - 1.5 * p2[axis] + 0.5 * p3[axis];
    const a1 = p0[axis] - 2.5 * p1[axis] + 2 * p2[axis] - 0.5 * p3[axis];
    const a2 = -0.5 * p0[axis] + 0.5 * p2[axis];
    out[axis] = a0 * localT3 + a1 * localT2 + a2 * localT + p1[axis];
  }
  return out;
}

function buildSplineArcTable(points) {
  const steps = 128;
  const samples = Array.from({ length: steps + 1 }, (_, index) => sampleCatmullRomCurve(points, index / steps));
  const lengths = new Float64Array(steps + 1);
  for (let index = 1; index <= steps; index++) {
    lengths[index] = lengths[index - 1] + vec3.distance(samples[index - 1], samples[index]);
  }
  const totalLength = lengths[steps];
  const endTangent = vec3.subtract(new Float64Array(3), samples[steps], samples[steps - 1]);
  if (vec3.length(endTangent) > NEAR_ZERO) vec3.normalize(endTangent, endTangent);
  else endTangent[0] = 1;
  function pointAtDistance(distance) {
    if (distance <= 0 || totalLength <= NEAR_ZERO) return Float64Array.from(samples[0]);
    if (distance >= totalLength) {
      return vec3.scaleAndAdd(new Float64Array(3), samples[steps], endTangent, distance - totalLength);
    }
    let low = 0;
    let high = steps;
    while (low < high - 1) {
      const mid = (low + high) >> 1;
      if (lengths[mid] <= distance) low = mid;
      else high = mid;
    }
    const span = lengths[high] - lengths[low];
    const alpha = span > NEAR_ZERO ? (distance - lengths[low]) / span : 0;
    return vec3.lerp(new Float64Array(3), samples[low], samples[high], alpha);
  }
  return { totalLength, endTangent, pointAtDistance };
}

/** Multi-bone IK chain solved by cyclic coordinate descent with optional pole plane, poleAngle, stretch and joint limits. */
function solveChain(solver, time, context) {
  const { state, prepared, localRotations, update, setWorldRotation } = context;
  const weight = checkedWeight(solver.weight, time, `${solver.label} weight`);
  const end = solver.joints[solver.joints.length - 1];
  const target = resolvedPoint(solver.target, time, state.positions[end], `${solver.label} target`);
  if (weight === 0) return { reached: true, error: 0, warnings: [], limited: [] };
  const baseRotations = solver.joints.map(index => Float64Array.from(localRotations[index]));
  const baseTranslations = solver.stretchIndices.map(index => Float64Array.from(context.localTranslations[index]));
  const endRotation = Float64Array.from(state.rotations[end]);
  let totalLength = 0;
  for (let slot = 0; slot < solver.joints.length - 1; slot++) {
    totalLength += vec3.distance(state.positions[solver.joints[slot]], state.positions[solver.joints[slot + 1]]);
  }
  const rootPos = Float64Array.from(state.positions[solver.joints[0]]);
  const toTarget = vec3.subtract(new Float64Array(3), target, rootPos);
  const targetDistance = vec3.length(toTarget);
  if (targetDistance < NEAR_ZERO || totalLength < NEAR_ZERO) {
    return { reached: false, error: vec3.distance(state.positions[end], target), warnings: [], limited: [] };
  }
  if (solver.stretch > 0 && targetDistance > totalLength) {
    const scaleFactor = 1 + (targetDistance / totalLength - 1) * solver.stretch;
    for (const index of solver.stretchIndices) {
      vec3.scale(context.localTranslations[index], context.localTranslations[index], scaleFactor);
    }
    update();
    totalLength *= scaleFactor;
  }
  const axis = vec3.scale(new Float64Array(3), toTarget, 1 / targetDistance);
  if (solver.pole !== undefined) {
    const midJoint = solver.joints[Math.floor(solver.joints.length / 2)];
    const polePoint = resolvedPoint(solver.pole, time, state.positions[midJoint], `${solver.label} pole`);
    const toPole = vec3.subtract(new Float64Array(3), polePoint, rootPos);
    const polePerp = vec3.scaleAndAdd(new Float64Array(3), toPole, axis, -vec3.dot(toPole, axis));
    if (vec3.length(polePerp) < NEAR_ZERO) vec3.copy(polePerp, perpendicularTo(axis));
    else vec3.normalize(polePerp, polePerp);
    if (solver.poleRadians !== 0) {
      vec3.transformQuat(polePerp, polePerp, quat.setAxisAngle(new Float64Array(4), axis, solver.poleRadians));
    }
    const segmentCount = solver.joints.length - 1;
    for (let slot = 0; slot < segmentCount; slot++) {
      const joint = solver.joints[slot];
      const nextJoint = solver.joints[slot + 1];
      const curDir = vec3.subtract(new Float64Array(3), state.positions[nextJoint], state.positions[joint]);
      const curLen = vec3.length(curDir);
      if (curLen <= NEAR_ZERO) continue;
      vec3.scale(curDir, curDir, 1 / curLen);
      const arch = targetDistance < totalLength ? (0.5 - (slot + 0.5) / segmentCount) * 0.75 : 0;
      const aimDir = vec3.normalize(new Float64Array(3), vec3.scaleAndAdd(new Float64Array(3), axis, polePerp, arch));
      const turn = quat.rotationTo(new Float64Array(4), curDir, aimDir);
      setWorldRotation(joint, quat.multiply(new Float64Array(4), turn, state.rotations[joint]), 1);
    }
  }
  for (let iteration = 0; iteration < solver.iterations; iteration++) {
    for (let slot = solver.joints.length - 2; slot >= 0; slot--) {
      const joint = solver.joints[slot];
      const jointPos = state.positions[joint];
      const toEnd = vec3.subtract(new Float64Array(3), state.positions[end], jointPos);
      const toGoal = vec3.subtract(new Float64Array(3), target, jointPos);
      const endLen = vec3.length(toEnd);
      const goalLen = vec3.length(toGoal);
      if (endLen <= NEAR_ZERO || goalLen <= NEAR_ZERO) continue;
      vec3.scale(toEnd, toEnd, 1 / endLen);
      vec3.scale(toGoal, toGoal, 1 / goalLen);
      const turn = quat.rotationTo(new Float64Array(4), toEnd, toGoal);
      setWorldRotation(joint, quat.multiply(new Float64Array(4), turn, state.rotations[joint]), 1);
    }
    if (solver.limits.length && applyJointLimits(solver.limits, prepared, localRotations).length) update();
    if (vec3.distance(state.positions[end], target) <= 1e-6) break;
  }
  const limited = applyJointLimits(solver.limits, prepared, localRotations);
  if (limited.length) update();
  if (solver.keepEndRotation) setWorldRotation(end, endRotation, 1);
  if (weight < 1) {
    solver.joints.forEach((index, slot) => {
      quat.normalize(localRotations[index], quat.slerp(localRotations[index], baseRotations[slot], localRotations[index], weight));
    });
    solver.stretchIndices.forEach((index, slot) => {
      vec3.lerp(context.localTranslations[index], baseTranslations[slot], context.localTranslations[index], weight);
    });
    update();
  }
  const error = vec3.distance(state.positions[end], target);
  return { reached: error <= totalLength * 1e-3 + 1e-4, error, warnings: [], limited };
}

/** Spline IK along a Catmull-Rom curve, fitting each bone chord to its arc-length parameter along the curve. */
function solveSpline(solver, time, context) {
  const { state, localRotations, localTranslations, update, setWorldRotation } = context;
  const weight = checkedWeight(solver.weight, time, `${solver.label} weight`);
  const rawPoints = typeof solver.curve === 'function' ? solver.curve(time) : solver.curve;
  const points = checkedCurvePoints(rawPoints, solver.label);
  if (weight === 0) return { reached: true, error: 0 };
  const baseRotations = solver.joints.map(index => Float64Array.from(localRotations[index]));
  const baseTranslations = solver.stretchIndices.map(index => Float64Array.from(localTranslations[index]));
  const segmentCount = solver.joints.length - 1;
  const segmentLengths = new Float64Array(segmentCount);
  const cumulative = new Float64Array(segmentCount + 1);
  for (let slot = 0; slot < segmentCount; slot++) {
    segmentLengths[slot] = vec3.distance(state.positions[solver.joints[slot]], state.positions[solver.joints[slot + 1]]);
    cumulative[slot + 1] = cumulative[slot] + segmentLengths[slot];
  }
  const totalBoneLength = cumulative[segmentCount];
  const table = buildSplineArcTable(points);
  const spanLength = totalBoneLength + (table.totalLength - totalBoneLength) * solver.stretch;
  const targets = Array.from({ length: segmentCount + 1 }, (_, slot) => {
    const fraction = totalBoneLength > NEAR_ZERO ? cumulative[slot] / totalBoneLength : slot / segmentCount;
    return table.pointAtDistance(fraction * spanLength);
  });
  for (let slot = 0; slot < segmentCount; slot++) {
    const joint = solver.joints[slot];
    const nextJoint = solver.joints[slot + 1];
    const jointPos = state.positions[joint];
    const goalVec = vec3.subtract(new Float64Array(3), targets[slot + 1], jointPos);
    const goalLen = vec3.length(goalVec);
    let curVec = vec3.subtract(new Float64Array(3), state.positions[nextJoint], jointPos);
    let curLen = vec3.length(curVec);
    if (solver.stretch > 0 && curLen > NEAR_ZERO && goalLen > NEAR_ZERO) {
      const ratio = 1 + (goalLen / curLen - 1) * solver.stretch;
      for (const childIndex of solver.segmentChildren[slot]) {
        vec3.scale(localTranslations[childIndex], localTranslations[childIndex], ratio);
      }
      update();
      curVec = vec3.subtract(new Float64Array(3), state.positions[nextJoint], state.positions[joint]);
      curLen = vec3.length(curVec);
    }
    if (curLen > NEAR_ZERO && goalLen > NEAR_ZERO) {
      vec3.scale(curVec, curVec, 1 / curLen);
      vec3.scale(goalVec, goalVec, 1 / goalLen);
      const turn = quat.rotationTo(new Float64Array(4), curVec, goalVec);
      setWorldRotation(joint, quat.multiply(new Float64Array(4), turn, state.rotations[joint]), 1);
    }
  }
  if (weight < 1) {
    solver.joints.forEach((index, slot) => {
      quat.normalize(localRotations[index], quat.slerp(localRotations[index], baseRotations[slot], localRotations[index], weight));
    });
    solver.stretchIndices.forEach((index, slot) => {
      vec3.lerp(localTranslations[index], baseTranslations[slot], localTranslations[index], weight);
    });
    update();
  }
  const end = solver.joints[segmentCount];
  const error = vec3.distance(state.positions[end], targets[segmentCount]);
  return { reached: error <= Math.max(table.totalLength, totalBoneLength) * 1e-2 + 1e-4, error };
}

// A custom solver (spring bones) brings its own `solve`; it keeps its own state between calls.
function solveCustom(solver, time, context) {
  return solver.solve(time, context, checkedWeight(solver.weight, time, `${solver.label} weight`));
}

const SOLVERS = { 'two-bone': solveTwoBone, aim: solveAim, chain: solveChain, spline: solveSpline, custom: solveCustom };

const GLTF_TRACK_PROPERTIES = { position: 'translation', quaternion: 'rotation', scale: 'scale' };
const GLTF_STEP_INTERPOLATION = 2300;
const GLTF_LINEAR_INTERPOLATION = 2301;
const GLTF_CUBIC_INTERPOLATION = 2302;
const RESAMPLE_RATE = 30;

function trackKeyframes(track, size) {
  const interpolation = track.getInterpolation?.();
  if (interpolation === GLTF_LINEAR_INTERPOLATION || interpolation === GLTF_STEP_INTERPOLATION) {
    return Array.from(track.times, (time, index) => ({ time, value: Array.from(track.values.subarray(index * size, (index + 1) * size)) }));
  }
  // Cubic glTF tracks store tangents in their values; sample them instead of carrying a second tangent convention.
  const interpolant = track.createInterpolant(new Float64Array(size));
  const start = track.times[0];
  const end = track.times[track.times.length - 1];
  const steps = Math.max(1, Math.ceil((end - start) * RESAMPLE_RATE));
  return Array.from({ length: steps + 1 }, (_, step) => {
    const time = start + (end - start) * step / steps;
    return { time, value: Array.from(interpolant.evaluate(time)) };
  });
}

/**
 * Convert an animation from a loaded glTF asset (`asset.animations[n]`) into a clip layers and retargetClip can use.
 * Node tracks keep their decoded node names. Morph weight tracks are skipped. Step keys stay step; cubic keys are
 * resampled at 30 frames per second.
 */
export function clipFromGltfAnimation(animation, { loop = false, rename = {} } = {}) {
  if (!Array.isArray(animation?.tracks) || !Number.isFinite(animation.duration)) throw new TypeError('clipFromGltfAnimation needs an animation from asset.animations.');
  const tracks = [];
  for (const track of animation.tracks) {
    const separator = track.name.lastIndexOf('.');
    const property = GLTF_TRACK_PROPERTIES[track.name.slice(separator + 1)];
    if (!property || !track.times.length) continue;
    const size = property === 'rotation' ? 4 : 3;
    const trackTarget = track.name.slice(0, separator);
    tracks.push({
      target: Object.hasOwn(rename, trackTarget) ? rename[trackTarget] : trackTarget, property,
      interpolation: track.getInterpolation?.() === GLTF_STEP_INTERPOLATION ? 'STEP' : 'LINEAR',
      keyframes: trackKeyframes(track, size),
    });
  }
  return createAnimationClip({ duration: Math.max(animation.duration, 1e-3), loop, tracks });
}

const MORPH_TRACK_SUFFIX = '.morphTargetInfluences';

/**
 * The morph weight tracks of a loaded glTF animation, which `clipFromGltfAnimation` leaves out. Each track names the mesh
 * part it moves and is sampled with the decoder's own interpolant, so step, linear and cubic keys all play as authored.
 * Pass the result as `morphs` on a layer of `createAssetPose`.
 */
export function morphClipFromGltfAnimation(animation, { loop = false } = {}) {
  if (!Array.isArray(animation?.tracks) || !Number.isFinite(animation.duration)) throw new TypeError('morphClipFromGltfAnimation needs an animation from asset.animations.');
  const tracks = animation.tracks
    .filter(track => track.name.endsWith(MORPH_TRACK_SUFFIX) && track.times.length)
    .map(track => {
      const valuesPerKey = track.values.length / track.times.length;
      const count = track.getInterpolation?.() === GLTF_CUBIC_INTERPOLATION ? valuesPerKey / 3 : valuesPerKey;
      return { part: track.name.slice(0, -MORPH_TRACK_SUFFIX.length), count, interpolant: track.createInterpolant(new Float64Array(count)) };
    });
  return { duration: Math.max(animation.duration, 1e-3), loop, tracks };
}

function morphClipTime(morphs, layerTime) {
  if (!morphs.loop) return Math.min(morphs.duration, Math.max(0, layerTime));
  return ((layerTime % morphs.duration) + morphs.duration) % morphs.duration;
}

/** The deepest asset node that owns each mesh part, by index, so a layer mask can include or leave out a part by its bone. */
function ownerNodeByPart(nodes) {
  const owners = new Map();
  nodes.forEach((node, index) => {
    for (const meshId of node.meshIds ?? []) owners.set(Number(meshId.slice('mesh-'.length)), index);
  });
  return owners;
}

function createMorphLayers(asset, nodes, layers, rig) {
  const prepared = prepareRigGeometry(rig, 'Pose');
  const resolveJoint = jointResolver(rig, prepared);
  const owners = ownerNodeByPart(nodes);
  return layers.filter(layer => layer.morphs?.tracks.length).map(layer => {
    const mask = maskWeights(prepared, resolveJoint, layer.mask);
    const partIndices = new Map();
    for (const track of layer.morphs.tracks) {
      const matching = [...asset.parts.keys()].filter(index => {
        const part = asset.parts[index];
        return part.name === track.part && part.morph?.weights.length === track.count && mask[owners.get(index)] > 0;
      });
      partIndices.set(track, matching);
    }
    return {
      morphs: layer.morphs, partIndices, mask, owners, additive: layer.additive === true,
      speed: layer.speed ?? 1, offset: layer.offset ?? 0, clipTime: layer.clipTime, label: 'Morph layer',
      weight: weightFunction(layer.weight ?? 1, 'Morph layer weight'),
      reference: checkedReferenceTime(layer.reference, 'Morph layer'),
    };
  });
}

/** Blend each morph layer's weights over the ones before it. Returns [{ part, weights }] for the parts any layer drives. */
function evaluateMorphLayers(morphLayers, time) {
  const blended = new Map();
  for (const layer of morphLayers) {
    const layerWeight = checkedWeight(layer.weight, time, 'Morph layer weight');
    if (layerWeight === 0) continue;
    const layerTime = layerClipTime(layer, time);
    for (const track of layer.morphs.tracks) {
      const sampled = Array.from(track.interpolant.evaluate(morphClipTime(layer.morphs, layerTime)));
      const reference = layer.additive ? Array.from(track.interpolant.evaluate(morphClipTime(layer.morphs, layer.reference))) : null;
      for (const part of layer.partIndices.get(track)) {
        const weights = blended.get(part) ?? new Array(track.count).fill(0);
        const strength = layerWeight * layer.mask[layer.owners.get(part)];
        weights.forEach((current, index) => {
          const target = reference ? current + sampled[index] - reference[index] : sampled[index];
          weights[index] = Math.min(1, Math.max(0, current + (target - current) * strength));
        });
        blended.set(part, weights);
      }
    }
  }
  return [...blended].map(([part, weights]) => ({ part, weights }));
}

/** A rig from an asset's decoded nodes. Joints are named as the nodes are; `rootMatrix` places the asset in the world. */
export function rigFromAssetNodes(nodes, { rootMatrix } = {}) {
  const indexById = new Map(nodes.map((node, index) => [node.id, index]));
  const jointNames = nodes.filter(node => node.joint).map(node => node.name);
  return {
    mapping: mapHumanoidBones(jointNames).mapping,
    ...(rootMatrix ? { rootMatrix } : {}),
    joints: nodes.map(node => ({
      name: node.name,
      parent: node.parent === null ? -1 : indexById.get(node.parent),
      translation: node.translation, rotation: node.rotation, scale: node.scale,
    })),
  };
}

function checkAssetIkScales(rig, solvedNames) {
  const indexByName = new Map(rig.joints.map((joint, index) => [joint.name, index]));
  for (const name of solvedNames) {
    let current = rig.joints[indexByName.get(name)]?.parent ?? -1;
    while (current >= 0) {
      const joint = rig.joints[current];
      const [first, second, third] = joint.scale;
      if (Math.max(first, second, third) - Math.min(first, second, third) > 1e-3 * Math.max(first, second, third)) {
        throw new RangeError(`IK: node ${joint.name} above ${name} has non-uniform scale ${JSON.stringify(joint.scale)}, which IK cannot solve through.`);
      }
      current = joint.parent;
    }
  }
}

function createAssetPoseParts(asset, layers, ik) {
  if (typeof asset?.stagePose !== 'function' || !Array.isArray(asset.nodes)) throw new TypeError('createAssetPose needs an asset from loadGltf or parseGltf.');
  if (!Array.isArray(layers) || !Array.isArray(ik)) throw new TypeError('layers and ik must be arrays.');
  const nodes = asset.nodes;
  const rig = rigFromAssetNodes(nodes);
  const nodeLayers = layers.filter(layer => layer?.clip || !layer?.morphs);
  const pose = createSkeletonPose({ rig, layers: nodeLayers, ik });
  checkAssetIkScales(rig, pose.solvedJointNames);
  const written = pose.writtenJoints.filter(({ index }) => nodes[index].editable);
  const morphLayers = createMorphLayers(asset, nodes, layers, rig);
  /** Rebuild the pose for a time and return what the asset needs to stage it. */
  function evaluate(time) {
    pose.apply(time);
    const nodeOverrides = written.map(({ index, translation }) => {
      const override = { id: nodes[index].id, rotation: Array.from(pose.localRotation(index)) };
      if (translation) override.translation = Array.from(pose.localTranslation(index));
      return override;
    });
    return { nodeOverrides, morphWeights: evaluateMorphLayers(morphLayers, time) };
  }
  return { pose, evaluate };
}

/**
 * Evaluate layers alone, without IK and without committing anything: for a host that stages the result itself, as the
 * MCP asset recipe does before it solves IK. `evaluate(time)` gives `{ nodeOverrides, morphWeights }` for
 * `asset.stagePose`. The same time always gives the same result.
 */
export function createAssetLayerEvaluator(asset, layers) {
  return { evaluate: createAssetPoseParts(asset, layers, []).evaluate };
}

/**
 * Pose a loaded glTF asset from { layers, ik }. Unlike a skin palette this moves every skin and every rigid part attached
 * to the hierarchy, and IK targets are in the asset's world space. Joints are named by decoded node name or humanoid bone.
 * A layer may carry `morphs` from `morphClipFromGltfAnimation` to drive morph weights too; its mask picks parts by the
 * bone that owns them. `apply(time)` commits the pose and returns `asset.parts`; pass them to `renderer.updateParts`.
 */
export function createAssetPose(asset, { layers = [], ik = [] } = {}) {
  const { pose, evaluate } = createAssetPoseParts(asset, layers, ik);
  return {
    apply(time) {
      const { nodeOverrides, morphWeights } = evaluate(time);
      return asset.stagePose({ animation: null, nodeOverrides, morphWeights }).commit();
    },
    jointWorld: pose.jointWorld,
    get ikResults() {
      return pose.ikResults;
    },
  };
}

/**
 * Build a pose evaluator from { skin, rig, meshWorldMatrix, layers, ik }. Give `skin` to write its joint palette, or only
 * `rig` to read joint positions. Layers run in order: each blends its clip over the pose so far, or adds its change from
 * `reference` when `additive` is true. IK solvers run in order after every layer.
 */
export function createSkeletonPose({ skin, rig = skin && createRigFromSkin(skin), meshWorldMatrix, layers = [], ik = [] } = {}) {
  if (!rig) throw new TypeError('createSkeletonPose needs a skin or a rig.');
  validateRigJoints(rig.joints, 'Pose');
  checkRestValues(rig.joints);
  if (!Array.isArray(layers) || !Array.isArray(ik)) throw new TypeError('layers and ik must be arrays.');
  const prepared = prepareRigGeometry(rig, 'Pose');
  const resolveJoint = jointResolver(rig, prepared);
  const compiledLayers = layers.map((layer, position) => createLayer(layer, position, prepared, resolveJoint));
  const solvers = ik.map((solver, position) => createSolver(solver, position, prepared, resolveJoint));
  const solvedIndices = new Set(solvers.flatMap(solver => (solver.type === 'two-bone' ? [solver.root, solver.middle, solver.end] : solver.joints)));
  const solverTranslated = solvers.flatMap(solver => (solver.stretch > 0 ? solver.stretchIndices : []));
  const translatedIndices = new Set([
    ...compiledLayers.flatMap(layer => layer.bindings.filter(binding => binding.property === 'translation').map(binding => binding.index)),
    ...solverTranslated,
  ]);
  const writtenIndices = new Set([...solvedIndices, ...translatedIndices, ...compiledLayers.flatMap(layer => layer.bindings.filter(binding => binding.property === 'rotation').map(binding => binding.index))]);
  const jointCount = rig.joints.length;
  const localRotations = prepared.restRotations.map(rotation => Float64Array.from(rotation));
  const localTranslations = prepared.restTranslations.map(translation => Float64Array.from(translation));
  const state = createPoseState(jointCount);
  const context = createSolverContext(prepared, state, localRotations, localTranslations);
  const jointWorldMatrices = new Float32Array(jointCount * 16);
  const scratchMatrix = mat4.create();
  const results = solvers.map(() => ({ reached: true, error: 0 }));
  const bindMatrix = skin?.bindMatrix ?? mat4.create();
  const meshMatrix = meshWorldMatrix ?? bindMatrix;

  function writePalette() {
    for (let index = 0; index < jointCount; index++) {
      const scale = state.scales[index];
      mat4.fromRotationTranslationScale(scratchMatrix, state.rotations[index], state.positions[index], [scale, scale, scale]);
      jointWorldMatrices.set(scratchMatrix, index * 16);
    }
    updateSkinPose(skin, jointWorldMatrices, skin.inverseBindMatrices, meshMatrix, bindMatrix);
  }

  function jointWorld(name) {
    const index = resolveJoint(name, 'jointWorld');
    return { position: Array.from(state.positions[index]), rotation: Array.from(state.rotations[index]) };
  }

  return {
    /**
     * Rebuild the pose for an absolute time in seconds. Returns the skin when there is one. `setBase`, if given, receives
     * the local rotation and translation arrays (by rig joint index) to replace the rest pose before layers and IK.
     */
    apply(time, setBase) {
      if (!Number.isFinite(time)) throw new RangeError('Pose time must be finite.');
      for (let index = 0; index < jointCount; index++) {
        localRotations[index].set(prepared.restRotations[index]);
        localTranslations[index].set(prepared.restTranslations[index]);
      }
      setBase?.(localRotations, localTranslations);
      for (const layer of compiledLayers) applyLayer(layer, time, localRotations, localTranslations);
      context.update();
      solvers.forEach((solver, position) => {
        results[position] = SOLVERS[solver.type](solver, time, context);
      });
      if (skin) writePalette();
      return skin;
    },
    /** World position and rotation of a joint after the last apply. */
    jointWorld,
    /** Local rotation of a joint by rig index after the last apply. The array is reused by the next apply. */
    localRotation(index) {
      return localRotations[index];
    },
    /** Local translation of a joint by rig index after the last apply. The array is reused by the next apply. */
    localTranslation(index) {
      return localTranslations[index];
    },
    /** Rig indices a layer or solver can change, and whether their translation can change too. */
    writtenJoints: [...writtenIndices].map(index => ({ index, translation: translatedIndices.has(index) })),
    /** Names of the joints IK solvers move. */
    solvedJointNames: [...solvedIndices].map(index => rig.joints[index].name),
    /** One { reached, error } per IK solver from the last apply: metres for two-bone, radians for aim. */
    get ikResults() {
      return results;
    },
  };
}