three-vat 1.0.1 → 2.0.0

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:

package/dist/tsl.js

@@ -1,6 +1,7 @@
-import { createCrowdGeometry, PLAYBACK_ATTRIBUTES } from './chunk-SXTVASKG.js';
+import { isBatchedCarrier, assertVATCarrier, assertBakedNormal } from './chunk-W2ZAFMPB.js';
+import { INFINITE_REPETITIONS, LoopMode, EndMode, createVATPlaybackTexture, PACK_TEXELS } from './chunk-2PGZ44TP.js';
 import { InstancedMesh } from 'three';
-import { uniform, Fn, positionLocal, positionGeometry, normalLocal, instancedMesh, int, vertexIndex, textureLoad, ivec2, mix, float, hash, instanceIndex, attribute } from 'three/tsl';
+import { uniform, Fn, positionLocal, positionGeometry, normalLocal, batch, instancedMesh, int, vertexIndex, float, bool, textureLoad, ivec2, mix, batchIndirectIndex, instanceIndex, hash } from 'three/tsl';
 
 function getMaxTextureSize(renderer) {
   const backend = renderer.backend;
@@ -10,17 +11,30 @@ function getMaxTextureSize(renderer) {
   if (gl) return gl.getParameter(gl.MAX_TEXTURE_SIZE);
   throw new Error("three-vat: renderer has no initialized backend \u2014 call `await renderer.init()` first");
 }
-var floatAttribute = (name) => attribute(name, "float");
-function attributePlayback() {
-  const frames = floatAttribute(PLAYBACK_ATTRIBUTES.clipFrames);
+var packTexel = (texture, field, instance) => textureLoad(texture, ivec2(int(field), instance));
+function texturePlayback(texture, instance) {
+  const clip = packTexel(texture, PACK_TEXELS.clip, instance);
+  const playback = packTexel(texture, PACK_TEXELS.playback, instance);
+  const fade = packTexel(texture, PACK_TEXELS.fade, instance);
+  const frames = clip.y;
   return {
-    startFrame: int(floatAttribute(PLAYBACK_ATTRIBUTES.clipStart)),
+    startFrame: int(clip.x),
     frames,
-    duration: frames.div(floatAttribute(PLAYBACK_ATTRIBUTES.clipFps)),
-    timeOffset: floatAttribute(PLAYBACK_ATTRIBUTES.timeOffset),
-    speed: floatAttribute(PLAYBACK_ATTRIBUTES.speed)
+    duration: frames.div(clip.z),
+    startTime: playback.x,
+    speed: clip.w,
+    loopMode: playback.y,
+    repetitions: playback.z,
+    endMode: playback.w,
+    fade: {
+      startFrame: fade.x,
+      frames: fade.y,
+      phase: fade.z,
+      duration: fade.w
+    }
   };
 }
+var instanceIdOf = (carrier) => isBatchedCarrier(carrier) ? int(batchIndirectIndex) : int(instanceIndex);
 function clipAt(vat, clipIndex) {
   const clip = vat.clips[clipIndex];
   if (!clip) {
@@ -28,60 +42,102 @@ function clipAt(vat, clipIndex) {
   }
   return clip;
 }
-function hashedPlayback(clip, desync) {
+function hashedPlayback(clip, desync, instance) {
   return {
     startFrame: int(clip.startFrame),
     frames: float(clip.frames),
     duration: float(clip.frames / clip.fps),
-    timeOffset: hash(instanceIndex).mul(desync),
-    speed: float(1)
+    // Negated, because desync is now a start time in the *past*: an instance
+    // that began `desync` seconds ago is that far into its clip already.
+    startTime: hash(instance).mul(-desync),
+    // Everything but the phase comes from the clip's own baked defaults, so a
+    // clip baked "once, clamped, at 2x" plays that way here too. A second set
+    // of defaults living in this path would be a crowd that animates
+    // differently depending on whether anyone wrote the attributes.
+    speed: float(clip.speed),
+    loopMode: float(clip.loopMode),
+    repetitions: float(clip.repetitions),
+    endMode: float(clip.endMode),
+    // Nothing to fade out of: this path is the zero-config default, where an
+    // instance has never been written and so has no animation it left behind.
+    fade: { startFrame: float(0), frames: float(0), phase: float(0), duration: float(0) }
   };
 }
-function checkPlaybackAttributes(geometry) {
-  const names = Object.values(PLAYBACK_ATTRIBUTES);
-  const missing = names.filter((name) => geometry.getAttribute(name) === void 0);
-  if (missing.length === 0) return true;
-  if (missing.length === names.length) return false;
-  throw new Error(
-    `three-vat: geometry carries only part of the instance-playback contract (missing ${missing.join(", ")}) \u2014 write all of it with \`addVATInstanceAttributes\` from \`three-vat\`, or pass no geometry for the hashed default`
-  );
-}
 function vatNodes(vat, options = {}) {
-  const { time = uniform(0), instancedMesh: instanced } = options;
+  const { time = uniform(0), carrier } = options;
   const { position, normal } = vatDecode(vat, options);
   const decode = Fn(() => {
-    positionLocal.assign((instanced ? positionGeometry : positionLocal).add(position));
-    normalLocal.assign(normal);
-    if (instanced) instancedMesh(instanced);
+    positionLocal.assign((carrier ? positionGeometry : positionLocal).add(position));
+    if (normal) normalLocal.assign(normal);
+    if (carrier) {
+      if (isBatchedCarrier(carrier)) batch(carrier);
+      else instancedMesh(carrier);
+    }
     return positionLocal;
   }, "vec3");
   return { positionNode: decode(), time };
 }
 function vatDecode(vat, options = {}) {
-  const { time = uniform(0), geometry, clipIndex = 0, desync = 0 } = options;
-  const playback = geometry && checkPlaybackAttributes(geometry) ? attributePlayback() : hashedPlayback(clipAt(vat, clipIndex), desync);
+  const { time = uniform(0), playback: playbackTexture, carrier, clipIndex = 0, desync = 0 } = options;
+  if (carrier) assertVATCarrier(carrier, vat);
+  const instance = instanceIdOf(carrier);
+  const playback = playbackTexture ? texturePlayback(playbackTexture.texture, instance) : hashedPlayback(clipAt(vat, clipIndex), desync, instance);
   const vertexRow = int(vertexIndex);
+  const frames = playback.frames;
+  const last = frames.sub(1);
+  const elapsed = time.sub(playback.startTime);
+  const local = elapsed.mul(playback.speed);
+  const loops = local.div(playback.duration);
+  const started = local.greaterThanEqual(0);
+  const finished = started.and(playback.repetitions.notEqual(INFINITE_REPETITIONS)).and(loops.greaterThanEqual(playback.repetitions));
+  const isPingPong = playback.loopMode.equal(LoopMode.PingPong);
+  const bounce = loops.mod(2);
+  const pingPongPhase = bounce.lessThan(1).select(bounce, float(2).sub(bounce));
+  const endPhase = playback.endMode.equal(EndMode.Clamp).select(float(1), float(0));
+  const phase = started.select(
+    finished.select(endPhase, isPingPong.select(pingPongPhase, loops.fract())),
+    float(0)
+  );
+  const wraps = started.select(
+    finished.select(bool(false), isPingPong.select(bool(false), bool(true))),
+    bool(false)
+  );
+  const f = phase.mul(wraps.select(frames, last));
+  const f0 = f.floor().min(last);
+  const f1 = wraps.select(f0.add(1).mod(frames), f0.add(1).min(last));
+  const frameMix = f.sub(f0);
+  const bandRow = (offset) => int(offset).add(playback.startFrame);
+  const row0 = bandRow(f0);
+  const row1 = bandRow(f1);
+  const fade = playback.fade;
+  const fadeWeight = fade.duration.greaterThan(0).select(
+    float(1).sub(elapsed.div(fade.duration).clamp(0, 1)),
+    float(0)
+  );
+  const frozenRow = int(fade.phase.mul(fade.frames).floor().min(fade.frames.sub(1)).max(0)).add(
+    int(fade.startFrame)
+  );
   const sample = (tex) => {
-    const t = time.mul(playback.speed).add(playback.timeOffset).div(playback.duration).fract().mul(playback.frames);
-    const f0 = int(t);
-    const f1 = int(f0.add(1).toFloat().mod(playback.frames));
-    const s0 = textureLoad(tex, ivec2(vertexRow, f0.add(playback.startFrame))).xyz;
-    const s1 = textureLoad(tex, ivec2(vertexRow, f1.add(playback.startFrame))).xyz;
-    return mix(s0, s1, t.fract());
+    const s0 = textureLoad(tex, ivec2(vertexRow, row0)).xyz;
+    const s1 = textureLoad(tex, ivec2(vertexRow, row1)).xyz;
+    const frozen = textureLoad(tex, ivec2(vertexRow, frozenRow)).xyz;
+    return mix(mix(s0, s1, frameMix), frozen, fadeWeight);
   };
+  const normalTexture = vat.normalTexture;
   return {
     position: sample(vat.positionTexture),
-    normal: sample(vat.normalTexture).normalize()
+    normal: normalTexture ? sample(normalTexture).normalize() : null
   };
 }
 function createVATMesh(vat, instances, options = {}) {
   const time = options.time ?? uniform(0);
-  const geometry = createCrowdGeometry(vat, instances);
+  const playback = createVATPlaybackTexture(instances);
+  for (const source of vat.materials) assertBakedNormal(vat, source);
   const materials = vat.materials.map((source) => source.clone());
-  const mesh = new InstancedMesh(geometry, materials, instances.length);
-  const { positionNode } = vatNodes(vat, { time, geometry, instancedMesh: mesh });
+  const mesh = new InstancedMesh(vat.geometry, materials, instances.length);
+  const { positionNode } = vatNodes(vat, { time, playback, carrier: mesh });
   for (const material of materials) material.positionNode = positionNode;
-  return { mesh, time };
+  return { mesh, time, playback };
 }
 
 export { createVATMesh, getMaxTextureSize, vatDecode, vatNodes };