Three.js Blocks

Home
Documentation
Examples
Tools

SPH

@three-blocks/coreWebGPU
new SPH(options : Object)

Smoothed Particle Hydrodynamics (SPH) fluid simulation with spatial grid acceleration.

Features

  • Pressure, viscosity, and gravity forces with configurable SPH kernels (Poly6, Spiky, Viscosity)
  • Spatial grid acceleration (default) or naive O(N²) neighbor search
  • 2D and 3D modes with appropriate kernel functions
  • Domain attachment to Three.js objects for dynamic boundary transforms
  • Pointer-based interaction for user-driven forces
  • Optional direction storage for oriented particle rendering

Architecture

  • Compute passes: density → pressure → forces (pressure + viscosity) → interaction → integration
  • Spatial grid reduces neighbor search from O(N²) to O(N) via cell hashing
  • Domain matrix transforms allow particles to follow moving/rotating objects
  • Kernel radius auto-scales with domain transformations when scaleKernelWithDomain is enabled
Constructor Parameters
optionsoptionalObject
Configuration options.
Default is {}.
  • countoptionalnumber
    Number of particles to simulate.
    Default is 5000.
  • is3Doptionalboolean
    Enable 3D mode; false uses 2D kernels.
    Default is true.
  • domainDimensionsoptionalTHREE.Vector3
    Simulation domain size (default: 32x32x32).
  • massoptionalnumber
    Particle mass.
    Default is 0.4.
  • hoptionalnumber
    Smoothing kernel radius.
    Default is 1.0.
  • restDensityoptionalnumber | null
    Target rest density (auto-computed if null).
    Default is null.
  • pressureStiffnessoptionalnumber
    Pressure force multiplier.
    Default is 100.0.
  • viscosityMuoptionalnumber
    Viscosity coefficient.
    Default is 0.12.
  • restitutionoptionalnumber
    Boundary collision restitution.
    Default is 0.1.
  • maxSpeedoptionalnumber
    Maximum particle velocity.
    Default is 15.0.
  • gravityoptionalTHREE.Vector3
    Gravity acceleration (default: -9.81 Y).
  • fixedTimeStepoptionalnumber | null
    Fixed timestep (null for variable dt).
    Default is 1/60.
  • maxSubstepsoptionalnumber
    Max fixed timesteps per frame.
    Default is 5.
  • maxFrameDeltaoptionalnumber
    Max frame delta to avoid large jumps.
    Default is 0.1.
  • debugoptionalboolean
    Enable debug buffers.
    Default is false.
  • useDirectionoptionalboolean
    Allocate direction buffers.
    Default is false.
  • scaleKernelWithDomainoptionalboolean
    Scale kernel with domain.
    Default is true.
  • useSpatialGridoptionalboolean
    Enable spatial grid acceleration.
    Default is true.
  • useMatricesoptionalboolean
    Write per-instance matrices.
    Default is false.
  • spatialGridOptionsoptionalObject
    SpatialGrid options.
    Default is {}.
  • spatialGridoptionalSpatialGrid
    Preconfigured SpatialGrid.
    Default is null.
  • initialPositionsoptionalTHREE.StorageInstancedBufferAttribute
    External positions buffer.
    Default is null.
  • sdfVolumeConstraintoptionalSDFVolumeConstraint
    SDF boundary constraint.
    Default is null.
  • bvhVolumeConstraintoptionalBVHVolumeConstraint
    BVH boundary constraint.
    Default is null.
See also
  • SpatialGrid
Example
import { SPH } from '@three-blocks/core';
import { SphereGeometry, InstancedMesh, MeshStandardNodeMaterial } from 'three/webgpu';
import { storage, instanceIndex } from 'three/tsl';

const sph = new SPH({
  count: 2000,
  is3D: true,
  domainDimensions: new THREE.Vector3(20, 20, 20),
  h: 1.2,
  viscosityMu: 0.15,
  useMatrices: true
});

// Create instanced mesh for rendering particles
const geometry = new SphereGeometry(0.3, 8, 8);
const material = new MeshStandardNodeMaterial();
const positionNode = storage(sph.buffers.positions, 'vec3', sph.particleCount);
material.positionNode = positionNode.element(instanceIndex);
const mesh = new InstancedMesh(geometry, material, sph.particleCount);
// When useMatrices is enabled, you can feed instance matrices directly
mesh.instanceMatrix = sph.buffers.instanceMatrices.value;
scene.add(mesh);

// Simulation loop
async function animate() {
  await sph.step(renderer);
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

Properties

.sdfVolumeConstraint : SDFVolumeConstraint|null

.bvhVolumeConstraint : BVHVolumeConstraint|null

Methods

setDomainDimensions#

setDomainDimensions(dimensions : THREE.Vector3) : this

Manually set the simulation domain dimensions. Updates UBOs and synchronizes the spatial grid.

Parameters
dimensionsTHREE.Vector3
New domain dimensions.
Returns
this

setDomainFromObject#

setDomainFromObject(object : THREE.Object3D, options : Object) : this

Bind simulation domain to a Three.js object's world-space bounds. Particles will be constrained to the object's local space and follow its transforms.

Parameters
objectTHREE.Object3D
Target object (mesh or group).
optionsoptionalObject
Configuration options.
Default is {}.
  • paddingoptionalnumber | THREE.Vector3
    Extend domain bounds by padding.
    Default is 0.
  • autoUpdateoptionalboolean
    Update domain matrices every frame.
    Default is true.
  • simulationScaleoptionalnumber | THREE.Vector3
    Override domain scale for visualization.
    Default is null.
Returns
this

attachSpatialGrid#

attachSpatialGrid(grid : SpatialGrid) : this

Attach an external SpatialGrid instance for neighbor acceleration. Rebuilds compute passes to use grid-accelerated lookups.

Parameters
gridSpatialGrid
External SpatialGrid instance.
Returns
this

setSmoothingRadius#

setSmoothingRadius(radius : number) : this

Update the SPH smoothing kernel radius (h parameter). Recomputes kernel coefficients and syncs spatial grid cell size.

Parameters
radiusnumber
New smoothing radius (h).
Returns
this

setRestDensity#

setRestDensity(value : number|null|undefined) : this

Set rest density manually. Passing null/undefined re-enables auto rest density.

Parameters
valuenumber | null | undefined
Returns
this

setMass#

setMass(value : number) : this

Set particle mass. Recomputes auto rest density when enabled.

Parameters
valuenumber
Returns
this

setKernelScaleEnabled#

setKernelScaleEnabled(enabled : boolean) : this

Enable/disable automatic kernel radius scaling with domain transformations.

Parameters
enabledboolean
Whether to scale h with domain scale.
Returns
this

enableSpatialGrid#

enableSpatialGrid(options : Object) : this

Create and attach an internal spatial grid for neighbor acceleration. Automatically configures grid based on current domain and kernel radius.

Parameters
optionsoptionalObject
Options forwarded to SpatialGrid constructor.
Default is {}.
Returns
this

setSpatialGridEnabled#

setSpatialGridEnabled(enabled : boolean, options : Object) : this

Toggle spatial grid acceleration.

Parameters
enabledboolean
Enable (true) or disable (false) spatial grid.
optionsoptionalObject
Options passed to enableSpatialGrid() if enabling.
Returns
this

detachSpatialGrid#

detachSpatialGrid() : this

Detach and dispose of the spatial grid, reverting to naive O(N²) neighbor search.

Returns
this

syncSpatialGrid#

syncSpatialGrid() : this

Synchronize spatial grid configuration with current domain and kernel radius. Automatically called when domain or kernel changes.

Returns
this

step#

step(renderer : THREE.WebGPURenderer) : Promise<void>

Advance the simulation by one frame using GPU compute passes. Executes: grid update → density → pressure → forces → interaction → integration.

Parameters
rendererTHREE.WebGPURenderer
WebGPU renderer instance.
Returns
Promise<void>

attachGUI#

attachGUI(gui : Object, options : Object) : Object

Attach SPH parameters to a GUI for interactive tuning. Compatible with lil-gui, dat.gui, and Three.js Inspector.

Parameters
guiObject
GUI instance (e.g., new GUI() from lil-gui or renderer.inspector.createParameters()).
optionsoptionalObject
Configuration options.
Default is {}.
  • folderNameoptionalstring
    Name for the main folder.
    Default is 'SPH'.
  • openoptionalboolean
    Whether folders start open.
    Default is false.
Returns
Object — Object containing created GUI folders: { main, physics, simulation, domain, pointer }.

Type Definitions

SPHBuffers#

positions:THREE.InstancedBufferAttribute, velocities:THREE.InstancedBufferAttribute, densities:THREE.InstancedBufferAttribute, pressures:THREE.InstancedBufferAttribute, +4 more
Properties
positionsTHREE.InstancedBufferAttribute
Particle world positions (vec3).
velocitiesTHREE.InstancedBufferAttribute
Particle velocities (vec3).
densitiesTHREE.InstancedBufferAttribute
Computed particle densities (float).
pressuresTHREE.InstancedBufferAttribute
Computed particle pressures (float).
pressureForcesTHREE.InstancedBufferAttribute
Pressure gradient forces (vec3).
viscosityForcesTHREE.InstancedBufferAttribute
Viscosity forces (vec3).
prevVelocitiesoptionalTHREE.InstancedBufferAttribute
Previous frame velocities (optional, if useDirection enabled).
directionsoptionalTHREE.InstancedBufferAttribute
Smoothed directions (optional, if useDirection enabled).