Get Grassworks running

Start from examples/basic. The surrounding scene is ordinary Three.js; Grassworks adds the terrain-aware grass system, tile management, LOD, interaction and authoring features.

1. Package contents

The distribution gives you the built files for direct use and the source implementation for inspection or customization. The production-ready entry points are grassworks.js and grassworks.min.js. If you need to modify the library itself, the source implementation is included as well.

import Grassworks from "./grassworks.min.js";

Use the minified build for a production import when you do not need to modify the library. Use the readable build or source implementation while developing or customizing.

2. Module setup

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.module.js",
    "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.webgpu.js",
    "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.tsl.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.185.0/examples/jsm/"
  }
}
</script>

import * as THREE from "three/webgpu";
import Grassworks from "./grassworks.min.js";

The shipped basic example is the canonical module setup. Keep Grassworks in a module context so its Three.js imports and async initialization work correctly.

3. Create the system

Initialize WebGPURenderer before creating Grassworks:

const renderer = new THREE.WebGPURenderer({ canvas });
renderer.setSize(window.innerWidth, window.innerHeight);
await renderer.init();

Grassworks accepts a plane-based terrain mesh, which must already be present in the scene at its final world-space position, rotation and scale before Grassworks is initialized.

const terrainGeometry = new THREE.PlaneGeometry(1000, 1000);
const terrainMaterial = new THREE.MeshStandardMaterial({
  color: 0x3a4d20
});

const terrain = new THREE.Mesh(
  terrainGeometry,
  terrainMaterial
);

terrain.rotation.x = -Math.PI / 2;
scene.add(terrain);

Once the terrain and renderer are ready, create Grassworks with the required configuration:

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

For the complete configuration surface, see the Configuration reference.

4. Update Grassworks every frame

Grassworks performs its normal per-frame work when update() is called. The example uses THREE.Timer

const timer = new THREE.Timer();
timer.connect(document);

function animate() {
  timer.update();
  grassworks.update(timer);
  renderer.render(scene, camera);
}

renderer.setAnimationLoop(animate);

5. First successful scene

At this point the canonical example should initialize and render the grass field. Getting Started deliberately stops here; runtime GUI and authoring are covered separately in the Runtime GUI guide.