three-vat 1.0.1 → 2.1.0

package/README.md

@@ -16,7 +16,7 @@ Bake a glTF `AnimationClip` into GPU textures and animate **hundreds or thousand
 npm install three-vat three
 ```
 
-`three` (>= 0.185) is a peer dependency.
+`three` (>= 0.186) is a peer dependency.
 
 ## One crowd, start to finish
 
@@ -46,10 +46,13 @@ const vat = bakeVAT(gltf.scene, gltf.animations, {
   maxTextureSize: getMaxTextureSize(renderer), // this GPU's real ceiling
 })
 
-// One entry per character: which clip it plays, its phase, its rate.
+// One entry per character: which clip it plays, when it started, its rate.
+// Everything but `startTime` is optional — a clip baked from a configured
+// `AnimationAction` carries its own loop, repetition count, end behaviour and
+// speed, and an instance overrides only what it wants to differ.
 const instances = Array.from({ length: 500 }, (_, i) => ({
   clip: vat.clips[i % vat.clips.length],
-  timeOffset: Math.random() * 2, // desync, so the crowd is not in lockstep
+  startTime: -Math.random() * 2, // began a moment ago, so the crowd is not in lockstep
   speed: 0.9 + Math.random() * 0.2,
 }))
 
@@ -78,6 +81,11 @@ Two things worth knowing the first time:
 - **Materials are never merged.** A 500-robot crowd with 3 materials is 3 draw
   calls — not 1, and not 500. VAT collapses instance count, not material count.
 
+**A skinned character?** There is a second encoding: `{ encoding: 'rig' }` bakes
+the posed rig instead of the posed vertices — two orders of magnitude less
+texture, a bake in milliseconds, and faster on a phone, for an asset a rig can
+express. [The rig encoding](./docs/usage.md#the-rig-encoding-encoding-rig).
+
 <details>
 <summary><b>Does it work with my model?</b></summary>
 
@@ -97,6 +105,65 @@ of `gltf.animations` rather than spending texture rows on them.
 
 </details>
 
+<details>
+<summary><b>Per-clip playback defaults</b></summary>
+
+`bakeVAT` takes an `AnimationClip` **or** an `AnimationAction`, in the same
+array. Configure the action the way three already taught you, and every instance
+of that clip inherits it — and overrides any field it names.
+
+```ts
+const death = mixer.clipAction(deathClip)
+death.loop = THREE.LoopOnce
+
+const vat = bakeVAT(gltf.scene, [walkClip, death, idleClip])
+```
+
+`loop`, `repetitions` and `timeScale` are read; `time` and `paused` are ignored,
+because a VAT has no playhead of its own to seed; a non-unit `weight` or an
+additive `blendMode` throws, because one baked band cannot be several actions
+blended at once.
+
+**Both inputs clamp, where three rewinds.** `clampWhenFinished` defaults to
+`false` in three, which means an untouched action says nothing about the end
+either — and a crowd's answer to nothing is to hold the last frame, because a
+corpse standing back up is the worse default. So the end mode is not read off
+the action; an instance asks for three's rewind with `endMode: EndMode.Rewind`,
+which is the finer grain anyway.
+
+[Declaring the defaults at the bake](./docs/usage.md#declaring-the-defaults-at-the-bake).
+
+</details>
+
+<details>
+<summary><b>Upgrading from 1.x</b></summary>
+
+The breaks that reach a 1.x caller, no shims — the package had no users on the
+1.x playback contract, so 2.0 spells it one way rather than two. The full list
+is [the CHANGELOG's 2.0.0 entry](./CHANGELOG.md).
+
+```ts
+{ clip, timeOffset: 1.4, speed: 1 }  // 1.x — every field required
+{ clip, startTime: -1.4 }            // 2.0 — desync is a start time in the past
+```
+
+`timeOffset` is gone (`startTime: -timeOffset / speed`), and with it
+`aTimeOffset`. The pack is three `vec4`s — clip, playback, fade — in a
+**playback texture** keyed by the instance's logical index, not instanced
+attributes, which are indexed by the *drawn* slot:
+`addInstancedVATAttributes` is removed, `createVATPlaybackTexture(instances)`
+replaces `addVATInstanceAttributes`, and `setVATInstance(playback, id, instance)`
+takes that texture — `createVATMesh` returns it as `playback` — rather than a
+geometry. A VAT texture's `image.data` is now opaque. Node 20, where
+1.x said 18, and `three >= 0.186`, where `batchIndirectIndex` is exported;
+browsers are unaffected.
+
+New, and none of it breaking: per-instance loop modes, one-shots,
+`setVATInstance` after the crowd is built, and a crowd on a `BatchedMesh`.
+[By hand, on either path](./docs/usage.md#by-hand-on-either-path).
+
+</details>
+
 <details>
 <summary><b>Going bigger: texture limits, bake cost, Web Workers</b></summary>
 
@@ -117,7 +184,8 @@ worker recipe, the draw-call arithmetic, and the primitives underneath
 <details>
 <summary><b>What it does not do</b></summary>
 
-No clip crossfade (instances cut between clips), no LOD, no baking CLI or file
+No clip crossfade (an instance blends out of a frozen pose, not between two
+clips that are both playing), no LOD, no baking CLI or file
 format, no React/drei binding, glTF input only. Each is a decision rather than a
 gap, and each is written up with its reasoning in
 **[docs/usage.md](./docs/usage.md#what-10-does-not-do)**, alongside the

package/dist/carrier-BXaLAPRO.d.ts

@@ -0,0 +1,515 @@
+import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh, BatchedMesh } from 'three';
+
+/**
+ * How an instance repeats its clip — the numbers `THREE.LoopRepeat`,
+ * `THREE.LoopOnce` and `THREE.LoopPingPong` name, in three's own order, as
+ * values a `Float32Array` can carry.
+ *
+ * What each one *means* is {@link resolveVATFrame}, in one place, transcribed
+ * by both decode paths.
+ */
+declare const LoopMode: {
+    /** Play the clip end to end, forever (or `repetitions` times). */
+    readonly Repeat: 0;
+    /** Play the clip through once. */
+    readonly Once: 1;
+    /** Play forward, then backward, without baking the reversed frames. */
+    readonly PingPong: 2;
+};
+type LoopMode = (typeof LoopMode)[keyof typeof LoopMode];
+/**
+ * What an instance does once it has finished — three's `clampWhenFinished`, as
+ * a pair of numbers.
+ *
+ * `Clamp` is first because it is this library's default, where three's
+ * `clampWhenFinished` defaults to `false`. A one-shot in a crowd — a death, an
+ * impact — almost always has to *stay* in its final state, and a rewinding
+ * corpse standing back up is the failure a crowd library should not ship by
+ * default. The divergence is deliberate.
+ */
+declare const EndMode: {
+    /** Hold the last frame. */
+    readonly Clamp: 0;
+    /** Return to the first frame. */
+    readonly Rewind: 1;
+};
+type EndMode = (typeof EndMode)[keyof typeof EndMode];
+/**
+ * An endless repeat count, as the pack spells it. `Infinity` does not survive a
+ * `Float32Array` usefully, so it is converted once, here, at the boundary.
+ */
+declare const INFINITE_REPETITIONS = -1;
+/**
+ * The longest fade {@link setVATInstance} will honour, in seconds.
+ *
+ * The cap exists because of what this fade *is*: one frozen pose of the
+ * outgoing clip, blended away — not a second playback running alongside the
+ * first. Over a tenth of a second that is invisible; over half a second the
+ * instance visibly skates, because whatever it was doing stopped dead the
+ * moment the transition began. A longer fade would not be a better fade, it
+ * would be a more visible bug, so the number is clamped rather than trusted.
+ *
+ * Provisional, like the fade itself: a real two-clip crossfade (#30) replaces
+ * both, and nothing else should be built on top of them.
+ */
+declare const MAX_FADE_DURATION = 0.25;
+/**
+ * The frozen pose a fade blends away from: one phase of the clip an instance
+ * was playing when its animation changed, and the band that phase indexes.
+ *
+ * Not a second playback state — there is no start time and no speed here,
+ * because nothing about it moves. That is the whole of the freeze, and the
+ * whole of its limit; see {@link MAX_FADE_DURATION}.
+ */
+interface VATFadeFrom {
+    /** First texture row of the outgoing clip's band. */
+    startFrame: number;
+    /** Rows in that band. */
+    frames: number;
+    /** The phase of that band the instance was at, in `[0, 1]`. */
+    phase: number;
+}
+/**
+ * Per-instance playback state consumed by both decode paths.
+ *
+ * Every policy field is optional because the clip already answers it: a bake
+ * handed a configured `AnimationAction` records the answer in the clip table
+ * ({@link VATClipDefaults}), and an instance that says nothing inherits it. A
+ * crowd of a thousand deaths says "once, clamped" once, at the bake.
+ */
+interface VATInstance {
+    /**
+     * The clip band to play, straight out of `vat.clips`. Its playback defaults
+     * come along with it; a clip table assembled by hand may carry none, and then
+     * the library defaults below apply.
+     */
+    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'> & Partial<VATClipDefaults>;
+    /**
+     * Absolute clock time, in seconds, at which this animation began. May be in
+     * the past — and **desync is exactly that**: give each instance of a crowd its
+     * own start time a little way back and they stop moving in lockstep.
+     *
+     * The one field with no clip-level default: when an animation began is a fact
+     * about the instance and nothing else.
+     */
+    startTime: number;
+    /**
+     * Playback rate multiplier, `>= 0`. Defaults to the clip's speed, then to
+     * `1`. A negative rate is refused when the instance is written: a VAT plays
+     * forward, and a clip that must run backwards is baked as a reversed clip.
+     * `0` is legal — the instance holds its clip's first row.
+     */
+    speed?: number;
+    /** How the clip repeats. Defaults to the clip's, then {@link LoopMode.Repeat}. */
+    loopMode?: LoopMode;
+    /**
+     * How many times to play the clip, or {@link INFINITE_REPETITIONS}. Defaults
+     * to the clip's count, then to endless for {@link LoopMode.Repeat} and a
+     * single play for anything else — the counts three's own `LoopRepeat` and
+     * `LoopOnce` imply.
+     *
+     * A count belongs to the mode it was configured under: replace the clip's
+     * `loopMode` and say nothing here, and the count comes from the new mode
+     * rather than from the clip — a one-shot over a looping clip finishes.
+     */
+    repetitions?: number;
+    /**
+     * What to do once the repetitions run out. Defaults to the clip's, then
+     * {@link EndMode.Clamp} — where three's `clampWhenFinished` defaults to
+     * `false`; see {@link EndMode}.
+     */
+    endMode?: EndMode;
+    /**
+     * The frozen outgoing pose to fade away from. Normally you do not write this
+     * yourself: {@link setVATInstance} freezes whatever the instance was playing
+     * and fills it in when you ask for a {@link fadeDuration}.
+     */
+    from?: VATFadeFrom;
+    /**
+     * Seconds to blend {@link from} away over, capped at {@link MAX_FADE_DURATION}.
+     * Wall-clock seconds from {@link startTime}: the clip's `speed` does not
+     * stretch a fade.
+     *
+     * Ignored without a `from` to fade away from — and at creation there is
+     * nothing to fade away from, so this is `setVATInstance`'s field in practice.
+     */
+    fadeDuration?: number;
+}
+/**
+ * Where in its VAT an instance is at a given moment: the two frame rows to
+ * sample, the blend between them, and the two facts a decode cannot re-derive
+ * from the rows alone.
+ */
+interface VATFrame {
+    /** The frame row to sample — an absolute texture row, clip band included. */
+    row: number;
+    /** The row it interpolates toward. */
+    rowNext: number;
+    /** Blend between {@link row} and {@link rowNext}, in `[0, 1)`. */
+    mix: number;
+    /**
+     * Whether {@link rowNext} crossed the clip's last row back into its first.
+     * True only while a clip is genuinely looping: a ping-pong bounces rather
+     * than wraps, and a finished one-shot must not wrap at all or the corpse
+     * stands back up for a frame.
+     */
+    wraps: boolean;
+    /** Whether the repetitions have run out and the instance is holding an end pose. */
+    finished: boolean;
+    /** How far through the clip this is, in `[0, 1]` — what {@link row} is derived from. */
+    phase: number;
+    /**
+     * The frozen outgoing row a fade blends away from. Equal to {@link row} when
+     * the instance is not fading, so a reader that ignores {@link fade} — the
+     * demo's texture-panel cursors among them — never points at a row this
+     * instance is not sampling.
+     */
+    fadeRow: number;
+    /**
+     * How much of {@link fadeRow} is still showing: `1` at the moment of the
+     * write, falling to `0` across `fadeDuration`, and `0` for an instance that
+     * is not fading. The decode mixes the sampled clip toward the frozen pose by
+     * exactly this weight — the weight of the fade, not the fade itself, which is
+     * the pose-freeze fade `CONTEXT.md` names.
+     */
+    fadeWeight: number;
+}
+/**
+ * What the vertex shader computes, as a pure function of `(instance, time)` —
+ * the **one definition** of the playback semantics. Both decode paths
+ * transcribe it (`DECODE_PRELUDE` in src/webgl.ts, `vatDecode` in src/tsl.ts);
+ * neither invents it.
+ *
+ * It exists in TypeScript because the arithmetic is otherwise reachable only
+ * inside a GLSL string and a TSL node graph, neither of which CI can evaluate
+ * without a GPU — and because a caller scheduling what happens after a one-shot
+ * needs to ask the same question the shader answers.
+ *
+ * There is no accumulated state anywhere in here: an instance is written once,
+ * at the moment its animation changes, and every frame after that is this
+ * function of the shared clock.
+ */
+declare function resolveVATFrame(instance: VATInstance, time: number): VATFrame;
+/**
+ * What carries the pack to the shader: one `DataTexture`, three texels wide,
+ * one row per instance, read by the instance's *logical* index (ADR-0016).
+ *
+ * Held by the caller rather than hidden behind the geometry, because a
+ * `BufferGeometry` has nowhere to put a texture and a side channel — a
+ * `WeakMap`, or a `userData` the first `clone()` loses — would not say what
+ * {@link setVATInstance} writes into. `createVATMesh` hands one back on either
+ * decode path; build your own with {@link createVATPlaybackTexture} when you
+ * are assembling a crowd by hand.
+ */
+interface VATPlaybackTexture {
+    /**
+     * The texture both decode paths bind: `x = field`, `y = instance`, RGBA
+     * float, {@link PACK_WIDTH} texels wide.
+     */
+    texture: DataTexture;
+    /** Instances it carries — the rows of {@link texture}. */
+    count: number;
+}
+/**
+ * Write a crowd's instance playback into a new playback texture. Call once,
+ * before rendering, and bind the result into the decode — `createVATMesh` does
+ * both for you.
+ *
+ * The layout below is the shared contract, spelled once in {@link PACK_TEXELS}.
+ * Both decode paths read exactly these three texels of row `instanceIndex` —
+ * `DECODE_PRELUDE` in `src/webgl.ts` with `texelFetch`, `texturePlayback` in
+ * `src/tsl.ts` with `textureLoad`.
+ *
+ * | Texel            | r                   | g            | b             | a             |
+ * | ---------------- | ------------------- | ------------ | ------------- | ------------- |
+ * | `x = 0` clip     | clip start row      | clip frames  | clip fps      | speed         |
+ * | `x = 1` playback | start time          | loop mode    | repetitions   | end mode      |
+ * | `x = 2` fade     | from clip start row | from frames  | from phase    | fade duration |
+ *
+ * **A texture, not three instanced attributes.** An attribute with divisor 1 is
+ * indexed by the *drawn slot*, and the drawn slot stops being the instance the
+ * moment a renderer culls or sorts per instance — on a `BatchedMesh` every
+ * vertex would read element 0 and the whole crowd would play instance 0's clip
+ * (ADR-0016). A row keyed by the logical index is what three itself does for
+ * the same problem, in `_matricesTexture`.
+ *
+ * **Three texels, not thirteen floats.** The move to a texture touched no
+ * decode arithmetic, because the layout did not change with it: the pack was
+ * already three RGBA-shaped `vec4`s (ADR-0009). Published 1.x is the other
+ * story — five one-float attributes there, so a 1.x caller meets both changes
+ * at once.
+ *
+ * **`FloatType`, and it stays that way.** A `startTime` in seconds does not
+ * survive half precision — one second of resolution at 2 048 s — so a narrower
+ * encoding for the VAT textures does not reach this one.
+ *
+ * The policy fields, and the clip texel's speed, come from the instance where
+ * it names them and from the clip's baked defaults where it does not — resolved
+ * in the one place those tiers are spelled — and both decode paths read them as
+ * {@link resolveVATFrame} defines them. The fade texel is written as zeroes,
+ * which is what "not fading" is: a crowd being created has no pose to fade away
+ * from. Fades belong to {@link setVATInstance}, where an instance's animation
+ * changes and there is something to fade out of.
+ */
+declare function createVATPlaybackTexture(instances: VATInstance[]): VATPlaybackTexture;
+/**
+ * Change one instance's animation, after the crowd is built. The single write
+ * the whole event-driven half of this library is made of: an enemy hit at
+ * `t = 12.3s` becomes a dying enemy here, and the CPU does not touch it again.
+ *
+ * ```ts
+ * // the moment it is hit — and nothing per frame afterwards
+ * setVATInstance(playback, enemyId, {
+ *   clip: vat.clips[2],      // "once, clamped" came with the bake
+ *   startTime: time.value,
+ *   fadeDuration: 0.1,       // blend out of whatever it was doing
+ * })
+ * ```
+ *
+ * `playback` is the crowd's playback texture — `createVATMesh` hands it back
+ * beside the mesh and the clock — and `index` the instance's index in the array
+ * the crowd was built from, the same one `setMatrixAt` takes.
+ *
+ * Only that instance's row is marked for upload, so a crowd of a thousand costs
+ * one small write rather than a full re-upload. Everything else about the
+ * instance — its matrix, its clip's defaults — is untouched. On the TSL path
+ * the range is recorded and ignored: three's WebGPU backend re-uploads the
+ * whole image on `needsUpdate`, which is 48 bytes per instance once per frame
+ * in which anything changed (docs/usage.md says what that costs).
+ *
+ * Ask for a `fadeDuration` and the pose the instance is in *at `startTime`* is
+ * frozen and blended away over that many wall-clock seconds, so the change does
+ * not pop. It is a frozen pose and not a second playback: see
+ * {@link MAX_FADE_DURATION} for what that costs and how far it can be pushed.
+ * One pose, too — writing an instance that is *already* fading freezes the clip
+ * it had switched to and drops the older pose, because the pack holds one.
+ *
+ * A written instance is a pure function of the clock from here on, so what
+ * happens *after* it is a matter of scheduling one more of these writes —
+ * {@link endsAt} says exactly when. Chaining stays yours: the GPU never learns
+ * about a next clip.
+ *
+ * This is deliberately a function over a playback texture rather than an
+ * `InstancedMesh` method. The primitives stay composable for a crowd rendered
+ * onto something else, which is the escape hatch ADR-0009 and ADR-0014 commit
+ * to — and the playback texture is the object such a caller holds (ADR-0016).
+ */
+declare function setVATInstance(playback: VATPlaybackTexture, index: number, instance: VATInstance): void;
+/**
+ * The exact clock time this instance stops animating — when
+ * {@link resolveVATFrame} first reports `finished` — or `null` for an animation
+ * that never gets there: an endless loop, or a speed of zero.
+ *
+ * This is what makes chaining one clip to the next a single scheduled write
+ * rather than a per-frame poll:
+ *
+ * ```ts
+ * const hit = { clip: vat.clips[1], startTime: now, loopMode: LoopMode.Once }
+ * setVATInstance(playback, id, hit)
+ *
+ * const at = endsAt(hit)
+ * if (at !== null) schedule(at, () => setVATInstance(playback, id, { clip: walk, startTime: at }))
+ * ```
+ *
+ * Nothing about the chain reaches the GPU: it reads one pack, and the next clip
+ * does not exist to it until that write happens.
+ */
+declare function endsAt(instance: VATInstance): number | null;
+
+/**
+ * The playback policy a clip carries for every instance that plays it —
+ * declared once, at the bake, instead of repeated at every instance. Hand
+ * `bakeVAT` a configured `AnimationAction` rather than a bare `AnimationClip`
+ * and these come from it; hand it a clip and they are the library defaults
+ * (repeat, forever, speed 1, clamping when finished).
+ *
+ * Defaults, never decisions: an instance overrides any of them, field by field
+ * ({@link VATInstance}). Nothing in the texels changes between "once" and
+ * "forever" — a bake produces poses, and this is the policy those poses are
+ * played under.
+ */
+interface VATClipDefaults {
+    /** How the clip repeats, from the action's `loop`. */
+    loopMode: LoopMode;
+    /**
+     * How many times it plays, from the action's `repetitions` — `Infinity`
+     * converted to `INFINITE_REPETITIONS`, because a `Float32Array` cannot carry
+     * the former.
+     */
+    repetitions: number;
+    /**
+     * What it does once finished — {@link EndMode.Clamp} from the bake, whichever
+     * of the two inputs it came from.
+     *
+     * three defaults `clampWhenFinished` to `false`, and a crowd's answer to a
+     * one-shot is to hold the last frame: a corpse standing back up is the worse
+     * default to ship (see {@link EndMode}). A bare `AnimationClip` says nothing,
+     * and an untouched action's `false` is not a statement either — it is what
+     * the field already holds — so the bake gives both the same answer rather
+     * than punishing the caller who configured an action. `clampWhenFinished =
+     * true` agrees with it; three's rewind is asked for per instance, with
+     * `endMode: EndMode.Rewind` (ADR-0017).
+     */
+    endMode: EndMode;
+    /**
+     * Playback rate, from the action's `timeScale`. `>= 0`: a band is sampled
+     * forward from its own first row, so a negative rate is refused at the bake
+     * rather than held on that row for ever. `0` is a held first row, on purpose.
+     */
+    speed: number;
+}
+/**
+ * One baked animation range within a VAT's stacked frame rows, and the playback
+ * defaults every instance of it inherits.
+ */
+interface VATClip extends VATClipDefaults {
+    /** 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 displacement (metres) of any vertex from the rest pose across the
+     * clip — the same number under either encoding, because the rig bake skins
+     * every vertex on the CPU for the bounds anyway and measures it there.
+     * 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 `DataTexture` (and the normal
+ * one, unless the bake was told to skip it), 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.
+ *
+ * The typed array behind either texture's `image.data` is the bake's choice,
+ * not part of this contract: `Float32Array` today, and a narrower encoding may
+ * change it in a minor release. Move the buffer, hand it to {@link makeVATTexture};
+ * do not read numbers out of it.
+ */
+interface VATBase {
+    /**
+     * Merged rest-pose geometry, in whichever space the encoding stores it: root
+     * space under the vertex encoding, where its `position` is the delta
+     * reference; each part's own local space under the rig encoding, where the
+     * slot carries the placement and also keeps `skinIndex` and `skinWeight`.
+     * Carries `normal` always, and `uv`, `color` and `tangent` when every source
+     * mesh carried them.
+     */
+    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;
+}
+/**
+ * A VAT under the **vertex encoding**: a row holds where every vertex ended up,
+ * as a position delta and, unless the bake was told to skip it, a normal. The
+ * source-agnostic encoding (ADR-0008) and the default; the member every bake
+ * produced before there was a second one (ADR-0018).
+ */
+interface DeltaVAT extends VATBase {
+    /** Which encoding a row holds — the discriminant of {@link VAT}. */
+    encoding: 'delta';
+    /** 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`),
+     * or `null` when the bake was told to skip it (`bakeNormals: false`) — halving
+     * the VAT for a crowd that never reads a normal. Neither decode path samples
+     * it when it is absent; a smooth-shaded lit material paired with such a VAT is
+     * refused rather than lit by its rest pose.
+     */
+    normalTexture: DataTexture | null;
+}
+/**
+ * A VAT under the **rig encoding** (ADR-0018): a row holds the posed rig — one
+ * **slot** per bone, as a rotation, a translation and a uniform scale — and the
+ * vertex shader skins the rest-pose geometry from it. Two orders of magnitude
+ * smaller than the vertex encoding and bake-cheap, at the price of source
+ * agnosticism: what a rig cannot express is refused at the bake.
+ *
+ * No normal texture, and none missing: normals and tangents come out of the
+ * skin matrix, as in three's own skinning.
+ */
+interface RigVAT extends VATBase {
+    /** Which encoding a row holds — the discriminant of {@link VAT}. */
+    encoding: 'rig';
+    /**
+     * RGBA float **rig texture**: two texels per slot — `(qx, qy, qz, qw)` then
+     * `(tx, ty, tz, s)` — laid out as `x = slot × 2 + texel`, `y = frame`, clips
+     * stacked as bands exactly as in the position texture. Consecutive rows of
+     * one slot sit on one quaternion hemisphere; the decode still flips the
+     * second row onto the first's side, because a looping clip blends a band's
+     * last row into its first and those are not neighbours.
+     */
+    rigTexture: DataTexture;
+    /** Slots in the rig — the texture is `slotCount × 2` texels wide. */
+    slotCount: number;
+}
+/**
+ * A baked VAT, discriminated on `encoding`. A decode that samples a texture
+ * narrows on `encoding` first, so an encoding it does not decode is refused by
+ * name rather than sampled as a texture the VAT does not have (ADR-0018).
+ */
+type VAT = DeltaVAT | RigVAT;
+/**
+ * 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;
+    /**
+     * The crowd's **playback texture**: what carries each instance's clip, phase
+     * and policy to the shader, and what `setVATInstance` writes one row of
+     * (ADR-0016). Exposed rather than hidden behind the mesh because it is the
+     * object a caller has to hold to change an instance after the crowd is
+     * built — a `BufferGeometry` cannot carry a texture, so there is nowhere
+     * else honest to keep it.
+     */
+    playback: VATPlaybackTexture;
+}
+
+/**
+ * A mesh a VAT crowd can ride.
+ *
+ * `InstancedMesh` is what `createVATMesh` builds on either path.
+ * `BatchedMesh` is reached through the primitives, and buys per-instance
+ * frustum culling and depth sorting from three.js itself — see
+ * docs/usage.md, which also says what it does *not* buy.
+ */
+type VATCarrier = InstancedMesh | BatchedMesh;
+
+export { type DeltaVAT as D, EndMode as E, INFINITE_REPETITIONS as I, LoopMode as L, MAX_FADE_DURATION as M, type RigVAT as R, type VAT as V, type VATBase as a, type VATCarrier as b, type VATClip as c, type VATClipDefaults as d, type VATClock as e, type VATCrowd as f, type VATFadeFrom as g, type VATFrame as h, type VATInstance as i, type VATPlaybackTexture as j, createVATPlaybackTexture as k, endsAt as l, resolveVATFrame as r, setVATInstance as s };