Start here

Installation

NatureGL River ships as a folder with a runnable demo, the library source and a prebuilt ES module with TypeScript declarations. Pick whichever of the three integration paths suits your build.

#Requirements

three.js	`>= 0.180` as a peer dependency. Developed and tested on r186
Renderer	`THREE.WebGLRenderer` with WebGL2. The shaders are GLSL; there is no WebGPU or TSL path
Camera	`THREE.PerspectiveCamera`. The depth pipeline reads its near, far and field of view
Units	Metres, seconds and radians. Preset angles are in degrees
Node	18 or newer, only for the demo and the build scripts

#Run the demo first

#Install

bash

cd naturegl-river
npm install

#Start the dev server

bash

npm run dev

It opens http://localhost:5183/demo/: the mountain-stream valley, authored with the API. The demo page lists every control.

#Build or test (optional)

bash

npm run build   # library -> build/, static demo -> dist/
npm test        # headless GPU smoke test of every preset -> test-results/*.png

#What's in the folder

naturegl-river/

├── src/the library: no DOM UI, no scenery│   ├── RiverSystem.jsthe facade: create, author, update, render, queries│   ├── bodies/River, Lake, Waterfall│   ├── core/RiverPath, WaterMap, Floaters, procedural textures│   ├── materials/patchMaterial (wet band + caustics)│   ├── shaders/GLSL as template strings│   └── config/QualityLevels.js, presets/├── build/prebuilt ESM bundle + source map + .d.ts├── demo/the mountain-stream demo (npm run dev)├── examples/basic/minimal Vite integration├── examples/cdn/plain JS + import map against build/├── docs/API.mdthe API reference as Markdown└── scripts/smoke.mjsheadless real-GPU test

#Add it to your project

three is always an external import. Your bundler or import map has to resolve it.

Copy build/ into your project, for example as lib/naturegl-river/:

import { RiverSystem } from './lib/naturegl-river/index.js';

This is the prebuilt bundle with a source map and index.d.ts, so editors pick up the types.

Copy src/ if you want to read or change the source. It runs with or without a bundler, because the shaders are plain template strings.

import { RiverSystem } from './lib/naturegl-river/src/index.js';

Alias the package name to the source. This is what the demo does.

vite.config.js

import { resolve } from 'node:path';

export default {
  resolve: {
    alias: { 'naturegl-river': resolve(__dirname, 'lib/naturegl-river/src/index.js') },
  },
};

import { RiverSystem } from 'naturegl-river';

#Without a bundler

An import map resolves three from a CDN, and the library comes from build/:

index.html

<script type="importmap">
  { "imports": {
      "three": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.module.js",
      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.0/examples/jsm/"
  } }
</script>
<script type="module">
  import * as THREE from 'three';
  import { RiverSystem } from './lib/naturegl-river/index.js';   // the build/ folder
  // … the same code as the quick start
</script>

To try the bundled example, run npx http-server . in the package root and open /examples/cdn/.