/Fluid-JS

A JavaScript library that allows for easy deployment of WebGL rendered fluid simulations.

Primary LanguageJavaScript

🌊 Fluid.js 🌊

A JavaScript library that allows for easy deployment of WebGL rendered fluid simulations based on the Navier-Stokes Equations for Incompressible Flow.

Set up is easy and customization is rich, get a beautifully rendered WebGL fluid simulation running in your responsive web project in less than five minutes.

This library is an extension on the fluid simulation implemented by PavelDoGreat.

This project is in early-development and open to contribution. Do not use this library in your production level project unless you have properly evaluated the performance and browser compatibility.

Getting Started

CDN
<script src="https://cdn.jsdelivr.net/npm/fluid-canvas@latest"></script>
Terminal
npm i fluid-canvas
Clone
git clone https://github.com/malik-tillman/Fluid-JS.git

Usage

Add Fluid.js to your <head>
<head>
  <meta charset="UTF-8">
  <title>Fluid JS Example</title>

  
  <script src="https://cdn.jsdelivr.net/npm/fluid-canvas@latest"></script>
</head>
Create a canvas element to render the fluid

Give it an identifier to reference in javascript

<body>
    . . .
    
    <canvas id="renderSurface"></canvas>
</body>
Now we can initialize the canvas as our fluid's surface
import Fluid from 'fluid';

const canvas = document.getElementById('renderSurface');
let myFluid = new Fluid(canvas);

myFluid.activate();

Or do it with an inline script tag

 <script>
    const canvas = document.getElementById('renderSurface');
    const myFluid = new Fluid(canvas);

    myFluid.activate();
 </script>
You may also want to add some styles
body {
  margin: 0;
}

canvas {
  width: 100vw;
  height: 100vh;
}
Full Example Code
<html>
  <head>
    <title>Fluid JS Example</title>

    <script src="https://cdn.jsdelivr.net/npm/fluid-canvas@latest"></script>
    
    <style>
      body {
          margin: 0;
      }

      #renderSurface {
          width: 100vw;
          height: 100vh;
      }
    </style>
  </head>

  <body>
      <canvas id="renderSurface"></canvas>

      <script>
          const canvas = document.getElementById('renderSurface');
          let myFluid = new Fluid(canvas);
          myFluid.activate();
      </script>
  </body>
</html>

Configuring Fluid Behavior

There are two ways you can configure the fluid simulation's behavior.

Mapping Behaviors

Map multiple behavior properties at once.

.mapBehaviors does not dynamically assign values. This means you must .activate your fluid every time you map new behavior properties.

Syntax
fluid.mapBehaviors({
    property: value
});
Example
fluid.mapBehaviors({
    sim_resolution: 128,
    dye_resolution: 512,

    paused: false,
    embedded_dither: true,

    dissipation: .97,
    velocity: .98,
    pressure: .8,
    pressure_iteration: 20,
    curl: 0,
    emitter_size: 0.5,

    render_shaders: true,
    multi_color: true,

    render_bloom: false,
    bloom_iterations: 8,
    bloom_resolution: 256,
    intensity: 0.8,
    threshold: 0.6,
    soft_knee: 0.7,

    background_color: { r: 15, g: 15, b: 15 },
    transparent: false
});

fluid.activate();

These are the main behavior configurations. Documentation on each property and how to use them is currently in the works.

Dynamic Assignment

This method allows for most fluid behaviors to be adjusted on-the-fly. This means you can change a property without having to re-activate your simulation.

Syntax
fluid.PARAMS.property = value;
Example
fluid.PARAMS.curl = 25;

Documentation in-progress

Changing Background

You may set the background mode to 'solid', 'gradient', or 'image'. Applying a background requires you specify a mode and a value for that mode. You also have the option of adding addition configurations for the background.

The value is the same it would be if you was using regular CSS.

Syntax
fluid.applyBackground(mode, value, options);
Example
// Solid Background
fluid.applyBackground('solid', '#e66465');

// Gradient Background
fluid.applyBackground('gradient', '#e66465, #9198e5', 'linear');
fluid.applyBackground('gradient', '#e66465, #9198e5', 'radial');
fluid.applyBackground('gradient', '#f69d3c, #3f87a6', 'conic');
fluid.applyBackground('gradient', '#f69d3c, #3f87a6 50px', 'repeating-linear');
fluid.applyBackground('gradient', '#f69d3c, #3f87a6 50px', 'repeating-radial');

// Image Background
fluid.applyBackground(
    'image', 
    './image.jpg', 
    {
        repeat: 'repeat',
        position: 'center',
        size: '100px',
        color: 'none'  
    }
);

Documentation in-progress

Setting Dither

By default, the simulation will utilize the embedded dither. But you have the option to use a custom image.

For this set .PARAM.embedded_dither to false. This will search for a dither image in ROOT/assets/dither.png.

fluid.PARAMS.embedded_dither = false;

You may also change this default path with .setDitherURL.

fluid.setDitherURL('../images/myDither.png');

Documentation in-progress

Browser Support

These browsers are guaranteed working as per my testing:

  • Chrome
  • FireFox
  • Safari
  • Opera
  • Edge (IE11)

References