Skip to content

3D engine that AI agents drive

4.5 KB
Raw Blame

Ground clutter

crucible/addons/clutter scatters pebbles, rocks, twigs and fallen leaves over terrain. It is in the current source and not yet published.

import { createClutter } from 'crucible/addons/clutter';

const clutter = createClutter({
  preset: 'forest',
  area: { minX: -40, maxX: 40, minZ: -70, maxZ: 30 },
  terrainHeight: terrain.heightAt,
  eye,
  seed: 5,
});

const renderer = new CrucibleRenderer(canvas, [...terrain.parts, ...grass.parts, ...clutter.parts], { world: true, ground: false });

// When the camera moves:
if (clutter.update(eye)) renderer.replaceParts([...terrain.parts, ...grass.parts, ...clutter.parts]);

How it is made

  • A stone is a sphere displaced by smooth noise. Rocks are also cut by four random planes, which gives them flat, chipped faces. Pebbles stay round.
  • A stone sinks a third to a half of its height into the ground and tilts with the terrain.
  • Vertex colours give each stone its own tone and hue, from blue-grey to rust. Blotches follow the stone's own space. The underside is darker and soil clings near the ground line.
  • Rocks carry the renderer's moss layer: rough, sheened cushions on their tops, shaded as moss rather than painted on. Pebbles stay bare.
  • Twigs are tapered tubes that lie on the ground and follow it. Leaves are small cupped strips in a palette of dry browns.
  • Items gather into patches of about 7 m (clumping), so the ground does not read as an even sprinkle.
  • Everything is vertex-coloured and untextured. Each tile has at most three parts, rocks, pebbles and litter, and all stream through renderer.replaceParts.

Clutter shows best on paths, clearings, riverbanks and forest floor. Under a dense meadow most of it hides in the grass. To fill a path, pass the inverse of the grass mask as the clutter mask.

Options

Option Default Meaning
area required { minX, maxX, minZ, maxZ } in metres.
preset 'meadow' meadow, forest, riverbed or scree. Every other option overrides the preset.
terrainHeight () => 0 Ground height at (x, z). Pass terrain.heightAt.
mask none Coverage at (x, z) from 0 to 1.
pebbles, rocks, twigs, leaves from preset Items per square metre.
pebbleSize, rockSize [0.012, 0.05], [0.08, 0.38] Radius range in metres. Most stones fall near the small end.
moss from preset Moss cover on rocks, 0 to 1. It sets the rock material's moss.
clumping 0.6 How strongly items gather into patches, 0 to 1.
stoneColor, mossColor, soilColor, twigColor earth tones Linear RGB.
leafColors four dry browns A list of linear RGB colours. Each leaf picks one.
castShadow true Stones cast shadows. Twigs and leaves never do.
tileSize, levels, cullDistance 4, CLUTTER_LEVELS, last level Tiling and level of detail; tileSize must be finite. An area needing over 262144 tiles throws.
eye, seed area centre, 1 Initial camera position and random seed.

createClutter returns { parts, update(eye), stats(), materials, settings }.

Level of detail

Level Distance Kept Stone mesh
0 up to 12 m everything rocks 12 × 7, pebbles 6 × 4
1 12 to 30 m 20 % rocks 6 × 4, pebbles an octahedron
2 30 to 70 m rocks only rocks 6 × 4

Grass and clutter share the tile system in src/tile-field.js, with the same 10 % hysteresis.

Measured

On an 80 × 100 m area, eye 1.3 m above the ground, built in Node:

Preset Triangles Geometry Build
meadow 28 k about 1 MB about 0.1 s
forest 84 k about 4.5 MB about 0.3 s
riverbed 445 k about 16.5 MB about 1 s
scree 604 k about 22 MB about 1 s

riverbed and scree are dense by design. Lower pebbles or cullDistance for phones.

Settling stones into a pile

Clutter tiles are meshes, so they stay where they were scattered. To drop stones and let them lie against a wall or each other, use the settle step (Settling props): list the stone poses as instances, or let it scatter boxes and balls over an area. It returns resting transforms to draw as static parts.

Limits

  • Stones are untextured. Up close they read as smooth, mottled stones, not as scanned rock.
  • Clutter does not collide with grass blades or with each other, so two stones can overlap.
  • Leaves lie flat and do not move in the wind.