three-vat 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -313
- package/package.json +10 -13
package/README.md
CHANGED
|
@@ -1,23 +1,14 @@
|
|
|
1
1
|
# three-vat
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://www.npmjs.com/package/three-vat)
|
|
5
|
-
[](./LICENSE)
|
|
6
|
-
|
|
7
|
-
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.
|
|
8
|
-
|
|
9
|
-
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.
|
|
10
|
-
|
|
11
|
-
## Live demos
|
|
3
|
+
|
|
12
4
|
|
|
13
|
-
|
|
14
|
-
- **[WebGPU crowd](https://mikefernandez-pro.github.io/three-vat/webgpu_crowd.html)** — the same crowd through the TSL decode path, on `WebGPURenderer`.
|
|
5
|
+
**[Open the live demo →](https://mikefernandez-pro.github.io/three-vat/)** and drag the count from 1 robot to 340. The draw calls do not move.
|
|
15
6
|
|
|
16
|
-
|
|
17
|
-
cursors on the frame rows each instance is sampling. Source in
|
|
18
|
-
[`examples/`](./examples); they deploy from `main` on every push.
|
|
7
|
+
Bake a glTF `AnimationClip` into GPU textures and animate **hundreds or thousands of instanced characters with zero per-frame CPU** — one draw call per material, no `SkinnedMesh` per character. Works on `WebGLRenderer` and `WebGPURenderer`, from the same baked VAT.
|
|
19
8
|
|
|
20
|
-
|
|
9
|
+
[](https://github.com/MikeFernandez-Pro/three-vat/actions/workflows/ci.yml)
|
|
10
|
+
[](https://www.npmjs.com/package/three-vat)
|
|
11
|
+
[](./LICENSE)
|
|
21
12
|
|
|
22
13
|
## Install
|
|
23
14
|
|
|
@@ -27,344 +18,146 @@ npm install three-vat three
|
|
|
27
18
|
|
|
28
19
|
`three` (>= 0.185) is a peer dependency.
|
|
29
20
|
|
|
30
|
-
##
|
|
21
|
+
## One crowd, start to finish
|
|
31
22
|
|
|
32
23
|
```ts
|
|
24
|
+
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
|
|
33
25
|
import { bakeVAT } from 'three-vat'
|
|
34
|
-
|
|
35
|
-
//
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
//
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
const vat = bakeVAT(gltf.scene, clips, {
|
|
26
|
+
import { createVATMesh, getMaxTextureSize } from 'three-vat/webgl'
|
|
27
|
+
// WebGPURenderer? `from 'three-vat/tsl'` — that import is the only line that changes.
|
|
28
|
+
|
|
29
|
+
// The parts you already know — renderer, scene, camera, lights, clock — made
|
|
30
|
+
// however you usually make them. Nothing on this line is VAT-specific.
|
|
31
|
+
const { renderer, scene, camera, clock } = setUpYourScene()
|
|
32
|
+
|
|
33
|
+
const gltf = await new GLTFLoader().loadAsync('/robot.glb')
|
|
34
|
+
|
|
35
|
+
// Bake once, at load. Pass the subtree root — `gltf.scene` — and not a mesh
|
|
36
|
+
// inside it: the bake unit is the whole subtree, merged and recorded in root
|
|
37
|
+
// space. This same call takes
|
|
38
|
+
// - a skinned character (Mixamo, Sketchfab, `Soldier.glb`)
|
|
39
|
+
// - a morph-target mesh
|
|
40
|
+
// - a hierarchy of rigid, node-animated parts (three's `RobotExpressive`)
|
|
41
|
+
// - any mix of those in one subtree
|
|
42
|
+
// because a VAT records where a vertex ended up and never how it got there.
|
|
43
|
+
// Nothing to classify, and no variant of this call to go looking for.
|
|
44
|
+
const vat = bakeVAT(gltf.scene, gltf.animations, {
|
|
54
45
|
fps: 30,
|
|
55
|
-
maxTextureSize: getMaxTextureSize(renderer),
|
|
46
|
+
maxTextureSize: getMaxTextureSize(renderer), // this GPU's real ceiling
|
|
56
47
|
})
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
## Render a crowd
|
|
60
48
|
|
|
61
|
-
One
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
49
|
+
// One entry per character: which clip it plays, its phase, its rate.
|
|
50
|
+
const instances = Array.from({ length: 500 }, (_, i) => ({
|
|
51
|
+
clip: vat.clips[i % vat.clips.length],
|
|
52
|
+
timeOffset: Math.random() * 2, // desync, so the crowd is not in lockstep
|
|
53
|
+
speed: 0.9 + Math.random() * 0.2,
|
|
54
|
+
}))
|
|
67
55
|
|
|
68
|
-
|
|
69
|
-
//
|
|
56
|
+
// The crowd: one InstancedMesh, its geometry and materials already decoding the
|
|
57
|
+
// VAT, plus the clock that drives every instance.
|
|
70
58
|
const { mesh, time } = createVATMesh(vat, instances)
|
|
71
59
|
mesh.castShadow = mesh.receiveShadow = true
|
|
72
60
|
scene.add(mesh)
|
|
73
61
|
|
|
74
|
-
//
|
|
75
|
-
for (let i = 0; i < instances.length; i++) mesh.setMatrixAt(i,
|
|
62
|
+
// Where each character stands is yours — the library never guesses a layout.
|
|
63
|
+
for (let i = 0; i < instances.length; i++) mesh.setMatrixAt(i, matrixFor(i))
|
|
76
64
|
mesh.instanceMatrix.needsUpdate = true
|
|
77
|
-
mesh.computeBoundingSphere() // or frustumCulled = false, if matrices
|
|
65
|
+
mesh.computeBoundingSphere() // or frustumCulled = false, if matrices move every frame
|
|
78
66
|
|
|
79
|
-
|
|
80
|
-
time.value = clock.
|
|
67
|
+
renderer.setAnimationLoop(() => {
|
|
68
|
+
time.value = clock.getElapsedTime() // the whole per-frame cost of the animation
|
|
69
|
+
renderer.render(scene, camera)
|
|
70
|
+
})
|
|
81
71
|
```
|
|
82
72
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
Shadows are the one place the renderers genuinely differ, and the call absorbs it: on WebGL it attaches the patched depth and distance materials the shadow passes need (miss them by hand and the crowd's body animates while its shadow stays in the bind pose); on TSL it attaches nothing, because `positionNode` already feeds the depth pass. Either way you write `castShadow` and nothing else.
|
|
73
|
+
Two things worth knowing the first time:
|
|
86
74
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
75
|
+
- **Render `vat.geometry`, not your source mesh.** The merged vertex ordering is
|
|
76
|
+
the baker's, and the textures are indexed by it. `createVATMesh` does this for
|
|
77
|
+
you; by hand, clone that geometry and no other.
|
|
78
|
+
- **Materials are never merged.** A 500-robot crowd with 3 materials is 3 draw
|
|
79
|
+
calls — not 1, and not 500. VAT collapses instance count, not material count.
|
|
90
80
|
|
|
91
81
|
<details>
|
|
92
|
-
<summary>
|
|
82
|
+
<summary><b>Does it work with my model?</b></summary>
|
|
93
83
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
import { createVATUniforms, createVATDepthMaterial, patchVATMaterial } from 'three-vat/webgl'
|
|
97
|
-
|
|
98
|
-
const uniforms = createVATUniforms()
|
|
99
|
-
|
|
100
|
-
// vat.geometry already carries the all-frames bounding box/sphere, so instances
|
|
101
|
-
// never cull mid-animation.
|
|
102
|
-
const geometry = vat.geometry.clone()
|
|
103
|
-
// Instance playback — `{ clip, timeOffset, speed }` per instance — is a core
|
|
104
|
-
// contract both decode paths read, not a WebGL-only concept.
|
|
105
|
-
addVATInstanceAttributes(geometry, instances)
|
|
106
|
-
|
|
107
|
-
// One patched material per source material, sharing one clock.
|
|
108
|
-
const materials = vat.materials.map((source) => {
|
|
109
|
-
const material = source.clone()
|
|
110
|
-
patchVATMaterial(material, vat, uniforms)
|
|
111
|
-
return material
|
|
112
|
-
})
|
|
84
|
+
If `GLTFLoader` loads it and it has an `AnimationClip`, yes — the four shapes
|
|
85
|
+
listed in the snippet above, and any mix of them, through that one call.
|
|
113
86
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
87
|
+
The bake unit is the **subtree**, not the mesh
|
|
88
|
+
([ADR-0008](./docs/adr/0008-a-vat-bakes-a-posed-subtree-not-a-skinnedmesh.md)),
|
|
89
|
+
which is where the one real mistake lives: pass `gltf.scene`, or the node you
|
|
90
|
+
want animated, never a `SkinnedMesh` you fished out of it.
|
|
118
91
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
92
|
+
Positions bake exactly under any rig; normals match what three's own skinning
|
|
93
|
+
shader draws, which is approximate under non-uniform bone scale — `bakeVAT`
|
|
94
|
+
warns once and names the bone. A rest-pose track such as Mixamo's `TPose` bakes
|
|
95
|
+
to a frozen band and reports it as a near-zero `clip.maxDelta`: filter those out
|
|
96
|
+
of `gltf.animations` rather than spending texture rows on them.
|
|
122
97
|
|
|
123
98
|
</details>
|
|
124
99
|
|
|
125
100
|
<details>
|
|
126
|
-
<summary>
|
|
101
|
+
<summary><b>Going bigger: texture limits, bake cost, Web Workers</b></summary>
|
|
127
102
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
import { vatNodes } from 'three-vat/tsl'
|
|
132
|
-
|
|
133
|
-
const geometry = vat.geometry.clone()
|
|
134
|
-
addVATInstanceAttributes(geometry, instances)
|
|
135
|
-
|
|
136
|
-
// The mesh is built first, because the decode is built from it.
|
|
137
|
-
const material = new MeshStandardNodeMaterial()
|
|
138
|
-
const mesh = new THREE.InstancedMesh(geometry, material, instances.length)
|
|
139
|
-
|
|
140
|
-
// `geometry`: each instance plays its own clip, phase and rate.
|
|
141
|
-
// `instancedMesh`: the decode re-applies this mesh's instancing itself, because
|
|
142
|
-
// three applies the instance matrix to `positionLocal` *before* it reads
|
|
143
|
-
// `positionNode` — so the delta has to be added in the geometry's own space and
|
|
144
|
-
// instanced afterwards. Omit it only for a single, non-instanced mesh.
|
|
145
|
-
const { positionNode, time } = vatNodes(vat, { geometry, instancedMesh: mesh })
|
|
146
|
-
material.positionNode = positionNode
|
|
147
|
-
|
|
148
|
-
// per frame:
|
|
149
|
-
time.value = clock.elapsedTime
|
|
150
|
-
```
|
|
103
|
+
The VAT is one `vertexCount` × `totalFrames` texture pair, so both axes hit the
|
|
104
|
+
GPU's texture ceiling. Always pass `maxTextureSize: getMaxTextureSize(renderer)`
|
|
105
|
+
as above: the default is a desktop-shaped guess, and mobile is often 4096.
|
|
151
106
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
built in the *fragment* stage and expected in view space, which is neither where
|
|
156
|
-
nor what a per-vertex, object-space VAT normal is.
|
|
107
|
+
The bake is CPU work done once at load — about 100 ms for the demo's robot, and
|
|
108
|
+
seconds for a 20k-vertex skinned character with many clips. It never touches the
|
|
109
|
+
renderer, so it moves into a Web Worker as-is.
|
|
157
110
|
|
|
158
|
-
|
|
111
|
+
**[docs/usage.md](./docs/usage.md)** has the measured bake-cost table, the
|
|
112
|
+
worker recipe, the draw-call arithmetic, and the primitives underneath
|
|
113
|
+
`createVATMesh` for when you are not rendering onto a plain `InstancedMesh`.
|
|
159
114
|
|
|
160
115
|
</details>
|
|
161
116
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
A VAT is produced exactly one way — `bakeVAT` at runtime
|
|
165
|
-
([ADR-0010](./docs/adr/0010-drop-the-offline-format-runtime-bake-is-the-library.md)).
|
|
166
|
-
There is no file format to write or load, so the one cost to budget is the bake
|
|
167
|
-
itself, once at load. Measured on `three@0.185.1` (Node, Apple Silicon, mean of
|
|
168
|
-
3 runs after warm-up):
|
|
169
|
-
|
|
170
|
-
| Asset | Clips | fps | Rows | Bake |
|
|
171
|
-
|---|---|---|---|---|
|
|
172
|
-
| `RobotExpressive` (rigid, 7 214 v) | 3 (the demo) | 30 | 158 | 97 ms |
|
|
173
|
-
| `RobotExpressive` | 5 | 30 | 313 | 178 ms |
|
|
174
|
-
| `RobotExpressive` | 14 (all) | 30 | 585 | 330 ms |
|
|
175
|
-
| `RobotExpressive` | 14 (all) | 60 | 1 168 | 659 ms |
|
|
176
|
-
| `Soldier` (skinned, 7 434 v) | 4 (all) | 30 | 113 | 250 ms |
|
|
177
|
-
| `Soldier` (skinned) | 4 (all) | 60 | 224 | 492 ms |
|
|
178
|
-
|
|
179
|
-
Cost is linear in `vertices × frames`, and **a skinned vertex costs ~4× per
|
|
180
|
-
frame row what a rigid one does** (2.2 ms/row here vs 0.56) — the four-weight
|
|
181
|
-
bone blend is the hot loop. So budget by rows, and halve `fps` before you cut
|
|
182
|
-
clips. A 20k-vertex skinned character with 6 clips at 30 fps extrapolates to
|
|
183
|
-
~1.8 s on this machine and several seconds on a mid-range phone — enough to
|
|
184
|
-
matter, and the point at which the bake belongs off the main thread.
|
|
185
|
-
|
|
186
|
-
It can go there as-is: **the baker is pure CPU and never touches the renderer**,
|
|
187
|
-
so it runs in a Web Worker, with the texel buffers transferred back at no copy
|
|
188
|
-
cost. The worker loads the glTF and bakes; the main thread rebuilds the
|
|
189
|
-
textures and the geometry from plain buffers.
|
|
117
|
+
<details>
|
|
118
|
+
<summary><b>What it does not do</b></summary>
|
|
190
119
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
120
|
+
No clip crossfade (instances cut between clips), no LOD, no baking CLI or file
|
|
121
|
+
format, no React/drei binding, glTF input only. Each is a decision rather than a
|
|
122
|
+
gap, and each is written up with its reasoning in
|
|
123
|
+
**[docs/usage.md](./docs/usage.md#what-10-does-not-do)**, alongside the
|
|
124
|
+
trade-offs against `SkinnedMesh` and bone-texture instancing.
|
|
195
125
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
const normal = vat.normalTexture.image.data as Float32Array
|
|
202
|
-
const index = vat.geometry.getIndex()
|
|
203
|
-
|
|
204
|
-
self.postMessage(
|
|
205
|
-
{
|
|
206
|
-
position,
|
|
207
|
-
normal,
|
|
208
|
-
// Every attribute the merge produced — position, normal, and uv/color
|
|
209
|
-
// when the source had them. Carry each itemSize rather than guessing it.
|
|
210
|
-
attributes: Object.fromEntries(
|
|
211
|
-
Object.entries(vat.geometry.attributes).map(([name, a]) => [
|
|
212
|
-
name,
|
|
213
|
-
{ array: a.array, itemSize: a.itemSize },
|
|
214
|
-
]),
|
|
215
|
-
),
|
|
216
|
-
index: index?.array,
|
|
217
|
-
groups: vat.geometry.groups,
|
|
218
|
-
clips: vat.clips,
|
|
219
|
-
bounds: { min: vat.bounds.min.toArray(), max: vat.bounds.max.toArray() },
|
|
220
|
-
vertexCount: vat.vertexCount,
|
|
221
|
-
totalFrames: vat.totalFrames,
|
|
222
|
-
},
|
|
223
|
-
// Transferred, not copied — the texel buffers are the large part.
|
|
224
|
-
[position.buffer, normal.buffer],
|
|
225
|
-
)
|
|
226
|
-
}
|
|
227
|
-
```
|
|
126
|
+
Both decode paths — GLSL on `WebGLRenderer`, TSL on `WebGPURenderer` — read one
|
|
127
|
+
shared instance-playback contract and export the same `createVATMesh`, so
|
|
128
|
+
nothing documented here is true on one renderer and false on the other. That the
|
|
129
|
+
two decode *pixel-identically* is a manual gate before every release
|
|
130
|
+
([docs/releasing.md](./docs/releasing.md)).
|
|
228
131
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
// the main thread can ask the GPU for its limits.
|
|
238
|
-
const worker = new Worker(new URL('./bake.worker.ts', import.meta.url), { type: 'module' })
|
|
239
|
-
|
|
240
|
-
function bakeInWorker(url: string, fps = 30): Promise<VAT> {
|
|
241
|
-
return new Promise((resolve) => {
|
|
242
|
-
worker.onmessage = ({ data: d }) => {
|
|
243
|
-
const geometry = new THREE.BufferGeometry()
|
|
244
|
-
for (const [name, { array, itemSize }] of Object.entries(d.attributes)) {
|
|
245
|
-
geometry.setAttribute(name, new THREE.BufferAttribute(array, itemSize))
|
|
246
|
-
}
|
|
247
|
-
if (d.index) geometry.setIndex(new THREE.BufferAttribute(d.index, 1))
|
|
248
|
-
for (const g of d.groups) geometry.addGroup(g.start, g.count, g.materialIndex)
|
|
249
|
-
|
|
250
|
-
const bounds = new THREE.Box3(
|
|
251
|
-
new THREE.Vector3(...d.bounds.min),
|
|
252
|
-
new THREE.Vector3(...d.bounds.max),
|
|
253
|
-
)
|
|
254
|
-
// The union-of-all-frames volume, or a deformed crowd culls mid-animation.
|
|
255
|
-
geometry.boundingBox = bounds.clone()
|
|
256
|
-
geometry.boundingSphere = bounds.getBoundingSphere(new THREE.Sphere())
|
|
257
|
-
|
|
258
|
-
resolve({
|
|
259
|
-
positionTexture: makeVATTexture(d.position, d.vertexCount, d.totalFrames),
|
|
260
|
-
normalTexture: makeVATTexture(d.normal, d.vertexCount, d.totalFrames),
|
|
261
|
-
geometry,
|
|
262
|
-
// One per group, in `materialIndex` order — see the note below.
|
|
263
|
-
materials: d.groups.map(() => new THREE.MeshStandardMaterial()),
|
|
264
|
-
clips: d.clips,
|
|
265
|
-
bounds,
|
|
266
|
-
vertexCount: d.vertexCount,
|
|
267
|
-
totalFrames: d.totalFrames,
|
|
268
|
-
encoding: 'delta',
|
|
269
|
-
})
|
|
270
|
-
}
|
|
271
|
-
worker.postMessage({ url, fps, maxTextureSize: getMaxTextureSize(renderer) })
|
|
272
|
-
})
|
|
273
|
-
}
|
|
274
|
-
|
|
275
|
-
const { mesh, time } = createVATMesh(await bakeInWorker('/robot.glb'), instances)
|
|
132
|
+
</details>
|
|
133
|
+
|
|
134
|
+
<details>
|
|
135
|
+
<summary><b>Development</b></summary>
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
pnpm i
|
|
139
|
+
pnpm run dev # opens the demo — this and the line above are the whole setup
|
|
276
140
|
```
|
|
277
141
|
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
- **Materials.** A `Material` holds textures and GPU state, so it has to be
|
|
281
|
-
built on the main thread. The placeholder above is a stand-in: `materials`
|
|
282
|
-
must have one entry per `geometry.groups[].materialIndex`, or every group past
|
|
283
|
-
the first renders undefined. For a glTF's real materials, load it a second
|
|
284
|
-
time on the main thread (the browser serves it from cache) and take
|
|
285
|
-
`gltf.scene`'s materials in the same order the merge recorded them.
|
|
286
|
-
- **The renderer's `maxTextureSize`**, which only the main thread can ask for —
|
|
287
|
-
read it there and pass it in, as the snippet does.
|
|
288
|
-
|
|
289
|
-
A `bakeVATInWorker` helper is deferred, for the reason in
|
|
290
|
-
[What 1.0 does not do](#what-10-does-not-do).
|
|
291
|
-
|
|
292
|
-
## Trade-offs
|
|
293
|
-
|
|
294
|
-
- **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.
|
|
295
|
-
- **vs bone-texture instancing:** smaller textures and supports blending, but more fetches per vertex. VAT also captures morph/non-skeletal deformation for free.
|
|
296
|
-
- **VAT limits:** no runtime IK/blending, discrete frames, memory cost (`verts × frames × 16 B × 2` textures). No clip crossfade — see [What 1.0 does not do](#what-10-does-not-do).
|
|
297
|
-
- **Skinned normals:** positions bake exactly under any rig. Normals reproduce what three's own skinning shader renders — linear-blend skinning transforms a normal by the skin matrix rather than its inverse-transpose, exact for rigid and uniformly-scaled bones, an approximation otherwise. Non-uniform bone scale is where that shows, so `bakeVAT` warns once, naming the bone.
|
|
298
|
-
|
|
299
|
-
## What 1.0 does not do
|
|
300
|
-
|
|
301
|
-
Named rather than left to be discovered. None of these is a known defect; each
|
|
302
|
-
is a decision, with the reasoning recorded where it was made.
|
|
303
|
-
|
|
304
|
-
- **No clip crossfade.** An instance cuts between clips, it does not blend.
|
|
305
|
-
Crossfade doubles the per-vertex texel fetches (2 → 4) and adds per-instance
|
|
306
|
-
transition state, which is not worth spending before the single-clip decode is
|
|
307
|
-
proven on both paths ([ADR-0007](./docs/adr/0007-v1-scope-library-only.md)).
|
|
308
|
-
The instance-attribute layout reserves room for a second clip index, so it
|
|
309
|
-
stays a non-breaking addition.
|
|
310
|
-
- **No LOD.** Every instance samples the VAT at full vertex count, whatever its
|
|
311
|
-
distance.
|
|
312
|
-
- **No `npx vat-bake` CLI, and no file format for it to write.** The offline
|
|
313
|
-
format was removed in 1.0 and the runtime bake is the only way to produce a
|
|
314
|
-
VAT ([ADR-0010](./docs/adr/0010-drop-the-offline-format-runtime-bake-is-the-library.md));
|
|
315
|
-
the design a CLI would build on is kept on record in the superseded
|
|
316
|
-
[ADR-0003](./docs/adr/0003-offline-format-float16-bin-plus-manifest.md), so
|
|
317
|
-
reviving it is a decision rather than a fresh design problem.
|
|
318
|
-
- **No React/drei hook or component.** A downstream contribution rather than a
|
|
319
|
-
library surface, and `createVATMesh` is what makes it thin enough to be one.
|
|
320
|
-
- **No `bakeVATInWorker` helper.** 1.0 ships the [recipe](#bake-cost-and-baking-in-a-web-worker)
|
|
321
|
-
instead: adding a second, async way to bake while the API stabilizes is the
|
|
322
|
-
two-entry-point split [ADR-0008](./docs/adr/0008-a-vat-bakes-a-posed-subtree-not-a-skinnedmesh.md)
|
|
323
|
-
refused, and demand should decide it.
|
|
324
|
-
- **glTF/GLB input only**, and multi-material meshes are rejected rather than
|
|
325
|
-
split by geometry group — `GLTFLoader` emits one mesh per primitive, so the
|
|
326
|
-
case is unreachable through the only input surface there is.
|
|
327
|
-
|
|
328
|
-
## Development
|
|
142
|
+
Three more verbs, and that is the table:
|
|
329
143
|
|
|
330
144
|
```bash
|
|
331
|
-
pnpm
|
|
332
|
-
pnpm
|
|
333
|
-
pnpm
|
|
334
|
-
pnpm test:examples # the demo's own suite (crowd layout, page/bundle shape)
|
|
335
|
-
pnpm typecheck
|
|
336
|
-
pnpm typecheck:examples
|
|
337
|
-
pnpm build
|
|
338
|
-
pnpm example # serves the demo pages in examples/ (model bundled)
|
|
339
|
-
pnpm parity # cross-path pixel-diff gate — needs a GPU and a WebGPU browser
|
|
145
|
+
pnpm test # every suite: the baker core, the release suite, the demo's own
|
|
146
|
+
pnpm typecheck # all three tsconfigs: library, release suite, demo
|
|
147
|
+
pnpm build # the published library (`pnpm run build:watch` to watch)
|
|
340
148
|
```
|
|
341
149
|
|
|
342
|
-
`examples/` is
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
([
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
at the WebGL demo when there is none — `WebGPURenderer` would otherwise fall
|
|
354
|
-
back to its WebGL backend and quietly draw the WebGPU demo through GLSL.
|
|
355
|
-
|
|
356
|
-
`pnpm parity` is the one check that is not in CI and not optional. It renders
|
|
357
|
-
one bake through both decode paths at the same camera, lights and time and
|
|
358
|
-
compares the frames pixel by pixel — the only thing that can catch a decode
|
|
359
|
-
subtly wrong on one path only, and the only thing that needs a real GPU on both
|
|
360
|
-
backends. It is a **required gate before publishing**, not a test; see
|
|
361
|
-
[docs/releasing.md](./docs/releasing.md) for what it checks and how to read a
|
|
362
|
-
failure.
|
|
363
|
-
|
|
364
|
-
The suite is green on a fresh clone with no network: the real-asset tests skip
|
|
365
|
-
when their asset is missing. Run `pnpm fetch:test-assets` before touching the
|
|
366
|
-
baker, so a real skinned character is actually being baked — see
|
|
367
|
-
[docs/test-assets.md](./docs/test-assets.md).
|
|
150
|
+
`examples/` is the demo — one page per renderer, self-contained on purpose
|
|
151
|
+
([ADR-0011](./docs/adr/0011-one-example-per-renderer-duplicated-on-purpose.md)),
|
|
152
|
+
deployed from `main` on every push. Release steps are `node` invocations rather
|
|
153
|
+
than table entries, the parity gate among them and required
|
|
154
|
+
([docs/releasing.md](./docs/releasing.md)). The suite is green on a fresh clone
|
|
155
|
+
with no network: real-asset tests skip when their asset is missing, so fetch it
|
|
156
|
+
before touching the baker ([docs/test-assets.md](./docs/test-assets.md)).
|
|
157
|
+
|
|
158
|
+
</details>
|
|
159
|
+
|
|
160
|
+
Deeper: [docs/](./docs) · [CHANGELOG.md](./CHANGELOG.md) · [live WebGPU demo](https://mikefernandez-pro.github.io/three-vat/webgpu_crowd.html)
|
|
368
161
|
|
|
369
162
|
## License
|
|
370
163
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "three-vat",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -52,27 +52,24 @@
|
|
|
52
52
|
},
|
|
53
53
|
"devDependencies": {
|
|
54
54
|
"@types/three": "^0.185.0",
|
|
55
|
+
"gifenc": "1.0.3",
|
|
56
|
+
"playwright-core": "1.63.0",
|
|
57
|
+
"pngjs": "7.0.0",
|
|
55
58
|
"three": "^0.185.0",
|
|
56
59
|
"tsup": "^8.3.0",
|
|
57
60
|
"typescript": "^5.6.0",
|
|
61
|
+
"vite": "^7.1.0",
|
|
58
62
|
"vitest": "^2.1.0"
|
|
59
63
|
},
|
|
60
64
|
"engines": {
|
|
61
65
|
"node": ">=18"
|
|
62
66
|
},
|
|
63
67
|
"scripts": {
|
|
68
|
+
"dev": "pnpm --filter three-vat-example dev",
|
|
69
|
+
"test": "vitest run && pnpm --filter three-vat-example test",
|
|
64
70
|
"build": "tsup",
|
|
65
|
-
"
|
|
66
|
-
"
|
|
67
|
-
"test:watch": "vitest"
|
|
68
|
-
"fetch:test-assets": "node scripts/fetch-test-assets.mjs",
|
|
69
|
-
"typecheck": "tsc --noEmit",
|
|
70
|
-
"release": "pnpm publish ${NPM_OTP:+--otp=\"$NPM_OTP\"} && pnpm verify:published",
|
|
71
|
-
"verify:published": "node scripts/verify-published.mjs",
|
|
72
|
-
"example": "pnpm --filter three-vat-example dev",
|
|
73
|
-
"build:examples": "pnpm --filter three-vat-example build",
|
|
74
|
-
"test:examples": "pnpm --filter three-vat-example test",
|
|
75
|
-
"parity": "pnpm --filter three-vat-example parity",
|
|
76
|
-
"typecheck:examples": "pnpm --filter three-vat-example typecheck"
|
|
71
|
+
"typecheck": "tsc --noEmit && tsc --noEmit -p release/tsconfig.json && pnpm --filter three-vat-example typecheck",
|
|
72
|
+
"build:watch": "tsup --watch",
|
|
73
|
+
"test:watch": "vitest"
|
|
77
74
|
}
|
|
78
75
|
}
|