Methods

Every public runtime method is documented below as an independently addressable reference entry. Use the URL fragment to link directly to a method.

Configuration & Serialization

setConfig

js
async setConfig(config = {})

Applies a configuration object to an existing system, including type, preset, LOD, interaction, visibility and shadow settings.

Parameters

  • config — object.

Returns

Promise<this> — the Grassworks instance for chaining.

Example

js
await grassworks.setConfig({
  maxDistance: 150,
  tileSize: 20
});

applyConfig

js
async applyConfig(config = {})

Applies a configuration object and is the documented GUI-to-production configuration path.

Parameters

  • config — object.

Returns

Promise<this> — the Grassworks instance for chaining.

Example

js
await grassworks.applyConfig(finalConfig);

toJSON

js
toJSON()

Returns a serializable configuration/state snapshot.

Returns

object.

Example

js
const config = grassworks.toJSON();
console.log(config);

Grass

setGrassType

js
async setGrassType(type)

Switches between Blade and Billboard grass without recreating the Grassworks instance.

Parameters

  • type — "blade" | "billboard".

Returns

Promise<this> — the Grassworks instance for chaining.

Example

js
await grassworks.setGrassType("billboard");

setPreset

js
setPreset(name)

Applies one of the named Blade presets.

Parameters

  • name — string; available Blade preset key.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setPreset("kentuckyBluegrass");

getPreset

js
getPreset()

Returns the current preset key.

Returns

string.

Example

js
const preset = grassworks.getPreset();
console.log(preset);

getPresets

js
getPresets()

Returns the available named Blade preset keys. Billboard returns an empty array.

Returns

string[].

Example

js
const presets = grassworks.getPresets();

setGrassParam

js
setGrassParam(name, value)

Updates one grass parameter at runtime.

Parameters

  • name — string; supported grass parameter name.
  • value — parameter value.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setGrassParam("windIntensity", 0.4);

setGrassParams

js
setGrassParams(params = {})

Updates multiple grass parameters at runtime.

Parameters

  • params — object; parameter/value pairs.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setGrassParams({
  bladeHeight: 2.5,
  windIntensity: 0.3
});

getGrassParams

js
getGrassParams()

Returns a shallow copy of the current grass parameters.

Returns

object.

Example

js
const params = grassworks.getGrassParams();

Interaction

addInfluence

js
addInfluence(mesh)

Registers an influence object whose nearby presence bends grass.

Parameters

  • mesh — THREE.Object3D; influence object.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.addInfluence(carTire);

removeInfluence

js
removeInfluence(mesh)

Removes a previously registered influence object.

Parameters

  • mesh — THREE.Object3D; registered influence object.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.removeInfluence(carTire);

clearInfluences

js
clearInfluences()

Removes all registered influence objects.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.clearInfluences();

setInteraction

js
setInteraction(enabled)

Enables or disables the interaction system.

Parameters

  • enabled — boolean.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setInteraction(false);

setInfluenceRecoverySpeed

js
setInfluenceRecoverySpeed(value)

Sets how quickly influence effects recover toward the upright state.

Parameters

  • value — number; 0–1.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setInfluenceRecoverySpeed(0.95);

setInfluenceWorldSize

js
setInfluenceWorldSize(value)

Sets the world-space coverage of the camera-following interaction map.

Parameters

  • value — number; greater than 0.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setInfluenceWorldSize(80);

setInfluenceResolution

js
async setInfluenceResolution(value)

Sets the interaction-map resolution.

Parameters

  • value — positive integer.

Returns

Promise<this> — the Grassworks instance for chaining.

Example

js
await grassworks.setInfluenceResolution(512);

setInfluenceDebugPlaneVisible

js
setInfluenceDebugPlaneVisible(enabled)

Shows or hides the influence debug plane.

Parameters

  • enabled — boolean.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setInfluenceDebugPlaneVisible(true);

Performance

setLOD

js
setLOD(name, params = {})

Updates one LOD level and immediately re-evaluates the scene.

Parameters

  • name — "high" | "medium" | "low" | "veryLow".
  • params — object; distance, density and/or detail.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setLOD("high", {
  distance: 0.35,
  density: 4,
  detail: 4
});

setLODConfig

js
setLODConfig(config = {})

Updates one or more LOD levels at once.

Parameters

  • config — object containing high, medium, low and/or veryLow configurations.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setLODConfig({
  high: { distance: 0.4 },
  medium: { distance: 0.7 }
});

getLOD

js
getLOD(name)

Returns the configuration of one LOD level.

Parameters

  • name — "high" | "medium" | "low" | "veryLow".

Returns

object.

Example

js
const high = grassworks.getLOD("high");

getLODConfig

js
getLODConfig()

Returns all four LOD configurations.

Returns

object.

Example

js
const lod = grassworks.getLODConfig();

setTileSize

js
setTileSize(value)

Changes the world-space size of grass tiles and recalculates the tile grid.

Parameters

  • value — number; greater than 0.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setTileSize(20);

setMaxDistance

js
setMaxDistance(value)

Sets the maximum camera distance at which grass remains visible.

Parameters

  • value — number; greater than 0.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setMaxDistance(150);

refresh

js
refresh()

Recalculates tile/grid state and re-evaluates visibility and LOD using the current terrain and configuration.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.refresh();

rebuild

js
rebuild()

Rebuilds the current tile grid and re-evaluates visibility.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.rebuild();

refreshTerrain

js
async refreshTerrain()

Re-captures the current terrain and rebuilds the terrain-dependent grass state.

Returns

Promise<object>.

Example

js
await grassworks.refreshTerrain();

Scene & Visibility

setCamera

js
setCamera(camera)

Changes the camera Grassworks uses for culling, LOD and interaction follow behavior.

Parameters

  • camera — THREE.Camera.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setCamera(newCamera);

setVisible

js
setVisible(visible)

Sets the visible state of generated grass meshes.

Parameters

  • visible — boolean.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setVisible(false);

setEnabled

js
setEnabled(enabled)

Enables or disables Grassworks per-frame updating.

Parameters

  • enabled — boolean.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setEnabled(false);

setCastShadow

js
setCastShadow(enabled)

Sets generated grass meshes to cast shadows.

Parameters

  • enabled — boolean.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setCastShadow(true);

setReceiveShadow

js
setReceiveShadow(enabled)

Sets generated grass meshes to receive shadows.

Parameters

  • enabled — boolean.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setReceiveShadow(true);

Runtime GUI

createGUI

js
createGUI()

Creates the runtime authoring GUI and returns it; repeated calls reuse the existing GUI.

Returns

GrassGUI.

Example

js
grassworks.createGUI();

destroyGUI

js
destroyGUI()

Destroys the runtime GUI if one exists.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.destroyGUI();

Debugging

setDebugBoxes

js
setDebugBoxes(enabled)

Shows or hides tile debug boxes.

Parameters

  • enabled — boolean.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.setDebugBoxes(true);

Events

on

js
on(event, callback)

Subscribes to a public Grassworks event.

Parameters

  • event — string; public event name.
  • callback — function; called with the event payload.

Returns

this — the Grassworks instance for chaining.

Example

js
grassworks.on("ready", (instance) => {
  console.log(instance);
});

off

js
off(event, callback)

Removes one event callback, or all callbacks for an event when callback is omitted.

Parameters

  • event — string; public event name.
  • callback — function; optional callback to remove.

Returns

this — the Grassworks instance for chaining.

Example

js
const callback = (payload) => console.log(payload);
grassworks.on("ready", callback);
grassworks.off("ready", callback);

Lifecycle

dispose

js
dispose()

Disposes Grassworks resources, removes its generated scene state and marks the instance disposed.

Returns

void.

Example

js
grassworks.dispose();