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 Map | Dynamic Color Map | |
|---|---|---|
| Option | grassMap | colorMap |
| Controls | Where grass grows and how tall | The color of the grass by position |
| Values | Black = full-height grass, white = no grass, grays in between | RGB color (sRGB) |
| Static version | Grass Maps | Color 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
- Set
flipY = false. Grassworks does this for you when you pass an image path. With your own texture you set it yourself. - 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.
- Tell Three.js when the content changes. After you change a
CanvasTextureorDataTexture, settexture.needsUpdate = true. AVideoTextureupdates itself. - Color space. A Dynamic Color Map is treated as sRGB color.
- Combining. A Dynamic Color Map works with a normal or a Dynamic Grass Map, and the other way around.
- Terrain Painter. A texture map can't be combined with
painter: { enabled: true }.Grassworks.create()throws an error. The painter works with image paths (orcolorMap: true). - 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| Method | Accepts |
|---|---|
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()andapplyConfig()don't change maps, andtoJSON()doesn't include them. Use these two methods.
Troubleshooting
| Symptom | Check |
|---|---|
| The map doesn't change | Did you set needsUpdate = true after changing the content? (Not needed for VideoTexture.) |
| The map looks mirrored | Is flipY set to false? Remember the first row is the terrain's -Z edge. |
| The video map stays still | Is the video playing? Muted autoplay may need a click or key press first. |
Grassworks.create() throws about the painter | A texture map can't be combined with painter.enabled. |
| Colors look washed out or too dark | A Dynamic Color Map is sRGB. Check baseColorDarkness. |
A map change after create() has no effect | Change maps with setGrassMap() and setColorMap(), not by assigning properties. |
See also: Grass Maps · Color Maps · Terrain Painter · setGrassMap() · setColorMap()