Grass

GPU grass grown on mesh entities - GrassSurface groups ground meshes, GroundCover says what grows on each, GrassSpecies describes the plant in SI units; blades bend in the scene's wind and are pressed by obstacles.

Grass grows on ordinary mesh entities. Three components describe it, and the renderer does the rest on the GPU: it samples the ground on a lattice, bakes the tiles a view looks at, and draws individual blades that sway in the scene’s wind and are pressed flat by obstacles.

ComponentOnSays
GrassSurfaceany entity with a Transform64this entity’s frame is a surface: its ground is sampled as one lattice, along the frame’s up axis
GroundCovera mesh entity (ShadedGeometry + Transform64)which surface the mesh is ground of, what grows on it, and how densely
GrassSpeciesshared by covers, not an entitythe plant: blade length and width, blades per m², colours, lean, curl, stiffness, turbulence, recovery time

Setup

import { GrassSpecies } from "@woosh/meep-engine/src/engine/graphics/ecs/grass/GrassSpecies.js";
import { GrassSurface } from "@woosh/meep-engine/src/engine/graphics/ecs/grass/GrassSurface.js";
import { GroundCover } from "@woosh/meep-engine/src/engine/graphics/ecs/grass/GroundCover.js";
import { GrassSurfaceSystem } from "@woosh/meep-engine/src/engine/graphics3/GrassSurfaceSystem.js";
import { GroundCoverSystem } from "@woosh/meep-engine/src/engine/graphics3/GroundCoverSystem.js";

em.addSystem(new ShadedGeometrySystem(engine.graphics, scene));
em.addSystem(new GrassSurfaceSystem(engine.graphics, scene));
em.addSystem(new GroundCoverSystem());     // needs the GrassSurfaceSystem on the same manager

const meadow = GrassSpecies.from({ blade_length: 0.4, blade_width: 0.015, density: 300 });

const field = new Entity()
    .add(new Transform64())
    .add(new GrassSurface())
    .build(ecd);

new Entity()
    .add(groundTransform)
    .add(groundShadedGeometry)
    .add(GroundCover.from({ surface: field, species: meadow }))
    .build(ecd);

// a rock on the field: hides the ground under it, grows nothing
new Entity()
    .add(rockTransform)
    .add(rockShadedGeometry)
    .add(GroundCover.from({ surface: field, species: null }))
    .build(ecd);

Membership is its own relation. GroundCover.surface says which surface a mesh is sampled with, and nothing about where the mesh is (TransformAttachment) or how long it lives (ParentEntity). A meadow of loose meshes is one surface without a transform parent. A mesh that carries both components and names itself is a surface of one. A surface that moves as one carries its grass with it, and nothing is re-baked. surface must not change while the component is attached: remove the component and add it back to move a mesh to another surface.

A member with no species only hides ground - a boulder, a path, the floor of a building. Nothing grows on it or through it, and it hides the ground of other members under it.

Density is painted. The red channel of the geometry’s vertex colour scales how densely the species grows across the mesh (1 where there is no vertex colour), and GroundCover.density (0 to 1) scales that.

After editing a GroundCover or a GrassSpecies in place, dispatch its onChanged. Nothing is rewritten per frame; links, unlinks, announced edits and announced moves queue the work.

Wind and pressing

Blades bend in the scene’s wind field with the same drag law the foliage rig uses, so register GPUFluidSystem and a GlobalFluidEffector (see Fluid) for grass that moves. GrassSpecies.turbulence adds sway the wind field does not resolve, and elastic_modulus with blade_depth set how stiff a blade is.

Solid obstacles in the GPU fluid press grass down: an entity with a FluidObstacle, a Collider and a RigidBody flattens the blades under it, and they stand back up over GrassSpecies.recovery_time seconds. A porous obstacle (FluidObstacle.drag above 0) presses nothing: the air passes through it, and so does the grass. grass_system.blades.press.enabled switches pressing off, and press.spacing (0.125 m) sets how fine its edge is.

Quality settings

grass_system.surfaces.settings is a GrassSurfaceSettings. surfaces and blades are null until the scene has a GPU context.

SettingDefaultMeaning
finest_spacing0.125distance between the finest lattice’s columns, world units: how exactly blade roots follow the ground
narrowest_blade1.5least blade width drawn, in render-resolution pixels; picks each distance’s lattice level
shortest_blade2least blade length drawn, in pixels; no tile is asked for past that distance
bake_capacity64most tile layers baked per view per frame: how fast newly seen ground gets grass
canopy_opacity6blades a view ray may cross before the grass behind is left out; lower shows more ground at grazing angles