three-vat 2.0.0 → 3.0.0

package/dist/tsl.d.ts

@@ -1,5 +1,5 @@
 import { Node } from 'three/webgpu';
-import { d as VATClock, i as VATPlaybackTexture, a as VATCarrier, V as VAT, h as VATInstance, e as VATCrowd } from './carrier-BFCPmcQK.js';
+import { e as VATClock, k as VATPlaybackTexture, b as VATCarrier, V as VAT, h as VATInstance, f as VATCrowd } from './carrier-BxRuW47G.js';
 import 'three';
 
 /**
@@ -14,8 +14,12 @@ import 'three';
 declare function getMaxTextureSize(renderer: object): number;
 /** A fluent TSL float node (has `.add`, `.mul`, … via NodeExtensions). */
 type FloatNode = Node<'float'>;
+/** A fluent TSL int node. */
+type IntNode = Node<'int'>;
 /** A fluent TSL vec3 node. */
 type Vec3Node = Node<'vec3'>;
+/** A fluent TSL bool node — a branch condition, and what `.select()` reads. */
+type BoolNode = Node<'bool'>;
 /**
  * A TSL float uniform: a node the graph reads, and a `{ value }` clock the
  * caller sets per frame. Both halves matter — the node is what the decode
@@ -48,14 +52,16 @@ interface VATNodeOptions {
      *
      * 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).
+     * 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
@@ -82,17 +88,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
@@ -103,6 +111,28 @@ interface VATNodes {
     /** The time uniform in use — set `.value` each frame. */
     time: VATTimeUniform;
 }
+/** The clip texel: which band an instance plays, how long it is, and how fast. */
+interface ClipTexel {
+    /** First texture row of the clip's band. */
+    startFrame: IntNode;
+    /** Rows in the band. */
+    frames: FloatNode;
+    /** Seconds the band spans. */
+    duration: FloatNode;
+    /** Rate multiplier. */
+    speed: FloatNode;
+}
+/** The playback texel: when this animation began, and how it repeats. */
+interface PlaybackTexel {
+    /** Absolute clock time this animation began. In the past, for a desynced crowd. */
+    startTime: FloatNode;
+    /** {@link LoopMode}, as the number the pack carries. */
+    loopMode: FloatNode;
+    /** Repeat count, or {@link INFINITE_REPETITIONS}. */
+    repetitions: FloatNode;
+    /** {@link EndMode}, as the number the pack carries. */
+    endMode: FloatNode;
+}
 /**
  * Build TSL decode nodes for a baked VAT, for the WebGPU/TSL renderer path.
  * Shadows work automatically because `positionNode` also feeds the depth pass.
@@ -118,9 +148,62 @@ interface VATNodes {
  */
 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.
+ * 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;
+};
+/**
+ * One band resolved — the TSL spelling of the GLSL decode's `VatBand` struct:
+ * the two rows and the blend between them, plus the two facts those rows cannot
+ * be read back out of.
+ *
+ * @internal The return type of {@link resolveBand}, exported for the structural
+ * tests and for nothing else.
+ */
+interface Band {
+    row0: IntNode;
+    row1: IntNode;
+    blend: FloatNode;
+    /** Whether the sampling crossed the band's last row back into its first. */
+    wraps: BoolNode;
+    /** Whether the repetitions have run out and the instance is holding an end pose. */
+    finished: BoolNode;
+}
+/**
+ * `resolveVATFrame` (src/instance-playback.ts) as a node graph, for one (clip
+ * texel, playback texel) pair — branch for branch with the GLSL decode's
+ * `vatBand`. The semantics live there; this transcribes them, and the mode
+ * constants come from that module rather than being retyped as literals.
+ *
+ * A function of the pair rather than of the instance, because the pair is what
+ * there are two of: a crossfading instance resolves its outgoing band by
+ * calling this a second time, not by transcribing it a second time.
+ *
+ * @internal Exported for the structural tests, and for nothing else. Not
+ * re-exported from `three-vat`.
+ */
+declare function resolveBand(clip: ClipTexel, playback: PlaybackTexel, time: FloatNode): Band;
+/**
+ * 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),
@@ -128,10 +211,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 | null;
-};
+declare function vatDecode(vat: VAT, options?: VATNodeOptions): VATDecoded;
 /** Options for {@link createVATMesh}. */
 interface CreateVATMeshOptions {
     /**
@@ -173,4 +253,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 Band, type CreateVATMeshOptions, type VATDecoded, type VATNodeOptions, type VATNodes, type VATTimeUniform, createVATMesh, getMaxTextureSize, resolveBand, vatDecode, vatNodes };

package/dist/tsl.js

@@ -1,7 +1,7 @@
-import { isBatchedCarrier, assertVATCarrier, assertBakedNormal } from './chunk-W2ZAFMPB.js';
-import { INFINITE_REPETITIONS, LoopMode, EndMode, createVATPlaybackTexture, PACK_TEXELS } from './chunk-2PGZ44TP.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-J5IEUGSB.js';
 import { InstancedMesh } from 'three';
-import { uniform, Fn, positionLocal, positionGeometry, normalLocal, batch, instancedMesh, int, vertexIndex, float, bool, textureLoad, ivec2, mix, batchIndirectIndex, instanceIndex, hash } 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;
@@ -13,27 +13,37 @@ function getMaxTextureSize(renderer) {
 }
 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;
+  const crossfade = packTexel(texture, PACK_TEXELS.crossfade, instance);
   return {
-    startFrame: int(clip.x),
-    frames,
-    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
+    live: liveBand(
+      packTexel(texture, PACK_TEXELS.clip, instance),
+      packTexel(texture, PACK_TEXELS.playback, instance)
+    ),
+    crossfadeDuration: crossfade.x,
+    outgoing: outgoingBand(
+      packTexel(texture, PACK_TEXELS.outgoingClip, instance),
+      packTexel(texture, PACK_TEXELS.outgoingPlayback, instance)
+    )
+  };
+}
+function bandTexels(clip, playback, frames, fps) {
+  return {
+    clip: {
+      startFrame: int(clip.x),
+      frames,
+      duration: frames.div(fps),
+      speed: clip.w
+    },
+    playback: {
+      startTime: playback.x,
+      loopMode: playback.y,
+      repetitions: playback.z,
+      endMode: playback.w
     }
   };
 }
+var liveBand = (clip, playback) => bandTexels(clip, playback, clip.y, clip.z);
+var outgoingBand = (clip, playback) => bandTexels(clip, playback, clip.y.max(1), clip.z.max(1));
 var instanceIdOf = (carrier) => isBatchedCarrier(carrier) ? int(batchIndirectIndex) : int(instanceIndex);
 function clipAt(vat, clipIndex) {
   const clip = vat.clips[clipIndex];
@@ -43,32 +53,40 @@ function clipAt(vat, clipIndex) {
   return clip;
 }
 function hashedPlayback(clip, desync, instance) {
-  return {
-    startFrame: int(clip.startFrame),
-    frames: float(clip.frames),
-    duration: float(clip.frames / clip.fps),
-    // 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) }
+  const live = {
+    clip: {
+      startFrame: int(clip.startFrame),
+      frames: float(clip.frames),
+      duration: float(clip.frames / clip.fps),
+      // 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)
+    },
+    playback: {
+      // 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),
+      loopMode: float(clip.loopMode),
+      repetitions: float(clip.repetitions),
+      endMode: float(clip.endMode)
+    }
   };
+  return { live, crossfadeDuration: float(0), outgoing: live };
 }
 function vatNodes(vat, options = {}) {
   const { time = uniform(0), carrier } = options;
-  const { position, normal } = vatDecode(vat, options);
+  const decoded = vatDecode(vat, options);
   const decode = Fn(() => {
-    positionLocal.assign((carrier ? positionGeometry : positionLocal).add(position));
-    if (normal) normalLocal.assign(normal);
+    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);
@@ -77,17 +95,11 @@ function vatNodes(vat, options = {}) {
   }, "vec3");
   return { positionNode: decode(), time };
 }
-function vatDecode(vat, options = {}) {
-  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;
+function resolveBand(clip, playback, time) {
+  const frames = clip.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 local = time.sub(playback.startTime).mul(clip.speed);
+  const loops = local.div(clip.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);
@@ -105,30 +117,134 @@ function vatDecode(vat, options = {}) {
   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)),
+  const bandRow = (offset) => int(offset).add(clip.startFrame);
+  return {
+    row0: bandRow(f0),
+    row1: bandRow(f1),
+    blend: f.sub(f0),
+    wraps,
+    finished
+  };
+}
+function vatDecode(vat, options = {}) {
+  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 live = resolveBand(playback.live.clip, playback.live.playback, time);
+  const elapsed = time.sub(playback.live.playback.startTime);
+  const duration = playback.crossfadeDuration;
+  const weight = duration.greaterThan(0).select(
+    float(1).sub(elapsed.div(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 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 resolved = resolveBand(playback.outgoing.clip, playback.outgoing.playback, time);
+  const blending = weight.greaterThan(0);
+  const outgoing = {
+    row0: blending.select(resolved.row0, live.row0),
+    row1: blending.select(resolved.row1, live.row1),
+    blend: blending.select(resolved.blend, live.blend),
+    // Not selected, and deliberately: a sampler reads a band's rows and its
+    // blend and nothing else, so these two are carried because the band
+    // resolver answers them and not because anything downstream asks.
+    wraps: resolved.wraps,
+    finished: resolved.finished
+  };
+  const rows = { live, outgoing, weight };
+  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 band = (tex, of) => {
+    const s0 = textureLoad(tex, ivec2(vertexRow, of.row0)).xyz;
+    const s1 = textureLoad(tex, ivec2(vertexRow, of.row1)).xyz;
+    return mix(s0, s1, of.blend);
   };
-  const normalTexture = vat.normalTexture;
+  const sample = (tex) => mix(band(tex, rows.live), band(tex, rows.outgoing), rows.weight);
   return {
-    position: sample(vat.positionTexture),
+    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 pose = (rotation, placement, of) => {
+    const q0 = fetch(rotation, of.row0);
+    const ts0 = fetch(placement, of.row0);
+    const q1 = hemisphereOf(q0, fetch(rotation, of.row1));
+    const ts1 = fetch(placement, of.row1);
+    return {
+      // A normalised lerp, not a slerp: at a bake's frame step the angular error
+      // against a true slerp is far below anything visible. It is still a
+      // *rotation* at every blend, which is what a componentwise matrix lerp is
+      // not — that one shortens a limb as it turns (ADR-0018).
+      q: mix(q0, q1, of.blend).normalize(),
+      ts: mix(ts0, ts1, of.blend)
+    };
+  };
+  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 live = pose(rotation, placement, rows.live);
+    const outgoing = pose(rotation, placement, rows.outgoing);
+    const q = mix(live.q, hemisphereOf(live.q, outgoing.q), rows.weight).normalize();
+    const ts = mix(live.ts, outgoing.ts, rows.weight);
+    return compose(q, ts).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 {
+    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 playback = createVATPlaybackTexture(instances);
@@ -140,4 +256,4 @@ function createVATMesh(vat, instances, options = {}) {
   return { mesh, time, playback };
 }
 
-export { createVATMesh, getMaxTextureSize, vatDecode, vatNodes };
+export { createVATMesh, getMaxTextureSize, resolveBand, vatDecode, vatNodes };

package/dist/webgl.d.ts

@@ -1,5 +1,5 @@
 import { IUniform, MeshDepthMaterial, WebGLRenderer, Material } from 'three';
-import { V as VAT, i as VATPlaybackTexture, a as VATCarrier, h as VATInstance, e as VATCrowd } from './carrier-BFCPmcQK.js';
+import { b as VATCarrier, V as VAT, k as VATPlaybackTexture, h as VATInstance, f as VATCrowd } from './carrier-BxRuW47G.js';
 
 /**
  * The real maximum texture dimension this GPU accepts, for
@@ -16,6 +16,73 @@ interface VATUniforms {
 }
 /** Create the shared time uniform. Update `uVatTime.value` once per frame. */
 declare function createVATUniforms(time?: number): VATUniforms;
+/**
+ * The caller's own GLSL, run after the decode has posed the vertex (ADR-0021):
+ * a wind sway, a twist toward a target, a per-instance squash — deformation
+ * that is the scene's and never the library's. The WebGL path's answer to what
+ * `positionNode` already gives the TSL path, which needs none of this.
+ *
+ * It has **two** injection points because three expands `beginnormal_vertex`
+ * *before* `begin_vertex` and derives `transformedNormal` between them: a chunk
+ * that only moves the position cannot repair a normal that was already taken,
+ * and the crowd would shade as though it had never moved. One point is a hook
+ * that looks right in the viewport and is wrong in the light.
+ *
+ * ```ts
+ * const hook = {
+ *   key: 'twist',
+ *   uniforms: { uTarget: { value: new Vector3() } },
+ *   prelude: `
+ *     uniform vec3 uTarget;
+ *     vec3 twistY( vec3 p, float a ) {
+ *       float s = sin( a ), c = cos( a );
+ *       return vec3( c * p.x + s * p.z, p.y, -s * p.x + c * p.z );
+ *     }`,
+ *   position: 'transformed = twistY( transformed, vatTwistAngle( vatInstanceIndex ) );',
+ *   normal: 'objectNormal = twistY( objectNormal, vatTwistAngle( vatInstanceIndex ) );',
+ * }
+ * const { mesh } = createVATMesh(vat, instances, { hook })
+ * ```
+ */
+interface VATPostDecodeHook {
+    /**
+     * What tells this hook's compiled program from another's. Required, and
+     * folded into the library's own key rather than replacing it: without it two
+     * crowds whose materials are identical in every parameter three looks at
+     * share one program, and one of them renders the other's GLSL (ADR-0006).
+     */
+    key: string;
+    /**
+     * GLSL emitted ahead of three's shader — helper functions, the `uniform`
+     * declarations {@link uniforms} binds. Not an injection point, so ADR-0006
+     * does not govern it: this is where a helper the two chunks share is declared
+     * once.
+     */
+    prelude?: string;
+    /**
+     * The chunk run where three takes the position, with `transformed` in object
+     * space and already posed by the decode. Assign to it.
+     */
+    position?: string;
+    /**
+     * The chunk run where three takes the normal, with `objectNormal` already
+     * posed. Assign to it — otherwise a deformed crowd shades undeformed.
+     */
+    normal?: string;
+    /** Uniforms bound beside the library's own, so the chunks can be driven by your game state. */
+    uniforms?: Record<string, IUniform>;
+}
+/**
+ * What {@link patchVATMaterial} and {@link createVATDepthMaterial} take in
+ * place of a bare carrier — so a batched crowd with a hook passes one object
+ * rather than a positional carrier plus something else.
+ */
+interface VATPatchOptions {
+    /** The mesh this material will draw on. Means exactly what the bare argument means. */
+    carrier?: VATCarrier;
+    /** The caller's own GLSL, after the decode. */
+    hook?: VATPostDecodeHook;
+}
 /**
  * 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
@@ -33,19 +100,26 @@ declare function createVATUniforms(time?: number): VATUniforms;
  * 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.
+ *
+ * That fifth argument also takes a {@link VATPatchOptions} object, which is how
+ * a {@link VATPostDecodeHook} is passed — the caller's own GLSL after the
+ * decode, and the carrier beside it in one object.
  */
-declare function patchVATMaterial<T extends Material>(material: T, vat: VAT, uniforms: VATUniforms, playback: VATPlaybackTexture, carrier?: VATCarrier): T;
+declare function patchVATMaterial<T extends Material>(material: T, vat: VAT, uniforms: VATUniforms, playback: VATPlaybackTexture, options?: VATCarrier | VATPatchOptions): T;
 /**
  * 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.
+ * The fourth argument 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 — or pass
+ * the options object, so a hand-wired crowd's shadow deforms with the hook its
+ * render material carries. A deformed crowd casting an undeformed shadow is
+ * exactly the class of mistake this library exists to take off the caller.
  */
-declare function createVATDepthMaterial(vat: VAT, uniforms: VATUniforms, playback: VATPlaybackTexture, carrier?: VATCarrier): MeshDepthMaterial;
+declare function createVATDepthMaterial(vat: VAT, uniforms: VATUniforms, playback: VATPlaybackTexture, options?: VATCarrier | VATPatchOptions): MeshDepthMaterial;
 /** Options for {@link createVATMesh}. */
 interface CreateVATMeshOptions {
     /**
@@ -55,6 +129,14 @@ interface CreateVATMeshOptions {
      * `time`. The TSL path's `vatNodes` takes its clock the same way.
      */
     time?: IUniform<number>;
+    /**
+     * Your own GLSL after the decode (ADR-0021), threaded to every material this
+     * crowd draws with — the render materials, the depth material and the
+     * distance material. Threaded here rather than applied by hand afterwards
+     * because omitting one of the three is the bug: a twisted crowd casting an
+     * untwisted shadow.
+     */
+    hook?: VATPostDecodeHook;
 }
 /**
  * Turn a baked VAT and a list of instances into a crowd ready to render: an
@@ -90,4 +172,4 @@ interface CreateVATMeshOptions {
  */
 declare function createVATMesh(vat: VAT, instances: VATInstance[], options?: CreateVATMeshOptions): VATCrowd;
 
-export { type CreateVATMeshOptions, type VATUniforms, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };
+export { type CreateVATMeshOptions, type VATPatchOptions, type VATPostDecodeHook, type VATUniforms, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };