three-vat 2.0.0 → 3.0.0

package/README.md

@@ -81,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>
 
@@ -143,7 +148,7 @@ is [the CHANGELOG's 2.0.0 entry](./CHANGELOG.md).
 ```
 
 `timeOffset` is gone (`startTime: -timeOffset / speed`), and with it
-`aTimeOffset`. The pack is three `vec4`s — clip, playback, fade — in a
+`aTimeOffset`. The pack became 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)`
@@ -179,9 +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 (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
+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
 trade-offs against `SkinnedMesh` and bone-texture instancing.

package/dist/{carrier-BFCPmcQK.d.ts → carrier-BxRuW47G.d.ts}

@@ -40,44 +40,20 @@ type EndMode = (typeof EndMode)[keyof typeof EndMode];
  */
 declare const INFINITE_REPETITIONS = -1;
 /**
- * The longest fade {@link setVATInstance} will honour, in seconds.
+ * One clip playing: which band, from when, how fast and under what policy.
  *
- * 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.
+ * The unit the pack carries twice — as the animation an instance is playing,
+ * and as the one it is blending out of ({@link VATInstance.from}). Both are
+ * resolved by {@link resolveVATFrame} through the very same arithmetic, which
+ * is the whole difference between a crossfade and the pose freeze it replaced
+ * (ADR-0025): the outgoing half is a clip still *playing*, not a photograph.
  *
  * 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
+ * ({@link VATClipDefaults}), and a state that says nothing inherits it. A
  * crowd of a thousand deaths says "once, clamped" once, at the bake.
  */
-interface VATInstance {
+interface VATPlaybackState {
     /**
      * 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
@@ -119,19 +95,33 @@ interface VATInstance {
      * `false`; see {@link EndMode}.
      */
     endMode?: EndMode;
+}
+/**
+ * Per-instance playback state consumed by both decode paths: the clip this
+ * instance is playing, and — while it is transitioning — the one it is
+ * crossfading out of.
+ */
+interface VATInstance extends VATPlaybackState {
     /**
-     * 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}.
+     * The outgoing playback state to blend away from: a clip *still playing*, in
+     * every respect an instance except that it carries no transition of its own.
+     *
+     * Normally you do not write this yourself — {@link setVATInstance} reads the
+     * instance's current pack back, whole, and fills it in when you ask for a
+     * {@link fadeDuration}. Write it by hand when you are assembling a crowd the
+     * library does not build for you; what you pass is what is written.
      */
-    from?: VATFadeFrom;
+    from?: VATPlaybackState;
     /**
-     * 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.
+     * Seconds to blend {@link from} away over. Uncapped, and wall-clock seconds
+     * from {@link startTime}: the incoming clip's `speed` does not stretch a
+     * transition.
      *
-     * 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.
+     * Zero, or absent, is a cut: no outgoing band is written. A negative or
+     * non-finite duration is refused when the instance is written.
+     *
+     * Ignored without a `from` to blend away from — and at creation there is
+     * nothing to blend away from, so this is `setVATInstance`'s field in practice.
      */
     fadeDuration?: number;
 }
@@ -159,26 +149,39 @@ interface VATFrame {
     /** 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.
+     * The band this instance is blending out of, resolved at the same moment —
+     * or `null` when it is not transitioning, which is almost always. Not a
+     * weight of zero, so a reader with no interest in transitions ignores one
+     * field rather than testing one.
      */
-    fadeRow: number;
+    outgoing: VATOutgoingFrame | null;
+}
+/**
+ * The outgoing half of a crossfade: the very frame the outgoing clip would be
+ * showing if nothing had interrupted it, and how much of it is still showing.
+ *
+ * It is a {@link VATFrame} because it is one — resolved by
+ * {@link resolveVATFrame} from the outgoing playback state, through the same
+ * arithmetic, so an outgoing one-shot that runs out mid-transition clamps
+ * exactly as it would have. Its own `outgoing` is always `null`: the pack holds
+ * two bands, and the recursion is one level deep.
+ */
+interface VATOutgoingFrame extends VATFrame {
     /**
-     * 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.
+     * How much of this band is still showing: `1` at the moment of the write,
+     * falling to `0` across `fadeDuration`, and `0` once the transition is over.
+     * Wall clock — `1 - clamp((time - startTime) / fadeDuration, 0, 1)` — so a
+     * half-speed incoming clip does not stretch the transition.
      */
-    fadeWeight: number;
+    weight: 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.
+ * transcribe it — its band half in `vatBand` (src/webgl.ts) and `resolveBand`
+ * (src/tsl.ts), one function of a clip and playback texel pair, *called twice*
+ * where an instance is transitioning; its crossfade weight beside the call, in
+ * `vatRows` and `vatDecode` — and 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
@@ -191,7 +194,7 @@ interface VATFrame {
  */
 declare function resolveVATFrame(instance: VATInstance, time: number): VATFrame;
 /**
- * What carries the pack to the shader: one `DataTexture`, three texels wide,
+ * What carries the pack to the shader: one `DataTexture`, five 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
@@ -207,24 +210,56 @@ interface VATPlaybackTexture {
      * float, {@link PACK_WIDTH} texels wide.
      */
     texture: DataTexture;
-    /** Instances it carries — the rows of {@link texture}. */
+    /**
+     * Rows of {@link texture} — the crowd's **capacity**, which is what the
+     * decode indexes and what {@link setVATInstance} bounds-checks against.
+     *
+     * Not a live population: for a crowd that spawns and dies, most of these
+     * rows may be reserved and empty at any moment, and the library has no
+     * notion of which (ADR-0022). The caller owns the indices, because the
+     * carrier already hands that numbering out.
+     */
     count: number;
 }
+/**
+ * How a playback texture is sized when the instances it is handed are not the
+ * whole story.
+ */
+interface VATPlaybackTextureOptions {
+    /**
+     * Rows to reserve — the crowd's ceiling, rather than its current population.
+     * Defaults to the number of instances given, which is a crowd placed once.
+     *
+     * At least that many, and at most `MAX_TEXTURE_SIZE`; both are refused by
+     * name. Fixed once the texture is made (ADR-0022): a texture does not grow
+     * in place, and growing one means rebuilding it and rebinding it on every
+     * patched material — `docs/usage.md` carries that recipe.
+     */
+    capacity?: 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`.
+ * Both decode paths read exactly these texels of row `instanceIndex` —
+ * `ROW_PRELUDE` in `src/webgl.ts` with `texelFetch`, `texturePlayback` in
+ * `src/tsl.ts` with `textureLoad` — the first three always, the last two only
+ * while a transition is running.
  *
- * | 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 |
+ * | 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` crossfade         | fade duration  | 0           | 0           | 0        |
+ * | `x = 3` outgoing clip     | clip start row | clip frames | clip fps    | speed    |
+ * | `x = 4` outgoing playback | start time     | loop mode   | repetitions | end mode |
+ *
+ * The outgoing pair is a full playback state — the same two texels, in the same
+ * order, with the same meaning — because that is the whole difference between a
+ * freeze and a crossfade (ADR-0025). The crossfade texel's three spare
+ * components are written as zero and read by nothing.
  *
  * **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
@@ -233,25 +268,35 @@ interface VATPlaybackTexture {
  * (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
+ * **RGBA-shaped texels, not loose 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.
+ * already 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.
+ * survive half precision — one second of resolution at 2 048 s — and there are
+ * now two of them per row, 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.
+ * {@link resolveVATFrame} defines them. The crossfade texel and the outgoing
+ * pair are written as zeroes, which is what "not transitioning" is: a crowd
+ * being created has no animation to blend away from. Transitions belong to
+ * {@link setVATInstance}, where an instance's animation changes and there is
+ * something to blend out of.
+ *
+ * **A crowd that spawns and dies gives a capacity** instead of a census
+ * ({@link VATPlaybackTextureOptions}, ADR-0022): the rows are reserved once,
+ * from the ceiling, and filled with {@link setVATInstance} as instances appear.
+ * The list may then be empty — a level that starts with nothing alive in it —
+ * and the reserved rows hold a first frame, held. The library allocates no
+ * indices and follows no `setInstanceCount`: the carrier already numbers the
+ * instances, and a texture does not grow in place. `docs/usage.md` carries both,
+ * with **row recycling** — the hazard of reusing a row an instance has died on.
  */
-declare function createVATPlaybackTexture(instances: VATInstance[]): VATPlaybackTexture;
+declare function createVATPlaybackTexture(instances: VATInstance[], options?: VATPlaybackTextureOptions): 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
@@ -274,15 +319,21 @@ declare function createVATPlaybackTexture(instances: VATInstance[]): VATPlayback
  * 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
+ * whole image on `needsUpdate`, which is 80 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.
+ * Ask for a `fadeDuration` and the animation the instance was playing **keeps
+ * playing**, blended away over that many wall-clock seconds from `startTime`,
+ * so the change is a transition rather than a pop (ADR-0025). Uncapped: a tenth
+ * of a second for a death, half a second for a walk into a run, and both clips
+ * move throughout. Zero, or none at all, is a cut.
+ *
+ * Two bands, and no more. Writing an instance that is *already* mid-transition
+ * replaces the outgoing band with the one it was switching to and drops the
+ * older band at whatever weight it still had — a pop proportional to how early
+ * the interruption came, and the one visible discontinuity a caller can
+ * produce. `startTime + fadeDuration` is when the transition ends, for a caller
+ * who would rather wait it out.
  *
  * 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 —
@@ -374,7 +425,9 @@ interface VATClip extends VATClipDefaults {
     /** Source clip duration in seconds. */
     duration: number;
     /**
-     * Largest per-vertex position-delta magnitude (metres) across the clip.
+     * 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.
      */
@@ -396,22 +449,14 @@ interface VATClip extends VATClipDefaults {
  * change it in a minor release. Move the buffer, hand it to {@link makeVATTexture};
  * do not read numbers out of it.
  */
-interface VAT {
-    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
-    positionTexture: DataTexture;
-    /**
-     * RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`),
-     * 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;
+interface VATBase {
     /**
-     * Merged, root-space rest-pose geometry. Its `position` is the delta
-     * reference. Carries `normal` always, and `uv`, `color` and `tangent` when
-     * every source mesh carried them; skinning attributes and morph targets are
-     * dropped, the VAT having replaced them.
+     * 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`. */
@@ -424,9 +469,58 @@ interface VAT {
     vertexCount: number;
     /** Total frame rows across all clips (texture height). */
     totalFrames: number;
-    /** Position encoding. Only `'delta'` in v1. */
+}
+/**
+ * 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
@@ -469,4 +563,4 @@ interface VATCrowd {
  */
 type VATCarrier = InstancedMesh | BatchedMesh;
 
-export { EndMode as E, INFINITE_REPETITIONS as I, LoopMode as L, MAX_FADE_DURATION as M, type VAT as V, type VATCarrier as a, type VATClip as b, type VATClipDefaults as c, type VATClock as d, type VATCrowd as e, type VATFadeFrom as f, type VATFrame as g, type VATInstance as h, type VATPlaybackTexture as i, createVATPlaybackTexture as j, endsAt as k, resolveVATFrame as r, setVATInstance as s };
+export { type DeltaVAT as D, EndMode as E, INFINITE_REPETITIONS as I, LoopMode as L, 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 VATFrame as g, type VATInstance as h, type VATOutgoingFrame as i, type VATPlaybackState as j, type VATPlaybackTexture as k, type VATPlaybackTextureOptions as l, createVATPlaybackTexture as m, endsAt as n, resolveVATFrame as r, setVATInstance as s };

package/dist/{chunk-W2ZAFMPB.js → chunk-I4STYOD5.js}

@@ -13,7 +13,7 @@ function needsBakedNormal(material) {
   return NORMAL_READING_FLAGS.some((flag) => flags[flag] === true);
 }
 function assertBakedNormal(vat, material) {
-  if (vat.normalTexture !== null || !needsBakedNormal(material)) return;
+  if (vat.encoding !== "delta" || vat.normalTexture !== null || !needsBakedNormal(material)) return;
   throw new Error(
     `three-vat: material "${material.name || "(unnamed)"}" (${material.type}) shades from a normal, but this VAT was baked with \`bakeNormals: false\` and carries none \u2014 the crowd would be lit by its rest pose. Set \`flatShading: true\` on the material (three then derives the normal from the deformed position, per fragment, which is the right normal for a posed mesh), or use an unlit material such as MeshBasicMaterial, or bake with \`bakeNormals: true\`.`
   );