three-vat 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,13 @@
 # three-vat
 
+[![npm version](https://img.shields.io/npm/v/three-vat.svg)](https://www.npmjs.com/package/three-vat)
+[![license: MIT](https://img.shields.io/npm/l/three-vat.svg)](./LICENSE)
+
 Bake a glTF `AnimationClip` into GPU textures and animate **hundreds or thousands of instanced characters with zero per-frame CPU** — one draw call, no `SkinnedMesh` per character.
 
-VAT (Vertex Animation Texture) is battle-tested in Unity/Unreal but has been a gap on the three.js side: only scattered demos, no maintained package, nothing in drei. `three-vat` bakes the VAT **at runtime, directly from the glTF** — so any Mixamo/Sketchfab asset works with zero pipeline — with an optional offline path that produces the identical texture.
+VAT (Vertex Animation Texture) is battle-tested in Unity/Unreal but has been a gap on the three.js side: only scattered demos, no maintained package, nothing in drei. `three-vat` bakes the VAT **at runtime, directly from the glTF** — so any Mixamo/Sketchfab asset works with zero pipeline, and there is exactly one way to produce a VAT.
 
-> **Status: v1 / pre-release.** The baker core and WebGL decode are ported from a browser-validated prototype. The TSL path is present but verified visually, not yet by automated tests. See [`docs/DESIGN.md`](./docs/DESIGN.md) and [`docs/adr/`](./docs/adr) for the full rationale.
+> **Status: early release — `0.3.0`, published on npm.** The baker core (skinning, morph targets **and** rigid node-animated subtrees) and WebGL decode are covered by tests. The TSL/WebGPU path ships but is verified visually, not yet by automated tests. See [`docs/DESIGN.md`](./docs/DESIGN.md) and [`docs/adr/`](./docs/adr) for the full rationale, and [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
 
 ## Install
 
@@ -19,10 +22,28 @@ npm install three-vat three
 ```ts
 import { bakeVAT } from 'three-vat'
 
-// gltf loaded via GLTFLoader; sourceMesh is the SkinnedMesh in it.
+// gltf loaded via GLTFLoader — pass the subtree root, not a mesh.
 const clips = gltf.animations.filter((c) => c.name !== 'TPose')
-const vat = bakeVAT(gltf.scene, sourceMesh, clips, { fps: 30 })
-// vat: { positionTexture, normalTexture, clips, bounds, vertexCount, totalFrames, encoding }
+const vat = bakeVAT(gltf.scene, clips, { fps: 30 })
+// vat: { positionTexture, normalTexture, geometry, materials, clips, bounds, ... }
+```
+
+The bake unit is the **whole subtree**, merged into one vertex set and recorded in root space ([ADR-0008](./docs/adr/0008-a-vat-bakes-a-posed-subtree-not-a-skinnedmesh.md)). A VAT only records *where a vertex ended up*, never how it got there, so one call handles a single `SkinnedMesh`, a morph-target mesh, a hierarchy of rigid node-animated parts (three.js `RobotExpressive`), or any mix — with no classification by the caller.
+
+Two consequences worth knowing up front:
+
+- **Render `vat.geometry`, not your source mesh.** The merged vertex ordering is the baker's, and the textures are indexed by it.
+- **Materials are never merged.** `vat.materials` lines up with `vat.geometry.groups`, giving one draw call per material. VAT collapses *instance* count, not *material* count — a 500-robot crowd with 3 materials is 3 draw calls, not 1 and not 500.
+
+The VAT is a flat `vertexCount` × `totalFrames` texture pair, so **both** axes are bounded by the GPU's max texture dimension. The baker is renderer-agnostic and defaults to a conservative `16384`; pass the real limit whenever you have a renderer, or a bake that allocates on desktop can fail on mobile (commonly 4096–8192):
+
+```ts
+import { getMaxTextureSize } from 'three-vat/webgl' // or 'three-vat/tsl'
+
+const vat = bakeVAT(gltf.scene, clips, {
+  fps: 30,
+  maxTextureSize: getMaxTextureSize(renderer),
+})
 ```
 
 ## Render a crowd — WebGL (`WebGLRenderer`)
@@ -32,15 +53,19 @@ import { addInstancedVATAttributes, createVATUniforms, createVATDepthMaterial, p
 
 const uniforms = createVATUniforms()
 
-const geometry = sourceMesh.geometry.clone()
+// vat.geometry already carries the all-frames bounding box/sphere, so instances
+// never cull mid-animation.
+const geometry = vat.geometry.clone()
 addInstancedVATAttributes(geometry, instances) // instances: { clip, timeOffset, speed }[]
-geometry.boundingBox = vat.bounds.clone()       // union of all frames — avoids culling pops
-geometry.boundingSphere = vat.bounds.getBoundingSphere(new THREE.Sphere())
 
-const material = sourceMesh.material.clone()
-patchVATMaterial(material, vat, uniforms)
+// One patched material per source material, sharing one clock.
+const materials = vat.materials.map((source) => {
+  const material = source.clone()
+  patchVATMaterial(material, vat, uniforms)
+  return material
+})
 
-const mesh = new THREE.InstancedMesh(geometry, material, instances.length)
+const mesh = new THREE.InstancedMesh(geometry, materials, instances.length)
 mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms) // correct instanced shadows
 mesh.castShadow = mesh.receiveShadow = true
 
@@ -65,17 +90,21 @@ time.value = clock.elapsedTime
 
 Shadows just work on the TSL path (`positionNode` feeds the depth pass). v1 plays one clip per material with per-instance phase desync; use the WebGL path for mixed-clip crowds.
 
-## Offline (bake once, ship the texture)
+## Offline format — deprecated, removed in 1.0
 
-```ts
-import { serializeVAT, loadVAT } from 'three-vat'
+> **Do not use `serializeVAT` / `loadVAT`.** They still ship in `0.3.0` for
+> compatibility and are removed in `1.0`
+> ([ADR-0010](./docs/adr/0010-drop-the-offline-format-runtime-bake-is-the-library.md)).
 
-const { manifest, position, normal } = serializeVAT(vat, { precision: 'float16' })
-// write manifest as JSON, position/normal as .bin — then later:
-const vat = loadVAT({ manifest, position, normal })
-```
+The format stores the texel buffers and a manifest, but *not* the geometry. Since
+`0.3.0` a bake merges the whole subtree into a new vertex set and the textures are
+indexed by that ordering, so a serialized VAT can only be rendered by reloading the
+source glTF and re-running the merge — the work the file existed to save. A VAT
+restored by `loadVAT` has no `geometry` or `materials`, so it is **not**
+interchangeable with a freshly-baked one, whatever earlier releases claimed.
 
-The canonical format is a raw Float16 `.bin` + versioned JSON manifest (KTX2 rejected as default — its GPU compression doesn't apply to float data). The loaded VAT is interchangeable with a freshly-baked one.
+Bake at runtime instead. The baker is pure CPU and touches no renderer, so if bake
+time hurts on load, run `bakeVAT` in a Web Worker and transfer the texel buffers back.
 
 ## Trade-offs
 
@@ -90,7 +119,7 @@ pnpm install
 pnpm test        # baker core — pure CPU, no GPU needed
 pnpm typecheck
 pnpm build
-pnpm example     # runs the crowd demo in examples/ (needs a Soldier.glb)
+pnpm example     # runs the robot-crowd demo in examples/ (model bundled)
 ```
 
 ## License

package/dist/index.d.ts

@@ -1,19 +1,42 @@
-import { Object3D, SkinnedMesh, AnimationClip, TypedArray, TextureDataType, DataTexture } from 'three';
-import { V as VAT, a as VATClip } from './types-DVtQvVjk.js';
+import { Object3D, AnimationClip, TypedArray, TextureDataType, DataTexture } from 'three';
+import { B as BakedVAT, V as VATClip, a as VAT } from './types-wVmIj2tC.js';
 
-/** Maximum texture dimension we support; `vertexCount` must not exceed it. */
+/**
+ * Conservative fallback texture-dimension cap, used when the caller does not
+ * pass `maxTextureSize`. This is the WebGL2 *spec floor for high-end desktop*,
+ * not a guarantee — plenty of mobile GPUs report 4096 or 8192. The baker is
+ * renderer-agnostic by design (it runs in Node, and in a Web Worker), so it cannot
+ * query the real limit itself: pass `getMaxTextureSize(renderer)` from
+ * `three-vat/webgl` or `three-vat/tsl` whenever a renderer exists.
+ */
 declare const MAX_TEXTURE_SIZE = 16384;
 interface BakeOptions {
     /** Sample rate in frames per second. Default `30`. */
     fps?: number;
+    /**
+     * Largest texture dimension the target GPU accepts. Both VAT axes are checked
+     * against it: `vertexCount` (width) and `totalFrames` (height). Defaults to
+     * {@link MAX_TEXTURE_SIZE}; pass the renderer's real limit to avoid baking a
+     * VAT that allocates on your desktop and fails on a phone.
+     */
+    maxTextureSize?: number;
 }
 /**
- * Bake skinned `AnimationClip`s into a VAT by sampling the posed mesh frame by
- * frame on the CPU. Positions are stored as deltas from the bind pose; normals
- * are stored absolute. Renderer-agnostic — touches no WebGL/WebGPU context — so
- * it runs identically at runtime and offline in Node.
+ * Bake `AnimationClip`s into a VAT by sampling the posed subtree frame by frame
+ * on the CPU.
+ *
+ * The unit of a bake is the whole subtree under `root`, merged into one vertex
+ * set and recorded in root space (ADR-0008) — so it handles a single
+ * `SkinnedMesh`, a morph-target mesh, a hierarchy of rigid node-animated parts
+ * (three.js `RobotExpressive`), or any mix of them, without the caller having
+ * to classify the asset. A VAT only records *where a vertex ended up*, never
+ * how it got there.
+ *
+ * Positions are stored as deltas from the merged rest pose; normals absolute.
+ * Renderer-agnostic — touches no WebGL/WebGPU context — so it runs identically
+ * at runtime, in a Web Worker, and in Node.
  */
-declare function bakeVAT(root: Object3D, skinnedMesh: SkinnedMesh, clips: AnimationClip[], { fps }?: BakeOptions): VAT;
+declare function bakeVAT(root: Object3D, clips: AnimationClip[], { fps, maxTextureSize }?: BakeOptions): BakedVAT;
 /**
  * Build a VAT `DataTexture` with the fixed sampling flags every path relies on:
  * RGBA, nearest filtering, no mipmaps. Frame interpolation is done manually in
@@ -55,12 +78,14 @@ interface SerializeOptions {
  * the on-disk format; the runtime object is always reconstructed with
  * {@link loadVAT}.
  */
+/** @deprecated Removed in 1.0 — see ADR-0010. Bake at runtime instead. */
 declare function serializeVAT(vat: VAT, { precision }?: SerializeOptions): SerializedVAT;
 /**
  * Reconstruct a runtime VAT from serialized buffers. `float16` uploads as
  * `HalfFloatType`; `float32` as `FloatType`. The result is interchangeable with
  * a {@link bakeVAT} result.
  */
+/** @deprecated Removed in 1.0 — see ADR-0010. Bake at runtime instead. */
 declare function loadVAT(serialized: SerializedVAT): VAT;
 
-export { type BakeOptions, MAX_TEXTURE_SIZE, type SerializeOptions, type SerializedVAT, VAT, VATClip, type VATManifest, type VATPrecision, bakeVAT, loadVAT, makeVATTexture, serializeVAT };
+export { type BakeOptions, BakedVAT, MAX_TEXTURE_SIZE, type SerializeOptions, type SerializedVAT, VAT, VATClip, type VATManifest, type VATPrecision, bakeVAT, loadVAT, makeVATTexture, serializeVAT };

package/dist/index.js

@@ -1,24 +1,151 @@
-import { FloatType, AnimationMixer, Box3, Vector4, Matrix4, Vector3, DataTexture, RGBAFormat, NearestFilter, DataUtils, HalfFloatType } from 'three';
+import { FloatType, Matrix4, AnimationMixer, Box3, Vector4, Vector3, Sphere, DataTexture, RGBAFormat, NearestFilter, DataUtils, HalfFloatType, BufferGeometry, BufferAttribute } from 'three';
 
 // src/bake.ts
 var MAX_TEXTURE_SIZE = 16384;
-function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
-  const geometry = skinnedMesh.geometry;
-  const vertexCount = geometry.attributes.position.count;
-  if (vertexCount > MAX_TEXTURE_SIZE) {
+function asAttribute(value, mesh, name) {
+  if (!(value instanceof BufferAttribute)) {
     throw new Error(
-      `three-vat: vertexCount ${vertexCount} exceeds MAX_TEXTURE_SIZE ${MAX_TEXTURE_SIZE}; row wrapping is not implemented`
+      `three-vat: mesh "${mesh.name || "(unnamed)"}" has an interleaved or unsupported "${name}" attribute; VAT bakes plain BufferAttributes`
+    );
+  }
+  return value;
+}
+function collectParts(root) {
+  const found = [];
+  root.traverse((o) => {
+    const mesh = o;
+    if (mesh.isMesh && mesh.geometry) found.push(mesh);
+  });
+  if (found.length === 0) {
+    throw new Error("three-vat: no Mesh found under root; nothing to bake");
+  }
+  const materials = [];
+  const parts = [];
+  for (const mesh of found) {
+    if (Array.isArray(mesh.material)) {
+      throw new Error(
+        `three-vat: mesh "${mesh.name || "(unnamed)"}" uses a material array; split it into one mesh per material before baking`
+      );
+    }
+    const geometry = mesh.geometry;
+    if (!geometry.attributes.normal) geometry.computeVertexNormals();
+    const material = mesh.material;
+    let materialIndex = materials.indexOf(material);
+    if (materialIndex === -1) materialIndex = materials.push(material) - 1;
+    const skinned = mesh;
+    parts.push({
+      mesh,
+      material,
+      materialIndex,
+      vertexStart: 0,
+      // assigned below, after material sorting
+      vertexCount: geometry.attributes.position.count,
+      basePos: asAttribute(geometry.attributes.position, mesh, "position"),
+      baseNrm: asAttribute(geometry.attributes.normal, mesh, "normal"),
+      isSkinned: !!geometry.attributes.skinWeight && !!skinned.skeleton,
+      skeleton: skinned.skeleton,
+      skinIndex: geometry.attributes.skinIndex,
+      skinWeight: geometry.attributes.skinWeight,
+      morphPos: geometry.morphAttributes.position,
+      morphRelative: geometry.morphTargetsRelative
+    });
+  }
+  parts.sort((a, b) => a.materialIndex - b.materialIndex);
+  let offset = 0;
+  for (const part of parts) {
+    part.vertexStart = offset;
+    offset += part.vertexCount;
+  }
+  return parts;
+}
+function mergeGeometry(parts, restMatrices, total) {
+  const position = new Float32Array(total * 3);
+  const normal = new Float32Array(total * 3);
+  const wantUV = parts.every((p) => !!p.mesh.geometry.attributes.uv);
+  const wantColor = parts.every((p) => !!p.mesh.geometry.attributes.color);
+  const uv = wantUV ? new Float32Array(total * 2) : null;
+  const color = wantColor ? new Float32Array(total * 3) : null;
+  const indices = [];
+  const groups = [];
+  const _v = new Vector3();
+  const _n = new Vector3();
+  parts.forEach((part, pi) => {
+    const m = restMatrices[pi];
+    const geometry = part.mesh.geometry;
+    const start = part.vertexStart;
+    const srcUV = uv ? asAttribute(geometry.attributes.uv, part.mesh, "uv") : null;
+    const srcColor = color ? asAttribute(geometry.attributes.color, part.mesh, "color") : null;
+    for (let v = 0; v < part.vertexCount; v++) {
+      _v.fromBufferAttribute(part.basePos, v).applyMatrix4(m);
+      _n.fromBufferAttribute(part.baseNrm, v).transformDirection(m);
+      const o3 = (start + v) * 3;
+      position[o3] = _v.x;
+      position[o3 + 1] = _v.y;
+      position[o3 + 2] = _v.z;
+      normal[o3] = _n.x;
+      normal[o3 + 1] = _n.y;
+      normal[o3 + 2] = _n.z;
+      if (uv && srcUV) {
+        uv[(start + v) * 2] = srcUV.getX(v);
+        uv[(start + v) * 2 + 1] = srcUV.getY(v);
+      }
+      if (color && srcColor) {
+        color[o3] = srcColor.getX(v);
+        color[o3 + 1] = srcColor.getY(v);
+        color[o3 + 2] = srcColor.getZ(v);
+      }
+    }
+    const groupStart = indices.length;
+    const index = geometry.index;
+    if (index) {
+      for (let i = 0; i < index.count; i++) indices.push(start + index.getX(i));
+    } else {
+      for (let v = 0; v < part.vertexCount; v++) indices.push(start + v);
+    }
+    const last = groups[groups.length - 1];
+    if (last && last.materialIndex === part.materialIndex) {
+      last.count += indices.length - groupStart;
+    } else {
+      groups.push({
+        start: groupStart,
+        count: indices.length - groupStart,
+        materialIndex: part.materialIndex
+      });
+    }
+  });
+  const merged = new BufferGeometry();
+  merged.setAttribute("position", new BufferAttribute(position, 3));
+  merged.setAttribute("normal", new BufferAttribute(normal, 3));
+  if (uv) merged.setAttribute("uv", new BufferAttribute(uv, 2));
+  if (color) merged.setAttribute("color", new BufferAttribute(color, 3));
+  merged.setIndex(indices);
+  for (const g of groups) merged.addGroup(g.start, g.count, g.materialIndex);
+  return merged;
+}
+function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } = {}) {
+  root.updateMatrixWorld(true);
+  const parts = collectParts(root);
+  const vertexCount = parts.reduce((n, p) => n + p.vertexCount, 0);
+  if (vertexCount > maxTextureSize) {
+    throw new Error(
+      `three-vat: vertexCount ${vertexCount} exceeds maxTextureSize ${maxTextureSize}; row wrapping is not implemented`
     );
   }
   const frameCounts = clips.map((c) => Math.max(2, Math.round(c.duration * fps)));
   const totalFrames = frameCounts.reduce((a, b) => a + b, 0);
+  if (totalFrames > maxTextureSize) {
+    throw new Error(
+      `three-vat: totalFrames ${totalFrames} exceeds maxTextureSize ${maxTextureSize}; lower fps or bake fewer clips`
+    );
+  }
+  const rootInverse = root.matrixWorld.clone().invert();
+  const restMatrices = parts.map(
+    (p) => new Matrix4().multiplyMatrices(rootInverse, p.mesh.matrixWorld)
+  );
+  const geometry = mergeGeometry(parts, restMatrices, vertexCount);
+  const mergedBase = geometry.attributes.position;
   const posData = new Float32Array(vertexCount * totalFrames * 4);
   const nrmData = new Float32Array(vertexCount * totalFrames * 4);
-  const basePos = geometry.attributes.position;
-  const baseNrm = geometry.attributes.normal;
-  const skinIndex = geometry.attributes.skinIndex;
-  const skinWeight = geometry.attributes.skinWeight;
-  const skeleton = skinnedMesh.skeleton;
   const mixer = new AnimationMixer(root);
   const bounds = new Box3();
   const clipTable = [];
@@ -27,9 +154,12 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
   const _bone = new Matrix4();
   const _acc = new Matrix4();
   const _skin = new Matrix4();
+  const _partMatrix = new Matrix4();
   const _p = new Vector3();
   const _bp = new Vector3();
   const _n = new Vector3();
+  const _mt = new Vector3();
+  const _mb = new Vector3();
   let rowOffset = 0;
   clips.forEach((clip, ci) => {
     const frames = frameCounts[ci];
@@ -40,37 +170,60 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
       mixer.setTime(f / frames * clip.duration);
       root.updateMatrixWorld(true);
       const row = rowOffset + f;
-      for (let v = 0; v < vertexCount; v++) {
-        _si.fromBufferAttribute(skinIndex, v);
-        _sw.fromBufferAttribute(skinWeight, v);
-        _acc.elements.fill(0);
-        for (let i = 0; i < 4; i++) {
-          const w = _sw.getComponent(i);
-          if (w === 0) continue;
-          const bi = _si.getComponent(i);
-          _bone.multiplyMatrices(skeleton.bones[bi].matrixWorld, skeleton.boneInverses[bi]);
-          const ae = _acc.elements;
-          const be = _bone.elements;
-          for (let e = 0; e < 16; e++) ae[e] += be[e] * w;
+      for (const part of parts) {
+        _partMatrix.multiplyMatrices(rootInverse, part.mesh.matrixWorld);
+        const influences = part.mesh.morphTargetInfluences;
+        const { morphPos, morphRelative, isSkinned, skeleton, skinIndex, skinWeight } = part;
+        for (let v = 0; v < part.vertexCount; v++) {
+          const vi = part.vertexStart + v;
+          _p.fromBufferAttribute(part.basePos, v);
+          _n.fromBufferAttribute(part.baseNrm, v);
+          if (morphPos && influences) {
+            if (!morphRelative) _mb.fromBufferAttribute(part.basePos, v);
+            for (let t = 0; t < morphPos.length; t++) {
+              const w = influences[t];
+              if (w === 0) continue;
+              _mt.fromBufferAttribute(morphPos[t], v);
+              if (!morphRelative) _mt.sub(_mb);
+              _p.addScaledVector(_mt, w);
+            }
+          }
+          if (isSkinned && skeleton) {
+            const skinned = part.mesh;
+            _si.fromBufferAttribute(skinIndex, v);
+            _sw.fromBufferAttribute(skinWeight, v);
+            _acc.elements.fill(0);
+            for (let i = 0; i < 4; i++) {
+              const w = _sw.getComponent(i);
+              if (w === 0) continue;
+              const bi = _si.getComponent(i);
+              _bone.multiplyMatrices(skeleton.bones[bi].matrixWorld, skeleton.boneInverses[bi]);
+              const ae = _acc.elements;
+              const be = _bone.elements;
+              for (let e = 0; e < 16; e++) ae[e] += be[e] * w;
+            }
+            _skin.multiplyMatrices(_acc, skinned.bindMatrix).premultiply(skinned.bindMatrixInverse);
+            _p.applyMatrix4(_skin);
+            _n.transformDirection(_skin);
+          }
+          _p.applyMatrix4(_partMatrix);
+          _n.transformDirection(_partMatrix);
+          bounds.expandByPoint(_p);
+          _bp.fromBufferAttribute(mergedBase, vi);
+          const o = (row * vertexCount + vi) * 4;
+          const dx = _p.x - _bp.x;
+          const dy = _p.y - _bp.y;
+          const dz = _p.z - _bp.z;
+          maxDeltaSq = Math.max(maxDeltaSq, dx * dx + dy * dy + dz * dz);
+          posData[o] = dx;
+          posData[o + 1] = dy;
+          posData[o + 2] = dz;
+          posData[o + 3] = 1;
+          nrmData[o] = _n.x;
+          nrmData[o + 1] = _n.y;
+          nrmData[o + 2] = _n.z;
+          nrmData[o + 3] = 1;
         }
-        _skin.multiplyMatrices(_acc, skinnedMesh.bindMatrix).premultiply(skinnedMesh.bindMatrixInverse);
-        _bp.fromBufferAttribute(basePos, v);
-        _p.copy(_bp).applyMatrix4(_skin);
-        bounds.expandByPoint(_p);
-        _n.fromBufferAttribute(baseNrm, v).transformDirection(_skin);
-        const o = (row * vertexCount + v) * 4;
-        const dx = _p.x - _bp.x;
-        const dy = _p.y - _bp.y;
-        const dz = _p.z - _bp.z;
-        maxDeltaSq = Math.max(maxDeltaSq, dx * dx + dy * dy + dz * dz);
-        posData[o] = dx;
-        posData[o + 1] = dy;
-        posData[o + 2] = dz;
-        posData[o + 3] = 1;
-        nrmData[o] = _n.x;
-        nrmData[o + 1] = _n.y;
-        nrmData[o + 2] = _n.z;
-        nrmData[o + 3] = 1;
       }
     }
     action.stop();
@@ -87,6 +240,10 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
   mixer.stopAllAction();
   mixer.setTime(0);
   root.updateMatrixWorld(true);
+  geometry.boundingBox = bounds.clone();
+  geometry.boundingSphere = bounds.getBoundingSphere(new Sphere());
+  const materials = [];
+  for (const part of parts) materials[part.materialIndex] = part.material;
   return {
     positionTexture: makeVATTexture(posData, vertexCount, totalFrames),
     normalTexture: makeVATTexture(nrmData, vertexCount, totalFrames),
@@ -94,7 +251,9 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
     bounds,
     vertexCount,
     totalFrames,
-    encoding: "delta"
+    encoding: "delta",
+    geometry,
+    materials
   };
 }
 function makeVATTexture(data, width, height, type = FloatType) {

package/dist/tsl.d.ts

@@ -1,7 +1,17 @@
 import { Node } from 'three/webgpu';
-import { V as VAT } from './types-DVtQvVjk.js';
+import { a as VAT } from './types-wVmIj2tC.js';
 import 'three';
 
+/**
+ * The real maximum texture dimension this renderer accepts, for
+ * `bakeVAT(..., { maxTextureSize })`. The baker is renderer-agnostic (it runs
+ * in Node, and in a Web Worker) so it cannot query this itself.
+ *
+ * Call this *after* `await renderer.init()` — the backend has no device before
+ * that. Handles both a WebGPU backend and the WebGL fallback backend a
+ * `WebGPURenderer` may silently switch to when WebGPU is unavailable.
+ */
+declare function getMaxTextureSize(renderer: object): number;
 /** A fluent TSL float node (has `.add`, `.mul`, … via NodeExtensions). */
 type FloatNode = Node<'float'>;
 /** A fluent TSL vec3 node. */
@@ -41,4 +51,4 @@ interface VATNodes {
  */
 declare function vatNodes(vat: VAT, options?: VATNodeOptions): VATNodes;
 
-export { type VATNodeOptions, type VATNodes, vatNodes };
+export { type VATNodeOptions, type VATNodes, getMaxTextureSize, vatNodes };

package/dist/tsl.js

@@ -1,6 +1,14 @@
 import { uniform, float, int, hash, instanceIndex, vertexIndex, positionLocal, textureLoad, ivec2, mix } from 'three/tsl';
 
 // src/tsl.ts
+function getMaxTextureSize(renderer) {
+  const backend = renderer.backend;
+  const device = backend?.["device"];
+  if (device?.limits?.maxTextureDimension2D) return device.limits.maxTextureDimension2D;
+  const gl = backend?.["gl"];
+  if (gl) return gl.getParameter(gl.MAX_TEXTURE_SIZE);
+  throw new Error("three-vat: renderer has no initialized backend \u2014 call `await renderer.init()` first");
+}
 function vatNodes(vat, options = {}) {
   const { time = uniform(0), clipIndex = 0, desync = 0 } = options;
   const clip = vat.clips[clipIndex];
@@ -27,4 +35,4 @@ function vatNodes(vat, options = {}) {
   };
 }
 
-export { vatNodes };
+export { getMaxTextureSize, vatNodes };

package/dist/{types-DVtQvVjk.d.ts → types-wVmIj2tC.d.ts}

@@ -1,4 +1,4 @@
-import { DataTexture, Box3 } from 'three';
+import { DataTexture, Box3, BufferGeometry, Material } from 'three';
 
 /** One baked animation range within a VAT's stacked frame rows. */
 interface VATClip {
@@ -41,5 +41,23 @@ interface VAT {
     /** Position encoding. Only `'delta'` in v1. */
     encoding: 'delta';
 }
+/**
+ * What {@link bakeVAT} returns: a VAT plus the geometry it was baked against.
+ *
+ * The merged vertex ordering is the baker's own invention and the textures are
+ * indexed by it (`x = gl_VertexID`), so the caller can no longer 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.
+ *
+ * `loadVAT` returns a plain {@link VAT} without these, which is precisely why the
+ * offline format is deprecated and removed in 1.0 (ADR-0010): a serialized VAT
+ * cannot be rendered without re-running the merge that produced its ordering.
+ */
+interface BakedVAT extends VAT {
+    /** Merged, root-space rest-pose geometry. Its `position` is the delta reference. */
+    geometry: BufferGeometry;
+    /** Source materials, indexed by `geometry.groups[].materialIndex`. */
+    materials: Material[];
+}
 
-export type { VAT as V, VATClip as a };
+export type { BakedVAT as B, VATClip as V, VAT as a };

package/dist/webgl.d.ts

@@ -1,6 +1,15 @@
-import { IUniform, BufferGeometry, MeshDepthMaterial, Material } from 'three';
-import { V as VAT } from './types-DVtQvVjk.js';
+import { IUniform, BufferGeometry, MeshDepthMaterial, WebGLRenderer, Material } from 'three';
+import { a as VAT } from './types-wVmIj2tC.js';
 
+/**
+ * The real maximum texture dimension this GPU accepts, for
+ * `bakeVAT(..., { maxTextureSize })`. The baker cannot query this itself — it
+ * is renderer-agnostic so it can run in Node or a Web Worker — so read it
+ * here and hand it over. Desktop typically reports 16384, but mobile GPUs
+ * commonly report 4096 or 8192, which is exactly the case a hardcoded default
+ * bakes straight past.
+ */
+declare function getMaxTextureSize(renderer: WebGLRenderer): number;
 /** The shared uniform driving every VAT-patched material's playback clock. */
 interface VATUniforms {
     uVatTime: IUniform<number>;
@@ -35,4 +44,4 @@ declare function patchVATMaterial<T extends Material>(material: T, vat: VAT, uni
  */
 declare function createVATDepthMaterial(vat: VAT, uniforms: VATUniforms): MeshDepthMaterial;
 
-export { type VATInstance, type VATUniforms, addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, patchVATMaterial };
+export { type VATInstance, type VATUniforms, addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, getMaxTextureSize, patchVATMaterial };

package/dist/webgl.js

@@ -1,10 +1,15 @@
 import { InstancedBufferAttribute, MeshDepthMaterial, RGBADepthPacking } from 'three';
 
 // src/webgl.ts
+function getMaxTextureSize(renderer) {
+  return renderer.capabilities.maxTextureSize;
+}
 function createVATUniforms(time = 0) {
   return { uVatTime: { value: time } };
 }
 function addInstancedVATAttributes(geometry, instances) {
+  geometry.morphAttributes = {};
+  geometry.morphTargetsRelative = false;
   const n = instances.length;
   const clipStart = new Float32Array(n);
   const clipFrames = new Float32Array(n);
@@ -78,4 +83,4 @@ function createVATDepthMaterial(vat, uniforms) {
   return depth;
 }
 
-export { addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, patchVATMaterial };
+export { addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, getMaxTextureSize, patchVATMaterial };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-vat",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
   "type": "module",
   "license": "MIT",
@@ -34,15 +34,6 @@
       "import": "./dist/tsl.js"
     }
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build",
-    "example": "pnpm --dir examples dev"
-  },
   "keywords": [
     "three",
     "threejs",
@@ -68,5 +59,15 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "release": "pnpm publish --otp=\"${NPM_OTP:?set NPM_OTP=<code from your authenticator>}\" && pnpm verify:published",
+    "verify:published": "node scripts/verify-published.mjs",
+    "example": "pnpm --dir examples dev"
   }
-}
+}