Three.js Blocks

Home
Documentation
Examples
Tools

PBF

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

Position Based Fluids (PBF) particle simulation optimized for GPU compute with optional spatial grid acceleration.

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 (legacy).
    Default is 100.0.
  • viscosityMuoptionalnumber
    Legacy viscosity (unused in PBF solver).
    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.
  • solverIterationsoptionalnumber
    Constraint iterations per frame.
    Default is 2.
  • lambdaEpsilonoptionalnumber
    PBF lambda denominator epsilon.
    Default is 50.0.
  • corrKoptionalnumber
    Artificial pressure strength (sCorr).
    Default is 0.001.
  • corrNoptionalnumber
    Artificial pressure exponent.
    Default is 4.0.
  • corrDeltaQMultiplieroptionalnumber
    sCorr reference distance fraction.
    Default is 0.3.
  • 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.
  • gridUpdatePerIterationoptionalboolean
    Rebuild grid each iteration.
    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 { PBF } from '@three-blocks/core';
import { SphereGeometry, InstancedMesh, MeshStandardNodeMaterial } from 'three/webgpu';
import { storage, instanceIndex } from 'three/tsl';

const pbf = new PBF({
  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(pbf.buffers.positions, 'vec3', pbf.particleCount);
material.positionNode = positionNode.element(instanceIndex);
const mesh = new InstancedMesh(geometry, material, pbf.particleCount);
// When useMatrices is enabled, you can feed instance matrices directly
mesh.instanceMatrix = pbf.buffers.instanceMatrices.value;
scene.add(mesh);

// Simulation loop
async function animate() {
  await pbf.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 PBF 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

setGridUpdatePerIteration#

setGridUpdatePerIteration(enabled : boolean) : this

Control whether the spatial grid rebuilds each solver iteration or once per step.

Parameters
enabledboolean
When true, rebuild on every solver iteration (slower, more accurate).
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 PBF 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 'PBF'.
  • openoptionalboolean
    Whether folders start open.
    Default is false.
Returns
Object — Object containing created GUI folders: { main, physics, simulation, domain, pointer }.

Type Definitions

PBFBuffers#

positions:THREE.InstancedBufferAttribute, velocities:THREE.InstancedBufferAttribute, densities:THREE.InstancedBufferAttribute, pressures:THREE.InstancedBufferAttribute, +5 more
Properties
positionsTHREE.InstancedBufferAttribute
Particle world positions (vec3).
velocitiesTHREE.InstancedBufferAttribute
Particle velocities (vec3).
densitiesTHREE.InstancedBufferAttribute
Computed particle densities (float).
pressuresTHREE.InstancedBufferAttribute
Stores PBF lambda values per particle (float).
pressureForcesTHREE.InstancedBufferAttribute
Accumulated position corrections (vec3).
prevPositionsTHREE.InstancedBufferAttribute
Previous-frame positions used to derive velocities (vec3).
viscosityForcesTHREE.InstancedBufferAttribute
Scratch buffer retained for compatibility (vec3).
prevVelocitiesoptionalTHREE.InstancedBufferAttribute
Previous frame velocities (optional, if useDirection enabled).
directionsoptionalTHREE.InstancedBufferAttribute
Smoothed directions (optional, if useDirection enabled).