three-vat 2.0.0 → 2.1.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>
 

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

@@ -374,7 +374,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 +398,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 +418,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 +512,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, 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 };

package/dist/{chunk-2PGZ44TP.js → chunk-3PWAY6MD.js}

@@ -199,4 +199,13 @@ function endsAt(instance) {
   return instance.startTime + duration * repetitions / speed;
 }
 
-export { EndMode, FORWARD_ONLY_REASON, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_FADE_DURATION, MAX_TEXTURE_SIZE, PACK_TEXELS, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };
+// src/rig-texture.ts
+var RIG_TEXELS = {
+  /** `(qx, qy, qz, qw)` — the slot's rotation, on one hemisphere with its neighbouring rows. */
+  rotation: 0,
+  /** `(tx, ty, tz, s)` — where the slot puts the origin, and its uniform scale in the spare component. */
+  placement: 1
+};
+var RIG_TEXELS_PER_SLOT = 2;
+
+export { EndMode, FORWARD_ONLY_REASON, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_FADE_DURATION, MAX_TEXTURE_SIZE, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };

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\`.`
   );

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AnimationClip, AnimationAction, Object3D, TypedArray, TextureDataType, DataTexture } from 'three';
-import { V as VAT } from './carrier-BFCPmcQK.js';
-export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, M as MAX_FADE_DURATION, a as VATCarrier, b as VATClip, c as VATClipDefaults, d as VATClock, e as VATCrowd, f as VATFadeFrom, g as VATFrame, h as VATInstance, i as VATPlaybackTexture, j as createVATPlaybackTexture, k as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BFCPmcQK.js';
+import { D as DeltaVAT, R as RigVAT, V as VAT } from './carrier-BXaLAPRO.js';
+export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, M as MAX_FADE_DURATION, a as VATBase, b as VATCarrier, c as VATClip, d as VATClipDefaults, e as VATClock, f as VATCrowd, g as VATFadeFrom, h as VATFrame, i as VATInstance, j as VATPlaybackTexture, k as createVATPlaybackTexture, l as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BXaLAPRO.js';
 
 /**
  * What {@link bakeVAT} takes for each animation: the clip itself, or an
@@ -37,8 +37,29 @@ interface BakeOptions {
      * Anything else that shades — a smooth-shaded lit material — would light the
      * crowd by its rest-pose normals, which is visibly wrong (ADR-0002). Both
      * decode paths refuse that pairing loudly rather than render it.
+     *
+     * Accepted and ignored under the rig encoding, which has no normal texture to
+     * drop: normals come out of the skin matrix there. Refusing a no-op would
+     * punish the caller who switched encodings and left their options alone.
      */
     bakeNormals?: boolean;
+    /**
+     * What a frame row holds (ADR-0018). Default `'delta'`.
+     *
+     * - **`'delta'`** — the vertex encoding: where every vertex ended up, as a
+     *   position delta and a normal. Source-agnostic — skinning, morph targets
+     *   and node animation alike — and the default.
+     * - **`'rig'`** — the rig encoding: the posed rig, one **slot** per bone as a
+     *   rotation, a translation and a uniform scale, skinned in the vertex shader
+     *   from the rest-pose geometry. Two orders of magnitude smaller, no vertex
+     *   ceiling, and unable to store what a rig cannot express — refused at the
+     *   bake by name, before a frame is sampled: a morph target whose influence a
+     *   baked clip animates, or a bone (or rigid part) scaled unevenly. A morph
+     *   influence no clip animates is folded into the rest pose; a rigid,
+     *   node-animated part is one slot of weight one; parts reading the same
+     *   bones through the same bind matrix share slots.
+     */
+    encoding?: 'delta' | 'rig';
 }
 /**
  * Bake animations into a VAT by sampling the posed subtree frame by frame on
@@ -89,8 +110,22 @@ interface BakeOptions {
  * approximation becomes visible, so the bake warns once, naming the bone.
  * Renderer-agnostic — touches no WebGL/WebGPU context — so it runs identically
  * at runtime, in a Web Worker, and in Node.
+ *
+ * All of that is the **vertex encoding**, the default. `encoding: 'rig'`
+ * stores the posed rig instead — one slot per bone, two texels, skinned in the
+ * vertex shader from the rest-pose geometry (ADR-0018) — under the same clip
+ * table and the same playback contract, at a fraction of the memory; see
+ * {@link BakeOptions.encoding} for what it refuses. Overloaded on the option's
+ * literal, so a call that names no encoding, or the vertex encoding, still
+ * holds the narrow {@link DeltaVAT} it always did.
  */
-declare function bakeVAT(root: Object3D, animations: BakeInput[], { fps, maxTextureSize, bakeNormals }?: BakeOptions): VAT;
+declare function bakeVAT(root: Object3D, animations: BakeInput[], options?: BakeOptions & {
+    encoding?: 'delta';
+}): DeltaVAT;
+declare function bakeVAT(root: Object3D, animations: BakeInput[], options: BakeOptions & {
+    encoding: 'rig';
+}): RigVAT;
+declare function bakeVAT(root: Object3D, animations: BakeInput[], options?: BakeOptions): VAT;
 
 /**
  * The WebGL2 *spec floor for high-end desktop*, which two things lean on.
@@ -117,4 +152,4 @@ declare const MAX_TEXTURE_SIZE = 16384;
  */
 declare function makeVATTexture(data: TypedArray, width: number, height: number, type?: TextureDataType): DataTexture;
 
-export { type BakeInput, type BakeOptions, MAX_TEXTURE_SIZE, VAT, bakeVAT, makeVATTexture };
+export { type BakeInput, type BakeOptions, DeltaVAT, MAX_TEXTURE_SIZE, RigVAT, VAT, bakeVAT, makeVATTexture };