threejs-worldgen

Procedural terrain and scenery for three.js and react-three-fiber. Each kind of thing you'd scatter or grow in an outdoor scene is its own small package, and every package shares one idea of where the ground is.

Website · Live demo · API docs

Docs map

Every package with its API reference, landing page and live demos, each demo in plain three.js and in React Three Fiber. Every package takes a Terrain (a mesh or a height function) the same way, and WORLDGEN.md has the design.

Package	API reference and landing page	Demos: three.js · R3F
threejs-heightfield Any mesh baked into a fast (x, z) => y lookup, with slope and ray-marching: the ground the other packages stand on.	threejs-heightfield threejs-heightfield/react Landing page	heightfield: three.js · R3F
threejs-biomes Seeded climate, mountains, rivers and 20 blended biomes, on a flat world or a planet, from orbit down to ant scale.	threejs-biomes threejs-biomes/react Landing page	terrain: three.js · R3F: not yet
threejs-water Oceans, rivers and lakes in WebGPU: one-draw-call seas from the beach to orbit, flowing rivers and real drainage.	threejs-water threejs-water/react Landing page	water: three.js · R3F: not yet
threejs-scatter Trees, rocks, anything: seamless blue-noise tiles streamed around the camera, pooled instancing, LODs and impostors.	threejs-scatter threejs-scatter/react Landing page	scatter: three.js · R3F: not yet
threejs-trees 29 procedural species grown by space colonisation, plus shrubs, flowers, ferns and rocks, with wind and weather.	threejs-trees threejs-trees/react Landing page	See threejs-scatter
threejs-grass Infinite, terrain-aware WebGPU grass: 12 presets, four LODs, wind, interaction and a terrain painter.	threejs-grass threejs-grass/react Landing page	grass: three.js · R3F corn: three.js · R3F
threejs-city Hamlets to cities where people live: a population model plans them, then tensor-field roads, lots, climate-matched buildings and lit facades.	threejs-city threejs-city/react Landing page	city: three.js · R3F population: three.js · R3F
threejs-props In development: street lights, power lines, mailboxes, fences and road surfaces, placed along your roads and drawn instanced.	threejs-props threejs-props/react Landing page	props: three.js · R3F
threejs-vehicles In development: seeded cars, trains, ships, aircraft and rockets that drive, sail, fly and launch, in a few draw calls.	threejs-vehicles threejs-vehicles/react Landing page	vehicles: three.js · R3F
threejs-fauna Procedural fish schools and bird flocks that live where they should, with no textures or models.	threejs-fauna threejs-fauna/react Landing page	fauna: three.js · R3F
threejs-weathering Seeded rain, snow, wind and lightning, wildfires that spread and regrow, and wet, snowy, burnt and damaged materials.	threejs-weathering threejs-weathering/react Landing page	weathering: three.js · R3F: not yet
threejs-sky A physically based sky from the ground to orbit: clouds, moon phases, Milky Way, meteors and a Keplerian solar system.	threejs-sky threejs-sky/react Landing page	sky: three.js · R3F: not yet
threejs-particles GPU particle systems for three.js WebGPU: compute-shader pools, seeded emitters, forces, lifetime curves, an optional particle/grid field, and lit smoke, blackbody flames and sparks.	threejs-particles threejs-particles/react	particles: three.js · R3F mpm: three.js · R3F mpm-lava: three.js · R3F mpm-snow: three.js · R3F mpm-water: three.js · R3F
threejs-worldgen Whole procedural worlds for three.js and react-three-fiber: biomes, terrain, water, forests, grass and cities in one component.	threejs-worldgen threejs-worldgen/react	No demo yet

Live demos

threejs-heightfield Any mesh baked into a fast (x, z) => y lookup, with slope and ray-marching: the ground the other packages stand on. Live demo · Landing page · API docs	threejs-biomes Seeded climate, mountains, rivers and 20 blended biomes, on a flat world or a planet, from orbit down to ant scale. Live demo · Landing page · API docs	threejs-water Oceans, rivers and lakes in WebGPU: one-draw-call seas from the beach to orbit, flowing rivers and real drainage. Live demo · Landing page · API docs
threejs-scatter Trees, rocks, anything: seamless blue-noise tiles streamed around the camera, pooled instancing, LODs and impostors. Live demo · Landing page · API docs	threejs-trees 29 procedural species grown by space colonisation, plus shrubs, flowers, ferns and rocks, with wind and weather. Live demo · Landing page · API docs	threejs-grass Infinite, terrain-aware WebGPU grass: 12 presets, four LODs, wind, interaction and a terrain painter. Live demo · Landing page · API docs
threejs-city Hamlets to cities where people live: a population model plans them, then tensor-field roads, lots, climate-matched buildings and lit facades. Live demo · Landing page · API docs	threejs-props In development: street lights, power lines, mailboxes, fences and road surfaces, placed along your roads and drawn instanced. Live demo · Landing page · API docs	threejs-vehicles In development: seeded cars, trains, ships, aircraft and rockets that drive, sail, fly and launch, in a few draw calls. Live demo · Landing page · API docs
threejs-fauna Procedural fish schools and bird flocks that live where they should, with no textures or models. Live demo · Landing page · API docs	threejs-weathering Seeded rain, snow, wind and lightning, wildfires that spread and regrow, and wet, snowy, burnt and damaged materials. Live demo · Landing page · API docs	threejs-sky A physically based sky from the ground to orbit: clouds, moon phases, Milky Way, meteors and a Keplerian solar system. Live demo · Landing page · API docs

Development

npm install          # links the workspaces
npm run dev          # demos at http://localhost:5173 and /r3f.html, running straight from packages/*/src
npm run typecheck
npm test             # node --test packages/*/test/*.test.ts
npm run build        # every package's dist/, in dependency order
npm run build:site   # landing page, demos and API docs into site/
npm run readme:cards # regenerate the docs map and demo cards in README.md and packages/*/README.md

New package: add packages/<name>/ with its own package.json (build and prepublishOnly scripts), then list it in workspaces (after its dependencies), in the paths in tsconfig.json, in the aliases in example/vite.config.ts and in the entryPoints in typedoc.json.

Package conventions

Every package follows the same shape, so worlds compose and every setting is live:

Parametric: one options object per feature, every number in it has a default, and set(partial) / reset(full) change it at runtime. Options are plain JSON (no functions or class instances except where noted), so they can be saved, shared, sent to a worker and bound to a GUI.
Deterministic: everything derives from seed and world position. The same options give the same world.
Plain three.js first: an imperative class with .object (add it to your scene), update() (once per frame) and dispose(). Async setup goes in static create().
Optional React Three Fiber: src/react.tsx (the ./react export) wraps each class in a component whose props are the options, calls reset(props) on every render and update() in useFrame. react and -three/fiber are optional peer dependencies; the core never imports them.
WebGPU: three/webgpu and TSL node materials, like threejs-grass.
Instancing and buffer geometry: anything that repeats is an InstancedMesh, BatchedMesh or InstancedBufferGeometry with per-instance attributes, never a mesh per object. Geometry is built straight into typed-array BufferAttributes, static parts are merged into few draw calls, materials are shared and varied per instance in TSL, and bounding spheres are set explicitly.
Plain TypeScript: no constructor parameter properties, enums or namespaces (Node runs the tests by stripping types).
Imports: relative imports end in .ts; other packages are imported by name (they resolve to src/ in development through the worldgen-source export condition).
Tests: packages/<name>/test/*.test.ts, run by node --test (no DOM, no GPU), for the pure logic.

Releasing

Each package is versioned and released on its own. Tags are <package>@<version>:

npm version minor -w threejs-grass        # bumps packages/grass/package.json only
git commit -am "threejs-grass 0.3.0"
git tag threejs-grass@0.3.0 && git push origin main threejs-grass@0.3.0

The tag starts .github/workflows/release.yml, which checks the tag against the package version, runs typecheck and the tests, publishes that one package to npm (using the NPM_TOKEN repo secret) and creates a GitHub release. Release a package's dependencies first. For example, threejs-grass needs its threejs-heightfield range on npm.

To publish every package from your machine instead, run npm run publish:all (scripts/publish-all.sh; add --dry-run to preview). It builds once, then publishes each package whose version isn't on npm yet, dependencies first. Packages marked "private": true and versions already on npm are skipped, so it's safe to re-run. It authenticates with NPM_TOKEN if that's set, otherwise your npm login, otherwise it asks. Set NPM_OTP if your account requires a 2FA code to publish. It doesn't create tags or GitHub releases.

License

Apache-2.0

threejs-worldgen