sbobyn / three-avbd

# three-avbd
Rigid-body physics on the GPU, in the browser: an implementation of *Augmented Vertex Block
Descent* (Giles, Diaz, Yuksel — SIGGRAPH 2025)
in TypeScript, Three.js and WGSL compute. Hundreds of thousands of bodies with contacts,
friction and joints, stepped entirely on the GPU and drawn straight from the solver's buffers.
**Live demo: three-avbd.vercel.app** ·
2D demo ·
Results vs the paper
**Built with it: Voxel City**, a Teardown-inspired
destructible city of 94,000 voxel bodies (code).
Needs a browser with WebGPU: Chrome or Edge on any platform, Safari 26 on macOS and iOS,
Firefox where it ships WebGPU. Nothing is baked: every scene is simulated live on your GPU.
## Experimental SDF collisions (unreleased)
The experimental `three-avbd/sdf` entry point (exported for the next release, not yet in a
published version; its API may change) provides mesh-to-voxel baking,
analytic/voxel sampling, mass properties and curvature seeds, plus a cancellable
worker helper. CPU baking/API usage feeds the experimental
`World.enableSdfCollisions()` API: automatic GPU candidate
spatial filtering, runtime body/field refresh, automatic capacity growth,
independent normals and warm starts.
Pair-level contact events and bounded SDF surface raycasts are supported.
Run `pnpm dev` and open `/sdf.html` for the interactive SDF showcase: rings,
warped boxes and a mesh-baked gear pile. Left-drag a body, right-drag to orbit,
spawn any of the three shapes, and toggle sampled contact points/normals.
It starts with 12 bodies and caps spawning at 36, with a 30 Hz display cap and
at most two physics steps per frame. Pause stops rendering once the view settles;
hidden tabs stop stepping. Contacts are an optional throttled readback, while
body rendering uses the GPU buffer directly. Mass/inertia use box proxies: this
is a visual collision showcase, not a reproduction of the paper's experiments.
Run `/sdf-released.html` for all eleven released scenes: stacked boxes and gears; falling
plain, bent, twisted and displaced planks; chairs, cows on spikes, bunnies; a spiky wheel; and
the analytic primitives. They use the original resolution-100 fields, analytic shape parameters,
poses, mass and full inertia tensors.
It starts paused and compares live metrics with the captured CPU reference.
Mesh quality (used for every non-convex scene) activates contacts earlier with the same resting gap; Released
settings keeps the captured collision parameters. Both use corrected sticking anchors.
See measured comparison and remaining gaps.
## Use it in your project
three-avbd on npm:
 [code] 
 [code] 
- **Bodies**: `addBox`, `addSphere`, `addHull({ points })` (convex hulls; pass the renderer
 `requiredLimits: await recommendedLimits()` so they collide as hulls), with position, rotation,
 velocity, density, friction, `fixed`;
 `body.applyImpulse(J, point)`, `applyForce(F, point)` (every step until `clearForces()`),
 `applyTorque`, collision groups (`group`, `collidesWith`), `body.moveTo(pos