Skip to content

3D engine that AI agents drive

59.6 KB
Raw Blame
import { mat4, quat, vec3 } from 'gl-matrix';
import { evaluateForceFields, normalizeForceFields } from './force-fields.js';

let rapierPromise;
let rapierEngine;
let buoyancyModule;
let loadRapierModule = () => import('@dimforge/rapier3d-compat');
const ZERO = [0, 0, 0];
const IDENTITY = [0, 0, 0, 1];
const MIN_NORMAL_FLOAT32 = 2 ** -126;
const MAX_JOINT_DISTANCE = 1e6;
const MAX_MOTOR_SPEED = 1e4;
const MAX_MOTOR_GAIN = 1e6;
const MAX_MOTOR_FORCE = 1e8;
const MAX_JOINT_ANGLE = Math.fround(Math.PI);
const LIMITS = {
  maxBodies: [256, 4096],
  maxColliders: [1024, 8192],
  maxJoints: [512, 8192],
  maxEvents: [10000, 100000],
  maxFrames: [3601, 1000000],
  maxColliderTriangles: [20000, 200000],
  maxHullPoints: [2048, 16384],
  maxContactEvents: [4096, 100000],
};
// A body counts as resting once it stays under both speeds until the last frame.
const REST_LINEAR_SPEED = 0.02;
const REST_ANGULAR_SPEED = 0.05;
const MAX_GROUP_BITS = 0xffff;

/** Replace how the Rapier module is imported, for hosts that serve it from a URL. */
export function setPhysicsModuleLoader(loader) {
  loadRapierModule = loader;
  rapierPromise = undefined;
  rapierEngine = undefined;
}

/** Load the code for floating bodies once. It is a separate chunk so a scene without floating bodies never fetches it. */
export async function loadPhysicsBuoyancy() {
  buoyancyModule ??= await import('./physics-buoyancy.js');
}

function requireBuoyancy(label) {
  if (!buoyancyModule) {
    throw new Error(`${label} floats, which needs the buoyancy code. Await loadPhysicsEngine({ buoyancy: true }) before baking or creating the system.`);
  }
  return buoyancyModule;
}

/**
 * Load the Rapier WASM engine once. After it resolves, bakePhysicsScene runs synchronously.
 * Pass `{ buoyancy: true }` when any body has a `float` field.
 */
export function loadPhysicsEngine(options = {}) {
  const engine = loadRapierEngine();
  return options.buoyancy ? Promise.all([engine, loadPhysicsBuoyancy()]).then(([rapier]) => rapier) : engine;
}

function loadRapierEngine() {
  rapierPromise ??= loadRapierModule().then(async module => {
    const rapier = module.default ?? module;
    await rapier.init();
    rapierEngine = rapier;
    return rapier;
  }, error => {
    rapierPromise = undefined;
    throw error;
  });
  return rapierPromise;
}

export function physicsEngineLoaded() {
  return rapierEngine !== undefined;
}

function fields(value, allowed, label) {
  if (!value || typeof value !== 'object' || Array.isArray(value)) {
    throw new TypeError(`${label} must be an object`);
  }
  for (const key of Object.keys(value)) {
    if (!allowed.includes(key)) {
      throw new TypeError(`${label}.${key} is unsupported`);
    }
  }
}

function scalar(value, label, min = -Infinity, max = Infinity) {
  const rounded = Math.fround(value);
  if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isFinite(rounded) || value < min || value > max || rounded < min || rounded > max) {
    throw new RangeError(`${label} must be finite Float32 in [${min}, ${max}]`);
  }
  return rounded;
}

function positive(value, label) {
  const result = scalar(value, label, 0);
  if (result === 0) {
    throw new RangeError(`${label} must remain positive in Float32`);
  }
  return result;
}

function normalPositive(value, label) {
  const result = scalar(value, label, MIN_NORMAL_FLOAT32);
  positive(1 / result, `${label} reciprocal`);
  return result;
}

function vectorLength(value, label) {
  const squaredLength = value[0] ** 2 + value[1] ** 2 + value[2] ** 2;
  scalar(squaredLength, `${label} squared norm`, 0);
  return Math.sqrt(squaredLength);
}

function vector(value, size, label, fallback) {
  value ??= fallback;
  if (!value || value.length !== size) {
    throw new TypeError(`${label} must contain ${size} numbers`);
  }
  return Array.from(value, (number, index) => scalar(number, `${label}[${index}]`));
}

function rotation(value, label) {
  const result = vector(value, 4, label, IDENTITY);
  const length = Math.hypot(...result);
  if (!length || Math.abs(length - 1) > 1e-4) {
    throw new RangeError(`${label} must be a unit quaternion`);
  }
  // A half-turn has two equivalent signs; keep its solver representation stable.
  const sign = result[3] === 0 && result.find(number => number !== 0) < 0 ? -1 : 1;
  return result.map(number => number === 0 ? 0 : Math.fround(sign * number / length));
}

function integer(value, label, min, max) {
  if (!Number.isSafeInteger(value) || value < min || value > max) {
    throw new RangeError(`${label} must be an integer in [${min}, ${max}]`);
  }
  return value;
}

function namedList(list, label, limit) {
  if (!Array.isArray(list) || list.length > limit) {
    throw new RangeError(`${label} must be an array with at most ${limit} entries`);
  }
  const names = new Set();
  for (const entry of list) {
    if (typeof entry?.name !== 'string' || !entry.name.length || names.has(entry.name)) {
      throw new TypeError(`${label} names must be nonempty and unique`);
    }
    names.add(entry.name);
  }
  return list;
}

function jointLimits(value, type) {
  const bounds = vector(value, 2, 'joint limits');
  const maximum = type === 'revolute' ? MAX_JOINT_ANGLE : MAX_JOINT_DISTANCE;
  for (const bound of bounds) scalar(bound, 'joint limit', -maximum, maximum);
  if (bounds[0] >= bounds[1]) throw new RangeError('joint limits must remain strictly increasing in Float32');
  return bounds;
}

function jointMotor(value, joint) {
  if (value === null) return null;
  fields(value, ['mode', 'target', 'stiffness', 'damping', 'maxForce'], 'motor');
  if (!['position', 'velocity'].includes(value.mode)) throw new TypeError('motor mode must be position or velocity');
  if (value.mode === 'velocity' && value.stiffness !== undefined) throw new TypeError('velocity motors do not accept stiffness');
  const maximum = value.mode === 'velocity' ? MAX_MOTOR_SPEED : joint.type === 'revolute' ? MAX_JOINT_ANGLE : MAX_JOINT_DISTANCE;
  const target = scalar(value.target, 'motor target', -maximum, maximum);
  if (value.target !== 0 && target === 0) throw new RangeError('motor target must not collapse to zero in Float32');
  if (value.mode === 'position' && joint.limits && (target < joint.limits[0] || target > joint.limits[1])) {
    throw new RangeError('motor position target must stay within joint limits');
  }
  const stiffness = value.mode === 'position' ? positive(value.stiffness, 'motor stiffness') : 0;
  if (stiffness > MAX_MOTOR_GAIN) throw new RangeError('motor stiffness exceeds the supported gain bound');
  const damping = scalar(value.damping, 'motor damping', 0, MAX_MOTOR_GAIN);
  if (value.damping !== 0 && damping === 0) throw new RangeError('motor damping must not collapse to zero in Float32');
  if (value.mode === 'velocity' && damping === 0) throw new RangeError('velocity motor damping must remain positive in Float32');
  const maxForce = normalPositive(value.maxForce, 'motor maxForce');
  if (maxForce > MAX_MOTOR_FORCE) throw new RangeError('motor maxForce exceeds the supported force bound');
  return { mode: value.mode, target, stiffness, damping, maxForce };
}

function initialJointCoordinate(joint, bodies) {
  const first = bodies[joint.bodyA];
  const second = bodies[joint.bodyB];
  const axisA = vec3.transformQuat(new Float64Array(3), joint.axis, first.rotation);
  const axisB = vec3.transformQuat(new Float64Array(3), joint.axis, second.rotation);
  if (vec3.distance(axisA, axisB) > 1e-4) throw new RangeError('controlled joint axes must initially align in world space');
  const anchorA = vec3.transformQuat(new Float64Array(3), joint.anchorA, first.rotation);
  const anchorB = vec3.transformQuat(new Float64Array(3), joint.anchorB, second.rotation);
  vec3.add(anchorA, anchorA, first.translation);
  vec3.add(anchorB, anchorB, second.translation);
  const difference = vec3.subtract(new Float64Array(3), anchorB, anchorA);
  const relativeRotation = quat.multiply(new Float64Array(4), quat.conjugate(new Float64Array(4), first.rotation), second.rotation);
  let coordinate;
  if (joint.type === 'prismatic') {
    coordinate = vec3.dot(difference, axisA);
    vec3.scaleAndAdd(difference, difference, axisA, -coordinate);
    if (vec3.length(difference) > 1e-4 || Math.abs(relativeRotation[3]) < 1 - 1e-4) {
      throw new RangeError('prismatic joint anchors must initially align along its axis with matching body orientations');
    }
  } else {
    if (vec3.length(difference) > 1e-4) throw new RangeError('controlled revolute joint anchors must initially coincide');
    coordinate = 2 * Math.atan2(relativeRotation[0] * joint.axis[0] + relativeRotation[1] * joint.axis[1] + relativeRotation[2] * joint.axis[2], relativeRotation[3]);
    if (coordinate > Math.PI) coordinate -= 2 * Math.PI;
    if (coordinate < -Math.PI) coordinate += 2 * Math.PI;
    if (Math.abs(coordinate) === Math.PI) {
      coordinate = joint.limits && joint.limits[1] < Math.PI ? -Math.PI : Math.PI;
    }
  }
  coordinate = scalar(coordinate, 'initial joint coordinate', joint.type === 'revolute' ? -MAX_JOINT_ANGLE : -MAX_JOINT_DISTANCE, joint.type === 'revolute' ? MAX_JOINT_ANGLE : MAX_JOINT_DISTANCE);
  if (joint.limits && (coordinate < joint.limits[0] || coordinate > joint.limits[1])) {
    throw new RangeError('initial joint coordinate must stay within joint limits');
  }
}

function finiteArray(values, label, maximumLength) {
  if (!Array.isArray(values) && !ArrayBuffer.isView(values)) {
    throw new TypeError(`${label} must be an array of numbers`);
  }
  if (values.length > maximumLength) {
    throw new RangeError(`${label} has ${values.length} numbers; the limit is ${maximumLength}`);
  }
  return Float32Array.from(values, (number, index) => scalar(number, `${label}[${index}]`));
}

function convexHullCollider(collider, limits) {
  if (collider.vertices !== undefined || collider.indices !== undefined || collider.radius !== undefined || collider.halfHeight !== undefined || collider.halfExtents !== undefined) {
    throw new TypeError('convexHull only accepts points');
  }
  if (!collider.points || collider.points.length % 3 !== 0 || collider.points.length < 12) {
    throw new TypeError('convexHull points must hold at least four xyz points');
  }
  const points = finiteArray(collider.points, 'points', limits.maxHullPoints * 3);
  const minimum = [Infinity, Infinity, Infinity];
  const maximum = [-Infinity, -Infinity, -Infinity];
  let largestExtent = 0;
  for (let index = 0; index < points.length; index += 3) {
    for (let axis = 0; axis < 3; axis++) {
      minimum[axis] = Math.min(minimum[axis], points[index + axis]);
      maximum[axis] = Math.max(maximum[axis], points[index + axis]);
    }
    largestExtent = Math.max(largestExtent, Math.hypot(points[index], points[index + 1], points[index + 2]));
  }
  const size = maximum.map((value, axis) => value - minimum[axis]);
  // The solver derives true mass from the hull; this bounding box only sizes the safety checks.
  return { shape: 'convexHull', points, volume: size[0] * size[1] * size[2], smallestExtent: Math.min(...size) / 2, largestExtent };
}

function trimeshCollider(collider, body, limits, budget) {
  if (body.type === 'dynamic') {
    throw new TypeError('trimesh colliders need a fixed or kinematic body; use convexHull for a dynamic body');
  }
  if (collider.points !== undefined || collider.radius !== undefined || collider.halfHeight !== undefined || collider.halfExtents !== undefined) {
    throw new TypeError('trimesh only accepts vertices and indices');
  }
  if (!collider.vertices || collider.vertices.length % 3 !== 0 || !collider.indices || collider.indices.length % 3 !== 0 || !collider.indices.length) {
    throw new TypeError('trimesh needs xyz vertices and triangle indices');
  }
  // Counts are checked before any typed array is allocated.
  budget.triangles += collider.indices.length / 3;
  if (budget.triangles > limits.maxColliderTriangles) {
    throw new RangeError(`trimesh colliders hold ${budget.triangles} triangles; maxColliderTriangles is ${limits.maxColliderTriangles}`);
  }
  const vertices = finiteArray(collider.vertices, 'vertices', limits.maxColliderTriangles * 3 * 3);
  const vertexCount = vertices.length / 3;
  const indices = Uint32Array.from(collider.indices, (index, position) => integer(index, `indices[${position}]`, 0, vertexCount - 1));
  return { shape: 'trimesh', vertices, indices };
}

function meshCollider(collider, body, limits, budget) {
  if (collider.shape === 'convexHull') return convexHullCollider(collider, limits);
  if (collider.shape === 'trimesh') return trimeshCollider(collider, body, limits, budget);
  if (collider.points !== undefined || collider.vertices !== undefined || collider.indices !== undefined) {
    throw new TypeError(`${collider.shape} does not accept points, vertices or indices`);
  }
  return null;
}

function prepare(definition, options) {
  fields(definition, ['bodies', 'colliders', 'joints', 'events', 'fields', 'gravity', 'ocean'], 'definition');
  fields(options, ['frameCount', 'timestep', 'solverIterations', 'maxMemoryBytes', ...Object.keys(LIMITS)], 'options');
  const limits = {};
  for (const [key, [fallback, cap]] of Object.entries(LIMITS)) {
    limits[key] = integer(options[key] ?? fallback, key, 1, cap);
  }
  const frameCount = integer(options.frameCount ?? 601, 'frameCount', 1, limits.maxFrames);
  const timestep = positive(options.timestep ?? 1 / 60, 'timestep');
  positive(1 / timestep, 'timestep reciprocal');
  if (timestep > 1) {
    throw new RangeError('timestep must be at most one second');
  }
  const solverIterations = integer(options.solverIterations ?? 8, 'solverIterations', 1, 128);
  const maxMemoryBytes = integer(options.maxMemoryBytes ?? 128 * 1024 * 1024, 'maxMemoryBytes', 1, 2 ** 31 - 1);
  const rawBodies = namedList(definition.bodies, 'bodies', limits.maxBodies);
  if (!rawBodies.length) {
    throw new RangeError('bodies must not be empty');
  }
  const rawColliders = namedList(definition.colliders ?? [], 'colliders', limits.maxColliders);
  const rawJoints = namedList(definition.joints ?? [], 'joints', limits.maxJoints);
  const rawEvents = definition.events ?? [];
  if (!Array.isArray(rawEvents) || rawEvents.length > limits.maxEvents) {
    throw new RangeError('events exceed maxEvents');
  }
  const timelineBytes = rawBodies.length * frameCount * 7 * Float32Array.BYTES_PER_ELEMENT;
  // Solver memory varies with contacts and WASM allocator reuse. This is a reservation estimate, not a heap measurement.
  const solverReserveBytes = 1048576 + rawBodies.length * 16384 + rawColliders.length * 16384 + rawJoints.length * 8192 + rawColliders.length ** 2 * 128;
  const estimatedPeakBytes = timelineBytes + solverReserveBytes;
  if (!Number.isSafeInteger(estimatedPeakBytes) || estimatedPeakBytes > maxMemoryBytes) {
    throw new RangeError(`physics memory plan ${estimatedPeakBytes} exceeds maxMemoryBytes ${maxMemoryBytes}`);
  }
  const bodies = rawBodies.map(body => {
    fields(body, ['name', 'type', 'translation', 'rotation', 'linearVelocity', 'angularVelocity', 'linearDamping', 'angularDamping', 'ccd', 'float'], `body ${body.name}`);
    const type = body.type ?? 'dynamic';
    if (!['dynamic', 'fixed', 'kinematic'].includes(type)) {
      throw new TypeError(`body ${body.name} has unsupported type`);
    }
    if (type !== 'dynamic' && (body.linearVelocity || body.angularVelocity || body.linearDamping !== undefined || body.angularDamping !== undefined || body.ccd !== undefined)) {
      throw new TypeError(`body ${body.name} only supports velocity, damping, and CCD when dynamic`);
    }
    if (body.ccd !== undefined && typeof body.ccd !== 'boolean') {
      throw new TypeError('ccd must be boolean');
    }
    if (body.float !== undefined && type !== 'dynamic') {
      throw new TypeError(`body ${body.name} only floats when dynamic; set type "dynamic" or drop float`);
    }
    if (body.float !== undefined && definition.ocean === undefined) {
      throw new TypeError(`body ${body.name} floats but the definition has no ocean; add ocean, such as { windSpeed: 5 }`);
    }
    return {
      name: body.name,
      type,
      float: body.float === undefined ? undefined : requireBuoyancy(`body ${body.name}`).normalizeFloat(body.float, `body ${body.name}.float`),
      translation: vector(body.translation, 3, 'translation', ZERO),
      rotation: rotation(body.rotation, 'rotation'),
      linearVelocity: vector(body.linearVelocity, 3, 'linearVelocity', ZERO),
      angularVelocity: vector(body.angularVelocity, 3, 'angularVelocity', ZERO),
      linearDamping: scalar(body.linearDamping ?? 0, 'linearDamping', 0),
      angularDamping: scalar(body.angularDamping ?? 0, 'angularDamping', 0),
      ccd: body.ccd ?? false,
    };
  });
  const bodyIndices = new Map(bodies.map((body, index) => [body.name, index]));
  function bodyIndex(name) {
    if (!bodyIndices.has(name)) {
      throw new TypeError(`unknown body ${name}`);
    }
    return bodyIndices.get(name);
  }
  const meshBudget = { triangles: 0 };
  const colliders = rawColliders.map(collider => {
    fields(collider, ['name', 'body', 'shape', 'radius', 'halfHeight', 'halfExtents', 'points', 'vertices', 'indices', 'translation', 'rotation', 'mass', 'density', 'friction', 'restitution', 'sensor', 'groups', 'mask'], `collider ${collider.name}`);
    const body = bodyIndex(collider.body);
    const mesh = meshCollider(collider, bodies[body], limits, meshBudget);
    if (collider.sensor !== undefined && typeof collider.sensor !== 'boolean') {
      throw new TypeError('sensor must be boolean');
    }
    const common = {
      name: collider.name,
      body,
      translation: vector(collider.translation, 3, 'collider translation', ZERO),
      rotation: rotation(collider.rotation, 'collider rotation'),
      friction: scalar(collider.friction ?? 0.5, 'friction', 0),
      restitution: scalar(collider.restitution ?? 0, 'restitution', 0, 1),
      sensor: collider.sensor ?? false,
      groups: integer(collider.groups ?? MAX_GROUP_BITS, 'groups', 0, MAX_GROUP_BITS),
      mask: integer(collider.mask ?? MAX_GROUP_BITS, 'mask', 0, MAX_GROUP_BITS),
    };
    if (mesh?.shape === 'trimesh') {
      return { ...common, ...mesh, effectiveMass: 0, minimumInertia: 0, largestExtent: 0 };
    }
    let radius;
    let halfHeight;
    let halfExtents;
    let volume;
    let smallestExtent;
    if (collider.shape === 'ball') {
      if (collider.halfHeight !== undefined || collider.halfExtents !== undefined) {
        throw new TypeError('ball only accepts radius');
      }
      radius = positive(collider.radius, 'radius');
      volume = 4 * Math.PI * radius ** 3 / 3;
      smallestExtent = radius;
    } else if (collider.shape === 'cuboid') {
      if (collider.radius !== undefined || collider.halfHeight !== undefined) {
        throw new TypeError('cuboid only accepts halfExtents');
      }
      halfExtents = vector(collider.halfExtents, 3, 'halfExtents');
      for (const extent of halfExtents) {
        positive(extent, 'halfExtents');
      }
      volume = 8 * halfExtents[0] * halfExtents[1] * halfExtents[2];
      smallestExtent = Math.min(...halfExtents);
    } else if (collider.shape === 'capsule') {
      if (collider.halfExtents !== undefined) {
        throw new TypeError('capsule only accepts radius and halfHeight');
      }
      radius = positive(collider.radius, 'radius');
      halfHeight = positive(collider.halfHeight, 'halfHeight');
      volume = Math.PI * radius ** 2 * 2 * halfHeight + 4 * Math.PI * radius ** 3 / 3;
      smallestExtent = radius;
    } else if (collider.shape === 'cylinder' || collider.shape === 'cone') {
      if (collider.halfExtents !== undefined) {
        throw new TypeError(`${collider.shape} only accepts radius and halfHeight`);
      }
      radius = positive(collider.radius, 'radius');
      halfHeight = positive(collider.halfHeight, 'halfHeight');
      volume = Math.PI * radius ** 2 * 2 * halfHeight / (collider.shape === 'cone' ? 3 : 1);
      smallestExtent = Math.min(radius, halfHeight);
    } else if (mesh) {
      volume = mesh.volume;
      smallestExtent = mesh.smallestExtent;
    } else {
      throw new TypeError(`unsupported collider shape ${collider.shape}`);
    }
    positive(volume, 'collider volume');
    if (collider.mass !== undefined && collider.density !== undefined) {
      throw new TypeError('collider accepts either mass or density');
    }
    const mass = collider.mass === undefined ? undefined : positive(collider.mass, 'mass');
    const density = mass === undefined ? positive(collider.density ?? 1, 'density') : undefined;
    const effectiveMass = normalPositive(mass ?? volume * density, 'collider effective mass');
    if (mass !== undefined) {
      positive(mass / volume, 'collider effective density');
    }
    const minimumInertia = normalPositive(0.1 * effectiveMass * smallestExtent ** 2, 'collider minimum inertia scale');
    const largestExtent = mesh ? mesh.largestExtent : halfExtents ? Math.max(...halfExtents) : radius + (halfHeight ?? 0);
    positive(effectiveMass * largestExtent ** 2, 'collider maximum inertia scale');
    return {
      ...common,
      shape: collider.shape,
      volume,
      radius,
      halfHeight,
      halfExtents,
      points: mesh?.points,
      mass,
      density,
      effectiveMass,
      minimumInertia,
      largestExtent,
    };
  });
  const massTotals = Array(bodies.length).fill(0);
  const inertiaTotals = Array(bodies.length).fill(0);
  const minimumInertiaTotals = Array(bodies.length).fill(0);
  const maximumColliderOffsets = Array(bodies.length).fill(0);
  for (const collider of colliders) {
    if (collider.shape === 'trimesh') continue;
    const index = collider.body;
    massTotals[index] = normalPositive(massTotals[index] + collider.effectiveMass, 'compound body mass');
    inertiaTotals[index] = positive(inertiaTotals[index] + collider.effectiveMass * (collider.largestExtent ** 2 + Math.hypot(...collider.translation) ** 2), 'compound body inertia scale');
    minimumInertiaTotals[index] = normalPositive(minimumInertiaTotals[index] + collider.minimumInertia, 'compound body minimum inertia');
    maximumColliderOffsets[index] = Math.max(maximumColliderOffsets[index], Math.hypot(...collider.translation));
    for (const component of collider.translation) {
      scalar(collider.effectiveMass * component, 'collider weighted center');
    }
  }
  for (let bodyIndex = 0; bodyIndex < bodies.length; bodyIndex++) {
    if (bodies[bodyIndex].type === 'dynamic' && massTotals[bodyIndex] === 0) {
      throw new TypeError(`dynamic body ${bodies[bodyIndex].name} requires a collider with mass`);
    }
  }
  const joints = rawJoints.map(joint => {
    fields(joint, ['name', 'type', 'bodyA', 'bodyB', 'anchorA', 'anchorB', 'axis', 'frameA', 'frameB', 'contactsEnabled', 'limits', 'motor', 'restLength', 'stiffness', 'damping', 'breakImpulse'], `joint ${joint.name}`);
    if (joint.breakImpulse !== undefined && joint.type !== 'fixed') {
      throw new TypeError('breakImpulse requires a fixed joint');
    }
    if (!['spherical', 'revolute', 'prismatic', 'fixed', 'spring'].includes(joint.type)) {
      throw new TypeError('unsupported joint type');
    }
    const bodyA = bodyIndex(joint.bodyA);
    const bodyB = bodyIndex(joint.bodyB);
    if (bodyA === bodyB) {
      throw new TypeError('joint bodies must differ');
    }
    if (joint.contactsEnabled !== undefined && typeof joint.contactsEnabled !== 'boolean') {
      throw new TypeError('contactsEnabled must be boolean');
    }
    const unitJoint = joint.type === 'revolute' || joint.type === 'prismatic';
    if (!unitJoint && joint.axis !== undefined) {
      throw new TypeError('axis requires a revolute or prismatic joint');
    }
    if (!unitJoint && (joint.limits !== undefined || joint.motor !== undefined)) throw new TypeError('limits and motors require a revolute or prismatic joint');
    if (joint.type !== 'fixed' && (joint.frameA !== undefined || joint.frameB !== undefined)) {
      throw new TypeError('joint frames require a fixed joint');
    }
    if (joint.type !== 'spring' && (joint.restLength !== undefined || joint.stiffness !== undefined || joint.damping !== undefined)) {
      throw new TypeError('restLength, stiffness and damping require a spring joint');
    }
    const axis = unitJoint ? vector(joint.axis, 3, 'axis') : undefined;
    if (axis && Math.abs(Math.hypot(...axis) - 1) > 1e-4) {
      throw new RangeError('axis must be a unit vector');
    }
    if (axis) {
      const axisLength = Math.hypot(...axis);
      for (let component = 0; component < 3; component++) {
        axis[component] = Math.fround(axis[component] / axisLength);
      }
    }
    const result = {
      name: joint.name,
      type: joint.type,
      bodyA,
      bodyB,
      anchorA: vector(joint.anchorA, 3, 'anchorA', ZERO),
      anchorB: vector(joint.anchorB, 3, 'anchorB', ZERO),
      axis,
      frameA: rotation(joint.frameA, 'frameA'),
      frameB: rotation(joint.frameB, 'frameB'),
      contactsEnabled: joint.contactsEnabled ?? false,
    };
    if (joint.type === 'spring') {
      result.restLength = scalar(joint.restLength ?? 0, 'restLength', 0, MAX_JOINT_DISTANCE);
      result.stiffness = positive(joint.stiffness, 'stiffness');
      if (result.stiffness > MAX_MOTOR_GAIN) throw new RangeError('spring stiffness exceeds the supported gain bound');
      result.damping = scalar(joint.damping ?? 0, 'damping', 0, MAX_MOTOR_GAIN);
    }
    if (joint.breakImpulse !== undefined) result.breakImpulse = positive(joint.breakImpulse, 'breakImpulse');
    if (joint.limits !== undefined) result.limits = jointLimits(joint.limits, joint.type);
    if (joint.motor !== undefined) result.motor = jointMotor(joint.motor, result);
    if (joint.type === 'prismatic' || joint.limits !== undefined || joint.motor !== undefined) initialJointCoordinate(result, bodies);
    return result;
  });
  for (const joint of joints) {
    if (joint.breakImpulse === undefined) continue;
    for (const collider of colliders) {
      if (collider.body !== joint.bodyA && collider.body !== joint.bodyB) continue;
      collider.breakForceThreshold = Math.min(collider.breakForceThreshold ?? Infinity, joint.breakImpulse / timestep);
    }
  }
  const jointIndices = new Map(rawJoints.map((joint, index) => [joint.name, index]));
  const events = rawEvents.map((event, order) => {
    const tick = integer(event.tick, 'event tick', 0, frameCount - 2);
    const type = event.type ?? 'impulse';
    if (type === 'jointMotor') {
      fields(event, ['tick', 'type', 'joint', 'motor'], `event ${order}`);
      if (!jointIndices.has(event.joint)) throw new TypeError(`unknown joint ${event.joint}`);
      const joint = jointIndices.get(event.joint);
      if (!['revolute', 'prismatic'].includes(joints[joint].type)) throw new TypeError('motor events require a revolute or prismatic joint');
      initialJointCoordinate(joints[joint], bodies);
      return { tick, type, order, joint, motor: jointMotor(event.motor, joints[joint]) };
    }
    fields(event, ['tick', 'body', 'type', 'impulse', 'torqueImpulse', 'point', 'translation', 'rotation'], `event ${order}`);
    const body = bodyIndex(event.body);
    if (type === 'impulse') {
      if (bodies[body].type !== 'dynamic') {
        throw new TypeError('impulses require a dynamic body');
      }
      if (event.translation !== undefined || event.rotation !== undefined || (event.impulse === undefined && event.torqueImpulse === undefined) || (event.point !== undefined && event.impulse === undefined)) {
        throw new TypeError('invalid impulse event fields');
      }
      return {
        tick,
        body,
        type,
        order,
        impulse: event.impulse === undefined ? undefined : vector(event.impulse, 3, 'impulse'),
        torqueImpulse: event.torqueImpulse === undefined ? undefined : vector(event.torqueImpulse, 3, 'torqueImpulse'),
        point: event.point === undefined ? undefined : vector(event.point, 3, 'point'),
      };
    }
    if (type !== 'kinematicPose' || bodies[body].type !== 'kinematic') {
      throw new TypeError('kinematicPose events require a kinematic body');
    }
    if (event.impulse !== undefined || event.torqueImpulse !== undefined || event.point !== undefined || (event.translation === undefined && event.rotation === undefined)) {
      throw new TypeError('invalid kinematicPose event fields');
    }
    return {
      tick,
      body,
      type,
      order,
      translation: event.translation === undefined ? undefined : vector(event.translation, 3, 'event translation'),
      rotation: event.rotation === undefined ? undefined : rotation(event.rotation, 'event rotation'),
    };
  }).sort((firstEvent, secondEvent) => firstEvent.tick - secondEvent.tick || firstEvent.order - secondEvent.order);
  const forceFields = normalizeForceFields(definition.fields ?? [], 'fields');
  const gravity = vector(definition.gravity, 3, 'gravity', [0, -9.81, 0]);
  validateMotionBounds(bodies, events, gravity, forceFields, timestep, frameCount, massTotals, minimumInertiaTotals, maximumColliderOffsets, joints, inertiaTotals);
  const buoyancy = buoyancyPlan(definition.ocean, bodies, colliders, frameCount);
  const memoryPlan = Object.freeze({
    timelineBytes,
    solverReserveBytes,
    estimatedPeakBytes,
    maxMemoryBytes,
    bodyCount: bodies.length,
    colliderCount: colliders.length,
    jointCount: joints.length,
    eventCount: events.length,
    frameCount,
  });
  return {
    bodies,
    colliders,
    joints,
    events,
    fields: forceFields,
    gravity,
    buoyancy,
    frameCount,
    timestep,
    solverIterations,
    maxContactEvents: limits.maxContactEvents,
    memoryPlan,
  };
}

/** The sea and the floating bodies of a definition, or null when no body has a float field. */
function buoyancyPlan(oceanInput, bodies, colliders, frameCount) {
  if (!bodies.some(body => body.float !== undefined)) return null;
  const { checkBuoyancyWork, floatingBody, normalizeOcean } = buoyancyModule;
  const floating = [];
  bodies.forEach((body, bodyIndex) => {
    if (body.float === undefined) return;
    const bodyColliders = colliders.filter(collider => collider.body === bodyIndex);
    floating.push({ bodyIndex, ...floatingBody(body.float, bodyColliders, `body ${body.name}`) });
  });
  const ocean = normalizeOcean(oceanInput);
  checkBuoyancyWork(ocean, floating, frameCount);
  return { ocean, floating };
}

function validateMotorBounds(bodies, joints, events, timestep, duration, massTotals, minimumInertiaTotals, maximumInertiaTotals, maximumColliderOffsets, linearSpeedBounds, angularSpeedBounds) {
  const components = bodies.map((_, index) => index);
  function component(index) {
    while (components[index] !== index) index = components[index];
    return index;
  }
  for (const joint of joints) components[component(joint.bodyB)] = component(joint.bodyA);
  const peakForces = joints.map(() => 0);
  function motorBound(jointIndex, motor) {
    if (!motor) return;
    const joint = joints[jointIndex];
    if (bodies[joint.bodyA].type !== 'dynamic' && bodies[joint.bodyB].type !== 'dynamic') throw new TypeError('active motors need at least one directly attached dynamic body');
    normalPositive(motor.maxForce ** 2, 'motor force squared norm');
    normalPositive((motor.maxForce * timestep) ** 2, 'motor step impulse squared norm');
    if (motor.stiffness) normalPositive((motor.stiffness * timestep ** 2) ** 2, 'motor timestep stiffness squared');
    if (motor.damping) normalPositive((motor.damping * timestep) ** 2, 'motor timestep damping squared');
    if (motor.target !== 0) {
      normalPositive(motor.target ** 2, 'motor target squared norm');
      const gain = motor.mode === 'position' ? motor.stiffness : motor.damping;
      const commandedForce = Math.min(Math.abs(gain * motor.target), motor.maxForce);
      normalPositive((commandedForce * timestep) ** 2, 'motor commanded impulse squared norm');
    }
    peakForces[jointIndex] = Math.max(peakForces[jointIndex], motor.maxForce);
  }
  for (let index = 0; index < joints.length; index++) motorBound(index, joints[index].motor);
  for (const event of events) {
    if (event.type === 'jointMotor') motorBound(event.joint, event.motor);
  }
  const forceTotals = bodies.map(() => 0);
  const torqueTotals = bodies.map(() => 0);
  const leverArms = bodies.map(() => 0);
  for (let index = 0; index < bodies.length; index++) leverArms[component(index)] += maximumColliderOffsets[index];
  for (let index = 0; index < joints.length; index++) {
    const joint = joints[index];
    const root = component(joint.bodyA);
    leverArms[root] += Math.hypot(...joint.anchorA) + Math.hypot(...joint.anchorB);
    if (joint.type === 'prismatic') forceTotals[root] += peakForces[index];
    else torqueTotals[root] += peakForces[index];
  }
  for (let index = 0; index < bodies.length; index++) {
    if (bodies[index].type !== 'dynamic') continue;
    const root = component(index);
    const force = forceTotals[root];
    const torque = torqueTotals[root] + force * leverArms[root];
    if (!force && !torque) continue;
    scalar(force ** 2, 'combined motor force squared norm', 0);
    scalar(torque ** 2, 'combined motor torque squared norm', 0);
    if (force) normalPositive((force / massTotals[index]) ** 2, 'motor linear acceleration squared norm');
    if (torque) normalPositive((torque / maximumInertiaTotals[index]) ** 2, 'motor angular acceleration squared norm');
    const angularAcceleration = torque / minimumInertiaTotals[index];
    const linearAcceleration = force / massTotals[index] + angularAcceleration * leverArms[root];
    angularSpeedBounds[index] += angularAcceleration * duration;
    linearSpeedBounds[index] += linearAcceleration * duration;
    scalar(angularSpeedBounds[index] ** 2, 'motor-induced angular velocity squared norm', 0);
    scalar(linearSpeedBounds[index] ** 2, 'motor-induced linear velocity squared norm', 0);
    scalar((Math.hypot(...bodies[index].translation) + linearSpeedBounds[index] * duration) ** 2, 'motor-induced position squared norm', 0);
  }
}

function validateMotionBounds(bodies, events, gravity, forceFields, timestep, frameCount, massTotals, minimumInertiaTotals, maximumColliderOffsets, joints, maximumInertiaTotals) {
  const duration = (frameCount - 1) * timestep;
  const fieldMagnitude = forceFields.reduce((total, field) => total + (field.type === 'drag' ? 0 : Math.abs(field.strength)), 0);
  const gravityMagnitude = vectorLength(gravity, 'gravity') + fieldMagnitude;
  const linearSpeedBounds = bodies.map(body => {
    const initialSpeed = vectorLength(body.linearVelocity, 'linearVelocity');
    const speedBound = initialSpeed + (body.type === 'dynamic' ? gravityMagnitude * duration : 0);
    scalar(speedBound ** 2, 'accumulated linear velocity squared norm', 0);
    return speedBound;
  });
  const angularSpeedBounds = bodies.map(body => vectorLength(body.angularVelocity, 'angularVelocity'));

  // Ignore damping and contact resistance to bound all declared impulses conservatively.
  for (const event of events) {
    if (event.type !== 'impulse') {
      continue;
    }
    if (event.impulse) {
      const impulseMagnitude = vectorLength(event.impulse, 'impulse');
      linearSpeedBounds[event.body] += impulseMagnitude / massTotals[event.body];
      scalar(linearSpeedBounds[event.body] ** 2, 'accumulated linear velocity squared norm', 0);
    }
    if (event.torqueImpulse) {
      const torqueMagnitude = vectorLength(event.torqueImpulse, 'torqueImpulse');
      angularSpeedBounds[event.body] += torqueMagnitude / minimumInertiaTotals[event.body];
      scalar(angularSpeedBounds[event.body] ** 2, 'accumulated angular velocity squared norm', 0);
    }
  }

  validateMotorBounds(bodies, joints, events, timestep, duration, massTotals, minimumInertiaTotals, maximumInertiaTotals, maximumColliderOffsets, linearSpeedBounds, angularSpeedBounds);

  const kinematicTranslations = bodies.map(body => body.translation.slice());
  const kinematicTickBaseTranslations = bodies.map(body => body.translation.slice());
  const kinematicTicks = Array(bodies.length).fill(-1);
  for (const event of events) {
    const body = bodies[event.body];
    if (event.type === 'kinematicPose') {
      if (event.translation) {
        // Same-tick targets share the last integrated pose, and gaps hold that pose.
        if (kinematicTicks[event.body] !== event.tick) {
          kinematicTickBaseTranslations[event.body] = kinematicTranslations[event.body];
        }
        const previousTranslation = kinematicTickBaseTranslations[event.body];
        const targetVelocity = event.translation.map((component, axis) => (component - previousTranslation[axis]) / timestep);
        vectorLength(targetVelocity, 'kinematic target velocity');
        kinematicTranslations[event.body] = event.translation;
        kinematicTicks[event.body] = event.tick;
      }
      if (event.rotation) {
        scalar((Math.PI / timestep) ** 2, 'kinematic angular velocity squared norm', 0);
      }
      continue;
    }
    if (event.impulse && event.point) {
      const impulseMagnitude = vectorLength(event.impulse, 'impulse');
      const maximumTravel = linearSpeedBounds[event.body] * duration;
      const leverArm = Math.hypot(...event.point) + Math.hypot(...body.translation) + maximumTravel + maximumColliderOffsets[event.body];
      const torqueBound = impulseMagnitude * leverArm;
      scalar(torqueBound ** 2, 'off-center torque impulse squared norm', 0);
      angularSpeedBounds[event.body] += torqueBound / minimumInertiaTotals[event.body];
      scalar(angularSpeedBounds[event.body] ** 2, 'accumulated angular velocity squared norm', 0);
    }
  }
}

/** Validate and estimate memory without loading or allocating the Rapier WASM world. */
export function planPhysicsScene(definition, options = {}) {
  return prepare(definition, options).memoryPlan;
}

const xyz = array => ({ x: array[0], y: array[1], z: array[2] });
const xyzw = array => ({ ...xyz(array), w: array[3] });

function applyJointMotor(rapier, joint, motor) {
  joint.configureMotorModel(rapier.MotorModel.ForceBased);
  joint.setMotorMaxForce(motor?.maxForce ?? 0);
  if (!motor) joint.configureMotor(0, 0, 0, 0);
  else if (motor.mode === 'position') joint.configureMotorPosition(motor.target, motor.stiffness, motor.damping);
  else joint.configureMotorVelocity(motor.target, motor.damping);
  joint.body1().wakeUp();
  joint.body2().wakeUp();
}

/** Bake a named rigid-body graph with Rapier, then release its solver world. */
export async function createPhysicsScene(definition, options = {}) {
  const preparedScene = prepare(definition, options);
  await loadPhysicsEngine();
  return bakePrepared(preparedScene);
}

/** Synchronous bake for hosts that already awaited loadPhysicsEngine. */
export function bakePhysicsScene(definition, options = {}) {
  if (!rapierEngine) {
    throw new Error('Physics engine is not loaded. Await loadPhysicsEngine() first.');
  }
  return bakePrepared(prepare(definition, options));
}

function colliderDescriptor(rapier, collider) {
  let descriptor;
  if (collider.shape === 'ball') {
    descriptor = rapier.ColliderDesc.ball(collider.radius);
  } else if (collider.shape === 'cuboid') {
    descriptor = rapier.ColliderDesc.cuboid(...collider.halfExtents);
  } else if (collider.shape === 'capsule') {
    descriptor = rapier.ColliderDesc.capsule(collider.halfHeight, collider.radius);
  } else if (collider.shape === 'cylinder') {
    descriptor = rapier.ColliderDesc.cylinder(collider.halfHeight, collider.radius);
  } else if (collider.shape === 'cone') {
    descriptor = rapier.ColliderDesc.cone(collider.halfHeight, collider.radius);
  } else if (collider.shape === 'convexHull') {
    descriptor = rapier.ColliderDesc.convexHull(collider.points);
    if (!descriptor) {
      throw new RangeError('convexHull points are degenerate: they must span a volume');
    }
  } else {
    descriptor = rapier.ColliderDesc.trimesh(collider.vertices, collider.indices);
  }
  descriptor.setTranslation(...collider.translation);
  descriptor.setRotation(xyzw(collider.rotation));
  descriptor.setFriction(collider.friction);
  descriptor.setRestitution(collider.restitution);
  descriptor.setSensor(collider.sensor);
  descriptor.setCollisionGroups(((collider.groups << 16) | collider.mask) >>> 0);
  const forceEvents = collider.breakForceThreshold === undefined ? 0 : rapier.ActiveEvents.CONTACT_FORCE_EVENTS;
  descriptor.setActiveEvents(rapier.ActiveEvents.COLLISION_EVENTS | forceEvents);
  if (forceEvents) descriptor.setContactForceEventThreshold(collider.breakForceThreshold);
  if (collider.shape !== 'trimesh') {
    if (collider.mass === undefined) {
      descriptor.setDensity(collider.density);
    } else {
      descriptor.setMass(collider.mass);
    }
  }
  return descriptor;
}

/** Build the Rapier world for a prepared scene. Shared by the recorded bake and the live runtime. Frees itself on failure. */
export function createRapierWorld(rapier, preparedScene) {
  const world = new rapier.World(xyz(preparedScene.gravity));
  const colliderIndices = new Map();
  try {
    world.timestep = preparedScene.timestep;
    world.numSolverIterations = preparedScene.solverIterations;
    const bodies = preparedScene.bodies.map(body => {
      let descriptor;
      if (body.type === 'dynamic') {
        descriptor = rapier.RigidBodyDesc.dynamic();
      } else if (body.type === 'fixed') {
        descriptor = rapier.RigidBodyDesc.fixed();
      } else {
        descriptor = rapier.RigidBodyDesc.kinematicPositionBased();
      }
      descriptor.setTranslation(...body.translation);
      descriptor.setRotation(xyzw(body.rotation));
      if (body.type === 'dynamic') {
        descriptor.setLinvel(...body.linearVelocity);
        descriptor.setAngvel(xyz(body.angularVelocity));
        descriptor.setLinearDamping(body.linearDamping);
        descriptor.setAngularDamping(body.angularDamping);
        descriptor.setCcdEnabled(body.ccd);
      }
      return world.createRigidBody(descriptor);
    });
    preparedScene.colliders.forEach((collider, colliderIndex) => {
      const created = world.createCollider(colliderDescriptor(rapier, collider), bodies[collider.body]);
      colliderIndices.set(created.handle, colliderIndex);
    });
    const joints = preparedScene.joints.map(joint => {
      const anchorA = xyz(joint.anchorA);
      const anchorB = xyz(joint.anchorB);
      let descriptor;
      if (joint.type === 'spherical') {
        descriptor = rapier.JointData.spherical(anchorA, anchorB);
      } else if (joint.type === 'revolute') {
        descriptor = rapier.JointData.revolute(anchorA, anchorB, xyz(joint.axis));
      } else if (joint.type === 'prismatic') {
        descriptor = rapier.JointData.prismatic(anchorA, anchorB, xyz(joint.axis));
      } else if (joint.type === 'spring') {
        descriptor = rapier.JointData.spring(joint.restLength, joint.stiffness, joint.damping, anchorA, anchorB);
      } else {
        descriptor = rapier.JointData.fixed(anchorA, xyzw(joint.frameA), anchorB, xyzw(joint.frameB));
      }
      const created = world.createImpulseJoint(descriptor, bodies[joint.bodyA], bodies[joint.bodyB], true);
      created.setContactsEnabled(joint.contactsEnabled);
      if (joint.limits) created.setLimits(...joint.limits);
      if (joint.motor !== undefined) applyJointMotor(rapier, created, joint.motor);
      return created;
    });
    return { world, bodies, joints, colliderIndices };
  } catch (error) {
    world.free();
    throw error;
  }
}

/** Push every floating body by the sea at `time`, as one impulse over a step. The buoyancy code is loaded whenever a body floats. */
export function applyBuoyancyImpulses(preparedScene, bodies, time) {
  buoyancyModule.applyBuoyancy(preparedScene, bodies, time);
}

/** Set the live throttle and rudder of a resolved boat (see physics-boat.js). */
export function setBoatControls(boat, controls, label) {
  buoyancyModule.setBoatControls(boat, controls, label);
}

/** Push every dynamic body by the force fields at `fieldTime`, as one impulse over a step. */
export function applyForceFieldImpulses(preparedScene, bodies, fieldTime) {
  const fieldAccel = [0, 0, 0];
  for (let bodyIndex = 0; bodyIndex < bodies.length; bodyIndex++) {
    if (preparedScene.bodies[bodyIndex].type !== 'dynamic') continue;
    const body = bodies[bodyIndex];
    const pos = body.translation();
    const vel = body.linvel();
    evaluateForceFields(preparedScene.fields, [pos.x, pos.y, pos.z], [vel.x, vel.y, vel.z], fieldTime, fieldAccel);
    const scale = body.mass() * preparedScene.timestep;
    if (fieldAccel[0] || fieldAccel[1] || fieldAccel[2]) {
      body.applyImpulse({ x: fieldAccel[0] * scale, y: fieldAccel[1] * scale, z: fieldAccel[2] * scale }, true);
    }
  }
}

function breakableJointTable(preparedScene, rapierJoints) {
  const table = [];
  preparedScene.joints.forEach((joint, index) => {
    if (joint.breakImpulse !== undefined) table.push({ index, joint, rapierJoint: rapierJoints[index], broken: false });
  });
  return table;
}

/**
 * Break every glue joint of a body that took a contact impulse over the joint strength in this step.
 * The impulse is the contact force magnitude times the timestep, so a body resting under its own weight stays glued.
 */
function breakJointsHitHard(world, eventQueue, preparedScene, colliderIndices, breakableJoints, frame, jointBreaks) {
  const impulseByBody = new Map();
  eventQueue.drainContactForceEvents(event => {
    const impulse = event.totalForceMagnitude() * preparedScene.timestep;
    for (const handle of [event.collider1(), event.collider2()]) {
      const body = preparedScene.colliders[colliderIndices.get(handle)].body;
      impulseByBody.set(body, Math.max(impulseByBody.get(body) ?? 0, impulse));
    }
  });
  for (const entry of breakableJoints) {
    if (entry.broken) continue;
    const impulse = Math.max(impulseByBody.get(entry.joint.bodyA) ?? 0, impulseByBody.get(entry.joint.bodyB) ?? 0);
    if (impulse < entry.joint.breakImpulse) continue;
    entry.broken = true;
    world.removeImpulseJoint(entry.rapierJoint, true);
    jointBreaks.push(Object.freeze({ frame, joint: entry.joint.name, impulse }));
  }
}

function bakePrepared(preparedScene) {
  const rapier = rapierEngine;
  const { world, bodies, joints, colliderIndices } = createRapierWorld(rapier, preparedScene);
  const eventQueue = new rapier.EventQueue(true);
  const contactEvents = [];
  const jointBreaks = [];
  const breakableJoints = breakableJointTable(preparedScene, joints);
  const lastMovingFrames = new Int32Array(preparedScene.bodies.length).fill(-1);
  let contactEventsTruncated = false;
  let timeline;
  try {
    timeline = new Float32Array(preparedScene.memoryPlan.timelineBytes / 4);
    let eventIndex = 0;
    for (let frame = 0; frame < preparedScene.frameCount; frame++) {
      if (frame > 0) {
        while (eventIndex < preparedScene.events.length && preparedScene.events[eventIndex].tick === frame - 1) {
          const event = preparedScene.events[eventIndex];
          eventIndex++;
          if (event.type === 'jointMotor') {
            applyJointMotor(rapier, joints[event.joint], event.motor);
            continue;
          }
          const body = bodies[event.body];
          if (event.type === 'kinematicPose') {
            if (event.translation) {
              body.setNextKinematicTranslation(xyz(event.translation));
            }
            if (event.rotation) {
              body.setNextKinematicRotation(xyzw(event.rotation));
            }
          } else {
            if (event.impulse) {
              if (event.point) {
                body.applyImpulseAtPoint(xyz(event.impulse), xyz(event.point), true);
              } else {
                body.applyImpulse(xyz(event.impulse), true);
              }
            }
            if (event.torqueImpulse) {
              body.applyTorqueImpulse(xyz(event.torqueImpulse), true);
            }
          }
        }
        if (preparedScene.fields.length) applyForceFieldImpulses(preparedScene, bodies, (frame - 1) * preparedScene.timestep);
        if (preparedScene.buoyancy) applyBuoyancyImpulses(preparedScene, bodies, (frame - 1) * preparedScene.timestep);
        world.step(eventQueue);
        eventQueue.drainCollisionEvents((firstHandle, secondHandle, started) => {
          if (contactEvents.length >= preparedScene.maxContactEvents) {
            contactEventsTruncated = true;
            return;
          }
          const first = colliderIndices.get(firstHandle);
          const second = colliderIndices.get(secondHandle);
          const sensor = preparedScene.colliders[first].sensor || preparedScene.colliders[second].sensor;
          contactEvents.push(Object.freeze({ frame, kind: sensor ? 'sensor' : 'contact', started, colliderA: first, colliderB: second }));
        });
        if (breakableJoints.length) {
          breakJointsHitHard(world, eventQueue, preparedScene, colliderIndices, breakableJoints, frame, jointBreaks);
        }
      }
      for (let bodyIndex = 0; bodyIndex < bodies.length; bodyIndex++) {
        const linearVelocity = bodies[bodyIndex].linvel();
        const angularVelocity = bodies[bodyIndex].angvel();
        scalar(linearVelocity.x ** 2 + linearVelocity.y ** 2 + linearVelocity.z ** 2, 'solver linear velocity squared norm', 0);
        scalar(angularVelocity.x ** 2 + angularVelocity.y ** 2 + angularVelocity.z ** 2, 'solver angular velocity squared norm', 0);
        if (Math.hypot(linearVelocity.x, linearVelocity.y, linearVelocity.z) > REST_LINEAR_SPEED || Math.hypot(angularVelocity.x, angularVelocity.y, angularVelocity.z) > REST_ANGULAR_SPEED) {
          lastMovingFrames[bodyIndex] = frame;
        }
        const position = bodies[bodyIndex].translation();
        const bodyRotation = bodies[bodyIndex].rotation();
        const offset = (frame * bodies.length + bodyIndex) * 7;
        timeline[offset] = position.x;
        timeline[offset + 1] = position.y;
        timeline[offset + 2] = position.z;
        timeline[offset + 3] = bodyRotation.x;
        timeline[offset + 4] = bodyRotation.y;
        timeline[offset + 5] = bodyRotation.z;
        timeline[offset + 6] = bodyRotation.w;
        for (let component = 0; component < 7; component++) {
          if (!Number.isFinite(timeline[offset + component])) {
            throw new RangeError(`solver produced nonfinite pose at frame ${frame}, body ${preparedScene.bodies[bodyIndex].name}`);
          }
        }
        const quaternionLength = Math.hypot(bodyRotation.x, bodyRotation.y, bodyRotation.z, bodyRotation.w);
        if (!quaternionLength || Math.abs(quaternionLength - 1) > 1e-3) {
          throw new RangeError('solver produced invalid quaternion');
        }
      }
    }
  } finally {
    eventQueue.free();
    world.free();
  }
  return recordedScene(preparedScene, timeline, { contactEvents, contactEventsTruncated, lastMovingFrames, jointBreaks });
}

function recordedScene(preparedScene, timeline, recording) {
  const bodyNames = Object.freeze(preparedScene.bodies.map(body => body.name));
  const indices = new Map(bodyNames.map((name, index) => [name, index]));
  const poseStride = bodyNames.length * 7;
  const duration = (preparedScene.frameCount - 1) * preparedScene.timestep;
  function ensureAlive() {
    if (!timeline) {
      throw new Error('physics scene is disposed');
    }
  }
  function bodyIndex(name) {
    ensureAlive();
    if (!indices.has(name)) {
      throw new TypeError(`unknown body ${name}`);
    }
    return indices.get(name);
  }
  function sample(time, output) {
    ensureAlive();
    if (typeof time !== 'number' || !Number.isFinite(time)) {
      throw new RangeError('sample time must be finite');
    }
    output ??= new Float32Array(poseStride);
    if (!(output instanceof Float32Array) || output.length !== poseStride) {
      throw new TypeError(`sample output must be Float32Array(${poseStride})`);
    }
    let frame = Math.max(0, Math.min(duration, time)) / preparedScene.timestep;
    const nearestFrame = Math.round(frame);
    if (Math.abs(frame - nearestFrame) <= Number.EPSILON * Math.max(1, frame) * 4) {
      frame = nearestFrame;
    }
    const leftFrame = Math.min(preparedScene.frameCount - 1, Math.floor(frame));
    const rightFrame = Math.min(preparedScene.frameCount - 1, leftFrame + 1);
    const interpolation = frame - leftFrame;
    for (let bodyIndex = 0; bodyIndex < bodyNames.length; bodyIndex++) {
      const outputOffset = bodyIndex * 7;
      const leftOffset = leftFrame * poseStride + outputOffset;
      const rightOffset = rightFrame * poseStride + outputOffset;
      for (let axis = 0; axis < 3; axis++) {
        output[outputOffset + axis] = timeline[leftOffset + axis] * (1 - interpolation) + timeline[rightOffset + axis] * interpolation;
      }
      if (interpolation === 0 || leftFrame === rightFrame) {
        for (let component = 3; component < 7; component++) {
          output[outputOffset + component] = timeline[leftOffset + component];
        }
        continue;
      }
      let quaternionDot = 0;
      for (let component = 3; component < 7; component++) {
        quaternionDot += timeline[leftOffset + component] * timeline[rightOffset + component];
      }
      const quaternionSign = quaternionDot < 0 ? -1 : 1;
      quaternionDot = Math.min(1, Math.abs(quaternionDot));
      let leftWeight = 1 - interpolation;
      let rightWeight = interpolation;
      if (quaternionDot < 0.9995) {
        const angle = Math.acos(quaternionDot);
        const angleSine = Math.sin(angle);
        leftWeight = Math.sin((1 - interpolation) * angle) / angleSine;
        rightWeight = Math.sin(interpolation * angle) / angleSine;
      }
      let quaternionLengthSquared = 0;
      for (let component = 3; component < 7; component++) {
        const interpolatedComponent = leftWeight * timeline[leftOffset + component] + quaternionSign * rightWeight * timeline[rightOffset + component];
        output[outputOffset + component] = interpolatedComponent;
        quaternionLengthSquared += interpolatedComponent ** 2;
      }
      const quaternionLength = Math.sqrt(quaternionLengthSquared);
      for (let component = 3; component < 7; component++) {
        output[outputOffset + component] /= quaternionLength;
      }
    }
    return output;
  }
  function bindParts(bindings) {
    ensureAlive();
    if (!Array.isArray(bindings) || bindings.length > preparedScene.memoryPlan.bodyCount * 16) {
      throw new RangeError('bindings must be a bounded array');
    }
    const matrices = new Set();
    const matricesByBuffer = new Map();
    const retainedBindings = bindings.map(binding => {
      fields(binding, ['body', 'part'], 'binding');
      const index = bodyIndex(binding.body);
      const matrix = binding.part?.matrix;
      if (!(matrix instanceof Float32Array) || matrix.length !== 16 || matrices.has(matrix)) {
        throw new TypeError('each binding requires a distinct retained Float32 part.matrix');
      }
      matrices.add(matrix);
      let bufferMatrices = matricesByBuffer.get(matrix.buffer);
      if (!bufferMatrices) {
        bufferMatrices = [];
        matricesByBuffer.set(matrix.buffer, bufferMatrices);
      }
      bufferMatrices.push(matrix);
      for (const value of matrix) {
        scalar(value, 'binding matrix');
      }
      if (matrix[3] !== 0 || matrix[7] !== 0 || matrix[11] !== 0 || matrix[15] !== 1) {
        throw new TypeError('binding matrix must be affine');
      }
      const scale = [Math.hypot(matrix[0], matrix[1], matrix[2]), Math.hypot(matrix[4], matrix[5], matrix[6]), Math.hypot(matrix[8], matrix[9], matrix[10])];
      for (const size of scale) {
        positive(size, 'binding scale');
      }
      for (const [firstAxis, secondAxis] of [[0, 1], [0, 2], [1, 2]]) {
        const axisDot = matrix[firstAxis * 4] * matrix[secondAxis * 4] + matrix[firstAxis * 4 + 1] * matrix[secondAxis * 4 + 1] + matrix[firstAxis * 4 + 2] * matrix[secondAxis * 4 + 2];
        if (Math.abs(axisDot / scale[firstAxis] / scale[secondAxis]) > 1e-5) {
          throw new TypeError('binding matrix shear is unsupported');
        }
      }
      if (mat4.determinant(matrix) < 0) {
        scale[0] *= -1;
      }
      return {
        part: binding.part,
        matrix,
        index,
        scale,
        position: new Float32Array(3),
        rotation: quat.create(),
        scratchMatrix: mat4.create(),
      };
    });
    for (const bufferMatrices of matricesByBuffer.values()) {
      bufferMatrices.sort((firstMatrix, secondMatrix) => firstMatrix.byteOffset - secondMatrix.byteOffset);
      for (let matrixIndex = 1; matrixIndex < bufferMatrices.length; matrixIndex++) {
        const previousMatrix = bufferMatrices[matrixIndex - 1];
        const currentMatrix = bufferMatrices[matrixIndex];
        if (previousMatrix.byteOffset + previousMatrix.byteLength > currentMatrix.byteOffset) {
          throw new TypeError('binding matrix views must not overlap');
        }
      }
    }
    const sampledPose = new Float32Array(poseStride);
    return Object.freeze({
      apply(time) {
        ensureAlive();
        for (let bindingIndex = 0; bindingIndex < retainedBindings.length; bindingIndex++) {
          if (retainedBindings[bindingIndex].part.matrix !== retainedBindings[bindingIndex].matrix) {
            throw new Error('binding part.matrix identity changed');
          }
        }
        sample(time, sampledPose);
        for (let bindingIndex = 0; bindingIndex < retainedBindings.length; bindingIndex++) {
          const binding = retainedBindings[bindingIndex];
          const offset = binding.index * 7;
          for (let axis = 0; axis < 3; axis++) {
            binding.position[axis] = sampledPose[offset + axis];
          }
          for (let component = 0; component < 4; component++) {
            binding.rotation[component] = sampledPose[offset + component + 3];
          }
          mat4.fromRotationTranslationScale(binding.scratchMatrix, binding.rotation, binding.position, binding.scale);
          for (let component = 0; component < 16; component++) {
            if (!Number.isFinite(binding.scratchMatrix[component])) {
              throw new RangeError('binding transform exceeds Float32 range');
            }
          }
        }
        for (let bindingIndex = 0; bindingIndex < retainedBindings.length; bindingIndex++) {
          retainedBindings[bindingIndex].matrix.set(retainedBindings[bindingIndex].scratchMatrix);
        }
        return bindings;
      },
    });
  }
  return Object.freeze({
    bodyNames,
    frameCount: preparedScene.frameCount,
    timestep: preparedScene.timestep,
    duration,
    memoryPlan: preparedScene.memoryPlan,
    bodyIndex,
    sample,
    bindParts,
    /** The stern of a boat body in body space, [x, y, z], or null when the body has no boat. */
    sternOf: name => preparedScene.buoyancy?.floating.find(floater => floater.bodyIndex === bodyIndex(name))?.boat?.stern ?? null,
    colliderNames: Object.freeze(preparedScene.colliders.map(collider => preparedScene.bodies[collider.body].name)),
    /** Contact and sensor start or stop events in step order, with collider indices into colliderNames. */
    contactEvents: Object.freeze(recording.contactEvents),
    contactEventsTruncated: recording.contactEventsTruncated,
    /** Glue joints that broke, in step order: the frame, the joint name and the contact impulse (N s) that broke it. */
    jointBreaks: Object.freeze(recording.jointBreaks),
    /** Per body: the frame at which it came to rest and stayed there, or -1 while it still moves at the end. */
    restFrames: Object.freeze(Array.from(recording.lastMovingFrames, frame => frame < preparedScene.frameCount - 1 ? frame + 1 : -1)),
    dispose() {
      timeline = null;
    },
    get disposed() {
      return timeline === null;
    },
  });
}

/** Validate a definition for the live runtime. There is no timeline, so the frame count is 1 and tick events are not accepted. */
export function prepareLivePhysics(definition, options = {}) {
  if (definition && definition.events !== undefined && definition.events.length) {
    throw new TypeError('a live physics definition takes no events; call applyImpulse, setKinematicPose or setLinearVelocity on the system instead');
  }
  const prepared = prepare({ ...definition, events: [] }, { ...options, frameCount: 1 });
  return prepared;
}

/** The loaded Rapier module, or throws when loadPhysicsEngine has not resolved. */
export function requireRapier() {
  if (!rapierEngine) throw new Error('Physics engine is not loaded. Await loadPhysicsEngine() first.');
  return rapierEngine;
}