Dynamic Maps

A Dynamic Map is a Grass Map or Color Map that you supply as a THREE.Texture instead of an image path, so its content can change while the scene runs. Use it to animate where grass grows and what color it has: mowing, footprints, ripples, seasons, or effects driven by video.

Dynamic Grass MapDynamic Color Map
OptiongrassMapcolorMap
ControlsWhere grass grows and how tallThe color of the grass by position
ValuesBlack = full-height grass, white = no grass, grays in betweenRGB color (sRGB)
Static versionGrass MapsColor Maps

Supported textures

  • CanvasTexture: draw the map with the 2D canvas API.
  • DataTexture: write pixel values from code.
  • VideoTexture: play a video as the map.

Quick start: a Dynamic Grass Map from a canvas

js
const canvas = document.createElement("canvas");
canvas.width = canvas.height = 512;
const ctx = canvas.getContext("2d");

const grassMap = new THREE.CanvasTexture(canvas);
grassMap.flipY = false;

const grassworks = await Grassworks.create({
  camera, scene, renderer, terrain,
  tileSize: 25,
  maxDistance: 200,
  grassMap
});

function animate() {
  // Black = grass, white = no grass
  ctx.fillStyle = "#000";
  ctx.fillRect(0, 0, 512, 512);
  ctx.fillStyle = "#fff";
  ctx.beginPath();
  ctx.arc(256, 256, 60, 0, Math.PI * 2);   // a clearing in the middle
  ctx.fill();

  grassMap.needsUpdate = true;
  grassworks.update(timer);
}

The grass follows the texture: wherever the canvas turns white, the grass disappears.

Rules

  1. Set flipY = false. Grassworks does this for you when you pass an image path. With your own texture you set it yourself.
  2. Orientation. The texture covers the terrain bounds, like an image map. The first row of the texture is the terrain's -Z edge and the first column is the -X edge.
  3. Tell Three.js when the content changes. After you change a CanvasTexture or DataTexture, set texture.needsUpdate = true. A VideoTexture updates itself.
  4. Color space. A Dynamic Color Map is treated as sRGB color.
  5. Combining. A Dynamic Color Map works with a normal or a Dynamic Grass Map, and the other way around.
  6. Terrain Painter. A texture map can't be combined with painter: { enabled: true }. Grassworks.create() throws an error. The painter works with image paths (or colorMap: true).
  7. You own the texture. Grassworks never changes or disposes a texture you pass in, apart from marking a Dynamic Color Map as sRGB. You update it, and you dispose it when you're done.

A Dynamic Grass Map from a DataTexture

js
const size = 256;
const data = new Uint8Array(size * size);        // 0 = full grass, 255 = no grass
const grassMap = new THREE.DataTexture(data, size, size, THREE.RedFormat);
grassMap.flipY = false;
grassMap.magFilter = THREE.LinearFilter;         // smooth result from a small map
grassMap.minFilter = THREE.LinearFilter;
grassMap.needsUpdate = true;

// Later, for example in your render loop:
data.fill(0);                                    // grass everywhere
for (let x = 100; x < 156; x++) data[128 * size + x] = 255;   // a path
grassMap.needsUpdate = true;

A Dynamic Color Map from a video

js
const video = document.createElement("video");
video.src = "/assets/colors.mp4";
video.loop = true;
video.muted = true;          // browsers only autoplay muted video
video.playsInline = true;
await video.play();

const colorMap = new THREE.VideoTexture(video);
colorMap.flipY = false;

const grassworks = await Grassworks.create({
  camera, scene, renderer, terrain,
  tileSize: 25,
  maxDistance: 200,
  colorMap
});

If the browser blocks autoplay, call video.play() after the first click or key press.

Changing maps at runtime

Use setGrassMap() and setColorMap() to replace a map without recreating Grassworks. Both are asynchronous.

js
await grassworks.setGrassMap(newGrassTexture);   // image path or THREE.Texture
await grassworks.setColorMap(newColorTexture);   // image path, true, THREE.Texture, or null
await grassworks.setColorMap(null);              // turn the Color Map off; procedural colors return
oldGrassTexture.dispose();                       // you dispose textures you created
MethodAccepts
setGrassMap(map)An image path or a THREE.Texture
setColorMap(map)An image path, true (default green), a THREE.Texture, or null
  • No refresh() call is needed.
  • Both throw while the Terrain Painter is enabled.
  • When a map is replaced, Grassworks disposes the previous texture only if it created it itself (loaded from a path, or the default green of colorMap: true). Textures you passed in are yours to dispose.
  • setConfig() and applyConfig() don't change maps, and toJSON() doesn't include them. Use these two methods.

Troubleshooting

SymptomCheck
The map doesn't changeDid you set needsUpdate = true after changing the content? (Not needed for VideoTexture.)
The map looks mirroredIs flipY set to false? Remember the first row is the terrain's -Z edge.
The video map stays stillIs the video playing? Muted autoplay may need a click or key press first.
Grassworks.create() throws about the painterA texture map can't be combined with painter.enabled.
Colors look washed out or too darkA Dynamic Color Map is sRGB. Check baseColorDarkness.
A map change after create() has no effectChange maps with setGrassMap() and setColorMap(), not by assigning properties.

See also: Grass Maps · Color Maps · Terrain Painter · setGrassMap() · setColorMap()