three-vat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# three-vat
+
+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.
+
+> **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.
+
+## Install
+
+```bash
+npm install three-vat three
+```
+
+`three` (>= 0.185) is a peer dependency.
+
+## Bake
+
+```ts
+import { bakeVAT } from 'three-vat'
+
+// gltf loaded via GLTFLoader; sourceMesh is the SkinnedMesh in it.
+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 }
+```
+
+## Render a crowd — WebGL (`WebGLRenderer`)
+
+```ts
+import { addInstancedVATAttributes, createVATUniforms, createVATDepthMaterial, patchVATMaterial } from 'three-vat/webgl'
+
+const uniforms = createVATUniforms()
+
+const geometry = sourceMesh.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)
+
+const mesh = new THREE.InstancedMesh(geometry, material, instances.length)
+mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms) // correct instanced shadows
+mesh.castShadow = mesh.receiveShadow = true
+
+// per frame:
+uniforms.uVatTime.value = clock.elapsedTime
+```
+
+## Render a crowd — TSL (`WebGPURenderer`)
+
+```ts
+import { MeshStandardNodeMaterial } from 'three/webgpu'
+import { vatNodes } from 'three-vat/tsl'
+
+const { positionNode, normalNode, time } = vatNodes(vat, { clipIndex: 0, desync: 10 })
+const material = new MeshStandardNodeMaterial()
+material.positionNode = positionNode
+material.normalNode = normalNode
+
+// per frame:
+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)
+
+```ts
+import { serializeVAT, loadVAT } from 'three-vat'
+
+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 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.
+
+## Trade-offs
+
+- **vs N × `SkinnedMesh`:** N draw calls + per-frame CPU skeletons → VAT is 1 draw call, zero per-frame CPU, 2 texel fetches per vertex. The headline.
+- **vs bone-texture instancing:** smaller textures and supports blending, but more fetches per vertex. VAT also captures morph/non-skeletal deformation for free.
+- **VAT limits:** no runtime IK/blending, discrete frames, memory cost (`verts × frames × 16 B × 2` textures). No clip crossfade in v1.
+
+## Development
+
+```bash
+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)
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import { Object3D, SkinnedMesh, AnimationClip, TypedArray, TextureDataType, DataTexture } from 'three';
+import { V as VAT, a as VATClip } from './types-DVtQvVjk.js';
+
+/** Maximum texture dimension we support; `vertexCount` must not exceed it. */
+declare const MAX_TEXTURE_SIZE = 16384;
+interface BakeOptions {
+    /** Sample rate in frames per second. Default `30`. */
+    fps?: 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.
+ */
+declare function bakeVAT(root: Object3D, skinnedMesh: SkinnedMesh, clips: AnimationClip[], { fps }?: BakeOptions): VAT;
+/**
+ * Build a VAT `DataTexture` with the fixed sampling flags every path relies on:
+ * RGBA, nearest filtering, no mipmaps. Frame interpolation is done manually in
+ * the shader, so linear filtering must stay off.
+ */
+declare function makeVATTexture(data: TypedArray, width: number, height: number, type?: TextureDataType): DataTexture;
+
+type VATPrecision = 'float16' | 'float32';
+/**
+ * The versioned descriptor of an offline-baked VAT. The manifest *is* the
+ * format — bump `version` on any breaking layout change.
+ */
+interface VATManifest {
+    version: 1;
+    vertexCount: number;
+    totalFrames: number;
+    encoding: 'delta';
+    precision: VATPrecision;
+    clips: VATClip[];
+    bounds: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+}
+/** A serialized VAT: manifest plus the two raw texel buffers. */
+interface SerializedVAT {
+    manifest: VATManifest;
+    /** Interleaved RGBA position deltas, `float16` or `float32` per `manifest.precision`. */
+    position: ArrayBuffer;
+    /** Interleaved RGBA absolute normals, same precision. */
+    normal: ArrayBuffer;
+}
+interface SerializeOptions {
+    /** On-disk texel precision. Default `'float16'` (half the bytes, uploads directly). */
+    precision?: VATPrecision;
+}
+/**
+ * Serialize a baked VAT to raw texel buffers + a versioned manifest. This is
+ * the on-disk format; the runtime object is always reconstructed with
+ * {@link loadVAT}.
+ */
+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.
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,154 @@
+import { FloatType, AnimationMixer, Box3, Vector4, Matrix4, Vector3, DataTexture, RGBAFormat, NearestFilter, DataUtils, HalfFloatType } 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) {
+    throw new Error(
+      `three-vat: vertexCount ${vertexCount} exceeds MAX_TEXTURE_SIZE ${MAX_TEXTURE_SIZE}; 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);
+  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 = [];
+  const _si = new Vector4();
+  const _sw = new Vector4();
+  const _bone = new Matrix4();
+  const _acc = new Matrix4();
+  const _skin = new Matrix4();
+  const _p = new Vector3();
+  const _bp = new Vector3();
+  const _n = new Vector3();
+  let rowOffset = 0;
+  clips.forEach((clip, ci) => {
+    const frames = frameCounts[ci];
+    const action = mixer.clipAction(clip);
+    action.play();
+    let maxDeltaSq = 0;
+    for (let f = 0; f < frames; f++) {
+      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;
+        }
+        _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();
+    clipTable.push({
+      name: clip.name,
+      startFrame: rowOffset,
+      frames,
+      fps: frames / clip.duration,
+      duration: clip.duration,
+      maxDelta: Math.sqrt(maxDeltaSq)
+    });
+    rowOffset += frames;
+  });
+  mixer.stopAllAction();
+  mixer.setTime(0);
+  root.updateMatrixWorld(true);
+  return {
+    positionTexture: makeVATTexture(posData, vertexCount, totalFrames),
+    normalTexture: makeVATTexture(nrmData, vertexCount, totalFrames),
+    clips: clipTable,
+    bounds,
+    vertexCount,
+    totalFrames,
+    encoding: "delta"
+  };
+}
+function makeVATTexture(data, width, height, type = FloatType) {
+  const tex = new DataTexture(data, width, height, RGBAFormat, type);
+  tex.minFilter = NearestFilter;
+  tex.magFilter = NearestFilter;
+  tex.generateMipmaps = false;
+  tex.needsUpdate = true;
+  return tex;
+}
+function serializeVAT(vat, { precision = "float16" } = {}) {
+  const pos = vat.positionTexture.image.data;
+  const nrm = vat.normalTexture.image.data;
+  const manifest = {
+    version: 1,
+    vertexCount: vat.vertexCount,
+    totalFrames: vat.totalFrames,
+    encoding: vat.encoding,
+    precision,
+    clips: vat.clips,
+    bounds: {
+      min: [vat.bounds.min.x, vat.bounds.min.y, vat.bounds.min.z],
+      max: [vat.bounds.max.x, vat.bounds.max.y, vat.bounds.max.z]
+    }
+  };
+  return { manifest, position: encode(pos, precision), normal: encode(nrm, precision) };
+}
+function encode(src, precision) {
+  if (precision === "float32") {
+    return src.slice().buffer;
+  }
+  const half = new Uint16Array(src.length);
+  for (let i = 0; i < src.length; i++) half[i] = DataUtils.toHalfFloat(src[i]);
+  return half.buffer;
+}
+function loadVAT(serialized) {
+  const { manifest, position, normal } = serialized;
+  const { vertexCount, totalFrames, precision } = manifest;
+  const type = precision === "float32" ? FloatType : HalfFloatType;
+  const posData = precision === "float32" ? new Float32Array(position) : new Uint16Array(position);
+  const nrmData = precision === "float32" ? new Float32Array(normal) : new Uint16Array(normal);
+  const bounds = new Box3(
+    new Vector3().fromArray(manifest.bounds.min),
+    new Vector3().fromArray(manifest.bounds.max)
+  );
+  return {
+    positionTexture: makeVATTexture(posData, vertexCount, totalFrames, type),
+    normalTexture: makeVATTexture(nrmData, vertexCount, totalFrames, type),
+    clips: manifest.clips,
+    bounds,
+    vertexCount,
+    totalFrames,
+    encoding: manifest.encoding
+  };
+}
+
+export { MAX_TEXTURE_SIZE, bakeVAT, loadVAT, makeVATTexture, serializeVAT };

package/dist/tsl.d.ts

@@ -0,0 +1,44 @@
+import { Node } from 'three/webgpu';
+import { V as VAT } from './types-DVtQvVjk.js';
+import 'three';
+
+/** A fluent TSL float node (has `.add`, `.mul`, … via NodeExtensions). */
+type FloatNode = Node<'float'>;
+/** A fluent TSL vec3 node. */
+type Vec3Node = Node<'vec3'>;
+interface VATNodeOptions {
+    /**
+     * Elapsed-time uniform node (seconds). Create once with `uniform(0)` and set
+     * `.value` per frame. Defaults to a fresh `uniform(0)` you can read back.
+     */
+    time?: FloatNode;
+    /** Which clip to play (index into `vat.clips`). Default `0`. */
+    clipIndex?: number;
+    /**
+     * Max random per-instance time offset in seconds, hashed from `instanceIndex`.
+     * `0` (default) plays every instance in lockstep.
+     */
+    desync?: number;
+}
+/** Position/normal nodes to assign onto a `MeshStandardNodeMaterial` (or similar). */
+interface VATNodes {
+    positionNode: Vec3Node;
+    normalNode: Vec3Node;
+    /** The time uniform in use — set `.value` each frame. */
+    time: FloatNode;
+}
+/**
+ * Build TSL decode nodes for a baked VAT, for the WebGPU/TSL renderer path.
+ * Per-instance desync comes from `hash(instanceIndex)` — no instanced
+ * attributes needed. Shadows work automatically because `positionNode` also
+ * feeds the depth pass.
+ *
+ * v1 limitation: a single clip per material (all instances share `clipIndex`,
+ * only their phase is desynced). Per-instance clip variety is future work; use
+ * the `three-vat/webgl` path for mixed-clip crowds today.
+ *
+ * NOTE: the TSL path is verified visually/manually in v1 (no automated GPU test).
+ */
+declare function vatNodes(vat: VAT, options?: VATNodeOptions): VATNodes;
+
+export { type VATNodeOptions, type VATNodes, vatNodes };

package/dist/tsl.js

@@ -0,0 +1,30 @@
+import { uniform, float, int, hash, instanceIndex, vertexIndex, positionLocal, textureLoad, ivec2, mix } from 'three/tsl';
+
+// src/tsl.ts
+function vatNodes(vat, options = {}) {
+  const { time = uniform(0), clipIndex = 0, desync = 0 } = options;
+  const clip = vat.clips[clipIndex];
+  if (!clip) {
+    throw new Error(`three-vat: clipIndex ${clipIndex} out of range (${vat.clips.length} clips)`);
+  }
+  const frames = float(clip.frames);
+  const startFrame = int(clip.startFrame);
+  const duration = float(clip.frames / clip.fps);
+  const offset = hash(instanceIndex).mul(desync);
+  const vertexRow = int(vertexIndex);
+  const sample = (tex) => {
+    const t = time.add(offset).div(duration).fract().mul(frames);
+    const f0 = int(t);
+    const f1 = int(f0.add(1).toFloat().mod(frames));
+    const s0 = textureLoad(tex, ivec2(vertexRow, f0.add(startFrame))).xyz;
+    const s1 = textureLoad(tex, ivec2(vertexRow, f1.add(startFrame))).xyz;
+    return mix(s0, s1, t.fract());
+  };
+  return {
+    positionNode: positionLocal.add(sample(vat.positionTexture)),
+    normalNode: sample(vat.normalTexture).normalize(),
+    time
+  };
+}
+
+export { vatNodes };

package/dist/types-DVtQvVjk.d.ts

@@ -0,0 +1,45 @@
+import { DataTexture, Box3 } from 'three';
+
+/** One baked animation range within a VAT's stacked frame rows. */
+interface VATClip {
+    /** 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 per-vertex position-delta magnitude (metres) across the clip.
+     * 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/normal `DataTexture`s plus the
+ * clip table and bounds needed to decode and render them. Produced by
+ * {@link bakeVAT} (runtime) or `loadVAT` (offline); the two paths yield
+ * identical objects.
+ */
+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`). */
+    normalTexture: DataTexture;
+    /** 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;
+    /** Position encoding. Only `'delta'` in v1. */
+    encoding: 'delta';
+}
+
+export type { VAT as V, VATClip as a };

package/dist/webgl.d.ts

@@ -0,0 +1,38 @@
+import { IUniform, BufferGeometry, MeshDepthMaterial, Material } from 'three';
+import { V as VAT } from './types-DVtQvVjk.js';
+
+/** The shared uniform driving every VAT-patched material's playback clock. */
+interface VATUniforms {
+    uVatTime: IUniform<number>;
+}
+/** Create the shared time uniform. Update `uVatTime.value` once per frame. */
+declare function createVATUniforms(time?: number): VATUniforms;
+/** Per-instance playback state consumed by the patched shader. */
+interface VATInstance {
+    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'>;
+    /** Phase offset in seconds — desyncs the crowd. */
+    timeOffset: number;
+    /** Playback rate multiplier. */
+    speed: number;
+}
+/**
+ * Attach the per-instance attributes the WebGL decode reads: clip band, fps,
+ * time offset, and speed. Call on the instanced geometry before rendering.
+ */
+declare function addInstancedVATAttributes(geometry: BufferGeometry, instances: VATInstance[]): void;
+/**
+ * Patch any built-in material so its vertex stage samples the VAT instead of
+ * skinning. Works on the render material and on `MeshDepthMaterial` (needed for
+ * instanced shadows — see {@link createVATDepthMaterial}). Mutates and returns
+ * the material.
+ */
+declare function patchVATMaterial<T extends Material>(material: T, vat: VAT, uniforms: VATUniforms): T;
+/**
+ * Build the `customDepthMaterial` an `InstancedMesh` needs so a VAT crowd casts
+ * correctly-deformed shadows instead of bind-pose shadows. Assign the result to
+ * `mesh.customDepthMaterial` (and, for point lights, mirror with a patched
+ * `MeshDistanceMaterial`).
+ */
+declare function createVATDepthMaterial(vat: VAT, uniforms: VATUniforms): MeshDepthMaterial;
+
+export { type VATInstance, type VATUniforms, addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, patchVATMaterial };

package/dist/webgl.js

@@ -0,0 +1,81 @@
+import { InstancedBufferAttribute, MeshDepthMaterial, RGBADepthPacking } from 'three';
+
+// src/webgl.ts
+function createVATUniforms(time = 0) {
+  return { uVatTime: { value: time } };
+}
+function addInstancedVATAttributes(geometry, instances) {
+  const n = instances.length;
+  const clipStart = new Float32Array(n);
+  const clipFrames = new Float32Array(n);
+  const clipFps = new Float32Array(n);
+  const timeOffset = new Float32Array(n);
+  const speed = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    const inst = instances[i];
+    clipStart[i] = inst.clip.startFrame;
+    clipFrames[i] = inst.clip.frames;
+    clipFps[i] = inst.clip.fps;
+    timeOffset[i] = inst.timeOffset;
+    speed[i] = inst.speed;
+  }
+  geometry.setAttribute("aClipStart", new InstancedBufferAttribute(clipStart, 1));
+  geometry.setAttribute("aClipFrames", new InstancedBufferAttribute(clipFrames, 1));
+  geometry.setAttribute("aClipFps", new InstancedBufferAttribute(clipFps, 1));
+  geometry.setAttribute("aTimeOffset", new InstancedBufferAttribute(timeOffset, 1));
+  geometry.setAttribute("aSpeed", new InstancedBufferAttribute(speed, 1));
+}
+var DECODE_PRELUDE = (
+  /* glsl */
+  `
+  uniform highp sampler2D uVatPosTex;
+  uniform highp sampler2D uVatNrmTex;
+  uniform float uVatTime;
+  attribute float aClipStart;
+  attribute float aClipFrames;
+  attribute float aClipFps;
+  attribute float aTimeOffset;
+  attribute float aSpeed;
+  vec3 vatSample( const in sampler2D tex ) {
+    float duration = aClipFrames / aClipFps;
+    float t = fract( ( uVatTime * aSpeed + aTimeOffset ) / duration ) * aClipFrames;
+    int f0 = int( t );
+    int f1 = int( mod( float( f0 + 1 ), aClipFrames ) );
+    vec3 s0 = texelFetch( tex, ivec2( gl_VertexID, f0 + int( aClipStart ) ), 0 ).xyz;
+    vec3 s1 = texelFetch( tex, ivec2( gl_VertexID, f1 + int( aClipStart ) ), 0 ).xyz;
+    return mix( s0, s1, fract( t ) );
+  }
+`
+);
+var DECODE_POSITION = (
+  /* glsl */
+  `
+  vec3 transformed = position + vatSample( uVatPosTex );
+`
+);
+var DECODE_NORMAL = (
+  /* glsl */
+  `
+  vec3 objectNormal = normalize( vatSample( uVatNrmTex ) );
+  #ifdef USE_TANGENT
+    vec3 objectTangent = vec3( tangent.xyz );
+  #endif
+`
+);
+function patchVATMaterial(material, vat, uniforms) {
+  material.onBeforeCompile = (shader) => {
+    shader.uniforms.uVatPosTex = { value: vat.positionTexture };
+    shader.uniforms.uVatNrmTex = { value: vat.normalTexture };
+    shader.uniforms.uVatTime = uniforms.uVatTime;
+    shader.vertexShader = DECODE_PRELUDE + shader.vertexShader.replace("#include <begin_vertex>", DECODE_POSITION).replace("#include <beginnormal_vertex>", DECODE_NORMAL);
+  };
+  material.customProgramCacheKey = () => "three-vat";
+  return material;
+}
+function createVATDepthMaterial(vat, uniforms) {
+  const depth = new MeshDepthMaterial({ depthPacking: RGBADepthPacking });
+  patchVATMaterial(depth, vat, uniforms);
+  return depth;
+}
+
+export { addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, patchVATMaterial };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "three-vat",
+  "version": "0.1.0",
+  "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mike Fernandez <mike.fernandez.sec@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MikeFernandez-Pro/three-vat.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MikeFernandez-Pro/three-vat/issues"
+  },
+  "homepage": "https://github.com/MikeFernandez-Pro/three-vat#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./webgl": {
+      "types": "./dist/webgl.d.ts",
+      "import": "./dist/webgl.js"
+    },
+    "./tsl": {
+      "types": "./dist/tsl.d.ts",
+      "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",
+    "vat",
+    "vertex-animation-texture",
+    "instancing",
+    "instancedmesh",
+    "crowd",
+    "animation",
+    "skinning",
+    "webgpu",
+    "tsl"
+  ],
+  "peerDependencies": {
+    "three": ">=0.185.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.185.0",
+    "three": "^0.185.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}