three-vat 2.1.0 → 3.0.0

package/dist/tsl.d.ts

@@ -1,5 +1,5 @@
 import { Node } from 'three/webgpu';
-import { e as VATClock, j as VATPlaybackTexture, b as VATCarrier, V as VAT, i as VATInstance, f as VATCrowd } from './carrier-BXaLAPRO.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
@@ -107,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.
@@ -143,6 +169,37 @@ type VATDecoded = {
     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
@@ -196,4 +253,4 @@ interface CreateVATMeshOptions {
  */
 declare function createVATMesh(vat: VAT, instances: VATInstance[], options?: CreateVATMeshOptions): VATCrowd;
 
-export { type CreateVATMeshOptions, type VATDecoded, 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,5 +1,5 @@
 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 { 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, 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';
 
@@ -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,25 +53,27 @@ 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;
@@ -83,16 +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 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);
@@ -110,19 +117,40 @@ 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 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)),
+  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 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 };
+  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);
@@ -138,12 +166,12 @@ function vatDecode(vat, options = {}) {
 }
 function vertexDecode({ positionTexture, normalTexture }, rows) {
   const vertexRow = int(vertexIndex);
-  const sample = (tex) => {
-    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);
+  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 sample = (tex) => mix(band(tex, rows.live), band(tex, rows.outgoing), rows.weight);
   return {
     encoding: "delta",
     position: sample(positionTexture),
@@ -181,21 +209,29 @@ 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 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 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);
@@ -220,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, j as VATPlaybackTexture, b as VATCarrier, i as VATInstance, f as VATCrowd } from './carrier-BXaLAPRO.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 };