three-vat 1.0.1 → 2.1.0

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 { e as VATClock, j as VATPlaybackTexture, b as VATCarrier, V as VAT, i as VATInstance, f as VATCrowd } from './carrier-BXaLAPRO.js';
+import 'three';
 
 /**
  * The real maximum texture dimension this renderer accepts, for
@@ -31,40 +31,52 @@ 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 pose in the geometry's own space and then re-apply that
+     * transform itself. Without this the vertex encoding adds its delta in
+     * instance space — unrotated and unscaled — and every instance deforms
+     * according to its own matrix; the rig encoding, which skins the rest pose
+     * outright, never applies the instance matrix at all and draws the whole
+     * crowd at the origin. 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;
 }
@@ -72,17 +84,19 @@ interface VATNodeOptions {
 interface VATNodes {
     /**
      * Assign to `material.positionNode`. It carries the whole decode — the normal
-     * with it.
+     * with it, and the tangent under the rig encoding.
      *
-     * There is deliberately no `normalNode`. A material's `normalNode` is built in
-     * the *fragment* stage (three reaches it from `normalView` through
-     * `builder.context.setupNormal()`) and is expected in **view** space, whereas a
-     * VAT's baked normals are per-vertex and in the geometry's own space. Handing
-     * an object-space normal to a fragment-stage node skipped both the instance
-     * matrix and the normal matrix, and took `vertexIndex` into the fragment stage
-     * with it — where `IndexNode` does not give you the vertex index at all, but
-     * quietly turns itself into a varying, so every fragment read a linearly
-     * *interpolated* index that addresses neither of the vertices it lies between.
+     * There is deliberately no `normalNode`, under either encoding. A material's
+     * `normalNode` is built in the *fragment* stage (three reaches it from
+     * `normalView` through `builder.context.setupNormal()`) and is expected in
+     * **view** space, whereas a VAT's normals are per-vertex and in the geometry's
+     * own space — read from the normal texture, or skinned from the rig one.
+     * Handing an object-space normal to a fragment-stage node skipped both the
+     * instance matrix and the normal matrix, and took `vertexIndex` into the
+     * fragment stage with it — where `IndexNode` does not give you the vertex
+     * index at all, but quietly turns itself into a varying, so every fragment
+     * read a linearly *interpolated* index that addresses neither of the vertices
+     * it lies between.
      *
      * Writing `normalLocal` inside the vertex-stage decode instead is what the
      * GLSL path does when it sets `objectNormal` in `beginnormal_vertex`: three
@@ -97,19 +111,42 @@ 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.
  */
 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.
+ * What a decode hands the vertex stage, discriminated on the encoding it read
+ * (ADR-0018) — because the two encodings answer a different question. The
+ * vertex encoding reads where this vertex *moved to*: `position` is the delta
+ * to add to the rest position, `normal` the baked normal or `null` when the
+ * bake skipped it. The rig encoding *skins* the rest pose: `position` is the
+ * posed position itself, `normal` always exists because it comes out of the
+ * skin matrix, and so does `tangent` when the geometry carries one.
+ *
+ * @internal The return type of {@link vatDecode}, exported for the same
+ * structural tests and for nothing else.
+ */
+type VATDecoded = {
+    encoding: 'delta';
+    position: Vec3Node;
+    normal: Vec3Node | null;
+} | {
+    encoding: 'rig';
+    position: Vec3Node;
+    normal: Vec3Node;
+    tangent: Vec3Node | null;
+};
+/**
+ * The decode's arithmetic: what this instance reads at this moment, as nodes —
+ * before the vertex-stage writes that place it. See {@link VATDecoded} for what
+ * `position` means under each encoding.
  *
  * @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),
@@ -117,10 +154,7 @@ declare function vatNodes(vat: VAT, options?: VATNodeOptions): VATNodes;
  * so the arithmetic that matters stays reachable as a graph. Not re-exported
  * from `three-vat`; nothing outside this package should build against it.
  */
-declare function vatDecode(vat: VAT, options?: VATNodeOptions): {
-    position: Vec3Node;
-    normal: Vec3Node;
-};
+declare function vatDecode(vat: VAT, options?: VATNodeOptions): VATDecoded;
 /** Options for {@link createVATMesh}. */
 interface CreateVATMeshOptions {
     /**
@@ -137,11 +171,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:
@@ -161,4 +196,4 @@ interface CreateVATMeshOptions {
  */
 declare function createVATMesh(vat: VAT, instances: VATInstance[], options?: CreateVATMeshOptions): VATCrowd;
 
-export { type CreateVATMeshOptions, type VATNodeOptions, type VATNodes, type VATTimeUniform, createVATMesh, getMaxTextureSize, vatDecode, vatNodes };
+export { type CreateVATMeshOptions, type VATDecoded, type VATNodeOptions, type VATNodes, type VATTimeUniform, createVATMesh, getMaxTextureSize, vatDecode, vatNodes };

package/dist/tsl.js

@@ -1,6 +1,7 @@
-import { createCrowdGeometry, PLAYBACK_ATTRIBUTES } from './chunk-SXTVASKG.js';
+import { isBatchedCarrier, assertVATCarrier, assertBakedNormal } from './chunk-I4STYOD5.js';
+import { INFINITE_REPETITIONS, LoopMode, EndMode, createVATPlaybackTexture, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT } from './chunk-3PWAY6MD.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, normalLocal, tangentLocal, positionGeometry, batch, instancedMesh, float, bool, int, vertexIndex, attribute, mat3, tangentGeometry, normalGeometry, vec4, batchIndirectIndex, instanceIndex, hash, mix, textureLoad, ivec2, dot, mat4 } 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,182 @@ 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 { position, normal } = vatDecode(vat, options);
+  const { time = uniform(0), carrier } = options;
+  const decoded = vatDecode(vat, options);
   const decode = Fn(() => {
-    positionLocal.assign((instanced ? positionGeometry : positionLocal).add(position));
-    normalLocal.assign(normal);
-    if (instanced) instancedMesh(instanced);
+    if (decoded.encoding === "rig") {
+      positionLocal.assign(decoded.position);
+      normalLocal.assign(decoded.normal);
+      if (decoded.tangent) tangentLocal.assign(decoded.tangent);
+    } else {
+      positionLocal.assign((carrier ? positionGeometry : positionLocal).add(decoded.position));
+      if (decoded.normal) normalLocal.assign(decoded.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 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 blend = 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 fadeRow = int(fade.phase.mul(fade.frames).floor().min(fade.frames.sub(1)).max(0)).add(
+    int(fade.startFrame)
+  );
+  const rows = { row0, row1, blend, fadeRow, fadeWeight };
+  switch (vat.encoding) {
+    case "delta":
+      return vertexDecode(vat, rows);
+    case "rig":
+      return rigDecode(vat, rows);
+    default: {
+      const unhandled = vat;
+      throw new Error(
+        `three-vat: vatDecode has no decode for encoding "${String(unhandled.encoding)}"`
+      );
+    }
+  }
+}
+function vertexDecode({ positionTexture, normalTexture }, rows) {
   const vertexRow = int(vertexIndex);
   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, rows.row0)).xyz;
+    const s1 = textureLoad(tex, ivec2(vertexRow, rows.row1)).xyz;
+    const frozen = textureLoad(tex, ivec2(vertexRow, rows.fadeRow)).xyz;
+    return mix(mix(s0, s1, rows.blend), frozen, rows.fadeWeight);
+  };
+  return {
+    encoding: "delta",
+    position: sample(positionTexture),
+    normal: normalTexture ? sample(normalTexture).normalize() : null
+  };
+}
+function compose(q, ts) {
+  const x = q.x;
+  const y = q.y;
+  const z = q.z;
+  const w = q.w;
+  const x2 = x.add(x);
+  const y2 = y.add(y);
+  const z2 = z.add(z);
+  const xx = x.mul(x2);
+  const xy = x.mul(y2);
+  const xz = x.mul(z2);
+  const yy = y.mul(y2);
+  const yz = y.mul(z2);
+  const zz = z.mul(z2);
+  const wx = w.mul(x2);
+  const wy = w.mul(y2);
+  const wz = w.mul(z2);
+  const s = ts.w;
+  const one = float(1);
+  return mat4(
+    vec4(one.sub(yy.add(zz)).mul(s), xy.add(wz).mul(s), xz.sub(wy).mul(s), 0),
+    vec4(xy.sub(wz).mul(s), one.sub(xx.add(zz)).mul(s), yz.add(wx).mul(s), 0),
+    vec4(xz.add(wy).mul(s), yz.sub(wx).mul(s), one.sub(xx.add(yy)).mul(s), 0),
+    vec4(ts.xyz, 1)
+  );
+}
+var hemisphereOf = (reference, q) => dot(reference, q).lessThan(0).select(q.negate(), q);
+function rigDecode({ rigTexture, geometry }, rows) {
+  const skinIndex = attribute("skinIndex", "uvec4");
+  const skinWeight = attribute("skinWeight", "vec4");
+  const fetch = (column, row) => textureLoad(rigTexture, ivec2(column, row));
+  const slot = (index, weight) => {
+    const column = (texel) => int(index).mul(RIG_TEXELS_PER_SLOT).add(texel);
+    const rotation = column(RIG_TEXELS.rotation);
+    const placement = column(RIG_TEXELS.placement);
+    const q0 = fetch(rotation, rows.row0);
+    const ts0 = fetch(placement, rows.row0);
+    const q1 = hemisphereOf(q0, fetch(rotation, rows.row1));
+    const ts1 = fetch(placement, rows.row1);
+    const q = mix(q0, q1, rows.blend).normalize();
+    const ts = mix(ts0, ts1, rows.blend);
+    const qf = hemisphereOf(q, fetch(rotation, rows.fadeRow));
+    const tsf = fetch(placement, rows.fadeRow);
+    const qFaded = mix(q, qf, rows.fadeWeight).normalize();
+    const tsFaded = mix(ts, tsf, rows.fadeWeight);
+    return compose(qFaded, tsFaded).mul(weight);
   };
+  const skin = slot(skinIndex.x, skinWeight.x).add(slot(skinIndex.y, skinWeight.y)).add(slot(skinIndex.z, skinWeight.z)).add(slot(skinIndex.w, skinWeight.w));
+  const skin3 = mat3(skin);
   return {
-    position: sample(vat.positionTexture),
-    normal: sample(vat.normalTexture).normalize()
+    encoding: "rig",
+    position: skin.mul(vec4(positionGeometry, 1)).xyz,
+    normal: skin3.mul(normalGeometry).normalize(),
+    // Gated on the geometry rather than read and ignored: `tangentGeometry`
+    // is an attribute read, and three computes tangents onto a geometry that
+    // has none the moment a graph asks for them.
+    tangent: geometry.hasAttribute("tangent") ? skin3.mul(tangentGeometry.xyz).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 };

package/dist/webgl.d.ts

@@ -1,5 +1,5 @@
 import { IUniform, MeshDepthMaterial, WebGLRenderer, Material } from 'three';
-import { d as VATInstance$1, e as addVATInstanceAttributes, V as VAT, c as VATCrowd } from './instance-playback-BrGBIKLe.js';
+import { V as VAT, j as VATPlaybackTexture, b as VATCarrier, i as VATInstance, f as VATCrowd } from './carrier-BXaLAPRO.js';
 
 /**
  * The real maximum texture dimension this GPU accepts, for
@@ -16,34 +16,36 @@ interface VATUniforms {
 }
 /** Create the shared time uniform. Update `uVatTime.value` once per frame. */
 declare function createVATUniforms(time?: number): VATUniforms;
-/**
- * The instance-playback contract now lives in the core entry point, so both
- * decode paths can read it (ADR-0009).
- *
- * @deprecated Renamed to `addVATInstanceAttributes` and moved to `three-vat`.
- * Removed from `three-vat/webgl` in the next minor version — import it from
- * `three-vat` instead.
- */
-declare const addInstancedVATAttributes: typeof addVATInstanceAttributes;
-/**
- * @deprecated Moved to `three-vat`. Removed from `three-vat/webgl` in the next
- * minor version — import `VATInstance` from `three-vat` instead.
- */
-type VATInstance = VATInstance$1;
 /**
  * Patch any built-in material so its vertex stage samples the VAT instead of
  * skinning. Works on the render material and on `MeshDepthMaterial` (needed for
  * instanced shadows — see {@link createVATDepthMaterial}). Mutates and returns
  * the material.
+ *
+ * `playback` is the crowd's playback texture — the decode reads the pack out of
+ * it by this instance's logical index, so a material patched for one crowd
+ * renders that crowd's playback and no other's.
+ *
+ * `carrier` is the mesh this material will draw on, and it is needed for one
+ * reason: how the shader names that logical index. Omit it for an
+ * `InstancedMesh`, where the index is `gl_InstanceID`. Pass a `BatchedMesh` and
+ * the decode resolves the index through `getIndirectIndex( gl_DrawID )`
+ * instead, because that carrier culls and sorts per instance and its drawn slot
+ * is a permutation that changes every frame (ADR-0016). A batch a VAT cannot be
+ * decoded on is refused here rather than rendered wrong.
  */
-declare function patchVATMaterial<T extends Material>(material: T, vat: VAT, uniforms: VATUniforms): T;
+declare function patchVATMaterial<T extends Material>(material: T, vat: VAT, uniforms: VATUniforms, playback: VATPlaybackTexture, carrier?: VATCarrier): T;
 /**
- * Build the `customDepthMaterial` an `InstancedMesh` needs so a VAT crowd casts
+ * Build the `customDepthMaterial` a VAT crowd needs so it casts
  * correctly-deformed shadows instead of bind-pose shadows. Assign the result to
  * `mesh.customDepthMaterial` (and, for point lights, mirror with a patched
  * `MeshDistanceMaterial`).
+ *
+ * `carrier` means what it means in {@link patchVATMaterial}: omit it for an
+ * `InstancedMesh`, pass the `BatchedMesh` for a batched crowd, so the shadow
+ * pass resolves the same instance index the render pass does.
  */
-declare function createVATDepthMaterial(vat: VAT, uniforms: VATUniforms): MeshDepthMaterial;
+declare function createVATDepthMaterial(vat: VAT, uniforms: VATUniforms, playback: VATPlaybackTexture, carrier?: VATCarrier): MeshDepthMaterial;
 /** Options for {@link createVATMesh}. */
 interface CreateVATMeshOptions {
     /**
@@ -56,12 +58,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, whose
- * materials decode the VAT, and whose shadows are deformed rather than frozen
- * in the bind pose.
+ * `InstancedMesh` rendering the bake's geometry, a playback texture carrying
+ * the instance-playback contract, materials that decode the VAT, and shadows
+ * that are deformed rather than frozen in the bind pose.
  *
  * ```ts
- * const { mesh, time } = createVATMesh(vat, instances)
+ * const { mesh, time, playback } = createVATMesh(vat, instances)
  * mesh.castShadow = mesh.receiveShadow = true
  * scene.add(mesh)
  * // per frame:
@@ -78,11 +80,14 @@ interface CreateVATMeshOptions {
  * - **`castShadow` / `receiveShadow`**, which are scene decisions. The depth and
  *   distance materials the shadow passes need are already attached either way.
  *
- * Everything here is the exported primitives — {@link addVATInstanceAttributes},
+ * Everything here is the exported primitives — `createVATPlaybackTexture`,
  * {@link patchVATMaterial}, {@link createVATDepthMaterial} — composed in the one
  * order that is correct. Reach for them directly only when rendering onto
- * something other than a plain `InstancedMesh`.
+ * something other than a plain `InstancedMesh` — a `BatchedMesh`, for three's
+ * own per-instance culling and sorting, being the other carrier this library
+ * supports (docs/usage.md); the returned `playback` is what
+ * {@link setVATInstance} writes into either way.
  */
-declare function createVATMesh(vat: VAT, instances: VATInstance$1[], options?: CreateVATMeshOptions): VATCrowd;
+declare function createVATMesh(vat: VAT, instances: VATInstance[], options?: CreateVATMeshOptions): VATCrowd;
 
-export { type CreateVATMeshOptions, type VATInstance, type VATUniforms, addInstancedVATAttributes, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };
+export { type CreateVATMeshOptions, type VATUniforms, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };