Forest Generator
Procedural forest generation utility for creating, querying, updating, and deleting forest items programmatically.
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
forestItemDictmapping 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) andmaxScl(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)