Start here

Installation

NatureGL Fire 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 r186
Renderer	`THREE.WebGLRenderer` with WebGL2 and `EXT_color_buffer_float`. There is no WebGPU path
Camera	`THREE.PerspectiveCamera` or `THREE.OrthographicCamera`
Node	18 or newer, only for the demo and the build scripts

FireSystem throws naturegl-fire: WebGL2 with EXT_color_buffer_float is required when the renderer can't render to float targets. Check it yourself first if you want a fallback:

const ok = renderer.capabilities.isWebGL2 && renderer.extensions.has('EXT_color_buffer_float');

#Run the demo first

#Install

bash

cd naturegl-fire
npm install

#Start the dev server

bash

npm run dev

It opens http://localhost:5186/demo/: a moonlit courtyard with a fire in the middle and the full control panel. The demo page lists every control.

#Build or test (optional)

bash

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

#What's in the folder

naturegl-fire/

├── src/the library: no DOM, no scenery│   ├── FireSystem.jsthe facade: create, update, render, composite, presets│   ├── sim/FireSimulation (solver), Emitters, Embers, shapes│   ├── render/VolumeCompositor (raymarch, TAA, haze), PostProcess (bloom, ACES)│   ├── lighting/FireLight: GPU probe → fireLight / fillLight│   ├── shaders/one GLSL file per GPU pass│   ├── materials/patchReflectiveMaterial (wet floors)│   ├── core/pass runner, noise, blackbody ramp│   └── config/QualityLevels.js, defaults.js, presets/├── build/prebuilt ESM bundle + .d.ts├── demo/the full demo app (courtyard scenery, UI)├── examples/basic/minimal Vite integration├── examples/cdn/plain JS + import map└── scripts/smoke.mjs (npm test) and shots.mjs

#Add it to your project

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

import { FireSystem } from './lib/naturegl-fire/index.js';

The bundle has a source map and .d.ts files next to it, so editors get types and go-to-definition.

The source is plain ES modules with JSDoc types. Copy src/ and let your bundler compile it.

import { FireSystem } from './vendor/naturegl-fire/src/index.js';

Point the package name at the source. This is what the demo does, so the demo is also a working reference.

vite.config.js

import { defineConfig } from 'vite';

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

import { FireSystem } from 'naturegl-fire';

#Plain JS with an import map

No bundler: map three and three/addons/ to a CDN and import the prebuilt module. The three/addons/ entry is required, because the build imports MeshSurfaceSampler and BufferGeometryUtils from it.

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 { FireSystem, createTeepeeGeometry } from './lib/naturegl-fire/index.js';
  // …same code as the quick start
</script>

examples/cdn/index.html is this setup. Serve the package root with any static server, for example npx http-server ., and open /examples/cdn/.