voxolithBushes
@voxolith/gen-bush: multi-stemmed shrubs, thickets, brambles, flowering shrubs and hedges, with thorns, berries, blossom and four seasons.
@voxolith/gen-bush grows shrubs. A bush is not a small tree: it has no trunk. Several stems leave
the ground together and lean outward, which is what gives a shrub its vase silhouette. A thicket
scatters more clumps of stems around the centre, at unequal sizes, so undergrowth reads as
undergrowth rather than as a ring of tidy bushes.
import { seededRandom } from "@voxolith/renderer/core";
import { generateBush, PRESETS } from "@voxolith/gen-bush";
const { entity, stats } = generateBush(PRESETS.thicket, seededRandom(42));
// entity.kind === "bush"; the anchor is the centre of the base, at ground levelBranch growth, clump placement, canopy carving and exposure shading come from gen-kit, shared with the tree and grass generators; what differs is the base.
How it works
Stems from the ground. Each clump seeds a ring of level-0 stems within baseSpreadRatio of
its centre, each leaning out by leanDeg (plus a random spread) at a random azimuth. With
clumps above 0, satellite clumps are placed around the centre at 55% to 105% of the main
clump's size, which keeps a thicket from looking like identical bushes in a ring.
Skeleton. growBranches grows side shoots on each stem by the preset's branch levels, with a
little gravity and a little upward bend toward the tip, then fitHeight scales it to height
less the room the foliage needs on top.
Wood. Stems of at least a voxel radius are exact capsules; thinner ones are 6-connected DDA lines, padded to two voxels when they are nearly one thick. Shrub stems are thin, so most of the plant takes a flat per-stem twig colour; only the thicker basal wood gets a bark pattern. Thorns are added outward from the surface, so they break the silhouette instead of speckling it.
Foliage. Leaf clumps are placed along the outermost branch level and, larger, at every tip.
Their density falls with health. The mass is hollowed below its hull, carved for sky holes and
shaded by exposure, with accent and dead leaves chosen per clump.
Flowers, fruit and snow. Blossom (in spring) and berries recolour the outer rim of whole clumps, never single voxels, or they read as confetti. In winter, deciduous species drop their leaves and take snow wherever a column of sky is clear above; the hedge stays green.
Prune everything not 6-connected to the ground, then crop with the anchor at the base centre.
Parameters split into shape and foliage (which voxels exist) and look (which role each gets).
Voxel values are tuned for a 64-tall bush and scale with shape.height. Roles are stems (dark, mid,
light), twigs, thorns, leaves (light, mid, dark, edge, accent, dead), blossom, berries and snow;
seasons change the palette behind the roles, not the roles themselves.
Presets
| preset | character |
|---|---|
bush | a single rounded shrub |
thicket | several staggered clumps of unequal size, for undergrowth |
bramble | long arching canes, thorns and berries |
flowering | blossom on whole clumps in spring |
hedge | clipped: dense, low and wide, with almost no visible structure; evergreen, so it keeps its leaves in winter |
Finer scales
At 20, 50 and 100 voxels per metre, leaves, blossom, berries and snow refine from the coarse voxels (leaves as single leaves in the coarse shade, thorns as pairs of short needles); the stems are redrawn from the skeleton as thin capsule shells, much slimmer than the coarse bush could draw them, with faint streaks along them. Leaves, blossom, berries, snow and thorns are loose roles. See scales and refinement.
Development
bun run --cwd generators/bush verify # connectivity to the ground, budget, determinism
bun run --cwd generators/bush preview species # contact sheets into previews/ (also: seeds, seasons)
bun run --cwd generators/bush gen # bake .vox files into out/Bush
voxolith/bush starts from the bush preset.
- Id
voxolith/bush- Version
- 0.1.0
- Scales
- 10, 20, 50, 100 voxels per metre
Parameters
Shape
| Parameter | Path | Range | Default |
|---|---|---|---|
Height overall height in voxels (10 per metre); the whole shrub scales with it | shape.height | 12 to 120 | 64 |
Stem lean how far the stems lean outward from vertical, in degrees; higher opens the vase wider | shape.leanDeg | 0 to 50, step 1 | 22 |
Stem length stem length as a fraction of height before the shrub is fitted to its height; longer stems give a leggier, more open shrub | shape.lengthRatio | 0.4 to 1.3, step 0.02 | 0.82 |
Stem radius stem base radius as a fraction of height; higher gives thicker, woodier stems | shape.radiusRatio | 0.008 to 0.05, step 0.001 | 0.022 |
Extra clumps extra, smaller clumps of stems scattered around the centre; 0 is a single shrub | shape.clumps | 0 to 8 | 0 |
Foliage
| Parameter | Path | Range | Default |
|---|---|---|---|
Clump radius leaf clump radius in voxels at height 64; larger clumps give a fuller, rounder mass | foliage.clusterRadius | 1.5 to 8, step 0.1 | 3.6 |
Leaf density fraction of leaf clumps kept; lower shows more of the twigs | foliage.density | 0.1 to 1, step 0.02 | 1 |
Sky holes size of the sky holes carved through the leaves; 0 carves none | foliage.macroThreshold | 0 to 0.6, step 0.01 | 0.2 |
Look
| Parameter | Path | Range | Default |
|---|---|---|---|
Season leaf colours and density; in winter every species but the hedge is bare, with snow on its upper faces | look.season | spring, summer, autumn, winter | summer |
Health 1 healthy; lower thins the leaves and turns more of them dead brown | look.health | 0 to 1, step 0.05 | 0.9 |
Thorns thorn spikes on a fraction of the stem surface; 0 is a smooth shrub | look.thorns | 0 to 0.5, step 0.01 | 0 |
Berries fraction of leaf clumps whose outer rim carries berries | look.berryFraction | 0 to 0.5, step 0.01 | 0 |
Presets
| Parameter | bush | thicket | bramble | flowering | hedge |
|---|---|---|---|---|---|
| Height | 64 | 56 | 64 | 64 | 48 |
| Stem lean | 22 | 28 | 34 | 18 | 12 |
| Stem length | 0.82 | 0.82 | 1.05 | 0.82 | 0.82 |
| Stem radius | 0.022 | 0.022 | 0.013 | 0.022 | 0.022 |
| Extra clumps | 0 | 4 | 0 | 0 | 2 |
| Clump radius | 3.6 | 3.2 | 2.6 | 3.4 | 3.8 |
| Leaf density | 1 | 1 | 0.62 | 1 | 1 |
| Sky holes | 0.2 | 0.2 | 0.3 | 0.2 | 0.08 |
| Season | summer | summer | summer | spring | summer |
| Health | 0.9 | 0.9 | 0.9 | 0.9 | 0.9 |
| Thorns | 0 | 0 | 0.22 | 0 | 0 |
| Berries | 0 | 0 | 0.12 | 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.
- 1Stem dark
stem.dark - 2Stem mid
stem.mid - 3Stem light
stem.light - 4Twig
twig - 5Twig dark
twig.dark - 6Thorn
thorn· may float when refined - 7Leaf light
leaf.hi· may float when refined - 8Leaf mid
leaf.mid· may float when refined - 9Leaf dark
leaf.lo· may float when refined - 10Leaf edge
leaf.edge· may float when refined - 11Leaf accent
leaf.accent· may float when refined - 12Dead leaf
leaf.dead· may float when refined - 13Blossom
blossom· may float when refined - 14Berry
berry· may float when refined - 15Snow
snow· may float when refined
Thicket
voxolith/thicket is the same generator starting from the thicket preset.
- Id
voxolith/thicket- Version
- 0.1.0
- Scales
- 10, 20, 50, 100 voxels per metre
Parameters
Shape
| Parameter | Path | Range | Default |
|---|---|---|---|
Height overall height in voxels (10 per metre); the whole shrub scales with it | shape.height | 12 to 120 | 56 |
Stem lean how far the stems lean outward from vertical, in degrees; higher opens the vase wider | shape.leanDeg | 0 to 50, step 1 | 28 |
Stem length stem length as a fraction of height before the shrub is fitted to its height; longer stems give a leggier, more open shrub | shape.lengthRatio | 0.4 to 1.3, step 0.02 | 0.82 |
Stem radius stem base radius as a fraction of height; higher gives thicker, woodier stems | shape.radiusRatio | 0.008 to 0.05, step 0.001 | 0.022 |
Extra clumps extra, smaller clumps of stems scattered around the centre; 0 is a single shrub | shape.clumps | 0 to 8 | 4 |
Foliage
| Parameter | Path | Range | Default |
|---|---|---|---|
Clump radius leaf clump radius in voxels at height 64; larger clumps give a fuller, rounder mass | foliage.clusterRadius | 1.5 to 8, step 0.1 | 3.2 |
Leaf density fraction of leaf clumps kept; lower shows more of the twigs | foliage.density | 0.1 to 1, step 0.02 | 1 |
Sky holes size of the sky holes carved through the leaves; 0 carves none | foliage.macroThreshold | 0 to 0.6, step 0.01 | 0.2 |
Look
| Parameter | Path | Range | Default |
|---|---|---|---|
Season leaf colours and density; in winter every species but the hedge is bare, with snow on its upper faces | look.season | spring, summer, autumn, winter | summer |
Health 1 healthy; lower thins the leaves and turns more of them dead brown | look.health | 0 to 1, step 0.05 | 0.9 |
Thorns thorn spikes on a fraction of the stem surface; 0 is a smooth shrub | look.thorns | 0 to 0.5, step 0.01 | 0 |
Berries fraction of leaf clumps whose outer rim carries berries | look.berryFraction | 0 to 0.5, step 0.01 | 0 |
Presets
| Parameter | bush | thicket | bramble | flowering | hedge |
|---|---|---|---|---|---|
| Height | 64 | 56 | 64 | 64 | 48 |
| Stem lean | 22 | 28 | 34 | 18 | 12 |
| Stem length | 0.82 | 0.82 | 1.05 | 0.82 | 0.82 |
| Stem radius | 0.022 | 0.022 | 0.013 | 0.022 | 0.022 |
| Extra clumps | 0 | 4 | 0 | 0 | 2 |
| Clump radius | 3.6 | 3.2 | 2.6 | 3.4 | 3.8 |
| Leaf density | 1 | 1 | 0.62 | 1 | 1 |
| Sky holes | 0.2 | 0.2 | 0.3 | 0.2 | 0.08 |
| Season | summer | summer | summer | spring | summer |
| Health | 0.9 | 0.9 | 0.9 | 0.9 | 0.9 |
| Thorns | 0 | 0 | 0.22 | 0 | 0 |
| Berries | 0 | 0 | 0.12 | 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.
- 1Stem dark
stem.dark - 2Stem mid
stem.mid - 3Stem light
stem.light - 4Twig
twig - 5Twig dark
twig.dark - 6Thorn
thorn· may float when refined - 7Leaf light
leaf.hi· may float when refined - 8Leaf mid
leaf.mid· may float when refined - 9Leaf dark
leaf.lo· may float when refined - 10Leaf edge
leaf.edge· may float when refined - 11Leaf accent
leaf.accent· may float when refined - 12Dead leaf
leaf.dead· may float when refined - 13Blossom
blossom· may float when refined - 14Berry
berry· may float when refined - 15Snow
snow· may float when refined
See the API reference for generateBush and the parameter types.