three-vat 1.0.1 → 2.0.0

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, i as VATPlaybackTexture, a as VATCarrier, h as VATInstance, e as VATCrowd } from './carrier-BFCPmcQK.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 };

package/dist/webgl.js

@@ -1,4 +1,5 @@
-import { addVATInstanceAttributes, createCrowdGeometry } from './chunk-SXTVASKG.js';
+import { assertBakedNormal, assertVATCarrier, isBatchedCarrier } from './chunk-W2ZAFMPB.js';
+import { PACK_TEXELS, EndMode, LoopMode, INFINITE_REPETITIONS, createVATPlaybackTexture } from './chunk-2PGZ44TP.js';
 import { MeshDepthMaterial, RGBADepthPacking, InstancedMesh, MeshDistanceMaterial } from 'three';
 
 function getMaxTextureSize(renderer) {
@@ -7,67 +8,168 @@ function getMaxTextureSize(renderer) {
 function createVATUniforms(time = 0) {
   return { uVatTime: { value: time } };
 }
-var addInstancedVATAttributes = addVATInstanceAttributes;
+var glslFloat = (n) => n.toFixed(1);
 var DECODE_PRELUDE = (
   /* glsl */
   `
   uniform highp sampler2D uVatPosTex;
-  uniform highp sampler2D uVatNrmTex;
+  uniform highp sampler2D uVatPlaybackTex;
   uniform float uVatTime;
-  attribute float aClipStart;
-  attribute float aClipFrames;
-  attribute float aClipFps;
-  attribute float aTimeOffset;
-  attribute float aSpeed;
-  vec3 vatSample( const in sampler2D tex ) {
-    float duration = aClipFrames / aClipFps;
-    float t = fract( ( uVatTime * aSpeed + aTimeOffset ) / duration ) * aClipFrames;
-    int f0 = int( t );
-    int f1 = int( mod( float( f0 + 1 ), aClipFrames ) );
-    vec3 s0 = texelFetch( tex, ivec2( gl_VertexID, f0 + int( aClipStart ) ), 0 ).xyz;
-    vec3 s1 = texelFetch( tex, ivec2( gl_VertexID, f1 + int( aClipStart ) ), 0 ).xyz;
-    return mix( s0, s1, fract( t ) );
+  vec3 vatSample( const in sampler2D tex, const in int vatInstance ) {
+    // The pack, fetched by this instance's *logical* index rather than read
+    // off an attribute indexed by the drawn slot (ADR-0016). Three texels of
+    // one row, in the order src/instance-playback.ts lays them out; the
+    // arithmetic below is untouched by where they came from, because the pack
+    // was already three vec4s.
+    //
+    // The index arrives as a parameter rather than being read here, because
+    // where it comes from is the carrier's business and not the decode's:
+    // gl_InstanceID on an InstancedMesh, getIndirectIndex( gl_DrawID ) on a
+    // BatchedMesh \u2014 see INSTANCE_ID in src/webgl.ts. It also has to be a
+    // parameter: getIndirectIndex is declared by batching_pars_vertex, which
+    // three expands *after* this prelude, so naming it up here would not
+    // compile.
+    //
+    // Fetched inside the function, so each injection point stays
+    // self-contained (ADR-0006) \u2014 which costs a second set of fetches in the
+    // normal decode. Every vertex of an instance reads the same three texels,
+    // so the texture cache absorbs them; the 5% demo bench is what says so.
+    vec4 vatClip     = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.clip}, vatInstance ), 0 );
+    vec4 vatPlayback = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.playback}, vatInstance ), 0 );
+    vec4 vatFade     = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.fade}, vatInstance ), 0 );
+
+    float frames = vatClip.y;
+    float last = frames - 1.0;
+    float duration = frames / vatClip.z;
+    // Local time: how far into its own animation this instance is. A start time
+    // in the past is what desyncs a crowd; a start time in the future has not
+    // begun, which is not the same thing as having finished.
+    float local = ( uVatTime - vatPlayback.x ) * vatClip.w;
+    float loops = local / duration;
+    float repetitions = vatPlayback.z;
+
+    bool started = local >= 0.0;
+    bool finished = started && repetitions != ${glslFloat(INFINITE_REPETITIONS)} && loops >= repetitions;
+
+    float phase;
+    bool wraps;
+    if ( !started ) {
+      phase = 0.0;
+      wraps = false;
+    } else if ( finished ) {
+      // Held at an end pose, and in neither case sampling past it.
+      phase = vatPlayback.w == ${glslFloat(EndMode.Clamp)} ? 1.0 : 0.0;
+      wraps = false;
+    } else if ( vatPlayback.y == ${glslFloat(LoopMode.PingPong)} ) {
+      float m = mod( loops, 2.0 );
+      phase = m < 1.0 ? m : 2.0 - m;
+      wraps = false; // a ping-pong bounces; it does not wrap
+    } else {
+      phase = fract( loops );
+      wraps = true;  // and here the interpolation crossing back is correct
+    }
+
+    float f = phase * ( wraps ? frames : last );
+    float f0 = min( floor( f ), last );
+    float f1 = wraps ? mod( f0 + 1.0, frames ) : min( f0 + 1.0, last );
+    vec3 s0 = texelFetch( tex, ivec2( gl_VertexID, int( vatClip.x + f0 ) ), 0 ).xyz;
+    vec3 s1 = texelFetch( tex, ivec2( gl_VertexID, int( vatClip.x + f1 ) ), 0 ).xyz;
+    vec3 sampled = mix( s0, s1, f - f0 );
+
+    // The pose-freeze fade, transcribed from the same resolver: one frozen row
+    // of the clip this instance was playing when it changed, blended away over
+    // vatFade.w. Wall clock, not clip time \u2014 the incoming clip's speed does
+    // not stretch a fade. A duration of zero is what "not fading" is, and the
+    // pack never writes one without a band to go with it.
+    if ( vatFade.w > 0.0 ) {
+      float weight = 1.0 - clamp( ( uVatTime - vatPlayback.x ) / vatFade.w, 0.0, 1.0 );
+      float fromRow = max( min( floor( vatFade.z * vatFade.y ), vatFade.y - 1.0 ), 0.0 );
+      vec3 frozen = texelFetch( tex, ivec2( gl_VertexID, int( vatFade.x + fromRow ) ), 0 ).xyz;
+      sampled = mix( sampled, frozen, weight );
+    }
+    return sampled;
   }
 `
 );
-var DECODE_POSITION = (
+var NORMAL_PRELUDE = (
   /* glsl */
   `
-  vec3 transformed = position + vatSample( uVatPosTex );
+  uniform highp sampler2D uVatNrmTex;
 `
 );
-var DECODE_NORMAL = (
+var INSTANCE_ID = {
+  instance: "gl_InstanceID",
+  batch: "int( getIndirectIndex( gl_DrawID ) )"
+};
+var decodePosition = (id) => (
   /* glsl */
   `
-  vec3 objectNormal = normalize( vatSample( uVatNrmTex ) );
+  vec3 transformed = position + vatSample( uVatPosTex, ${INSTANCE_ID[id]} );
+`
+);
+var decodeNormal = (id) => (
+  /* glsl */
+  `
+  vec3 objectNormal = normalize( vatSample( uVatNrmTex, ${INSTANCE_ID[id]} ) );
   #ifdef USE_TANGENT
     vec3 objectTangent = vec3( tangent.xyz );
   #endif
 `
 );
-function patchVATMaterial(material, vat, uniforms) {
+function patchVATMaterial(material, vat, uniforms, playback, carrier) {
+  assertBakedNormal(vat, material);
+  if (carrier) assertVATCarrier(carrier, vat);
+  const normalTexture = vat.normalTexture;
+  const id = isBatchedCarrier(carrier) ? "batch" : "instance";
   material.onBeforeCompile = (shader) => {
     shader.uniforms.uVatPosTex = { value: vat.positionTexture };
-    shader.uniforms.uVatNrmTex = { value: vat.normalTexture };
+    shader.uniforms.uVatPlaybackTex = { value: playback.texture };
     shader.uniforms.uVatTime = uniforms.uVatTime;
-    shader.vertexShader = DECODE_PRELUDE + shader.vertexShader.replace("#include <begin_vertex>", DECODE_POSITION).replace("#include <beginnormal_vertex>", DECODE_NORMAL);
+    let vertexShader = shader.vertexShader.replace("#include <begin_vertex>", decodePosition(id));
+    if (normalTexture) {
+      shader.uniforms.uVatNrmTex = { value: normalTexture };
+      vertexShader = vertexShader.replace("#include <beginnormal_vertex>", decodeNormal(id));
+    }
+    shader.vertexShader = (normalTexture ? NORMAL_PRELUDE : "") + DECODE_PRELUDE + vertexShader;
   };
-  material.customProgramCacheKey = () => "three-vat";
+  const key = `three-vat:${id}${normalTexture ? "" : ":no-normal"}`;
+  material.customProgramCacheKey = () => key;
+  guardCarrierMismatch(material, id);
   return material;
 }
-function createVATDepthMaterial(vat, uniforms) {
+function guardCarrierMismatch(material, id) {
+  const previous = material.onBeforeRender.bind(material);
+  let checked = false;
+  material.onBeforeRender = function(renderer, scene, camera, geometry, object, group) {
+    if (!checked) {
+      checked = true;
+      const drawnOn = isBatchedCarrier(object) ? "batch" : "instance";
+      if (drawnOn !== id) {
+        throw new Error(
+          `three-vat: this material was patched for ${CARRIER_NAME[id]} and is being drawn on ${CARRIER_NAME[drawnOn]}. Pass the carrier as \`patchVATMaterial\`'s fifth argument \u2014 the two spell the instance index differently, and a batch drawn with the instanced spelling plays instance 0\u2019s clip on every instance.`
+        );
+      }
+    }
+    previous(renderer, scene, camera, geometry, object, group);
+  };
+}
+var CARRIER_NAME = {
+  instance: "an InstancedMesh",
+  batch: "a BatchedMesh"
+};
+function createVATDepthMaterial(vat, uniforms, playback, carrier) {
   const depth = new MeshDepthMaterial({ depthPacking: RGBADepthPacking });
-  patchVATMaterial(depth, vat, uniforms);
+  patchVATMaterial(depth, vat, uniforms, playback, carrier);
   return depth;
 }
 function createVATMesh(vat, instances, options = {}) {
   const uniforms = options.time ? { uVatTime: options.time } : createVATUniforms();
-  const geometry = createCrowdGeometry(vat, instances);
-  const materials = vat.materials.map((source) => patchVATMaterial(source.clone(), vat, uniforms));
-  const mesh = new InstancedMesh(geometry, materials, instances.length);
-  mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms);
-  mesh.customDistanceMaterial = patchVATMaterial(new MeshDistanceMaterial(), vat, uniforms);
-  return { mesh, time: uniforms.uVatTime };
+  const playback = createVATPlaybackTexture(instances);
+  const materials = vat.materials.map((source) => patchVATMaterial(source.clone(), vat, uniforms, playback));
+  const mesh = new InstancedMesh(vat.geometry, materials, instances.length);
+  mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms, playback);
+  mesh.customDistanceMaterial = patchVATMaterial(new MeshDistanceMaterial(), vat, uniforms, playback);
+  return { mesh, time: uniforms.uVatTime, playback };
 }
 
-export { addInstancedVATAttributes, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };
+export { createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-vat",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "packageManager": "pnpm@10.19.0",
   "sideEffects": false,
   "files": [
     "dist"
@@ -34,6 +35,15 @@
       "import": "./dist/tsl.js"
     }
   },
+  "scripts": {
+    "dev": "pnpm --filter three-vat-example dev",
+    "test": "vitest run && pnpm --filter three-vat-example test",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p release/tsconfig.json && pnpm --filter three-vat-example typecheck",
+    "build:watch": "tsup --watch",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
   "keywords": [
     "three",
     "threejs",
@@ -48,28 +58,24 @@
     "tsl"
   ],
   "peerDependencies": {
-    "three": ">=0.185.0"
+    "three": ">=0.186.0"
   },
   "devDependencies": {
-    "@types/three": "^0.185.0",
+    "@types/three": "^0.186.0",
     "gifenc": "1.0.3",
     "playwright-core": "1.63.0",
     "pngjs": "7.0.0",
-    "three": "^0.185.0",
+    "three": "^0.186.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vite": "^7.1.0",
     "vitest": "^2.1.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
-  "scripts": {
-    "dev": "pnpm --filter three-vat-example dev",
-    "test": "vitest run && pnpm --filter three-vat-example test",
-    "build": "tsup",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p release/tsconfig.json && pnpm --filter three-vat-example typecheck",
-    "build:watch": "tsup --watch",
-    "test:watch": "vitest"
-  }
-}
+  "workspaces": [
+    ".",
+    "examples"
+  ]
+}

package/dist/chunk-SXTVASKG.js

@@ -1,40 +0,0 @@
-import { InstancedBufferAttribute } from 'three';
-
-// src/instance-playback.ts
-var PLAYBACK_ATTRIBUTES = {
-  clipStart: "aClipStart",
-  clipFrames: "aClipFrames",
-  clipFps: "aClipFps",
-  timeOffset: "aTimeOffset",
-  speed: "aSpeed"
-};
-function addVATInstanceAttributes(geometry, instances) {
-  geometry.morphAttributes = {};
-  geometry.morphTargetsRelative = false;
-  const n = instances.length;
-  const clipStart = new Float32Array(n);
-  const clipFrames = new Float32Array(n);
-  const clipFps = new Float32Array(n);
-  const timeOffset = new Float32Array(n);
-  const speed = new Float32Array(n);
-  for (let i = 0; i < n; i++) {
-    const inst = instances[i];
-    clipStart[i] = inst.clip.startFrame;
-    clipFrames[i] = inst.clip.frames;
-    clipFps[i] = inst.clip.fps;
-    timeOffset[i] = inst.timeOffset;
-    speed[i] = inst.speed;
-  }
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipStart, new InstancedBufferAttribute(clipStart, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipFrames, new InstancedBufferAttribute(clipFrames, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipFps, new InstancedBufferAttribute(clipFps, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.timeOffset, new InstancedBufferAttribute(timeOffset, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.speed, new InstancedBufferAttribute(speed, 1));
-}
-function createCrowdGeometry(vat, instances) {
-  const geometry = vat.geometry.clone();
-  addVATInstanceAttributes(geometry, instances);
-  return geometry;
-}
-
-export { PLAYBACK_ATTRIBUTES, addVATInstanceAttributes, createCrowdGeometry };

package/dist/instance-playback-BrGBIKLe.d.ts

@@ -1,109 +0,0 @@
-import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh } from 'three';
-
-/** One baked animation range within a VAT's stacked frame rows. */
-interface VATClip {
-    /** Clip name, taken from the source `AnimationClip`. */
-    name: string;
-    /** First frame row (y) of this clip in the texture. */
-    startFrame: number;
-    /** Number of frame rows baked for this clip. */
-    frames: number;
-    /** Effective frames-per-second of the bake (`frames / duration`). */
-    fps: number;
-    /** Source clip duration in seconds. */
-    duration: number;
-    /**
-     * Largest per-vertex position-delta magnitude (metres) across the clip.
-     * Near-zero means the clip baked as a frozen pose — the diagnostic for a
-     * mis-targeted or genuinely static clip.
-     */
-    maxDelta: number;
-}
-/**
- * A baked Vertex Animation Texture: the position/normal `DataTexture`s, the
- * geometry they are indexed by, and the clip table and bounds needed to decode
- * and render them. Produced exactly one way — {@link bakeVAT}, at runtime, from
- * a loaded glTF (ADR-0010).
- *
- * The merged vertex ordering is the baker's own invention and the textures are
- * indexed by it (`x = gl_VertexID`), so the caller cannot bring its own
- * geometry — it must render the one baked here. `materials` is ordered to match
- * `geometry.groups[].materialIndex`, giving one draw call per material.
- */
-interface VAT {
-    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
-    positionTexture: DataTexture;
-    /** RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`). */
-    normalTexture: DataTexture;
-    /** Merged, root-space rest-pose geometry. Its `position` is the delta reference. */
-    geometry: BufferGeometry;
-    /** Source materials, indexed by `geometry.groups[].materialIndex`. */
-    materials: Material[];
-    /** Clip table: name → `{ startFrame, frames, fps, ... }`. */
-    clips: VATClip[];
-    /** Union of every baked frame's bounds; use as the geometry bounding box. */
-    bounds: Box3;
-    /** Vertex count (texture width). */
-    vertexCount: number;
-    /** Total frame rows across all clips (texture height). */
-    totalFrames: number;
-    /** Position encoding. Only `'delta'` in v1. */
-    encoding: 'delta';
-}
-/**
- * The shared playback clock: one `{ value }` in seconds, read by every material
- * of every VAT mesh driven by it. Set it once per frame. Deliberately the
- * narrowest shape both decode paths satisfy — a WebGL `IUniform<number>` and a
- * TSL uniform node are both one of these — so `createVATMesh` returns the same
- * thing on either renderer.
- */
-interface VATClock {
-    value: number;
-}
-/**
- * A **crowd** ready to render: the mesh to add to the scene, and the clock to
- * advance. What `createVATMesh` returns on either decode path, so moving a
- * crowd between renderers is an import change and nothing else. Named for what
- * it is rather than for its `mesh` field — the clock is half of it.
- */
-interface VATCrowd {
-    /** Add to the scene. Its instance matrices are yours to write. */
-    mesh: InstancedMesh;
-    /** The shared playback clock — set `.value` once per frame. */
-    time: VATClock;
-}
-
-/** Per-instance playback state consumed by both decode paths. */
-interface VATInstance {
-    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'>;
-    /** Phase offset in seconds — desyncs the crowd. */
-    timeOffset: number;
-    /** Playback rate multiplier. */
-    speed: number;
-}
-/**
- * Attach the instance-playback attributes to an instanced geometry. Call once
- * before rendering, on the geometry you hand to the `InstancedMesh`.
- *
- * The attribute names and layout below are the shared contract, spelled once in
- * {@link PLAYBACK_ATTRIBUTES}. Both decode paths read exactly these five —
- * `DECODE_PRELUDE` in `src/webgl.ts` as GLSL attributes, `vatNodes` in
- * `src/tsl.ts` as TSL attribute nodes, when it is handed this geometry.
- *
- * | Attribute     | Type          | Source                |
- * | ------------- | ------------- | --------------------- |
- * | `aClipStart`  | `float` (x 1) | `instance.clip.startFrame` — first texture row of the clip's frame band |
- * | `aClipFrames` | `float` (x 1) | `instance.clip.frames` — rows in the band |
- * | `aClipFps`    | `float` (x 1) | `instance.clip.fps` — with `frames`, the clip's duration |
- * | `aTimeOffset` | `float` (x 1) | `instance.timeOffset` — phase, in seconds |
- * | `aSpeed`      | `float` (x 1) | `instance.speed` — rate multiplier |
- *
- * Every entry is a one-component `InstancedBufferAttribute` of `Float32Array`,
- * one element per instance, in instance order. Adding a field — crossfade's
- * reserved second clip index being the known case (ADR-0007) — means adding it
- * here, in the table above, and in each decode path's own attribute
- * declarations.
- */
-declare function addVATInstanceAttributes(geometry: BufferGeometry, instances: VATInstance[]): void;
-
-export { type VAT as V, type VATClip as a, type VATClock as b, type VATCrowd as c, type VATInstance as d, addVATInstanceAttributes as e };