Forest Generator

Procedural forest generation utility for creating, querying, updating, and deleting forest items programmatically.

Overview

util_forestGenerator wraps the engine's forest system to provide high-level functions for procedural vegetation placement. Supports creating single items, random rectangular/radial forests, querying items by polygon or radius, and clearing forests.

Extension path: lua/ge/extensions/util/forestGenerator.lua

Exports (M)

Function	Signature	Description
`initForest`	`()`	Initializes forest data and builds item type dictionary.
`createForestItem`	`(itemType, pos, rotDeg, scl)`	Creates a single forest item.
`createRandomForestRect`	`(itemTypeArray, amount, pos, minX, maxX, minY, maxY, rotSteps, minScl, maxScl)`	Creates random forest in a rectangle.
`createRandomForestRadial`	`(itemTypeArray, amount, pos, radius, rotSteps, minScl, maxScl)`	Creates random forest in a circle.
`updateForestItem`	`(item, pos, rotDeg, scl)`	Updates an existing forest item's transform.
`getForestItemTypes`	`()`	Returns sorted array of available item type names.
`getForestItemDict`	`()`	Returns dictionary of item type name → forest item template.
`getForestItemsPolygon`	`(polygon)`	Returns items within a polygon (or all items if nil).
`getForestItemsRadius`	`(pos, radius)`	Returns items within a radius (default: camera pos, 20 units).
`deleteForestItem`	`(item)`	Deletes a single forest item.
`clearForest`	`()`	Deletes all forest items except templates.

Internals

Initialization

initForest() is called on load and:

Gets the forest object via core_forest.getForestObject():getData().
Builds forestItemDict mapping internal names to item templates.
Sorts type names into forestItemTypes.

Random Placement - Rectangle

createRandomForestRect() uses blue noise distribution:

Positions are generated via vec3:getBlueNoise2d() and lerped into bounds.
Rotation is discretized by rotSteps (default 360).
Scale is randomized between minScl (0.75) and maxScl (1.25).
Z-height is set from terrain height if available.

Random Placement - Radial

createRandomForestRadial() uses vec3:getRandomPointInCircle(radius):

Similar randomization for rotation and scale.
Terrain height snapping.

Clear Forest

clearForest() iterates all items and deletes any whose key differs from the template's key (preserving the template/base items).

How It Works

Ensure a level is loaded with a Forest object.
Call initForest() (auto-called on load).
Use getForestItemTypes() to see available vegetation types.
Call creation functions to place vegetation.
Query with polygon/radius, update, or clear as needed.

Lua Examples

local fg = extensions.util_forestGenerator

-- List available forest item types
local types = fg.getForestItemTypes()
dump(types) -- {"oak_tree", "pine_tree", "bush_small", ...}

-- Create a single tree at position
fg.createForestItem("oak_tree", vec3(100, 200, 0), 45, 1.2)

-- Create 50 random trees in a 200x200 area
fg.createRandomForestRect({"oak_tree", "pine_tree"}, 50, vec3(0,0,0), -100, 100, -100, 100)

-- Create 30 random trees in a 50-unit radius circle
fg.createRandomForestRadial(nil, 30, vec3(100, 100, 0), 50)

-- Get items near camera
local nearby = fg.getForestItemsRadius(nil, 50)

-- Clear all generated items
fg.clearForest()

Additional Exports

M.clearForest - (undocumented)
M.createForestItem - (undocumented)
M.createRandomForestRadial - (undocumented)
M.createRandomForestRect - (undocumented)
M.deleteForestItem - (undocumented)
M.getForestItemDict - (undocumented)
M.getForestItemTypes - (undocumented)
M.getForestItemsPolygon - (undocumented)
M.getForestItemsRadius - (undocumented)
M.initForest - (undocumented)
M.updateForestItem - (undocumented)

Overview

Extension path: lua/ge/extensions/util/forestGenerator.lua

Exports (M)

Function	Signature	Description
`initForest`	`()`	Initializes forest data and builds item type dictionary.
`createForestItem`	`(itemType, pos, rotDeg, scl)`	Creates a single forest item.
`createRandomForestRect`	`(itemTypeArray, amount, pos, minX, maxX, minY, maxY, rotSteps, minScl, maxScl)`	Creates random forest in a rectangle.
`createRandomForestRadial`	`(itemTypeArray, amount, pos, radius, rotSteps, minScl, maxScl)`	Creates random forest in a circle.
`updateForestItem`	`(item, pos, rotDeg, scl)`	Updates an existing forest item's transform.
`getForestItemTypes`	`()`	Returns sorted array of available item type names.
`getForestItemDict`	`()`	Returns dictionary of item type name → forest item template.
`getForestItemsPolygon`	`(polygon)`	Returns items within a polygon (or all items if nil).
`getForestItemsRadius`	`(pos, radius)`	Returns items within a radius (default: camera pos, 20 units).
`deleteForestItem`	`(item)`	Deletes a single forest item.
`clearForest`	`()`	Deletes all forest items except templates.

Internals

Initialization

initForest() is called on load and:

Gets the forest object via core_forest.getForestObject():getData().
Builds forestItemDict mapping internal names to item templates.
Sorts type names into forestItemTypes.

Random Placement - Rectangle

createRandomForestRect() uses blue noise distribution:

Positions are generated via vec3:getBlueNoise2d() and lerped into bounds.
Rotation is discretized by rotSteps (default 360).
Scale is randomized between minScl (0.75) and maxScl (1.25).
Z-height is set from terrain height if available.

Random Placement - Radial

createRandomForestRadial() uses vec3:getRandomPointInCircle(radius):

Similar randomization for rotation and scale.
Terrain height snapping.

Clear Forest

clearForest() iterates all items and deletes any whose key differs from the template's key (preserving the template/base items).

How It Works

Ensure a level is loaded with a Forest object.
Call initForest() (auto-called on load).
Use getForestItemTypes() to see available vegetation types.
Call creation functions to place vegetation.
Query with polygon/radius, update, or clear as needed.

Lua Examples

local fg = extensions.util_forestGenerator

-- List available forest item types
local types = fg.getForestItemTypes()
dump(types) -- {"oak_tree", "pine_tree", "bush_small", ...}

-- Create a single tree at position
fg.createForestItem("oak_tree", vec3(100, 200, 0), 45, 1.2)

-- Create 50 random trees in a 200x200 area
fg.createRandomForestRect({"oak_tree", "pine_tree"}, 50, vec3(0,0,0), -100, 100, -100, 100)

-- Create 30 random trees in a 50-unit radius circle
fg.createRandomForestRadial(nil, 30, vec3(100, 100, 0), 50)

-- Get items near camera
local nearby = fg.getForestItemsRadius(nil, 50)

-- Clear all generated items
fg.clearForest()

Additional Exports

M.clearForest - (undocumented)
M.createForestItem - (undocumented)
M.createRandomForestRadial - (undocumented)
M.createRandomForestRect - (undocumented)
M.deleteForestItem - (undocumented)
M.getForestItemDict - (undocumented)
M.getForestItemTypes - (undocumented)
M.getForestItemsPolygon - (undocumented)
M.getForestItemsRadius - (undocumented)
M.initForest - (undocumented)
M.updateForestItem - (undocumented)

Forest Generator

Overview

Exports (M)

Internals

Initialization

Random Placement - Rectangle

Random Placement - Radial

Clear Forest

How It Works

Lua Examples

Additional Exports

See Also

On this page

Forest Generator

Overview

Exports (M)

Internals

Initialization

Random Placement - Rectangle

Random Placement - Radial

Clear Forest

How It Works

Lua Examples

Additional Exports

See Also

On this page