three-vat 1.0.0 → 2.0.0

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 };

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.0",
+  "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,31 +58,24 @@
     "tsl"
   ],
   "peerDependencies": {
-    "three": ">=0.185.0"
+    "three": ">=0.186.0"
   },
   "devDependencies": {
-    "@types/three": "^0.185.0",
-    "three": "^0.185.0",
+    "@types/three": "^0.186.0",
+    "gifenc": "1.0.3",
+    "playwright-core": "1.63.0",
+    "pngjs": "7.0.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": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "fetch:test-assets": "node scripts/fetch-test-assets.mjs",
-    "typecheck": "tsc --noEmit",
-    "release": "pnpm publish ${NPM_OTP:+--otp=\"$NPM_OTP\"} && pnpm verify:published",
-    "verify:published": "node scripts/verify-published.mjs",
-    "example": "pnpm --filter three-vat-example dev",
-    "build:examples": "pnpm --filter three-vat-example build",
-    "test:examples": "pnpm --filter three-vat-example test",
-    "parity": "pnpm --filter three-vat-example parity",
-    "typecheck:examples": "pnpm --filter three-vat-example typecheck"
-  }
-}
+  "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 };