Troubleshooting

The common problems, what causes them, and the fix for each.

It throws "WebGL2 with EXT_color_buffer_float is required"

The solver renders into float targets, which needs this WebGL2 extension. Some mobile GPUs and software renderers lack it. Check renderer.capabilities.isWebGL2 && renderer.extensions.has('EXT_color_buffer_float') before creating the system, and show a fallback if it's false.

The fire is cut off in a straight line

The fire only exists inside domain. A flat top or side means the flame or smoke reached the box's edge. Make the box bigger (or taller), move the emitters toward its centre, or reduce wind, buoyancy or smoke. The last few cells at the sides and top fade out on purpose.

Nothing burns

Check that the emitter is inside the domain and enabled, and that its temperature is above about 0.55, where fuel burns fully. Low fuel or a very high cooling also kills the flame. Remember that loadPreset() removes emitters you added before it.

The fire looks washed out, or the scene looks different under render()

render() does its own exposure and ACES tone mapping and ignores renderer.toneMapping and toneMappingExposure. Adjust fire.params.exposure, bloomStrength and bloomThreshold, or use composite() and tone-map yourself.

The fire slows down when the frame rate drops

The step is clamped to 1/30 s for stability, so below 30 fps the simulation runs slower than real time instead of blowing up. Drop a quality tier or shrink the volume scale.

The flame ghosts or trails when the camera moves fast

The volume TAA reprojects through the plane of the flame centroid. Lower params.temporalClip (less ghosting, more noise) or temporalBlend. Call fire.reset() after a camera cut to drop the history, although this also clears the fluid.

No embers with composite()

composite() doesn't draw embers. Add them to your scene with scene.add(fire.embers), so they're depth-tested against your geometry like everything else.

No reflection in my wet floor

The floor needs patchReflectiveMaterial(), a low roughness, and to be the domain's floor plane (the bottom of the box). params.reflections must be true. With composite(), keep the patched material's alpha in the colour texture you pass in.

The fire light doesn't cast shadows

Enable renderer.shadowMap.enabled, and set castShadow / receiveShadow on your meshes. Also check that you didn't pass addLights: false without adding the lights yourself.

The flame restarts when I change quality

setQualityLevel() rebuilds the grid, so the fluid starts again from empty. Emitters and obstacles are kept. This is expected.

#Known limitations

WebGL2 with EXT_color_buffer_float is required. There's no WebGPU path.
The fire only exists inside its domain box. Moving domain means creating a new system, and the fluid doesn't scroll with the camera.
setQualityLevel() rebuilds the grid, so the fire restarts.
Mesh emitters share one temperature and smoke setting. Their fuel only scales their weight.
A sphere or box obstacle is fully solid, with no partial occupancy, so obstacles thinner than a cell are lost.
render() replaces renderer.render() and applies its own ACES tone mapping. Use composite() if you already have a tone-mapped pipeline.
Wet-floor reflections only work on materials patched with patchReflectiveMaterial, and only on the domain's floor plane.