three-vat 1.0.0 → 2.0.0

package/dist/chunk-W2ZAFMPB.js

@@ -0,0 +1,53 @@
+// src/baked-normals.ts
+var NORMAL_READING_FLAGS = [
+  "isMeshStandardMaterial",
+  "isMeshPhongMaterial",
+  "isMeshLambertMaterial",
+  "isMeshToonMaterial",
+  "isMeshNormalMaterial",
+  "isMeshMatcapMaterial"
+];
+function needsBakedNormal(material) {
+  if (material.flatShading === true) return false;
+  const flags = material;
+  return NORMAL_READING_FLAGS.some((flag) => flags[flag] === true);
+}
+function assertBakedNormal(vat, material) {
+  if (vat.normalTexture !== null || !needsBakedNormal(material)) return;
+  throw new Error(
+    `three-vat: material "${material.name || "(unnamed)"}" (${material.type}) shades from a normal, but this VAT was baked with \`bakeNormals: false\` and carries none \u2014 the crowd would be lit by its rest pose. Set \`flatShading: true\` on the material (three then derives the normal from the deformed position, per fragment, which is the right normal for a posed mesh), or use an unlit material such as MeshBasicMaterial, or bake with \`bakeNormals: true\`.`
+  );
+}
+
+// src/carrier.ts
+function isBatchedCarrier(carrier) {
+  return carrier?.isBatchedMesh === true;
+}
+function rangeOf(batch, geometryId) {
+  try {
+    return batch.getGeometryRangeAt(geometryId);
+  } catch {
+    return null;
+  }
+}
+function assertVATCarrier(carrier, vat) {
+  if (!isBatchedCarrier(carrier)) return;
+  if (rangeOf(carrier, 1)) {
+    throw new Error(
+      "three-vat: a BatchedMesh carrier must hold exactly one geometry \u2014 the VAT\u2019s own. Both decode paths index the VAT by the vertex index, which on a batch is the geometry\u2019s vertexStart plus the vertex, so a second geometry\u2019s instances read another character\u2019s rows. One VAT, one geometry, N instances: mixing characters in one draw needs one VAT texture each, and a sampler is a uniform per draw call."
+    );
+  }
+  const range = rangeOf(carrier, 0);
+  if (!range) {
+    throw new Error(
+      "three-vat: this BatchedMesh holds no geometry \u2014 add `vat.geometry` with `addGeometry` before patching a material for it."
+    );
+  }
+  if (range.vertexStart !== 0 || range.vertexCount !== vat.vertexCount) {
+    throw new Error(
+      `three-vat: this BatchedMesh\u2019s geometry spans ${range.vertexCount} vertices from ${range.vertexStart}, and the VAT has ${vat.vertexCount} from 0. The decode reads the VAT at the batch\u2019s own vertex index, so the batch must hold \`vat.geometry\` and nothing before it.`
+    );
+  }
+}
+
+export { assertBakedNormal, assertVATCarrier, isBatchedCarrier };

package/dist/index.d.ts

@@ -1,16 +1,16 @@
-import { Object3D, AnimationClip, TypedArray, TextureDataType, DataTexture } from 'three';
-import { V as VAT } from './instance-playback-BrGBIKLe.js';
-export { a as VATClip, b as VATClock, c as VATCrowd, d as VATInstance, e as addVATInstanceAttributes } from './instance-playback-BrGBIKLe.js';
+import { AnimationClip, AnimationAction, Object3D, TypedArray, TextureDataType, DataTexture } from 'three';
+import { V as VAT } from './carrier-BFCPmcQK.js';
+export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, M as MAX_FADE_DURATION, a as VATCarrier, b as VATClip, c as VATClipDefaults, d as VATClock, e as VATCrowd, f as VATFadeFrom, g as VATFrame, h as VATInstance, i as VATPlaybackTexture, j as createVATPlaybackTexture, k as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BFCPmcQK.js';
 
 /**
- * Conservative fallback texture-dimension cap, used when the caller does not
- * pass `maxTextureSize`. This is the WebGL2 *spec floor for high-end desktop*,
- * not a guarantee — plenty of mobile GPUs report 4096 or 8192. The baker is
- * renderer-agnostic by design (it runs in Node, and in a Web Worker), so it cannot
- * query the real limit itself: pass `getMaxTextureSize(renderer)` from
- * `three-vat/webgl` or `three-vat/tsl` whenever a renderer exists.
+ * What {@link bakeVAT} takes for each animation: the clip itself, or an
+ * `AnimationAction` already configured the way three taught you.
+ *
+ * An action costs the baker nothing — it builds an `AnimationMixer` to pose the
+ * mesh either way — and buys the caller per-clip defaults every instance of
+ * that clip inherits ({@link VATClipDefaults}).
  */
-declare const MAX_TEXTURE_SIZE = 16384;
+type BakeInput = AnimationClip | AnimationAction;
 interface BakeOptions {
     /** Sample rate in frames per second. Default `30`. */
     fps?: number;
@@ -21,10 +21,55 @@ interface BakeOptions {
      * VAT that allocates on your desktop and fails on a phone.
      */
     maxTextureSize?: number;
+    /**
+     * Bake the normal texture. Default `true`.
+     *
+     * Turning it off halves the VAT — `verts x frames x 16 B x 2` becomes `x 1` —
+     * and is correct for exactly two material setups:
+     *
+     * - **Unlit** (`MeshBasicMaterial`, and its node twin), which never reads a
+     *   normal, so the texture was pure waste.
+     * - **`flatShading: true`**, where three derives the normal from screen-space
+     *   derivatives of the *deformed* position in the fragment stage. That is the
+     *   correct normal for the posed mesh, computed for free — the baked one is
+     *   not merely unnecessary there, it is redundant work.
+     *
+     * Anything else that shades — a smooth-shaded lit material — would light the
+     * crowd by its rest-pose normals, which is visibly wrong (ADR-0002). Both
+     * decode paths refuse that pairing loudly rather than render it.
+     */
+    bakeNormals?: boolean;
 }
 /**
- * Bake `AnimationClip`s into a VAT by sampling the posed subtree frame by frame
- * on the CPU.
+ * Bake animations into a VAT by sampling the posed subtree frame by frame on
+ * the CPU.
+ *
+ * Each entry of `animations` is an `AnimationClip`, or an `AnimationAction`
+ * already configured the way three taught you:
+ *
+ * ```ts
+ * const action = mixer.clipAction(deathClip)
+ * action.loop = THREE.LoopOnce
+ *
+ * const vat = bakeVAT(gltf.scene, [walkAction, action, idleClip])
+ * ```
+ *
+ * Every instance that plays `death` then inherits "once, clamped" without the
+ * caller saying so again, and may still override any of it. An action costs the
+ * bake nothing — it builds an `AnimationMixer` to pose the mesh either way — and
+ * a plain clip carries no configuration, so the simple case still needs no
+ * mixer at all and takes the library defaults ({@link VATClipDefaults}).
+ *
+ * `loop`, `repetitions` and `timeScale` are read. **`clampWhenFinished` is
+ * not**: it is `false` on every untouched action, so a crowd reads it as the
+ * silence it usually is and clamps either way — an instance names
+ * `endMode: EndMode.Rewind` to get three's behaviour back.
+ * **`time` and `paused` are ignored**: they say where a playhead is sitting,
+ * not how the animation is meant to play, and a VAT has no playhead of its own
+ * to seed — every instance's position is a function of the shared clock and its
+ * own `startTime`. A non-unit `weight` and an additive `blendMode` are refused
+ * outright; both describe several actions blended at once, which one baked band
+ * cannot be.
  *
  * The unit of a bake is the whole subtree under `root`, merged into one vertex
  * set and recorded in root space (ADR-0008) — so it handles a single
@@ -45,7 +90,26 @@ interface BakeOptions {
  * Renderer-agnostic — touches no WebGL/WebGPU context — so it runs identically
  * at runtime, in a Web Worker, and in Node.
  */
-declare function bakeVAT(root: Object3D, clips: AnimationClip[], { fps, maxTextureSize }?: BakeOptions): VAT;
+declare function bakeVAT(root: Object3D, animations: BakeInput[], { fps, maxTextureSize, bakeNormals }?: BakeOptions): VAT;
+
+/**
+ * The WebGL2 *spec floor for high-end desktop*, which two things lean on.
+ *
+ * - **The bake's fallback cap**, used when the caller does not pass
+ *   `maxTextureSize`. The baker is renderer-agnostic by design (it runs in
+ *   Node, and in a Web Worker) so it cannot query the real limit itself: pass
+ *   `getMaxTextureSize(renderer)` from `three-vat/webgl` or `three-vat/tsl`
+ *   whenever a renderer exists.
+ * - **The instance ceiling**, because the playback texture is one row per
+ *   instance (`createVATPlaybackTexture`, ADR-0016). That one takes no
+ *   override, the crowd being built long after the bake was sized.
+ *
+ * Not a guarantee either way: plenty of mobile GPUs report 4096 or 8192, and
+ * a crowd between that and this number is refused by the driver at upload
+ * rather than here. The bake is where the real limit is worth passing, because
+ * it is where the numbers get large.
+ */
+declare const MAX_TEXTURE_SIZE = 16384;
 /**
  * Build a VAT `DataTexture` with the fixed sampling flags every path relies on:
  * RGBA, nearest filtering, no mipmaps. Frame interpolation is done manually in
@@ -53,4 +117,4 @@ declare function bakeVAT(root: Object3D, clips: AnimationClip[], { fps, maxTextu
  */
 declare function makeVATTexture(data: TypedArray, width: number, height: number, type?: TextureDataType): DataTexture;
 
-export { type BakeOptions, MAX_TEXTURE_SIZE, VAT, bakeVAT, makeVATTexture };
+export { type BakeInput, type BakeOptions, MAX_TEXTURE_SIZE, VAT, bakeVAT, makeVATTexture };

package/dist/index.js

@@ -1,7 +1,54 @@
-export { addVATInstanceAttributes } from './chunk-SXTVASKG.js';
-import { FloatType, Matrix4, AnimationMixer, Box3, Vector4, Vector3, Sphere, DataTexture, RGBAFormat, NearestFilter, BufferGeometry, BufferAttribute } from 'three';
+import { LoopMode, MAX_TEXTURE_SIZE, makeVATTexture, LIBRARY_PLAYBACK_DEFAULTS, FORWARD_ONLY_REASON, INFINITE_REPETITIONS } from './chunk-2PGZ44TP.js';
+export { EndMode, INFINITE_REPETITIONS, LoopMode, MAX_FADE_DURATION, MAX_TEXTURE_SIZE, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance } from './chunk-2PGZ44TP.js';
+import { LoopRepeat, LoopOnce, LoopPingPong, Matrix4, AnimationMixer, Box3, Vector4, Vector3, Sphere, AdditiveAnimationBlendMode, BufferAttribute, BufferGeometry } from 'three';
 
-var MAX_TEXTURE_SIZE = 16384;
+var LOOP_MODES = /* @__PURE__ */ new Map([
+  [LoopRepeat, LoopMode.Repeat],
+  [LoopOnce, LoopMode.Once],
+  [LoopPingPong, LoopMode.PingPong]
+]);
+function isAction(input) {
+  return typeof input.getClip === "function";
+}
+function resolveAnimation(input) {
+  if (!isAction(input)) return { clip: input, defaults: { ...LIBRARY_PLAYBACK_DEFAULTS } };
+  const clip = input.getClip();
+  const name = clip.name || "(unnamed)";
+  const cannotBlend = (field, value) => new Error(
+    `three-vat: action for clip "${name}" has ${field} ${value}; that blends several actions at once, which a single baked band cannot represent \u2014 bake the clips separately and crossfade between them (three-vat#30), or reset the action before baking`
+  );
+  if (input.weight !== 1) throw cannotBlend("weight", String(input.weight));
+  if (input.blendMode === AdditiveAnimationBlendMode) throw cannotBlend("blendMode", "additive");
+  if (input.timeScale < 0) {
+    throw new Error(
+      `three-vat: action for clip "${name}" has timeScale ${input.timeScale}; ${FORWARD_ONLY_REASON}.`
+    );
+  }
+  const loopMode = LOOP_MODES.get(input.loop);
+  if (loopMode === void 0) {
+    throw new Error(
+      `three-vat: action for clip "${name}" has an unrecognised loop mode ${input.loop}; expected THREE.LoopRepeat, LoopOnce or LoopPingPong`
+    );
+  }
+  return {
+    clip,
+    defaults: {
+      loopMode,
+      // three's `repetitions` defaults to Infinity and `LoopOnce` ignores it
+      // outright — so a one-shot is one play whatever the field says, and an
+      // endless count becomes the sentinel a Float32Array can carry.
+      repetitions: loopMode === LoopMode.Once ? 1 : Number.isFinite(input.repetitions) ? input.repetitions : INFINITE_REPETITIONS,
+      // Not read off the action (see the rule above), so a bake clamps whichever
+      // input it was handed. Uniform across loop modes on purpose: an instance
+      // may override a repeating clip's `loopMode` to `Once` and inherit this
+      // field, so there is no mode whose end mode is safely unreachable and
+      // could hold a different answer. Rewind is per instance:
+      // `{ ..., endMode: EndMode.Rewind }` (#43, ADR-0017).
+      endMode: LIBRARY_PLAYBACK_DEFAULTS.endMode,
+      speed: input.timeScale
+    }
+  };
+}
 function asAttribute(value, mesh, name) {
   if (!(value instanceof BufferAttribute)) {
     throw new Error(
@@ -44,6 +91,8 @@ function collectParts(root) {
       baseNrm: asAttribute(geometry.attributes.normal, mesh, "normal"),
       isSkinned: !!geometry.attributes.skinWeight && !!skinned.skeleton,
       skeleton: skinned.skeleton,
+      pose: void 0,
+      // assigned below, once the distinct rigs are known
       skinIndex: geometry.attributes.skinIndex,
       skinWeight: geometry.attributes.skinWeight,
       morphPos: geometry.morphAttributes.position,
@@ -64,18 +113,25 @@ function mergeGeometry(parts, restMatrices, total) {
   const normal = new Float32Array(total * 3);
   const wantUV = parts.every((p) => !!p.mesh.geometry.attributes.uv);
   const wantColor = parts.every((p) => !!p.mesh.geometry.attributes.color);
+  const wantTangent = parts.every((p) => {
+    const t = p.mesh.geometry.attributes.tangent;
+    return t instanceof BufferAttribute && t.itemSize === 4;
+  });
   const uv = wantUV ? new Float32Array(total * 2) : null;
   const color = wantColor ? new Float32Array(total * 3) : null;
+  const tangent = wantTangent ? new Float32Array(total * 4) : null;
   const indices = [];
   const groups = [];
   const _v = new Vector3();
   const _n = new Vector3();
+  const _t = new Vector3();
   parts.forEach((part, pi) => {
     const m = restMatrices[pi];
     const geometry = part.mesh.geometry;
     const start = part.vertexStart;
     const srcUV = uv ? asAttribute(geometry.attributes.uv, part.mesh, "uv") : null;
     const srcColor = color ? asAttribute(geometry.attributes.color, part.mesh, "color") : null;
+    const srcTangent = tangent ? geometry.attributes.tangent : null;
     for (let v = 0; v < part.vertexCount; v++) {
       _v.fromBufferAttribute(part.basePos, v).applyMatrix4(m);
       _n.fromBufferAttribute(part.baseNrm, v).transformDirection(m);
@@ -95,6 +151,14 @@ function mergeGeometry(parts, restMatrices, total) {
         color[o3 + 1] = srcColor.getY(v);
         color[o3 + 2] = srcColor.getZ(v);
       }
+      if (tangent && srcTangent) {
+        _t.fromBufferAttribute(srcTangent, v).transformDirection(m);
+        const o4 = (start + v) * 4;
+        tangent[o4] = _t.x;
+        tangent[o4 + 1] = _t.y;
+        tangent[o4 + 2] = _t.z;
+        tangent[o4 + 3] = srcTangent.getW(v);
+      }
     }
     const groupStart = indices.length;
     const index = geometry.index;
@@ -119,11 +183,14 @@ function mergeGeometry(parts, restMatrices, total) {
   merged.setAttribute("normal", new BufferAttribute(normal, 3));
   if (uv) merged.setAttribute("uv", new BufferAttribute(uv, 2));
   if (color) merged.setAttribute("color", new BufferAttribute(color, 3));
+  if (tangent) merged.setAttribute("tangent", new BufferAttribute(tangent, 4));
   merged.setIndex(indices);
   for (const g of groups) merged.addGroup(g.start, g.count, g.materialIndex);
   return merged;
 }
-function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } = {}) {
+function bakeVAT(root, animations, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE, bakeNormals = true } = {}) {
+  const resolved = animations.map(resolveAnimation);
+  const clips = resolved.map((a) => a.clip);
   root.updateMatrixWorld(true);
   const parts = collectParts(root);
   const vertexCount = parts.reduce((n, p) => n + p.vertexCount, 0);
@@ -146,13 +213,13 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
   const geometry = mergeGeometry(parts, restMatrices, vertexCount);
   const mergedBase = geometry.attributes.position;
   const posData = new Float32Array(vertexCount * totalFrames * 4);
-  const nrmData = new Float32Array(vertexCount * totalFrames * 4);
+  const nrmData = bakeNormals ? new Float32Array(vertexCount * totalFrames * 4) : null;
+  const bakeNormal = nrmData !== null;
   const mixer = new AnimationMixer(root);
   const bounds = new Box3();
   const clipTable = [];
   const _si = new Vector4();
   const _sw = new Vector4();
-  const _bone = new Matrix4();
   const _acc = new Matrix4();
   const _skin = new Matrix4();
   const _partMatrix = new Matrix4();
@@ -162,7 +229,8 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
   const _mt = new Vector3();
   const _mb = new Vector3();
   const _mbn = new Vector3();
-  const influencers = parts.filter((p) => p.isSkinned && p.skeleton).map(influencedBones);
+  const poses = attachPoseBuffers(parts);
+  const influencers = bakeNormals ? parts.filter((p) => p.pose).map(influencedBones) : [];
   let warnedNonUniformScale = false;
   let rowOffset = 0;
   clips.forEach((clip, ci) => {
@@ -174,22 +242,24 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
       mixer.setTime(f / frames * clip.duration);
       root.updateMatrixWorld(true);
       const row = rowOffset + f;
+      poseSkeletons(poses);
       if (!warnedNonUniformScale) {
-        warnedNonUniformScale = warnOnNonUniformBoneScale(influencers, _bone);
+        warnedNonUniformScale = warnOnNonUniformBoneScale(influencers);
       }
       for (const part of parts) {
         _partMatrix.multiplyMatrices(rootInverse, part.mesh.matrixWorld);
         const influences = part.mesh.morphTargetInfluences;
-        const { morphPos, morphNrm, morphRelative, isSkinned, skeleton, skinIndex, skinWeight } = part;
+        const { morphPos, morphNrm, morphRelative, isSkinned, skinIndex, skinWeight } = part;
+        const boneMatrices = part.pose?.matrices;
         const morphCount = influences ? Math.min(influences.length, Math.max(morphPos?.length ?? 0, morphNrm?.length ?? 0)) : 0;
         for (let v = 0; v < part.vertexCount; v++) {
           const vi = part.vertexStart + v;
           _p.fromBufferAttribute(part.basePos, v);
-          _n.fromBufferAttribute(part.baseNrm, v);
+          if (bakeNormal) _n.fromBufferAttribute(part.baseNrm, v);
           if (influences && morphCount > 0) {
             if (!morphRelative) {
               _mb.fromBufferAttribute(part.basePos, v);
-              _mbn.fromBufferAttribute(part.baseNrm, v);
+              if (bakeNormal) _mbn.fromBufferAttribute(part.baseNrm, v);
             }
             for (let t = 0; t < morphCount; t++) {
               const w = influences[t];
@@ -200,7 +270,7 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
                 if (!morphRelative) _mt.sub(_mb);
                 _p.addScaledVector(_mt, w);
               }
-              const targetNrm = morphNrm?.[t];
+              const targetNrm = bakeNormal ? morphNrm?.[t] : void 0;
               if (targetNrm) {
                 _mt.fromBufferAttribute(targetNrm, v);
                 if (!morphRelative) _mt.sub(_mbn);
@@ -208,26 +278,24 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
               }
             }
           }
-          if (isSkinned && skeleton) {
+          if (isSkinned && boneMatrices) {
             const skinned = part.mesh;
             _si.fromBufferAttribute(skinIndex, v);
             _sw.fromBufferAttribute(skinWeight, v);
-            _acc.elements.fill(0);
+            const ae = _acc.elements;
+            ae.fill(0);
             for (let i = 0; i < 4; i++) {
               const w = _sw.getComponent(i);
               if (w === 0) continue;
-              const bi = _si.getComponent(i);
-              _bone.multiplyMatrices(skeleton.bones[bi].matrixWorld, skeleton.boneInverses[bi]);
-              const ae = _acc.elements;
-              const be = _bone.elements;
-              for (let e = 0; e < 16; e++) ae[e] += be[e] * w;
+              const b = _si.getComponent(i) * BONE_STRIDE;
+              for (let e = 0; e < 16; e++) ae[e] += boneMatrices[b + e] * w;
             }
             _skin.multiplyMatrices(_acc, skinned.bindMatrix).premultiply(skinned.bindMatrixInverse);
             _p.applyMatrix4(_skin);
-            _n.transformDirection(_skin);
+            if (bakeNormal) _n.transformDirection(_skin);
           }
           _p.applyMatrix4(_partMatrix);
-          _n.transformDirection(_partMatrix);
+          if (bakeNormal) _n.transformDirection(_partMatrix);
           bounds.expandByPoint(_p);
           _bp.fromBufferAttribute(mergedBase, vi);
           const o = (row * vertexCount + vi) * 4;
@@ -239,10 +307,12 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
           posData[o + 1] = dy;
           posData[o + 2] = dz;
           posData[o + 3] = 1;
-          nrmData[o] = _n.x;
-          nrmData[o + 1] = _n.y;
-          nrmData[o + 2] = _n.z;
-          nrmData[o + 3] = 1;
+          if (bakeNormal) {
+            nrmData[o] = _n.x;
+            nrmData[o + 1] = _n.y;
+            nrmData[o + 2] = _n.z;
+            nrmData[o + 3] = 1;
+          }
         }
       }
     }
@@ -253,7 +323,10 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
       frames,
       fps: frames / clip.duration,
       duration: clip.duration,
-      maxDelta: Math.sqrt(maxDeltaSq)
+      maxDelta: Math.sqrt(maxDeltaSq),
+      // Declared once, here, rather than repeated at every instance that plays
+      // this band. An instance overrides any of them, field by field.
+      ...resolved[ci].defaults
     });
     rowOffset += frames;
   });
@@ -266,7 +339,7 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
   for (const part of parts) materials[part.materialIndex] = part.material;
   return {
     positionTexture: makeVATTexture(posData, vertexCount, totalFrames),
-    normalTexture: makeVATTexture(nrmData, vertexCount, totalFrames),
+    normalTexture: nrmData ? makeVATTexture(nrmData, vertexCount, totalFrames) : null,
     clips: clipTable,
     bounds,
     vertexCount,
@@ -276,6 +349,32 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
     materials
   };
 }
+var BONE_STRIDE = 16;
+var IDENTITY = /* @__PURE__ */ new Matrix4();
+function attachPoseBuffers(parts) {
+  const byRig = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    if (!part.isSkinned || !part.skeleton) continue;
+    let pose = byRig.get(part.skeleton);
+    if (!pose) {
+      const matrices = new Float64Array(part.skeleton.bones.length * BONE_STRIDE);
+      pose = { skeleton: part.skeleton, matrices };
+      byRig.set(part.skeleton, pose);
+    }
+    part.pose = pose;
+  }
+  return [...byRig.values()];
+}
+function poseSkeletons(poses) {
+  const scratch = new Matrix4();
+  for (const { skeleton, matrices } of poses) {
+    const { bones, boneInverses } = skeleton;
+    for (let b = 0; b < bones.length; b++) {
+      scratch.multiplyMatrices(bones[b]?.matrixWorld ?? IDENTITY, boneInverses[b]);
+      matrices.set(scratch.elements, b * BONE_STRIDE);
+    }
+  }
+}
 function influencedBones(part) {
   const used = /* @__PURE__ */ new Set();
   const index = part.skinIndex;
@@ -285,37 +384,28 @@ function influencedBones(part) {
       if (weight.getComponent(v, i) !== 0) used.add(index.getComponent(v, i));
     }
   }
-  return { skeleton: part.skeleton, bones: [...used] };
+  return { pose: part.pose, bones: [...used] };
 }
 var SCALE_UNIFORMITY_EPSILON = 1e-4;
-function hasNonUniformScale(m) {
-  const e = m.elements;
-  const x = e[0] * e[0] + e[1] * e[1] + e[2] * e[2];
-  const y = e[4] * e[4] + e[5] * e[5] + e[6] * e[6];
-  const z = e[8] * e[8] + e[9] * e[9] + e[10] * e[10];
+function hasNonUniformScale(matrices, b) {
+  const o = b * BONE_STRIDE;
+  const x = matrices[o] ** 2 + matrices[o + 1] ** 2 + matrices[o + 2] ** 2;
+  const y = matrices[o + 4] ** 2 + matrices[o + 5] ** 2 + matrices[o + 6] ** 2;
+  const z = matrices[o + 8] ** 2 + matrices[o + 9] ** 2 + matrices[o + 10] ** 2;
   const max = Math.max(x, y, z);
   return max - Math.min(x, y, z) > SCALE_UNIFORMITY_EPSILON * max;
 }
-function warnOnNonUniformBoneScale(influencers, scratch) {
-  for (const { skeleton, bones } of influencers) {
+function warnOnNonUniformBoneScale(influencers) {
+  for (const { pose, bones } of influencers) {
     for (const b of bones) {
-      scratch.multiplyMatrices(skeleton.bones[b].matrixWorld, skeleton.boneInverses[b]);
-      if (!hasNonUniformScale(scratch)) continue;
+      if (!hasNonUniformScale(pose.matrices, b)) continue;
       console.warn(
-        `three-vat: bone "${skeleton.bones[b].name || "(unnamed)"}" animates with non-uniform scale; baked normals under it are approximate, because linear-blend skinning transforms a normal by the skin matrix rather than its inverse-transpose \u2014 the same shortcut three's own skinning shader takes. Positions are exact.`
+        `three-vat: bone "${pose.skeleton.bones[b].name || "(unnamed)"}" animates with non-uniform scale; baked normals under it are approximate, because linear-blend skinning transforms a normal by the skin matrix rather than its inverse-transpose \u2014 the same shortcut three's own skinning shader takes. Positions are exact.`
       );
       return true;
     }
   }
   return false;
 }
-function makeVATTexture(data, width, height, type = FloatType) {
-  const tex = new DataTexture(data, width, height, RGBAFormat, type);
-  tex.minFilter = NearestFilter;
-  tex.magFilter = NearestFilter;
-  tex.generateMipmaps = false;
-  tex.needsUpdate = true;
-  return tex;
-}
 
-export { MAX_TEXTURE_SIZE, bakeVAT, makeVATTexture };
+export { bakeVAT };

package/dist/tsl.d.ts

@@ -1,6 +1,6 @@
-import { BufferGeometry, InstancedMesh } from 'three';
 import { Node } from 'three/webgpu';
-import { b as VATClock, V as VAT, d as VATInstance, c as VATCrowd } from './instance-playback-BrGBIKLe.js';
+import { d as VATClock, i as VATPlaybackTexture, a as VATCarrier, V as VAT, h as VATInstance, e as VATCrowd } from './carrier-BFCPmcQK.js';
+import 'three';
 
 /**
  * The real maximum texture dimension this renderer accepts, for
@@ -31,40 +31,50 @@ interface VATNodeOptions {
      */
     time?: VATTimeUniform;
     /**
-     * The geometry these nodes will render. When it carries the instance-playback
-     * attributes — write them with `addVATInstanceAttributes` from `three-vat`
-     * *before* calling this — each instance plays its own clip, at its own phase
-     * and rate. Without them, every instance plays `clipIndex`, phase-desynced by
-     * `desync`.
+     * The crowd's playback texture — build it with `createVATPlaybackTexture`
+     * from `three-vat` *before* calling this, or let `createVATMesh` do it — and
+     * each instance plays its own clip, at its own phase and rate, read from its
+     * own row — which row that is, is the carrier's answer (see `carrier`). Without
+     * it, every instance plays `clipIndex`, phase-desynced by `desync`.
      *
-     * Which decode the graph compiles is decided here, at build time: a TSL
-     * attribute that is missing from the geometry reads as a constant, so the
-     * fallback cannot be a shader-side branch.
+     * Which decode the graph compiles is decided here, at build time: the
+     * fallback is a different graph, not a shader-side branch.
      */
-    geometry?: BufferGeometry;
+    playback?: VATPlaybackTexture;
     /**
-     * The `InstancedMesh` these nodes will render, when there is one.
+     * The crowd's **carrier** — the mesh these nodes will render on, an
+     * `InstancedMesh` or a `BatchedMesh`. Named as the WebGL path's
+     * `patchVATMaterial` names it, because it is the one concept (CONTEXT.md).
      *
-     * Required for a crowd, and for one reason: three applies the instance matrix
-     * to `positionLocal` *before* it reads `positionNode`, so the decode has to
-     * displace in the geometry's own space and then re-apply the instancing
-     * itself. Without this the delta is added in instance space — unrotated and
-     * unscaled — and every instance deforms according to its own matrix.
+     * Required for a crowd, and for two reasons. First: three applies the
+     * carrier's transform to `positionLocal` *before* it reads `positionNode`, so
+     * the decode has to displace in the geometry's own space and then re-apply
+     * that transform itself. Without this the delta is added in instance space —
+     * unrotated and unscaled — and every instance deforms according to its own
+     * matrix. Second: the carrier decides how this instance's *logical* index is
+     * spelled, which is the row of the playback texture the pack is read from —
+     * `instanceIndex` on an `InstancedMesh`, `batchIndirectIndex` on a
+     * `BatchedMesh`, whose drawn slot is a permutation that changes every frame
+     * (ADR-0016).
+     *
+     * One option rather than one per carrier, because those two answers have to
+     * come from the same object: a decode that re-applied one mesh's transform
+     * while reading another's index would render a crowd nothing could explain.
      *
      * Omit it for a single, non-instanced mesh, where `positionLocal` is the
      * geometry position and there is nothing to re-apply.
      */
-    instancedMesh?: InstancedMesh;
+    carrier?: VATCarrier;
     /**
      * Which clip to play (index into `vat.clips`). Ignored — along with
-     * `desync` — when `geometry` carries instance playback, which says all of this
-     * per instance. Default `0`.
+     * `desync` — when a `playback` texture is given, which says all of this per
+     * instance. Default `0`.
      */
     clipIndex?: number;
     /**
-     * Max random per-instance time offset in seconds, hashed from `instanceIndex`.
-     * `0` (default) plays every instance in lockstep. Ignored when `geometry`
-     * carries instance playback.
+     * Max random per-instance time offset in seconds, hashed from the instance's
+     * logical index. `0` (default) plays every instance in lockstep. Ignored when
+     * a `playback` texture is given.
      */
     desync?: number;
 }
@@ -97,11 +107,11 @@ interface VATNodes {
  * Build TSL decode nodes for a baked VAT, for the WebGPU/TSL renderer path.
  * Shadows work automatically because `positionNode` also feeds the depth pass.
  *
- * Pass the `geometry` you are about to render and each instance plays the clip,
- * phase and rate written into it by `addVATInstanceAttributes` — the same
+ * Pass the crowd's `playback` texture and each instance plays the clip, phase
+ * and rate written into its row by `createVATPlaybackTexture` — the same
  * instance-playback contract the WebGL path reads (ADR-0009), so a mixed-clip
- * crowd renders identically on either renderer. Without those attributes every
- * instance plays `clipIndex`, desynced by a phase hashed from `instanceIndex`.
+ * crowd renders identically on either renderer. Without it every instance plays
+ * `clipIndex`, desynced by a phase hashed from the instance index.
  *
  * Coverage note: the node graph is tested structurally in CI (no GPU); that the
  * two paths decode *identically* is a pixel-diff release gate.
@@ -110,6 +120,7 @@ declare function vatNodes(vat: VAT, options?: VATNodeOptions): VATNodes;
 /**
  * The decode's arithmetic: the position delta and the normal this instance reads
  * at this moment, as nodes — before the vertex-stage writes that place them.
+ * `normal` is `null` when the VAT was baked without a normal texture.
  *
  * @internal Split out and exported for the structural tests. A `Fn` body is
  * opaque to graph traversal (its statements are not built until the shader is),
@@ -119,7 +130,7 @@ declare function vatNodes(vat: VAT, options?: VATNodeOptions): VATNodes;
  */
 declare function vatDecode(vat: VAT, options?: VATNodeOptions): {
     position: Vec3Node;
-    normal: Vec3Node;
+    normal: Vec3Node | null;
 };
 /** Options for {@link createVATMesh}. */
 interface CreateVATMeshOptions {
@@ -137,11 +148,12 @@ interface CreateVATMeshOptions {
 }
 /**
  * Turn a baked VAT and a list of instances into a crowd ready to render: an
- * `InstancedMesh` whose geometry carries the instance-playback contract and
- * whose materials decode the VAT on the vertex stage.
+ * `InstancedMesh` rendering the bake's geometry, a playback texture carrying
+ * the instance-playback contract, and materials that decode the VAT on the
+ * vertex stage.
  *
  * ```ts
- * const { mesh, time } = createVATMesh(vat, instances)
+ * const { mesh, time, playback } = createVATMesh(vat, instances)
  * mesh.castShadow = mesh.receiveShadow = true
  * scene.add(mesh)
  * // per frame: