Start here

Installation

NatureGL Weather 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 against 0.186
Renderer	`THREE.WebGLRenderer` with WebGL2 and `EXT_color_buffer_float`. There is no WebGPU or TSL version
Node	18 or newer, only for the demo and the build scripts
Camera	`THREE.PerspectiveCamera`. Rain and snow wrap around this camera
Units	Metres, seconds and radians. Colours are linear RGB

#Run the demo first

#Install

bash

cd naturegl-weather
npm install

#Start the dev server

bash

npm run dev

It opens http://localhost:5184/demo/: the village square from weatherpro.html, with every preset, slider and toggle. The demo page lists the controls. The same server also serves examples/basic/ and examples/cdn/.

#Build or test (optional)

bash

npm run build   # library -> build/, static demo + examples -> dist/
npm test        # headless real-GPU smoke test: every preset -> test-results/*.png + fps

npm test fails on console errors, so it doubles as a check that your GPU and browser are supported.

Script	What it does
`npm run dev`	Vite dev server: landing page, `demo/`, `examples/basic/`, `examples/cdn/`
`npm run build:lib`	`src/` → `build/index.js` + `index.js.map` + `.d.ts` (`three` stays external)
`npm run build:demo`	Static demo and examples → `dist/`
`npm run build`	Both
`npm test`	Headless smoke test of every preset

#What's in the folder

naturegl-weather/

├── src/the library: no DOM UI, no scenery│   ├── index.jspublic exports│   ├── WeatherSystem.jsthe facade│   ├── rain/snow/        camera-following particles│   ├── lightning/bolts, flashes, strike and thunder events│   ├── fog/post/         height fog and the HDR pipeline behind render()│   ├── surface/wetness, puddles, snow cover (patchMaterial)│   ├── occlusion/the top-down shelter map│   ├── audio/synthesized rain, wind and thunder│   ├── core/shaders/     shared uniforms, GLSL as template strings│   └── config/QualityLevels.js, presets/ (one file per preset)├── build/prebuilt ESM bundle + source map + .d.ts├── demo/the village-square demo (UI, scenery, sky model)├── examples/basic/minimal Vite integration├── examples/cdn/plain JS + import map against build/├── scripts/smoke.mjs (npm test), shots, compare and perf helpers└── docs/API.mdthe API reference as Markdown

#Add it to your project

Copy build/ into your project, for example as lib/naturegl-weather/, and import from it. three stays an external import, so your bundler or an import map resolves it.

import { WeatherSystem } from './lib/naturegl-weather/index.js';

Types come with it in index.d.ts, and the source map points back at src/.

src/ is plain ES modules with JSDoc. The GLSL lives in .glsl.js template strings, so it runs with or without a bundler.

import { WeatherSystem } from './vendor/naturegl-weather/src/index.js';

Choose this if you want to read or patch the shaders in place.

Point an alias at the source. The demo itself uses this path.

vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: { 'naturegl-weather': '/path/to/naturegl-weather/src/index.js' },
  },
});

import { WeatherSystem } from 'naturegl-weather';

#Without a bundler

An import map resolves three and its addons from a CDN. The library comes from your copy of 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 { WeatherSystem } from './lib/naturegl-weather/index.js';
</script>

examples/cdn/index.html is a complete page. Serve the package root with any static server, such as npx http-server ., and open /examples/cdn/.

`examples/cdn/`: a patched ground and a wooden hut under the `snowfall` preset, loaded through an import map. Click to cycle presets.

#Next

Quick startRain, puddles and dry ground under a roof in one page of code.The demoEvery key, slider and toggle in the village demo.API referenceEvery option, method, subsystem and event.