threejs-biomes
v0.1.0
Published
Seeded climate, 20 blended biomes, mountains, rivers and streaming LOD terrain for three.js
Maintainers
Readme
threejs-biomes
Procedural worlds for three.js: seeded climate, continents, mountain ranges, rivers, volcanoes and 20 blended biomes,
on an infinite flat world or a whole planet, with streaming level-of-detail terrain from orbit down to the ground an
ant walks on. Everything is a deterministic function of seed and position (it looks random, but it never is), and
every setting is live.
npm i threejs-biomes threethree.js
import * as THREE from 'three/webgpu'
import { World, WorldTerrain, SurfaceControls } from 'threejs-biomes'
import TerrainWorker from 'threejs-biomes/worker?worker' // Vite; optional, builds chunks off the main thread
const renderer = new THREE.WebGPURenderer({ antialias: true, reversedDepthBuffer: true })
await renderer.init()
const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(55, innerWidth / innerHeight)
const world = new World({ seed: 'pangaea', surface: 'sphere', radius: 60_000 })
const controls = new SurfaceControls(camera, renderer.domElement, world) // 1 cm … orbit
const terrain = await WorldTerrain.create({ world, camera, scene, createWorker: () => new TerrainWorker() })
renderer.setAnimationLoop(() => {
controls.update()
terrain.setOrigin(controls.origin) // floating origin: precise at any scale
renderer.render(scene, camera)
})
world.height(120, -40) // metres, in the local frame (flat world, or around `origin` on a planet)
world.biomeAt(120, -40).name // 'Temperate grassland'
world.set({ mountains: { height: 1600 } }) // live: terrain rebuilds progressivelyReact Three Fiber
import { useWorld, WorldTerrain } from 'threejs-biomes/react'
function Scene() {
const world = useWorld({ seed: 7, mountains: { height: 1200 }, rivers: { enabled: true } })
return <WorldTerrain world={world} lodFactor={2.5} material={{ debug: 'none' }} />
}react and @react-three/fiber are optional peer dependencies; the core never imports them.
What's in the box
| Export | What it does |
|---|---|
| World | Climate fields, continents, mountains, hills, volcanoes, rivers, biome weights, ground mix, height modifiers. sampleAt, height, sample, biomeAt, frameAt, set/reset, onChange |
| BIOMES | The 20 biomes as plain JSON data: climate centre, ground mix, terrain shaping, grass preset, vegetation and rock scatter tables |
| LocalFrame | A locally flat (x, z) => y view of any spot on a planet, for packages that think in height functions |
| WorldTerrain | Streaming quadtree terrain (grid on flat worlds, cube-sphere on planets), worker builds, floating origin, TSL ground material |
| SurfaceControls | Camera controls from 1 cm to orbit, with automatic near/far planes |
| FloatingOrigin | Keeps the camera near render-space zero at planet scale |
| renderWorldMap | Top-down RGBA maps: biomes, height, temperature, moisture, rivers, ground |
| noise | hash4, mulberry32, 3D gradient noise with derivatives, fbm, ridged, erodedFbm, warp, cellular |
The 20 biomes
Deep ocean · beach and coast · temperate grassland · temperate deciduous forest · temperate rainforest · boreal forest (taiga) · tundra · glacier and ice sheet · alpine meadow · mountain peaks · hot desert (erg) · rocky desert and badlands (mesa) · savanna · tropical rainforest · tropical dry forest · Mediterranean shrubland · cold steppe · wetland · mangrove · volcanic.
Climate biomes are placed on a Whittaker diagram (temperature × moisture) and blended by distance in climate space. Ocean, coast, mangrove, wetland, alpine, peaks, glacier and volcanic override them where their conditions hold. Each biome can shape the ground: dunes, mesa terraces, tundra hummocks, flattened wetlands and glacier crevasses.
World options
| Group | Highlights (defaults) |
|---|---|
| seed, surface, radius, origin, seaLevel | 1, 'plane', 120000 m, [20, 0] (lat, lon), 0 |
| continents | scale 6000, octaves 5, warp 0.4, landBias 0.12, curve (continentalness → height) |
| mountains | height 950, scale 2400, octaves 8, sharpness 2, rangeScale 7000, threshold 0.5 |
| hills / detail / micro | eroded fBm hills (55 m), ground detail (1.6 m), ant-scale micro relief (5 cm, down to mm) |
| rivers | scale 3400, width, valleyWidth, depth 3, valleyDepth 0.7, maxHeight 320 |
| climate | base/equator/pole temperatures, lapseRate 6.5 °C/km, moisture, rain shadow, wind |
| rules | biome blend softness, coast height, treeline, glacier temperature, wetland and mangrove rules |
| volcanoes | chance 0.05, regionSize 14000, radius 2200, height 1100, crater 0.14 |
| ground | rock slope, snow temperature, sand band, material colours |
| biomes | the biome table (replace or edit freely) |
| modifiers | data-only height edits (circle, path) — cities flatten their roads and lots here |
Terrain options
resolution 33 (vertices per chunk side) · rootSize 4096 · lodFactor 2 · minChunkSize 1 (use 0.25 for ants) ·
viewDistance 24000 · skirt 0.03 · buildBudget 6 ms · castShadow · receiveShadow · origin ·
material: { debug: 'none' | 'biomes' | 'lod' | 'splat', detail, detailScale, detailDistance, octaves, bump, blend, cavity, microShadow,
brightness, saturation, haze, hazeHeight, hazeColor, sunColor, sunDirection, gravelColor, iceColor, ashColor, wireframe }.
The ground shader height-blends eight materials (biome soil, ash, mud, sand, gravel, rock, ice, snow), each with its own
procedural albedo, roughness and relief from a tileable 3D noise volume. octaves noise layers follow the pixel footprint,
so the ground has sharp detail from centimetres to orbit; fixed-size features (pebbles, ripples, cracks, sparkle) fade in
within detailDistance. Lighting adds curvature/relief occlusion (cavity), micro-shadowing and height-based aerial
perspective (haze, hazeHeight; set haze: 0 to use scene fog instead). Keep sunDirection in sync with your sun.
Below sea level the floor is tinted as deep or shallow water (sea, seaColor, shallowColor) so oceans read from
orbit without a water package. WorldTerrain.create({ textures }) takes optional PBR texture sets per ground material
(soil, ash, mud, sand, gravel, rock, ice, snow: map, normalMap, roughnessMap, aoMap, size in
metres), sampled triplanar; anything missing stays procedural.
For planets, earthLike(radius) is a preset: continents sized to the radius (~70 % ocean), mountain belts, temperature
by latitude with ice caps, and circulation-belt moisture (equatorial rainforest, subtropical deserts):
new World({ ...earthLike(60_000), seed: 7 }).
License
Apache-2.0
