@threenative/procedural-animals 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,815 @@
+import { Matrix4, BufferGeometry, BufferAttribute, Vector3, Group, Material, Mesh, Euler, Bone, DataTexture, RGBAFormat, FloatType, NearestFilter, Quaternion, Matrix3, Sphere, Box3 } from 'three';
+
+// src/format.ts
+var ANIMAL_DONOR_REVISION = "c95ae49346aa8e140a924376cec6cf0073d99512";
+var ANIMAL_ADAPTER_VERSION = 1;
+var ANIMAL_LIMITS = Object.freeze({
+  bytes: 64 * 1024 * 1024,
+  vertices: 25e4,
+  indices: 15e5,
+  bones: 256,
+  headerBytes: 1024 * 1024
+});
+var ANIMAL_ARRAYS = {
+  pos: [Float32Array, 3],
+  nrm: [Float32Array, 3],
+  index: [Uint32Array, 0],
+  skinIndex: [Uint16Array, 4],
+  skinWeight: [Float32Array, 4],
+  comb: [Float32Array, 3],
+  tint: [Float32Array, 4],
+  coat: [Float32Array, 4],
+  pat: [Float32Array, 4],
+  surf: [Float32Array, 4]
+};
+function bakeIntegrity(buffer) {
+  const view = new DataView(buffer);
+  const headerBytes = view.getUint32(8, true);
+  const start = Math.ceil((12 + headerBytes) / 8) * 8;
+  const bytes = new Uint8Array(buffer);
+  const header = JSON.parse(new TextDecoder().decode(bytes.subarray(12, 12 + headerBytes)));
+  const { integrity: _integrity, ...metadata } = header.threenative;
+  let hash = 2166136261;
+  for (const section of [
+    new TextEncoder().encode(JSON.stringify({ ...header, threenative: metadata })),
+    bytes.subarray(start)
+  ])
+    for (const byte of section) hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+  return hash.toString(16).padStart(8, "0");
+}
+var validatedBakes = /* @__PURE__ */ new WeakSet();
+function requireValidatedBake(bake) {
+  if (!validatedBakes.has(bake))
+    throw animalError("VALIDATION", "parse the complete bake before allocating resources");
+  validateArrayData(bake, bake.nV, bake.bones.length);
+}
+function animalError(code, detail) {
+  return new Error(`TN_ANIMAL_${code}: ${detail}`);
+}
+function record(value, name2) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw animalError("HEADER", `${name2} must be an object`);
+  }
+  return value;
+}
+function integer(value, min, max, name2) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+    throw animalError("LIMIT", `${name2} must be an integer in [${min}, ${max}]`);
+  }
+  return value;
+}
+function name(value, label) {
+  if (typeof value !== "string" || !/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/u.test(value)) {
+    throw animalError("RIG", `${label} must be a joint or bone name`);
+  }
+  return value;
+}
+function joints(value, label) {
+  const entries = Object.entries(record(value, label));
+  integer(entries.length, 2, 4096, `${label} count`);
+  for (const [key, point] of entries) {
+    name(key, label);
+    if (!Array.isArray(point) || point.length !== 3 || !point.every(Number.isFinite)) {
+      throw animalError("RIG", `${label}.${key} must be a finite point`);
+    }
+  }
+  return value;
+}
+function validateHeader(header) {
+  if (header.version !== 1 || header.species !== "wolf" || header.quality !== "high" && header.quality !== "crowd") {
+    throw animalError("REVISION", "expected version 1, wolf, and high or crowd geometry");
+  }
+  integer(header.seed, 0, 4294967295, "seed");
+  integer(header.nV, 3, ANIMAL_LIMITS.vertices, "vertex count");
+  const metadata = record(header.threenative, "threenative");
+  if (metadata.donorRevision !== ANIMAL_DONOR_REVISION || metadata.adapterVersion !== ANIMAL_ADAPTER_VERSION) {
+    throw animalError("REVISION", "unknown donor revision or adapter version");
+  }
+  if (typeof metadata.buildRuntime !== "string" || metadata.buildRuntime !== "node-v20.19.6" || typeof metadata.cacheKey !== "string" || !/^[a-f0-9]{64}$/u.test(metadata.cacheKey) || typeof metadata.integrity !== "string" || !/^[a-f0-9]{8}$/u.test(metadata.integrity)) {
+    throw animalError("HEADER", "missing pinned build runtime or SHA-256 cache key");
+  }
+  const params = record(header.params, "params");
+  if (typeof params.size !== "number" || !Number.isFinite(params.size) || params.size <= 0) {
+    throw animalError("RIG", "params.size must be finite and positive");
+  }
+  if (params.seed !== void 0 && params.seed !== header.seed)
+    throw animalError("OPTIONS", "individual seed contradicts bake seed");
+  const points = joints(header.joints, "joints");
+  joints(header.refJoints, "refJoints");
+  if (!Array.isArray(header.bones)) throw animalError("RIG", "bones must be an array");
+  integer(header.bones.length, 1, ANIMAL_LIMITS.bones, "bone count");
+  const parents = /* @__PURE__ */ new Map();
+  for (const value of header.bones) {
+    const bone = record(value, "bone");
+    const key = name(bone.name, "bone.name");
+    if (parents.has(key)) throw animalError("RIG", `duplicate bone ${key}`);
+    const parent = bone.parent === null ? null : name(bone.parent, `${key}.parent`);
+    parents.set(key, parent);
+    const headName = name(bone.headJ, `${key}.headJ`);
+    const tailName = name(bone.tailJ, `${key}.tailJ`);
+    const head = Object.hasOwn(points, headName) ? points[headName] : void 0;
+    const tail = Object.hasOwn(points, tailName) ? points[tailName] : void 0;
+    const length = head && tail ? Math.hypot(head[0] - tail[0], head[1] - tail[1], head[2] - tail[2]) : Number.NaN;
+    if (!Number.isFinite(length) || length < 1e-8) {
+      throw animalError("RIG", `${key} has missing joints or zero length`);
+    }
+  }
+  for (const key of parents.keys()) {
+    const seen = /* @__PURE__ */ new Set();
+    let current = key;
+    while (current !== null) {
+      if (seen.has(current) || !parents.has(current))
+        throw animalError("RIG", `${key} has a cyclic or missing parent`);
+      seen.add(current);
+      current = parents.get(current) ?? null;
+    }
+  }
+}
+function validateArrayData(arrays, vertices, boneCount) {
+  for (const key of Object.keys(ANIMAL_ARRAYS)) {
+    const array = arrays[key];
+    const [Constructor, width] = ANIMAL_ARRAYS[key];
+    if (!(array instanceof Constructor) || !array || (key === "index" ? array.length < 3 || array.length > ANIMAL_LIMITS.indices || array.length % 3 !== 0 : array.length !== vertices * width))
+      throw animalError("SECTIONS", `${key} changed after validation`);
+    for (const value of array) {
+      if (!Number.isFinite(value))
+        throw animalError("FINITE", `${key} contains a non-finite value`);
+      if (key === "index" && value >= vertices)
+        throw animalError("INDEX", `vertex index ${value} exceeds vertex count`);
+      if (key === "skinIndex" && value >= boneCount)
+        throw animalError("BONE_INDEX", `bone index ${value} exceeds bone count`);
+    }
+  }
+  const weights = arrays.skinWeight;
+  for (let i = 0; i < weights.length; i += 4) {
+    const group = weights.subarray(i, i + 4);
+    if (group.some((weight) => weight < 0 || weight > 1) || Math.abs(group.reduce((a, b) => a + b, 0) - 1) > 1e-4) {
+      throw animalError("WEIGHTS", `vertex ${i / 4} has non-normalized skin weights`);
+    }
+  }
+}
+function parseAnimalBake(buffer) {
+  if (!(buffer instanceof ArrayBuffer) || buffer.byteLength < 16 || buffer.byteLength > ANIMAL_LIMITS.bytes) {
+    throw animalError("LIMIT", `payload must contain 16..${ANIMAL_LIMITS.bytes} bytes`);
+  }
+  const bytes = new Uint8Array(buffer);
+  const view = new DataView(buffer);
+  if (view.getUint32(0, false) !== 1346457165) throw animalError("MAGIC", "expected PANM");
+  if (view.getUint32(4, true) !== 1) throw animalError("REVISION", "unknown PANM version");
+  const headerBytes = integer(
+    view.getUint32(8, true),
+    8,
+    ANIMAL_LIMITS.headerBytes,
+    "header bytes"
+  );
+  const start = Math.ceil((12 + headerBytes) / 8) * 8;
+  if (headerBytes % 8 !== 0 || start > buffer.byteLength)
+    throw animalError("SECTIONS", "truncated or unaligned header");
+  let header;
+  try {
+    header = record(
+      JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(12, 12 + headerBytes))
+      ),
+      "header"
+    );
+  } catch (error) {
+    throw animalError("HEADER", `invalid UTF-8/JSON header: ${String(error)}`);
+  }
+  const pending = [{ value: header, depth: 0 }];
+  let visited = 0;
+  while (pending.length > 0) {
+    if (++visited > 1e5)
+      throw animalError("LIMIT", "header exceeds the structural traversal limit");
+    const entry = pending.pop();
+    if (!entry) break;
+    const { value, depth } = entry;
+    if (depth > 64) throw animalError("LIMIT", "header nesting exceeds 64 levels");
+    if (typeof value === "number" && !Number.isFinite(value))
+      throw animalError("FINITE", "header contains a non-finite number");
+    if (value !== null && typeof value === "object")
+      for (const child of Object.values(value)) pending.push({ value: child, depth: depth + 1 });
+  }
+  validateHeader(header);
+  if (!Array.isArray(header.arrays) || header.arrays.length !== Object.keys(ANIMAL_ARRAYS).length) {
+    throw animalError("SECTIONS", "expected every supported array exactly once");
+  }
+  const arrays = {};
+  const ranges = [];
+  for (const value of header.arrays) {
+    const section = record(value, "section");
+    if (typeof section.key !== "string")
+      throw animalError("SECTIONS", "section key must be a string");
+    const key = section.key;
+    if (!Object.hasOwn(ANIMAL_ARRAYS, key) || arrays[key] !== void 0)
+      throw animalError("SECTIONS", `unknown or duplicate section ${String(key)}`);
+    const [Constructor, width] = ANIMAL_ARRAYS[key];
+    if (section.type !== Constructor.name)
+      throw animalError("SECTIONS", `${key} must contain ${Constructor.name}`);
+    const length = integer(
+      section.length,
+      1,
+      key === "index" ? ANIMAL_LIMITS.indices : ANIMAL_LIMITS.vertices * width,
+      `${key} length`
+    );
+    if (key === "index" && length % 3 !== 0 || key !== "index" && length !== Number(header.nV) * width) {
+      throw animalError("SECTIONS", `${key} length contradicts the vertex or triangle count`);
+    }
+    const offset = integer(section.offset, 0, ANIMAL_LIMITS.bytes, `${key} offset`);
+    const end2 = start + offset + Math.ceil(length * Constructor.BYTES_PER_ELEMENT / 8) * 8;
+    if (offset % 8 !== 0 || end2 > buffer.byteLength)
+      throw animalError("SECTIONS", `${key} is unaligned or truncated`);
+    ranges.push([start + offset, end2]);
+    arrays[key] = new Constructor(buffer, start + offset, length);
+  }
+  let end = start;
+  for (const range of ranges.sort((a, b) => a[0] - b[0])) {
+    if (range[0] !== end) throw animalError("SECTIONS", "sections overlap or contain gaps");
+    end = range[1];
+  }
+  if (end !== buffer.byteLength)
+    throw animalError("SECTIONS", "byte length contradicts section extents");
+  validateArrayData(arrays, Number(header.nV), header.bones.length);
+  if (bakeIntegrity(buffer) !== header.threenative.integrity)
+    throw animalError("INTEGRITY", "baked header or array bytes changed");
+  for (const key of Object.keys(arrays)) arrays[key] = arrays[key]?.slice();
+  const { arrays: _sections, ...data } = header;
+  const objects = [data];
+  while (objects.length > 0) {
+    const object = objects.pop();
+    if (!object) break;
+    for (const value of Object.values(object))
+      if (value !== null && typeof value === "object") objects.push(value);
+    Object.freeze(object);
+  }
+  const bake = Object.freeze({ ...data, ...arrays });
+  validatedBakes.add(bake);
+  return bake;
+}
+function checkCancelled(signal) {
+  if (signal?.aborted) throw animalError("ABORTED", "animal load cancelled");
+}
+function abortable(operation, signal, cancel) {
+  if (!signal) return operation;
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cancel?.();
+      signal.removeEventListener("abort", onAbort);
+      reject(animalError("ABORTED", "animal load cancelled"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        if (signal.aborted) onAbort();
+        else resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        if (signal.aborted) onAbort();
+        else reject(error);
+      }
+    );
+    if (signal.aborted) onAbort();
+  });
+}
+async function readBoundedBody(response, signal) {
+  if (!response.body) {
+    const bytes = await abortable(response.arrayBuffer(), signal);
+    if (bytes.byteLength > ANIMAL_LIMITS.bytes)
+      throw animalError("LIMIT", "decoded body exceeds the payload byte limit");
+    return bytes;
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let length = 0;
+  const cancel = () => {
+    void reader.cancel().catch(() => void 0);
+  };
+  try {
+    for (; ; ) {
+      checkCancelled(signal);
+      const result = await abortable(reader.read(), signal, cancel);
+      checkCancelled(signal);
+      if (result.done) break;
+      length += result.value.byteLength;
+      if (length > ANIMAL_LIMITS.bytes)
+        throw animalError("LIMIT", "decoded body exceeds the payload byte limit");
+      chunks.push(result.value);
+    }
+    const buffer = new ArrayBuffer(length);
+    const bytes = new Uint8Array(buffer);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return buffer;
+  } catch (error) {
+    cancel();
+    checkCancelled(signal);
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function loadAnimalBake(assets, logicalPath, options = {}) {
+  checkCancelled(options.signal);
+  const urls = await abortable(assets.resolve(logicalPath), options.signal);
+  checkCancelled(options.signal);
+  if (urls.length === 0) throw animalError("LOAD", `${logicalPath} resolved to no asset`);
+  const failures = [];
+  for (const url of urls) {
+    let response;
+    try {
+      response = await fetch(url, { signal: options.signal });
+    } catch (error) {
+      checkCancelled(options.signal);
+      failures.push(`${url}: ${String(error)}`);
+      continue;
+    }
+    if (options.signal?.aborted) {
+      await response.body?.cancel().catch(() => void 0);
+      checkCancelled(options.signal);
+    }
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => void 0);
+      failures.push(`${url}: HTTP ${response.status}`);
+      continue;
+    }
+    const announced = response.headers.get("content-length");
+    if (announced !== null && Number(announced) > ANIMAL_LIMITS.bytes) {
+      await response.body?.cancel().catch(() => void 0);
+      throw animalError("LIMIT", `${logicalPath} exceeds the payload byte limit`);
+    }
+    const buffer = await readBoundedBody(response, options.signal);
+    checkCancelled(options.signal);
+    return parseAnimalBake(buffer);
+  }
+  throw animalError("LOAD", `${logicalPath} failed: ${failures.join("; ")}`);
+}
+function createAnimalGeometry(buffer) {
+  const bake = parseAnimalBake(buffer);
+  return { bake, geometry: geometryFromValidatedBake(bake) };
+}
+function geometryFromValidatedBake(bake) {
+  requireValidatedBake(bake);
+  const geometry = new BufferGeometry();
+  for (const [name2, data, size] of [
+    ["position", bake.pos, 3],
+    ["normal", bake.nrm, 3],
+    ["skinIndex", bake.skinIndex, 4],
+    ["skinWeight", bake.skinWeight, 4],
+    ["aComb", bake.comb, 3],
+    ["aTint", bake.tint, 4],
+    ["aCoat", bake.coat, 4],
+    ["aPat", bake.pat, 4],
+    ["aSurf", bake.surf, 4]
+  ])
+    geometry.setAttribute(name2, new BufferAttribute(data.slice(), size));
+  geometry.setIndex(new BufferAttribute(bake.index.slice(), 1));
+  return geometry;
+}
+function float32Norm(x, y, z, w = 0) {
+  return Math.sqrt(x * x + y * y + z * z + w * w);
+}
+function createAnimalBounds(bake, geometry) {
+  requireValidatedBake(bake);
+  let radius = 0;
+  let minimumFirstWeight = 1;
+  let maximumWeightSum = 0;
+  let previousPosition;
+  let previousWeights;
+  let previousIndices;
+  let positionVersion = -1;
+  let weightVersion = -1;
+  let indexVersion = -1;
+  const measure = () => {
+    const attribute = (name2, size) => {
+      if (!geometry) return void 0;
+      const value = geometry.getAttribute(name2);
+      if (!(value instanceof BufferAttribute) || value.itemSize !== size || value.count !== bake.nV)
+        throw animalError(
+          "BOUNDS",
+          "edited geometry must retain ordinary position/skin attributes and vertex count"
+        );
+      return value;
+    };
+    const position = attribute("position", 3);
+    const weights = attribute("skinWeight", 4);
+    const indices = attribute("skinIndex", 4);
+    if (weights?.normalized || indices?.normalized)
+      throw animalError("BOUNDS", "normalized edited skin attributes are unsupported");
+    if (position === previousPosition && weights === previousWeights && indices === previousIndices && position?.version === positionVersion && weights?.version === weightVersion && indices?.version === indexVersion)
+      return;
+    radius = 0;
+    minimumFirstWeight = 1;
+    maximumWeightSum = 0;
+    for (let v = 0; v < bake.nV; v++) {
+      const x = position?.getX(v) ?? bake.pos[v * 3] ?? 0;
+      const y = position?.getY(v) ?? bake.pos[v * 3 + 1] ?? 0;
+      const z = position?.getZ(v) ?? bake.pos[v * 3 + 2] ?? 0;
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+        throw animalError("BOUNDS", "edited bind positions must be finite");
+      radius = Math.max(radius, Math.hypot(x, y, z));
+      let sum = 0;
+      for (let influence = 0; influence < 4; influence++) {
+        const weight = weights ? weights.array[v * 4 + influence] : bake.skinWeight[v * 4 + influence];
+        const index = indices ? indices.array[v * 4 + influence] : bake.skinIndex[v * 4 + influence];
+        if (weight === void 0 || !Number.isFinite(weight) || weight < 0 || weight > 1 || index === void 0 || !Number.isInteger(index) || index < 0 || index >= bake.bones.length)
+          throw animalError("BOUNDS", "edited skin weights/indices must remain valid");
+        if (influence === 0) minimumFirstWeight = Math.min(minimumFirstWeight, weight);
+        sum += weight;
+      }
+      if (Math.abs(sum - 1) > 1e-4)
+        throw animalError("BOUNDS", "edited skin weights must remain normalized");
+      maximumWeightSum = Math.max(maximumWeightSum, sum);
+    }
+    previousPosition = position;
+    previousWeights = weights;
+    previousIndices = indices;
+    positionVersion = previousPosition?.version ?? -1;
+    weightVersion = previousWeights?.version ?? -1;
+    indexVersion = previousIndices?.version ?? -1;
+  };
+  measure();
+  const sphere = new Sphere(new Vector3(), 0);
+  const box = new Box3();
+  return {
+    sphere,
+    box,
+    update(data) {
+      if (geometry) measure();
+      sphere.center.set(0, 0, 0);
+      if (data.length !== bake.bones.length * 20)
+        throw animalError("BOUNDS", "missing or non-finite pose packet");
+      for (let p = 0; p < data.length; p++)
+        if (!Number.isFinite(data[p]))
+          throw animalError("BOUNDS", "missing or non-finite pose packet");
+      let scaledRadius = 0;
+      let dualRadius = 0;
+      let minimumQuaternionLength = Number.POSITIVE_INFINITY;
+      const norm = data instanceof Float32Array ? float32Norm : Math.hypot;
+      for (let o = 0; o < data.length; o += 20) {
+        minimumQuaternionLength = Math.min(
+          minimumQuaternionLength,
+          norm(data[o] ?? 0, data[o + 1] ?? 0, data[o + 2] ?? 0, data[o + 3] ?? 0)
+        );
+        dualRadius = Math.max(
+          dualRadius,
+          norm(data[o + 4] ?? 0, data[o + 5] ?? 0, data[o + 6] ?? 0, data[o + 7] ?? 0)
+        );
+        let normSquared = 0;
+        for (let row = 8; row <= 16; row += 4)
+          for (let column = 0; column < 3; column++)
+            normSquared += (data[o + row + column] ?? 0) ** 2;
+        const offset = norm(data[o + 11] ?? 0, data[o + 15] ?? 0, data[o + 19] ?? 0);
+        scaledRadius = Math.max(scaledRadius, Math.sqrt(normSquared) * radius + offset);
+      }
+      const denominator = Math.max(minimumFirstWeight * minimumQuaternionLength, 1e-6);
+      const bound = scaledRadius + 2 * dualRadius * maximumWeightSum / denominator;
+      if (!Number.isFinite(bound)) throw animalError("BOUNDS", "unbounded pose envelope");
+      sphere.radius = bound * (1 + 64 * 2 ** -23) + 64 * 2 ** -23;
+      sphere.getBoundingBox(box);
+    }
+  };
+}
+function bindFrame(head, tail) {
+  const origin = new Vector3().fromArray(head);
+  const y = new Vector3().fromArray(tail).sub(origin).normalize();
+  const x = new Vector3(1, 0, 0).addScaledVector(y, -y.x);
+  if (x.lengthSq() < 1e-10) x.set(0, 0, 1).addScaledVector(y, -y.z);
+  x.normalize();
+  return new Matrix4().makeBasis(x, y, new Vector3().crossVectors(x, y)).setPosition(origin);
+}
+function createAnimalPose(bake) {
+  requireValidatedBake(bake);
+  const bind = bake.bones.map((bone) => {
+    const head = bake.joints[bone.headJ];
+    const tail = bake.joints[bone.tailJ];
+    if (!head || !tail) throw animalError("RIG", "validated joint disappeared");
+    return bindFrame(head, tail);
+  });
+  const bones = bind.map((matrix, i) => {
+    const bone = new Bone();
+    bone.name = bake.bones[i]?.name ?? "";
+    bone.matrixAutoUpdate = bone.matrixWorldAutoUpdate = false;
+    bone.matrixWorld.copy(matrix);
+    return bone;
+  });
+  const skeleton = { bones, bind, inverses: bind.map((matrix) => matrix.clone().invert()) };
+  const data = new Float32Array(bones.length * 20);
+  const pending = new Float32Array(data.length);
+  const texture = new DataTexture(data, bones.length * 5, 1, RGBAFormat, FloatType);
+  texture.minFilter = texture.magFilter = NearestFilter;
+  texture.generateMipmaps = false;
+  const bindRotation = [];
+  const bindPosition = [];
+  const bindAxes = [];
+  const position = new Vector3();
+  const rotation = new Quaternion();
+  const scale = new Vector3();
+  for (const matrix of bind) {
+    matrix.decompose(position, rotation, scale);
+    bindPosition.push(position.clone());
+    bindRotation.push(rotation.clone().invert());
+    bindAxes.push(new Matrix3().setFromMatrix4(new Matrix4().makeRotationFromQuaternion(rotation)));
+  }
+  const local = new Matrix4();
+  const affine = new Matrix3();
+  const scaling = new Matrix3();
+  const transpose = new Matrix3();
+  const translation = new Vector3();
+  let disposed = false;
+  return {
+    skeleton,
+    data,
+    texture,
+    update(worldToLocal) {
+      if (disposed) throw animalError("DISPOSED", "pose is disposed");
+      for (let i = 0; i < bones.length; i++) {
+        const bone = bones[i];
+        const inverse = bindRotation[i];
+        const origin = bindPosition[i];
+        const axes = bindAxes[i];
+        if (!bone || !inverse || !origin || !axes) throw animalError("RIG", "missing pose bone");
+        local.multiplyMatrices(worldToLocal, bone.matrixWorld);
+        for (let j = 0; j < local.elements.length; j++)
+          if (!Number.isFinite(local.elements[j]))
+            throw animalError("POSE", `${bone.name} has non-finite matrix`);
+        local.decompose(position, rotation, scale);
+        if (!(Math.abs(scale.x) > 1e-8) || !(Math.abs(scale.y) > 1e-8) || !(Math.abs(scale.z) > 1e-8))
+          throw animalError("POSE", `${bone.name} has singular scale`);
+        rotation.multiply(inverse);
+        translation.copy(origin).applyQuaternion(rotation).negate().add(position);
+        const o = i * 20;
+        const { x, y, z, w } = rotation;
+        const tx = translation.x;
+        const ty = translation.y;
+        const tz = translation.z;
+        pending[o] = x;
+        pending[o + 1] = y;
+        pending[o + 2] = z;
+        pending[o + 3] = w;
+        pending[o + 4] = 0.5 * (w * tx + ty * z - tz * y);
+        pending[o + 5] = 0.5 * (w * ty + tz * x - tx * z);
+        pending[o + 6] = 0.5 * (w * tz + tx * y - ty * x);
+        pending[o + 7] = -0.5 * (tx * x + ty * y + tz * z);
+        affine.multiplyMatrices(axes, scaling.set(scale.x, 0, 0, 0, scale.y, 0, 0, 0, scale.z)).multiply(transpose.copy(axes).transpose());
+        const e = affine.elements;
+        pending[o + 8] = e[0];
+        pending[o + 9] = e[3];
+        pending[o + 10] = e[6];
+        pending[o + 11] = origin.x - (e[0] * origin.x + e[3] * origin.y + e[6] * origin.z);
+        pending[o + 12] = e[1];
+        pending[o + 13] = e[4];
+        pending[o + 14] = e[7];
+        pending[o + 15] = origin.y - (e[1] * origin.x + e[4] * origin.y + e[7] * origin.z);
+        pending[o + 16] = e[2];
+        pending[o + 17] = e[5];
+        pending[o + 18] = e[8];
+        pending[o + 19] = origin.z - (e[2] * origin.x + e[5] * origin.y + e[8] * origin.z);
+      }
+      for (let p = 0; p < pending.length; p++)
+        if (!Number.isFinite(pending[p]))
+          throw animalError("POSE", "pose packet exceeds float range");
+      data.set(pending);
+      texture.needsUpdate = true;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      texture.dispose();
+    }
+  };
+}
+
+// src/follow.ts
+var identity = new Matrix4();
+function requireIdentityParent(object) {
+  if (!object) return;
+  if (!object.matrix.elements.every(Number.isFinite))
+    throw animalError("PARENT_TRANSFORM", "parent local matrix must be finite");
+  object.updateWorldMatrix(true, false);
+  if (object.matrixWorld.elements.some(
+    (value, index) => !Number.isFinite(value) || Math.abs(value - (identity.elements[index] ?? 0)) > 1e-9
+  ))
+    throw animalError(
+      "PARENT_TRANSFORM",
+      "the first animal adapter requires an identity parent world transform"
+    );
+}
+function finiteVector(value) {
+  if (!value || ![value.x, value.y, value.z].every(Number.isFinite))
+    throw animalError("FOLLOW_STATE", "accepted vectors must be finite");
+}
+function cleanupOwned(callbacks, failure) {
+  const errors = failure === void 0 ? [] : [failure];
+  for (const callback of callbacks) {
+    try {
+      callback();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, errors.map(String).join("; "));
+}
+function createAnimalActor(bake, options) {
+  requireValidatedBake(bake);
+  requireIdentityParent(options.parent ?? null);
+  const originOffset = new Vector3().copy(options.visualOriginOffset ?? { x: 0, y: 0, z: 0 });
+  finiteVector(originOffset);
+  if (typeof options.ground !== "function" || typeof options.motion !== "function" || typeof options.material !== "function")
+    throw animalError("OPTIONS", "ground, game motion and material factories are required");
+  const object = new Group();
+  const root = new Vector3();
+  const velocity = new Vector3();
+  const foot = new Vector3();
+  const geometry = geometryFromValidatedBake(bake);
+  const pose = createAnimalPose(bake);
+  const bounds = createAnimalBounds(bake, geometry);
+  const worldToLocal = new Matrix4();
+  let heading = 0;
+  let groundBias = 0;
+  let disposed = false;
+  let paused = false;
+  const actions = /* @__PURE__ */ new Set();
+  const ground = (x, z) => {
+    const height = options.ground(x, z);
+    if (!Number.isFinite(height))
+      throw animalError("GROUND", `no finite physics/navigation ground at ${x},${z}`);
+    return height + groundBias;
+  };
+  const createMotion = () => options.motion({
+    data: bake,
+    skeleton: pose.skeleton,
+    ground,
+    position: foot.clone(),
+    heading,
+    emit: () => void 0
+  });
+  let material;
+  let motion;
+  let motionOwned = false;
+  try {
+    material = options.material(pose);
+    if (!(material instanceof Material))
+      throw animalError("MATERIAL", "game factory must return a material");
+    motion = createMotion();
+    motionOwned = true;
+  } catch (error) {
+    cleanupOwned(
+      [
+        () => {
+          if (material instanceof Material) material.dispose();
+        },
+        () => geometry.dispose(),
+        () => pose.dispose()
+      ],
+      error
+    );
+    throw error;
+  }
+  if (!material) throw animalError("MATERIAL", "missing material");
+  const ownedMaterial = material;
+  const mesh = new Mesh(geometry, ownedMaterial);
+  object.add(mesh);
+  geometry.boundingSphere = bounds.sphere;
+  geometry.boundingBox = bounds.box;
+  const requireLive = () => {
+    if (disposed) throw animalError("DISPOSED", "animal actor is disposed");
+  };
+  const settle = (result) => {
+    for (const done of [...actions]) done(result);
+  };
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    settle("disposed");
+    cleanupOwned([
+      () => {
+        if (motionOwned) {
+          motionOwned = false;
+          motion.dispose();
+        }
+      },
+      () => object.removeFromParent(),
+      () => object.clear(),
+      () => geometry.dispose(),
+      () => ownedMaterial.dispose(),
+      () => pose.dispose()
+    ]);
+  };
+  const nextFoot = new Vector3();
+  const rootEuler = new Euler();
+  const up = new Vector3(0, 1, 0);
+  const following = { position: foot, velocity, heading: 0 };
+  const assign = (state) => {
+    finiteVector(state.position);
+    finiteVector(state.velocity);
+    if (!Number.isFinite(state.heading))
+      throw animalError("FOLLOW_STATE", "accepted heading must be finite");
+    requireIdentityParent(object.parent);
+    nextFoot.copy(originOffset).applyAxisAngle(up, state.heading).add(state.position);
+    finiteVector(nextFoot);
+    const sampled = options.ground(nextFoot.x, nextFoot.z);
+    if (!Number.isFinite(sampled)) throw animalError("GROUND", "missing ground at accepted root");
+    root.copy(state.position);
+    velocity.copy(state.velocity);
+    heading = state.heading;
+    object.position.copy(root);
+    object.quaternion.setFromEuler(rootEuler.set(0, heading, 0));
+    foot.copy(nextFoot);
+    groundBias = foot.y - sampled;
+    motion.input.speed = 0;
+    motion.input.target = null;
+    motion.input.heading = heading;
+    following.heading = heading;
+    motion.input.follow = following;
+  };
+  const upload = () => {
+    object.updateMatrix();
+    worldToLocal.copy(object.matrix).invert();
+    pose.update(worldToLocal);
+    bounds.update(pose.data);
+  };
+  try {
+    options.parent?.add(object);
+    motion.update(1e-4);
+    upload();
+  } catch (error) {
+    cleanupOwned([dispose], error);
+    throw error;
+  }
+  return {
+    object,
+    mesh,
+    pose,
+    bounds,
+    /** Measurement survives the explicit origin override. */
+    visualOriginOffset: originOffset.clone(),
+    get paused() {
+      return paused;
+    },
+    set paused(value) {
+      requireLive();
+      paused = value;
+    },
+    follow(state, dt) {
+      requireLive();
+      if (!Number.isFinite(dt) || dt < 0 || dt > 1 / 20)
+        throw animalError("FIXED_STEP", "follow requires a finite fixed step in [0, 1/20]");
+      assign(state);
+      if (paused || dt === 0) {
+        bounds.update(pose.data);
+        return;
+      }
+      motion.update(dt);
+      upload();
+    },
+    teleport(state) {
+      requireLive();
+      assign(state);
+      settle("interrupted");
+      try {
+        motionOwned = false;
+        motion.dispose();
+        velocity.set(0, 0, 0);
+        motion = createMotion();
+        motionOwned = true;
+        following.heading = heading;
+        motion.input.follow = following;
+        motion.update(1e-4);
+        upload();
+      } catch (error) {
+        cleanupOwned([dispose], error);
+        throw error;
+      }
+    },
+    play(name2) {
+      requireLive();
+      if (!["stand", "sit", "lie"].includes(name2))
+        throw animalError("ACTION", `unsupported first-slice action ${name2}`);
+      return new Promise((resolve, reject) => {
+        const done = (result) => {
+          if (!actions.delete(done)) return;
+          resolve(result);
+        };
+        actions.add(done);
+        try {
+          motion.play(name2).then(done, (error) => {
+            actions.delete(done);
+            reject(error);
+          });
+        } catch (error) {
+          actions.delete(done);
+          reject(error);
+        }
+      });
+    },
+    dispose
+  };
+}
+
+export { createAnimalActor, createAnimalGeometry, loadAnimalBake, parseAnimalBake };