dgreenheck/threejs-particle-fluids
dgreenheck/threejs-particle-fluids has 356 GitHub stars and 47 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-19 11:21 UTC. Last push 2026-09-28.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Particle Based Fluids (PBF) library for Three.js
Developer ToolsREADME.md
OriginalThree.js Particle Fluids
GPU particle physics for three.js: liquids, soft bodies, cloth, and smoke, simulated and rendered with WebGPU.

Live demo · Documentation · API reference
Install
npm install threejs-particle-fluids three
Requires three.js r184 and a browser with WebGPU (no WebGL fallback). See Requirements.
Quick start
import { Box3, Vector3 } from 'three';
import { Simulation, createParticleRenderer } from 'threejs-particle-fluids';
const renderer = await createParticleRenderer({ antialias: true });
const sim = new Simulation({
renderer,
scene,
camera,
container: new Box3(new Vector3(-0.5, 0, -0.3), new Vector3(0.5, 0.8, 0.3)),
particles: 5000, // total budget; sets the cost of each step
});
sim.addFluid({ box: new Box3(new Vector3(-0.5, 0, -0.3), new Vector3(-0.1, 0.5, 0.3)) });
async function frame() {
await sim.step();
renderer.render(scene, camera);
requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
Full scene with lighting and camera: Guide › First scene.
Documentation
| Page | Contents |
|---|---|
| Guide | Setup, particle sizing, frame loop, combining materials |
| API reference | Every exported class, option, property, and method |
| Limitations | Platform, performance, accuracy, and API constraints |
Demo
Live demo. To run locally (Node.js 22.12+):
npm ci
npm run dev
| Preset | Shows |
|---|---|
| Wave Chamber | A sealed tank turning end over end, driving water through its walls |
| Water Drop | A falling drop splashing into a shallow pool |
| Dam Break | A column of water collapses and floods into a large Stanford bunny |
| Liquid Marble | Inward gravity pulling a drop back together after a click bursts it |
| Honey Bunny | A circling nozzle drizzles viscous honey over the Stanford bunny |
| Buoyancy | Textured rubber ducks floating or sinking as their density changes |
| Soft Body Squeeze | 20 textured CC0 forms squeezed between closing plates |
| Bunny Lineup | Five jelly bunnies dropped side by side, from firm to very soft |
| Banana Blender | Soft bananas as dense as the liquid, swirled by a tall paddle |
| Velvet Curtain | Soft red velvet displaced by a moving chrome sphere |
| Velvet Drape | A square of red velvet dropped onto the Stanford bunny |
| Tarp Runoff | Red liquid pouring onto a sloped canvas tarp and spilling off its edge |
| Vortex Plume | A heated vent drives a buoyant, swirling plume that carries lit volumetric smoke |
| Control | Action |
|---|---|
| Space | Pause |
| R | Restart |
| Drag | Orbit |
| Click liquid | Splash |
| Particles menu | Particle count (5,000 to 50,000) |
| ↻ controls | Restart the preset when changed |
Preset sources: demo/presets/, built with the low-level API.
Development
| Command | Purpose |
|---|---|
npm run dev |
Start the demo and examples |
npm run build |
Build the library into dist/ and the demo into dist-demo/ |
npm run typecheck |
Type-check the library, demo, examples, tests, and scripts |
npm run lint |
Lint |
npm run format:check |
Check formatting |
npm test |
Run CPU tests |
npm run test:gpu |
Run WebGPU tests in installed Google Chrome |
npm run test:demo |
Run browser checks of the demo |
npm run test:perf |
Run GPU benchmarks and write a local report |
npm run perf:profile |
Time every kernel of each demo preset, compared with the last run |
npm run perf:ab |
Compare frame times with a git ref (-- --ref HEAD), alternating runs |
npm run perf:fingerprint |
Check the physics against a saved baseline (-- --save-baseline first) |
npm run assets:elastic |
Rebuild the soft-body meshes and particle templates |
npm run assets:honey |
Rebuild the Stanford bunny mesh and distance field |
GPU tests and benchmarks need a local GPU; the runner passes Chrome's --enable-unsafe-webgpu flag. Benchmark results depend on the browser, adapter, and driver.
src/
simulation/ The Simulation class and its handles
core/ Particles, the solver loop, contacts, colliders, neighbor grid
fluids/ Fluid solver and liquid surface renderer
softbody/ Shape matching, voxelization, mesh skinning
cloth/ Cloth constraints, wind, and surface rendering
gas/ Smoke tracers and renderers
sdf/ Mesh-to-distance-field baking
render/ Particle debug rendering
demo/ The preset gallery
examples/ Small examples of the API
tests/ Numerical GPU tests and benchmarks
License
MIT. The bundled Kenney and Poly Haven models are CC0; the Stanford bunny is courtesy of the Stanford 3D Scanning Repository. See THIRD_PARTY_NOTICES.md for sources and modifications.