
## Particle system

PG: <Playground id="#544N0Q#23" title="Particle system" description="Example of a particle system rendered as a fluid"/>

This example shows how a standard particle system can be rendered as a fluid.

To enable fluid rendering of a particle system, simply do:

```javascript
const fluidRenderer = scene.enableFluidRenderer() ;
fluidRenderer.addParticleSystem(particleSystem);
```

| particle system | The same particle system rendered as fluid |
|-----------------|-----------------------------------|
|![image](/img/features/fluidrenderer/demo_psys.webp!488)|![image](/img/features/fluidrenderer/demo_psys_fluid.webp!488)|

If you use the **Generate Diffuse Texture** parameter:

![image](/img/features/fluidrenderer/demo_psys_wdiffuse.webp)

With the generated diffuse texture being:

![image](/img/features/fluidrenderer/demo_psys_diffuse.webp)

## Particle custom shape

PG: <Playground id="#XMXDAA#112" title="Particle custom shape" description="Example of a custom particle system rendered as a fluid"/>

Note: It may take a little while to load, please be patient.

This demo shows how to use `fluidRenderer.addCustomParticles()` to render the famous Dude as a list of particles and have the particles break down using a simple simulation (NOT a fluid simulation!).

Click the **Start** button to make the particles fall apart.

The particles are generated using the `PointsCloudSystem` class, which is also capable of generating vertex colors, so the **Generate diffuse texture** function is enabled by default in this demo.

Starting position:

![image](/img/features/fluidrenderer/demo_dude_start.webp)

Image toward the end of the demo:

![image](/img/features/fluidrenderer/demo_dude_end.webp)

## Pre-computed particles - rendering only

PG: <Playground id="#XMXDAA#113" title="Precomputed particles" description="Example of a pre-computed animation of particles rendered as a fluid"/>

This demo shows a precomputed animation of about 70000 particles. The precomputed particle positions come from https://github.com/ttnghia/RealTimeFluidRendering/releases/tag/Datasets (**SphereDropGround** dataset).

Note:
* the position files have been optimized to be smaller and have been compressed into a single zip file. As such, the quality is not the best you can get because of the quantization used to make the files smaller (especially visible at the end of the animation, when the liquid does not fluctuate much). However, it does allow the demo to load very quickly.
* if you want to get the best quality, search for `_readZipped` and set it to `false`.

![image](/img/features/fluidrenderer/demo_precomputed.webp)

## Box, sphere and wall

PG: <Playground id="#XMXDAA#114" title="Box, sphere and wall" description="Example of real fluid simulation with dragging box and sphere"/>

This demo is the first to use a basic fluid simulator to simulate fluid movement (see the `FluidSimulator` class in the PG). Since the simulation is run in JavaScript, only a few thousand particles can be simulated at most, depending on the power of your computer; hence the relatively large size of these particles.

The wall and the sphere can be moved with the mouse. You can also rotate the box using the cursor keys (click on the screen first to focus on the scene!). You can also play with the **Check box bounds** and **Auto rotate box** settings.

![image](/img/features/fluidrenderer/demo_box_1.webp)

**Check box bounds** not checked:

![image](/img/features/fluidrenderer/demo_box_2.webp)

## Height map

PG: <Playground id="#XMXDAA#115" title="Height map" description="Example of real fluid simulation with a height map"/>

Note: the terrain may take a little time to load, please be patient.

This demo demonstrates the use of a height map as a collision object, in addition to the wall and sphere from the previous demo (you can only drag the wall in this demo, the sphere is moved automatically).

![image](/img/features/fluidrenderer/demo_heightmap_1.webp)

Instead of a basic water jet, you can inject particles according to some predefined shapes:

![image](/img/features/fluidrenderer/demo_heightmap_2.webp)

Notes:
* these shapes were generated offline using [SPlisHSPlasH Volume Sampler](https://splishsplash.readthedocs.io/en/latest/VolumeSampling.html)
* the typical command line (used to generate *Dragon 0.04*): `.\VolumeSampling.exe -i .\Dragon_50k.obj -o Dragon_50k.vtk --viscosity 0.05 -r 0.04 -s "2.5 2.5 2.5"`
* Then, [ParaView](https://www.paraview.org/) was used to load the .vtk file produced by the above command line and to generate the .txt file that you can find at `https://github.com/Popov72/FluidRendering/tree/main/src/assets/particles`. For example: [Dragon 0.04](https://github.com/Popov72/FluidRendering/blob/main/src/assets/particles/dragon_04.txt)

The values 0.03 / 0.04 in the names are the particle sizes used to generate the shapes. The smaller the value, the more particles the object has. For example, *Dragon 0.04* has 4507 particles, but *Dragon 0.03* has 10625. Even on a fast computer, you probably won't be able to run at 60fps using the 0.03 flavors...

![image](/img/features/fluidrenderer/demo_heightmap_3.webp)

![image](/img/features/fluidrenderer/demo_heightmap_4.webp)

## Glass

PG: <Playground id="#XMXDAA#116" title="Glass" description="Example of real fluid simulation of wine filling a glass"/>

Note: This may take a little while to load, so please be patient.

Nothing really new in this demo except that it uses a cut hollow sphere (both for rendering and collision) for the top end of the glass (you can move the glass by dragging the top end).

![image](/img/features/fluidrenderer/demo_glass_1.webp)

![image](/img/features/fluidrenderer/demo_glass_2.webp)

## Mesh SDF

PG: <Playground id="#XMXDAA#165" image="/img/playgroundsAndNMEs/pg-XMXDAA-117.webp" title="Mesh SDF" description="Example of real fluid simulation collision with mesh SDF"/>

Note: It may take a while to load, please be patient. Also, you must set `scene.useRightHandedSystem = true` for this demo to work (as of Babylon v6.49.0, due to changes made in https://github.com/BabylonJS/Babylon.js/pull/14884).

This one demonstrates the use of a custom mesh as collision object (both meshes can be moved by dragging them with the mouse).

The SDF representation of the mesh is generated offline using [SDFGen](https://github.com/christopherbatty/SDFGen). I have forked my own version to improve the .obj loading code a bit and to provide the binary exe file, so that users do not have to compile the project themselves (Windows only): [forked SDFGen](https://github.com/Popov72/SDFGen).

The **Dragon** and **High heels** SDF files used in the demo are located in the [SDF directory](https://github.com/Popov72/FluidRendering/blob/main/src/assets/sdf/).

![image](/img/features/fluidrenderer/demo_meshsdf_1.webp)

![image](/img/features/fluidrenderer/demo_meshsdf_2.webp)

Note: **High heels** model by cebraVFX found on Sketchfab (https://sketchfab.com/3d-models/high-heels-1561c09fc45349d680e48e3e007b64e0)



The fluid renderer has been implemented as a scene component (like the depth renderer, for example), so you can enable it with `scene.enableFluidRenderer()` (or use `fluidRenderer = scene.enableFluidRenderer()` to get a reference to the renderer) and disable it with `scene.disableFluidRenderer()`.

## Main classes

The fluid renderer handles two entities: `FluidRenderingObject` and `FluidRenderingTargetRenderer`:
* `FluidRenderingObject` is an object you want to render as a fluid: either a particle system (`FluidRenderingObjectParticleSystem`) or a raw list of particles (vertex coordinates - `FluidRenderingObjectCustomParticles`).
* `FluidRenderingTargetRenderer` is the class that generates the depth, thickness and diffuse textures and renders the object(s) as a fluid.

You can associate multiple fluid rendering objects with a single `FluidRenderingTargetRenderer`, or have multiple instances of `FluidRenderingTargetRenderer` and distribute your fluid objects among those target renderers. For performance reasons, it is better to use a single target renderer for multiple objects rather than creating a new target renderer instance for each object. However, if the target renderer settings need to differ depending on the object being rendered, you will need to create additional target renderers.

## Rendering objects as a fluid

For particle systems (`ParticleSystem` and `GPUParticleSystem`), you can enable fluid rendering by doing:

```javascript
const fluidRenderer = scene.enableFluidRenderer();
const renderObject = fluidRenderer.addParticleSystem(particleSystem);

const fluidObject = renderObject.object;
const targetRenderer = renderObject.targetRenderer;
```

Then you can use `fluidObject` and `targetRenderer` to customize the display of the particle system.

To create a fluid object for a list of custom particles, use `fluidRenderer.addCustomParticles()`:
```typescript
public addCustomParticles(
    buffers: { [key: string]: FloatArray },
    numParticles: number,
    generateDiffuseTexture?: boolean,
    targetRenderer?: FluidRenderingTargetRenderer,
    camera?: Camera
): IFluidRenderingRenderObject
```
Note that the `buffers` object must contain at least one **position** buffer! If you choose to generate a diffuse texture, you must also provide a **color** buffer.

## Per-particle size

By default, all the particles of a fluid object have the same size, set by `fluidObject.particleSize`. Since Babylon.js v9.25, you can use the size of each particle instead:

```javascript
BABYLON.FluidRenderingObject.UsePerParticleSizeAttribute = true;
```

The flag is static and is read when the effects of a fluid object are created, so set it before you add the objects to the fluid renderer. It is `false` by default, so existing scenes are not affected.

The size of a particle comes from:

* `ParticleSystem`: the size of the particle, with its scale (`minSize`/`maxSize`, size gradients, `minScaleX`/`maxScaleX`, `minScaleY`/`maxScaleY`).
* `GPUParticleSystem`: same as `ParticleSystem`, since Babylon.js v9.26.1.
* Custom particles: a **size** buffer with two floats (width and height) per particle:

```javascript
const sizes = new Float32Array(numParticles * 2);
// fill sizes[i * 2] (width) and sizes[i * 2 + 1] (height)

BABYLON.FluidRenderingObject.UsePerParticleSizeAttribute = true;
const renderObject = fluidRenderer.addCustomParticles({ position: positions, color: colors, size: sizes }, numParticles, true);
```

If a custom particle object has no **size** buffer, it keeps using `particleSize`. You can add the buffer later with `fluidObject.addBuffers({ size: sizes })`, the effects are recreated for you. To animate the sizes, update the buffer every frame with `fluidObject.vertexBuffers["size"].update(sizes)`.

Custom particles with their own size: <Playground id="#DBSRBB#1" title="Per-particle size with custom particles" description="Custom particles rendered as a fluid, each one with its own size"/>

A GPU particle system with a size gradient: <Playground id="#M9FSIH#2" title="Per-particle size with a GPU particle system" description="GPU particle system with a size gradient rendered as a fluid"/>

## Particle texture and the diffuse texture

When a particle system is added with `generateDiffuseTexture` set to `true`, the fluid object renders the particle system in the diffuse texture with alpha blending (`useTrueRenderingForDiffuseTexture` is `false` by default). Textures made for additive blending, like `flare.png`, are black outside of the glow, so the diffuse texture shows dark squares around the particles. To fix that, set `fluidObject.useTrueRenderingForDiffuseTexture = true` so that the blend mode of the particle system is used, or use a texture with an alpha channel.

## Custom shading

The fluid renderer is made for transparent liquids, but you can change the shading of the final pass without changing Babylon.js. The fluid rendering shaders are processed like post processes, so `PostProcess.RegisterShaderCodeProcessing` with the `"FluidRendering"` name lets you rewrite the shader code (`processFinalCode`), add uniforms (`defineCustomBindings`) and set them every frame (`bindCustomBindings`).

This example replaces the transparent shading by an opaque, foam-like shading, with a `foamBrightness` uniform you can animate (GLSL, for WebGL):

```javascript
let foamBrightness = 0.8;

BABYLON.PostProcess.RegisterShaderCodeProcessing("FluidRendering", {
    defineCustomBindings: (name, defines, uniforms) => {
        if (uniforms.indexOf("foamBrightness") === -1) {
            uniforms.push("foamBrightness");
        }
        return defines;
    },
    bindCustomBindings: (name, effect) => {
        effect.setFloat("foamBrightness", foamBrightness);
    },
    processFinalCode: (name, type, code) => {
        const cut = code.indexOf("vec3 refractionDir=");
        if (cut < 0) {
            return code;
        }
        const mainStart = code.indexOf("void main");
        return (
            code.slice(0, mainStart) +
            "uniform float foamBrightness;\n" +
            code.slice(mainStart, cut) +
            "float foamNdotL = max(0.0, dot(lightDir, normal));\n" +
            "vec3 finalColor = diffuseColor * (foamBrightness + 0.6 * foamNdotL) + vec3(specular) * 0.28;\n" +
            "glFragColor = vec4(finalColor, 1.0);\n}"
        );
    },
});
```

Note: the callbacks are called for all the fluid rendering shaders (depth, thickness, blur, final pass), so only change the one you want. Here the final fragment shader is found by its `refractionDir` variable. On WebGPU the shaders are written in WGSL, so the patch must be adapted to that language.

Opaque foam with an animated brightness: <Playground id="#OX4D4N#0" title="Opaque foam shading" description="Fluid renderer with a custom opaque shading and an animated foam brightness"/>

## Debugging

The `FluidRendererGUI` class allows you to see the fluid objects and target renderers registered with the fluid renderer, and to modify their properties easily:

![Fluid Debugging](/img/features/fluidrenderer/gui_debugging.webp)

This class is not integrated into Babylon.js because the inspector will be updated instead, so in the meantime you can find it [here](/features/featuresDeepDive/particles/fluid_renderer/fluid_gui).



As of version 5.36.0, a new fluid rendering component has been added to the `Scene` class, allowing you to render particles (`ParticleSystem`, `GPUParticleSystem`, or some custom vertex buffers) as a fluid.

![Fluid Rendering](/img/features/fluidrenderer/fluid_intro.webp)  



## Particle Properties

Once the PCS mesh is built, unless immutable, it can respond to changes in the properties of each particle. Existing properties are shown in the table below.

| Property | Type | Default |
| ---- | ---- | ----|
| position | Vector3 | (0, 0, 0) |
| rotation | Vector3 | (0, 0, 0) |
| rotationQuaternion | Vector3 | undefined |
| velocity | Vector3 | (0, 0, 0) |
| color | Vector4 | (1, 1, 1, 1) |
| pivot | Vector3  | (0, 0, 0) |
| uvs | Vector2  | (0,0) |
| translateFromPivot | boolean |false |
| parentId | integer | null |
| idx | integer (read only) | index of particle |
| groupId | integer (read only) | group number for a particle |


If you set a particle rotation quaternion, its rotation property will then be ignored.

New properties can be initialized.

**Note:** Since point particles **_always_** face the camera, setting the rotation of a particle only has any effect in two cases:

1. The rotation of a particle parent will rotate its children about itself;
2. A pivot is set for the particle.



### Initialising Particles

When using `addPoints`, particle properties can be set in the passed function. The `addSurfacePoints` and `addVolumePoints` methods obviously set the position and color properties of the particles, but you may still want to set the initial values of other particle properties.

This can be done using `initParticles`. To do this, iterate over all the particles by using the `nbParticles` property, and follow the call to this function with a call to `setParticles()`. For example:

```javascript
pcs.initParticles = function() {
   for (let p = 0; p < pcs.nbParticles; p++) {
       pcs.particles[p].velocity = BABYLON.Vector3.Zero();
       pcs.particles[p].acceleration = pcs.particles[p].position.scale(0.01);
   }
}

pcs.addSurfacePoints(model, 10000, BABYLON.PointColor.Color);
pcs.buildMeshAsync().then(() => {
  model.dispose()
  pcs.initParticles();
  pcs.setParticles();
});
```

### Updating Particles

Once the appropriate particle properties are initialized, the `updateParticles` method can be used. Unlike `initParticles`, this function is called by `setParticles` and already receives a particle as an argument. The `setParticles` method will execute only after the PCS mesh has been built, so it can safely be placed inside a render loop to produce an animation. For example:

```javascript
pcs.updateParticle = function(particle) {
  particle.velocity.addInPlace(particle.acceleration);
  particle.position.addInPlace(particle.velocity);
}

scene.registerBeforeRender(() => {
  pcs.setParticles();
});
```

**Note:** All particle positions are expressed in the *local space* of the PCS mesh. 

The particle `pivot` vector is also in the *local space* of the PCS mesh. By default, rotations around a pivot are calculated by translating the particle to the pivot point, then rotating it, and then applying the inverse translation. By setting the particle property `translateFromPivot` to `true` (default `false`), rotations are calculated using only the initial translation followed by the rotation, leaving the particle at the translated location.  

<Playground id="#UI95UC#12" title="Simple Animation" description="Simple example of animating a point cloud system."/>

In the following playground, the particle pivots in the top PCS are set relative to the particle position, and in the lower one they are set in the same place.
<Playground id="#UI95UC#14" title="Pivot Animation Example 1" description="Simple example of animating the pivot point of a point cloud system."/>

In this playground, the only difference is that the lower PCS has `translateFromPivot` set to `true`.
<Playground id="#UI95UC#15" title="Pivot Animation Example 2" description="Simple example of animating the pivot point of a point cloud system."/>

This playground animates the mesh, not the particles.
<Playground id="#UI95UC#16" title="Immutable Animation" description="Simple example of point cloud system immutable animation."/>

This playground loads meshes from a file, converts them to particles, and animates them.
<Playground id="#UI95UC#17" title="Loaded Mesh Animation" description="Simple example of point cloud system animation based on loaded mesh animation."/>

### UVs

While setting and changing particle colors is straightforward, doing the same for UVs is a little more complex. Using `BABYLON.PointColor.UV` as a parameter within `addSurfacepoints` or `addVolumePoints` will set the UVs automatically based on the passed mesh.

You can also set the UV value for each particle using the function passed to `addPoints`. To make the texture map correctly, the UV values should relate in some way to the positional values for each particle. To apply the texture with these UVs, both the `emissiveColor` and `emissiveTexture` for the PCS mesh material must be set after the mesh is built.

**Note:** Only use emissive.

For example

```javascript
var myfunc = function(particle) { 
    var x = Math.random();
    var y = Math.random();
    var z = 0;
    particle.position = new BABYLON.Vector3(x, y, z);
    //Relate uv values to positional values
    particle.uv.x = x;
    particle.uv.y = y; 
    }
    pcs.addPoints(5000, myfunc);

    pcs.buildMeshAsync().then(() => {
      pcs.mesh.material.emissiveColor = new BABYLON.Color3(0, 0, 0);
      pcs.mesh.material.emissiveTexture = myTexture;
    });
```

It is possible to use a texture atlas, but you need to customize and calculate the more complex relationship between positional and UV values.

<Playground id="#UI95UC#23" title="UV With Added Points" description="Simple example of updating the UVs and adding points of a point cloud system."/>
<Playground id="#UI95UC#24" title="UV With Texture Atlas" description="Simple example of updating the UVs of a point cloud system with textured atlas."/>

### Recycling Particles

You can write your own code to recycle particles using `recycleParticle`, which can be called from within `updateParticle`. For example:

```javascript
pcs.recycleParticle = function(particle) {
    particle.position = BABYLON.Vector3.Zero();
    particle.velocity = BABYLON.Vector3.Zero();
    particle.heightLim = 4 + 0.5 * Math.random();
}

pcs.updateParticle = function(particle) {
    if (particle.position.y > particle.heightLim) {
      this.recycleParticle(particle);
    }
    particle.velocity.addInPlace(particle.acceleration);
    particle.position.addInPlace(particle.velocity);
}
```

<Playground id="#UI95UC#19" title="Recycling Animations" description="Simple example of recycling animations of a point cloud system."/>

### Particle Parenting  

Each particle can be given another particle as a parent.  
The parent must be created before the child particle. This means the parent must have a lower index ID (`particle.idx`) than the current particle. So the first particle in the pool (`idx = 0`) cannot have a parent. To give a parent to a particle, just set its property `parentId` to the parent index ID value. 

```javascript
if (particle.idx > 0) {
    particle.parentId = particle.idx - 1; // the previous particle becomes the parent of the current one
}
```
To un-parent a particle, just set `.parentId` back to `null` which is the default value.  

When a particle has a parent, its position and rotation are then expressed in its parent's local space.  
```javascript
if (particle.idx > 0) {
    particle.parentId = particle.idx - 1; // the previous particle becomes the parent of the current one
    // the particle position and rotation are expressed in the previous particle space, this one being already 
    // rotated and translated from the yet previous particle. Etc.
    particle.rotation.z = 0.01;
    particle.position.x = 1.0;
}
```
 <Playground id="#UI95UC#18" title="Parent Animation" description="Simple example of animating a point cloud system parent."/>

### Particle Intersections
     
The PCS provides a simple way to deal with intersections between a particle and other meshes. As this feature consumes more memory and CPU, do not include it unless necessary.

To use it, call the method `intersectsMesh(target)` (`target` is a mesh) for any particle to check whether it intersects the _target_.  
It will simply return `true` or `false` depending on whether the particle intersects the target.    
  
```javascript
if (particle.intersectsMesh(anyMesh)) { 
  // change properties of particle
}
```
By default, the check is carried out on the mesh's (AABB) bounding box. If you want to use the mesh's bounding sphere, add the parameter `true`.
```javascript
if (particle.intersectsMesh(mesh, true) {
    // change properties of particle
}; 
```

<Playground id="#UI95UC#20" title="Recycling Particle Collisions" description="Simple example of recycling particle collisions of a point cloud system."/>
<Playground id="#UI95UC#21" title="Mesh Colliding With Point Cloud" description="Simple example of a mesh colliding with a point cloud."/>


Fluid Renderer

Coming next

Fluid Rendering Demos

Learn how to use the fluid renderer component to display particle systems as a fluid

Using the Fluid Renderer

Learn how to use the fluid renderer component to display particle systems as a fluid

Fluid Rendering GUI

GUI classes for fluid rendering projects.

Technical Implementation Details

Learn how the fluid renderer component has been implemented in Babylon.js.