voxolithRocks
@voxolith/gen-rock: boulders, outcrops and pebbles from fractured, noise-displaced superellipsoids, with strata, cracks, moss, lichen and snow.
@voxolith/gen-rock makes rocks. A rock is a noise-displaced superellipsoid, round, blocky or
slab-like, cleaved along a few fracture planes, with a surface pass that hands out mottled tones,
sedimentary strata on a tilted bedding plane, cracks, moss on the upward faces, lichen, a damp band
at the base and optional snow. outcrop tumbles smaller rocks against a main mass, kept as one
connected piece.
import { seededRandom } from "@voxolith/renderer/core";
import { generateRock, PRESETS } from "@voxolith/gen-rock";
const { entity, stats } = generateRock(PRESETS.boulder, seededRandom(42));
// stats.rocks, stats.moss, stats.cracks; the anchor is the base centre, raised by shape.sinkIt is the template for every solid-mass generator: see writing a generator.
How it works
Mass. The main rock is a blob with
half-extents from size, aspect (height) and elongation (depth). exponent picks the family:
2 round, 4 a rounded block, 8 nearly cubic. roughness and detail set the bumps; grit adds a
voxel or so of fine texture, which breaks the contour terraces bumps leave on shallow slopes.
Fractures. facet cleaves the
mass along facets planes, each removing up to facetDepth of it. A lumpy ellipsoid reads as a
potato; flat breaks meeting at hard edges read as stone. 0 leaves a water-worn cobble. The voxels on
each fracture face are tagged, so each break can take one even tone.
Extras. With cluster above 0, smaller rocks (clusterScale of the main one, with a random
spread) are placed touching it on the same floor, so the group reads as fallen together. Each rock
is shaped and fractured in its own scratch volume and then unioned in, so one rock's planes never
slice its neighbour, and the overlap keeps the whole one piece.
Surface. Every surface voxel is given a role from a snapshot, so no decision reads a neighbour
already repainted: light, mid and dark tones from two scales of value noise (mottle), one tone
per fracture face a notch lighter than weathered stone, darker undersides and crevices, strata
bands along a plane tilted by strataTiltDeg, thin cracks where a signed noise field crosses
zero, a damp band at the base (wet), lichen patches (lichen), moss on upward faces, denser
low down (moss), and snow on top faces with clear sky above (snow).
Anchor at the bottom centre, raised by sink of the height from the rock's real bottom, so the
rock sits in the ground rather than on it. The interior stays the mid tone: the renderer never sees
it, but a game that breaks a rock open will.
Parameters split into shape (which voxels exist) and look (which role each surface voxel gets).
The stone skin (species: granite, sandstone, basalt, limestone or slate) only changes the default
colours of the ten roles, so the same shape restyles by palette without regenerating.
Presets
| preset | character |
|---|---|
boulder | granite, rounded, nine fractures, some moss and lichen |
sandstone | bedded and blocky, weathered flat, with strong strata |
basalt | angular and near-cubic, many sharp fractures, little life |
limestone | pale, pitted and heavily cracked |
mossy | a low granite boulder under thick moss, with a damp base |
outcrop | a slate mass with five smaller rocks tumbled against it, on a steep bedding plane |
pebbles | a small group of water-worn cobbles, no fractures, sunk into the ground |
Finer scales
At 20, 50 and 100 voxels per metre the rock is refined with the smooth rule: it rounds off its voxel
steps and takes a rough, grainy surface, the mid tone breaks into light and dark speckle, hairline
cracks a voxel deep run across the faces, and moss and lichen become ragged patches. It has no
loose roles. See scales and refinement.
Development
bun run --cwd generators/rock verify # connectivity, determinism, knobs, share codes
bun run --cwd generators/rock preview species # contact sheets into previews/ (also: seeds, roughness, angularity)
bun run --cwd generators/rock gen # bake .vox files into out/Rock
voxolith/rock starts from the boulder preset.
- Id
voxolith/rock- Version
- 0.2.1
- Scales
- 10, 20, 50, 100 voxels per metre
Parameters
Shape
| Parameter | Path | Range | Default |
|---|---|---|---|
Size longest horizontal extent of the main rock, in voxels (10 per metre) | shape.size | 8 to 160 | 48 |
Height ratio height as a fraction of size: 1 is as tall as wide, 0.4 a slab | shape.aspect | 0.2 to 1.4, step 0.05 | 0.8 |
Depth ratio depth as a fraction of size; below 1 the footprint is an oval | shape.elongation | 0.4 to 1.4, step 0.05 | 0.85 |
Angularity 2 is round, 4 a rounded block, 8 nearly cubic | shape.exponent | 1.6 to 9, step 0.1 | 2.6 |
Roughness surface displacement as a fraction of radius; higher is lumpier | shape.roughness | 0 to 0.4, step 0.01 | 0.08 |
Bump size bumps per radius: low is a few great lumps, high many finer ones | shape.detail | 0.5 to 5, step 0.1 | 1.6 |
Fractures flat broken faces; 0 is a water-worn cobble | shape.facets | 0 to 20 | 9 |
Fracture depth most of the rock one fracture can shear away, as a fraction; higher cuts deeper faces | shape.facetDepth | 0.08 to 0.5, step 0.01 | 0.32 |
Grit fine surface texture; breaks up terracing | shape.grit | 0 to 2.5, step 0.1 | 0.3 |
Extra rocks smaller rocks nestled against the main one, overlapping so the whole stays one piece | shape.cluster | 0 to 10 | 0 |
Extra size size of the extra rocks as a fraction of the main one | shape.clusterScale | 0.15 to 0.9, step 0.01 | 0.45 |
Sink fraction of the height buried: the anchor sits this far up the rock | shape.sink | 0 to 0.5, step 0.01 | 0.12 |
Look
| Parameter | Path | Range | Default |
|---|---|---|---|
Stone stone colouring: granite, sandstone, basalt, limestone or slate | species | granite, sandstone, basalt, limestone, slate | granite |
Mottle contrast between the light and dark tones across the surface | look.mottle | 0 to 1, step 0.05 | 0.5 |
Strata bands bedding bands per rock height; 0 disables banding | look.strata | 0 to 12, step 0.5 | 0 |
Strata tilt tilt of the bedding planes in degrees | look.strataTiltDeg | -45 to 45, step 1 | 0 |
Cracks dark cracks over the surface; higher widens them, 0 for none | look.cracks | 0 to 1, step 0.05 | 0.25 |
Moss moss cover on upward-facing surfaces | look.moss | 0 to 1, step 0.05 | 0.35 |
Lichen pale lichen patches on any face | look.lichen | 0 to 1, step 0.05 | 0.2 |
Wet base height of the dark damp band at the base, as a fraction of height | look.wet | 0 to 0.5, step 0.01 | 0.12 |
Snow snow cover on upward-facing surfaces | look.snow | 0 to 1, step 0.05 | 0 |
Presets
| Parameter | boulder | sandstone | basalt | limestone | mossy | outcrop | pebbles |
|---|---|---|---|---|---|---|---|
| Size | 48 | 48 | 48 | 48 | 48 | 64 | 22 |
| Height ratio | 0.8 | 0.55 | 0.9 | 0.8 | 0.7 | 0.6 | 0.65 |
| Depth ratio | 0.85 | 0.85 | 0.85 | 0.85 | 0.85 | 0.7 | 0.85 |
| Angularity | 2.6 | 4 | 3 | 2.2 | 2.6 | 3.2 | 2.6 |
| Roughness | 0.08 | 0.06 | 0.04 | 0.14 | 0.1 | 0.08 | 0.1 |
| Bump size | 1.6 | 2.4 | 3 | 2.8 | 1.6 | 1.6 | 1.6 |
| Fractures | 9 | 6 | 14 | 8 | 5 | 11 | 0 |
| Fracture depth | 0.32 | 0.32 | 0.38 | 0.32 | 0.22 | 0.32 | 0.32 |
| Grit | 0.3 | 0.25 | 0.15 | 0.6 | 0.3 | 0.3 | 0.5 |
| Extra rocks | 0 | 0 | 0 | 0 | 0 | 5 | 7 |
| Extra size | 0.45 | 0.45 | 0.45 | 0.45 | 0.45 | 0.42 | 0.7 |
| Sink | 0.12 | 0.12 | 0.12 | 0.12 | 0.12 | 0.12 | 0.2 |
| Stone | granite | sandstone | basalt | limestone | granite | slate | granite |
| Mottle | 0.5 | 0.5 | 0.3 | 0.35 | 0.5 | 0.5 | 0.5 |
| Strata bands | 0 | 5 | 0 | 0 | 0 | 7 | 0 |
| Strata tilt | 0 | 8 | 0 | 0 | 0 | 22 | 0 |
| Cracks | 0.25 | 0.15 | 0.4 | 0.55 | 0.25 | 0.25 | 0.1 |
| Moss | 0.35 | 0.05 | 0.08 | 0.2 | 0.85 | 0.3 | 0.15 |
| Lichen | 0.2 | 0.1 | 0.15 | 0.35 | 0.3 | 0.2 | 0.1 |
| Wet base | 0.12 | 0.12 | 0.12 | 0.12 | 0.25 | 0.12 | 0.12 |
| Snow | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
Roles
Voxel values are these roles, in this order (value 1 is the first). The colours are the defaults; a host maps each role to a palette slot and can restyle it.
- 1Rock light
rock.light - 2Rock mid
rock.mid - 3Rock dark
rock.dark - 4Strata
strata - 5Crack
crack - 6Moss
moss - 7Moss dark
moss.dark - 8Lichen
lichen - 9Wet base
wet - 10Snow
snow
Outcrop
voxolith/outcrop is the same generator starting from the outcrop preset.
- Id
voxolith/outcrop- Version
- 0.2.1
- Scales
- 10, 20, 50, 100 voxels per metre
Parameters
Shape
| Parameter | Path | Range | Default |
|---|---|---|---|
Size longest horizontal extent of the main rock, in voxels (10 per metre) | shape.size | 8 to 160 | 64 |
Height ratio height as a fraction of size: 1 is as tall as wide, 0.4 a slab | shape.aspect | 0.2 to 1.4, step 0.05 | 0.6 |
Depth ratio depth as a fraction of size; below 1 the footprint is an oval | shape.elongation | 0.4 to 1.4, step 0.05 | 0.7 |
Angularity 2 is round, 4 a rounded block, 8 nearly cubic | shape.exponent | 1.6 to 9, step 0.1 | 3.2 |
Roughness surface displacement as a fraction of radius; higher is lumpier | shape.roughness | 0 to 0.4, step 0.01 | 0.08 |
Bump size bumps per radius: low is a few great lumps, high many finer ones | shape.detail | 0.5 to 5, step 0.1 | 1.6 |
Fractures flat broken faces; 0 is a water-worn cobble | shape.facets | 0 to 20 | 11 |
Fracture depth most of the rock one fracture can shear away, as a fraction; higher cuts deeper faces | shape.facetDepth | 0.08 to 0.5, step 0.01 | 0.32 |
Grit fine surface texture; breaks up terracing | shape.grit | 0 to 2.5, step 0.1 | 0.3 |
Extra rocks smaller rocks nestled against the main one, overlapping so the whole stays one piece | shape.cluster | 0 to 10 | 5 |
Extra size size of the extra rocks as a fraction of the main one | shape.clusterScale | 0.15 to 0.9, step 0.01 | 0.42 |
Sink fraction of the height buried: the anchor sits this far up the rock | shape.sink | 0 to 0.5, step 0.01 | 0.12 |
Look
| Parameter | Path | Range | Default |
|---|---|---|---|
Stone stone colouring: granite, sandstone, basalt, limestone or slate | species | granite, sandstone, basalt, limestone, slate | slate |
Mottle contrast between the light and dark tones across the surface | look.mottle | 0 to 1, step 0.05 | 0.5 |
Strata bands bedding bands per rock height; 0 disables banding | look.strata | 0 to 12, step 0.5 | 7 |
Strata tilt tilt of the bedding planes in degrees | look.strataTiltDeg | -45 to 45, step 1 | 22 |
Cracks dark cracks over the surface; higher widens them, 0 for none | look.cracks | 0 to 1, step 0.05 | 0.25 |
Moss moss cover on upward-facing surfaces | look.moss | 0 to 1, step 0.05 | 0.3 |
Lichen pale lichen patches on any face | look.lichen | 0 to 1, step 0.05 | 0.2 |
Wet base height of the dark damp band at the base, as a fraction of height | look.wet | 0 to 0.5, step 0.01 | 0.12 |
Snow snow cover on upward-facing surfaces | look.snow | 0 to 1, step 0.05 | 0 |
Presets
| Parameter | boulder | sandstone | basalt | limestone | mossy | outcrop | pebbles |
|---|---|---|---|---|---|---|---|
| Size | 48 | 48 | 48 | 48 | 48 | 64 | 22 |
| Height ratio | 0.8 | 0.55 | 0.9 | 0.8 | 0.7 | 0.6 | 0.65 |
| Depth ratio | 0.85 | 0.85 | 0.85 | 0.85 | 0.85 | 0.7 | 0.85 |
| Angularity | 2.6 | 4 | 3 | 2.2 | 2.6 | 3.2 | 2.6 |
| Roughness | 0.08 | 0.06 | 0.04 | 0.14 | 0.1 | 0.08 | 0.1 |
| Bump size | 1.6 | 2.4 | 3 | 2.8 | 1.6 | 1.6 | 1.6 |
| Fractures | 9 | 6 | 14 | 8 | 5 | 11 | 0 |
| Fracture depth | 0.32 | 0.32 | 0.38 | 0.32 | 0.22 | 0.32 | 0.32 |
| Grit | 0.3 | 0.25 | 0.15 | 0.6 | 0.3 | 0.3 | 0.5 |
| Extra rocks | 0 | 0 | 0 | 0 | 0 | 5 | 7 |
| Extra size | 0.45 | 0.45 | 0.45 | 0.45 | 0.45 | 0.42 | 0.7 |
| Sink | 0.12 | 0.12 | 0.12 | 0.12 | 0.12 | 0.12 | 0.2 |
| Stone | granite | sandstone | basalt | limestone | granite | slate | granite |
| Mottle | 0.5 | 0.5 | 0.3 | 0.35 | 0.5 | 0.5 | 0.5 |
| Strata bands | 0 | 5 | 0 | 0 | 0 | 7 | 0 |
| Strata tilt | 0 | 8 | 0 | 0 | 0 | 22 | 0 |
| Cracks | 0.25 | 0.15 | 0.4 | 0.55 | 0.25 | 0.25 | 0.1 |
| Moss | 0.35 | 0.05 | 0.08 | 0.2 | 0.85 | 0.3 | 0.15 |
| Lichen | 0.2 | 0.1 | 0.15 | 0.35 | 0.3 | 0.2 | 0.1 |
| Wet base | 0.12 | 0.12 | 0.12 | 0.12 | 0.25 | 0.12 | 0.12 |
| Snow | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
Roles
Voxel values are these roles, in this order (value 1 is the first). The colours are the defaults; a host maps each role to a palette slot and can restyle it.
- 1Rock light
rock.light - 2Rock mid
rock.mid - 3Rock dark
rock.dark - 4Strata
strata - 5Crack
crack - 6Moss
moss - 7Moss dark
moss.dark - 8Lichen
lichen - 9Wet base
wet - 10Snow
snow
See the API reference for generateRock and the parameter types.
Grass
@voxolith/gen-grass: ground cover (grass, meadow with flowers, reeds with seed heads, arching ferns, dry grass) as blades that each reach the ground.
Buildings
@voxolith/gen-building: cottages, farmhouses, townhouses, towers and barns from a shape grammar, with textured walls, furnished openings and coursed roofs.