Terrain Generator

Creates terrain blocks from heightmap arrays, PNG files, or project directories with full material support.

Overview

util_terrainGenerator provides an OOP interface for generating TerrainBlock objects. You can set heightmaps from Lua arrays or PNG files, configure materials from JSON, set texture layer maps, and create the final terrain. Supports import/export of terrain data.

Module path: lua/ge/extensions/util/terrainGenerator.lua Note: Used via require, returns a constructor.

Exports (M)

Function	Signature	Description
`new`	`(data?)` → `object`	Creates a new terrain generator instance.

Instance Methods (C)

Method	Signature	Description
`init`	`(data?)`	Initializes with optional config (scale, height, name, paths).
`saveBitmap`	`(path?)`	Saves the current heightmap bitmap as PNG.
`loadBitmap`	`(path?)`	Loads a heightmap from a PNG file.
`getMaxHeight`	`()` → `number`	Returns the current terrain's max height.
`setTerrainOffset`	`(vec3)`	Repositions the terrain block.
`centerTerrain`	`()`	Centers the terrain so origin is at the middle.
`setPoint`	`(x, y, z)`	Sets a single heightmap pixel.
`setBitmapFromArray`	`(array)`	Creates heightmap from a 2D Lua array. Dimensions auto-padded to 128 multiples.
`resetUserDir`	`(dir?)`	Clears heightmap/holemap/layermap files in a directory.
`resetTerrain`	`(deleteOnly?)`	Deletes existing terrain; optionally recreates a blank TerrainBlock.
`getTextureMap`	`(path, matName?)` → `table`	Returns a texture map data entry for a material.
`exportTerrainMaps`	`(dir?, prefix?)`	Exports current terrain's height/hole/layer maps as PNGs.
`setPngData`	`(path, size, height, scale, flipY)`	Directly sets heightmap file and parameters.
`setUserDir`	`(dir)`	Sets project directory; auto-discovers heightmaps, holemaps, and materials JSON.
`setDefaultMaterial`	`()`	Creates a default grid material (from smallgrid).
`setMaterials`	`(matData?)`	Loads terrain materials from JSON file, direct table, or existing terrain.
`setTextureMaps`	`()`	Discovers and matches layer map PNGs to materials. Creates blank maps for unmatched.
`createTerrain`	`()`	Creates the actual TerrainBlock from all configured data.

Internals

Init Data

{
  terrainScale = 1,        -- Grid size
  terrainHeight = maxHeight, -- Max height value
  name = "temp",           -- Generic name for files
  terrainName = "theTerrain", -- Scenetree object name
  userDir = "temp/",       -- Project directory
  heightMap = "temp/temp_heightMap.png",
  holeMap = "",
  textureMaps = nil,
  materials = nil,
}

Bitmap Format

Uses GBitmap with GFXFormatR16 (16-bit grayscale). Height values are mapped to [0, 65535] based on terrainHeight.

Material System

Supports both v1 materials (diffuseMap, normalMap, detailMap, macroMap) and v1.5 materials (TerrainMaterialTextureSet with baseColor/normal/roughness/ao/height texture properties).

Terrain Creation Flow

Reset/delete existing terrain.
Create new TerrainBlock registered in MissionGroup.
Load heightmap bitmap, configure scale/height.
Set materials and texture maps.
Call terrain:importMaps() with all data.
Save terrain file.

How It Works

Create instance: local gen = require('util/terrainGenerator').new().
Set heightmap via array or PNG.
Configure materials (JSON or defaults).
Call createTerrain() to build.
Optionally centerTerrain().

Lua Examples

extensions.load('util/terrainGenerator')
local gen = util_terrainGenerator.new()

-- Create from array
local arr = {}
for x = 1, 256 do
  arr[x] = {}
  for y = 1, 256 do
    arr[x][y] = randomGauss3() / 5
  end
end
gen:setBitmapFromArray(arr)
gen:createTerrain()
gen:centerTerrain()

-- Create from project directory
local gen2 = util_terrainGenerator.new({name = "myLevel"})
gen2:setUserDir("/levels/myLevel/terrainProject/")
gen2:createTerrain()

-- Export existing terrain
gen:exportTerrainMaps("/temp/export/", "myTerrain")

Additional Exports

M.new - (undocumented)

Overview

Module path: lua/ge/extensions/util/terrainGenerator.lua Note: Used via require, returns a constructor.

Exports (M)

Function	Signature	Description
`new`	`(data?)` → `object`	Creates a new terrain generator instance.

Instance Methods (C)

Method	Signature	Description
`init`	`(data?)`	Initializes with optional config (scale, height, name, paths).
`saveBitmap`	`(path?)`	Saves the current heightmap bitmap as PNG.
`loadBitmap`	`(path?)`	Loads a heightmap from a PNG file.
`getMaxHeight`	`()` → `number`	Returns the current terrain's max height.
`setTerrainOffset`	`(vec3)`	Repositions the terrain block.
`centerTerrain`	`()`	Centers the terrain so origin is at the middle.
`setPoint`	`(x, y, z)`	Sets a single heightmap pixel.
`setBitmapFromArray`	`(array)`	Creates heightmap from a 2D Lua array. Dimensions auto-padded to 128 multiples.
`resetUserDir`	`(dir?)`	Clears heightmap/holemap/layermap files in a directory.
`resetTerrain`	`(deleteOnly?)`	Deletes existing terrain; optionally recreates a blank TerrainBlock.
`getTextureMap`	`(path, matName?)` → `table`	Returns a texture map data entry for a material.
`exportTerrainMaps`	`(dir?, prefix?)`	Exports current terrain's height/hole/layer maps as PNGs.
`setPngData`	`(path, size, height, scale, flipY)`	Directly sets heightmap file and parameters.
`setUserDir`	`(dir)`	Sets project directory; auto-discovers heightmaps, holemaps, and materials JSON.
`setDefaultMaterial`	`()`	Creates a default grid material (from smallgrid).
`setMaterials`	`(matData?)`	Loads terrain materials from JSON file, direct table, or existing terrain.
`setTextureMaps`	`()`	Discovers and matches layer map PNGs to materials. Creates blank maps for unmatched.
`createTerrain`	`()`	Creates the actual TerrainBlock from all configured data.

Internals

Init Data

{
  terrainScale = 1,        -- Grid size
  terrainHeight = maxHeight, -- Max height value
  name = "temp",           -- Generic name for files
  terrainName = "theTerrain", -- Scenetree object name
  userDir = "temp/",       -- Project directory
  heightMap = "temp/temp_heightMap.png",
  holeMap = "",
  textureMaps = nil,
  materials = nil,
}

Reset/delete existing terrain.
Create new TerrainBlock registered in MissionGroup.
Load heightmap bitmap, configure scale/height.
Set materials and texture maps.
Call terrain:importMaps() with all data.
Save terrain file.

How It Works

Create instance: local gen = require('util/terrainGenerator').new().
Set heightmap via array or PNG.
Configure materials (JSON or defaults).
Call createTerrain() to build.
Optionally centerTerrain().

Lua Examples

extensions.load('util/terrainGenerator')
local gen = util_terrainGenerator.new()

-- Create from array
local arr = {}
for x = 1, 256 do
  arr[x] = {}
  for y = 1, 256 do
    arr[x][y] = randomGauss3() / 5
  end
end
gen:setBitmapFromArray(arr)
gen:createTerrain()
gen:centerTerrain()

-- Create from project directory
local gen2 = util_terrainGenerator.new({name = "myLevel"})
gen2:setUserDir("/levels/myLevel/terrainProject/")
gen2:createTerrain()

-- Export existing terrain
gen:exportTerrainMaps("/temp/export/", "myTerrain")

Additional Exports

M.new - (undocumented)

Terrain Generator

Overview

Exports (M)

Instance Methods (C)

Internals

Init Data

Bitmap Format

Material System

Terrain Creation Flow

How It Works

Lua Examples

Additional Exports

See Also

On this page

Terrain Generator

Overview

Exports (M)

Instance Methods (C)

Internals

Init Data

Bitmap Format

Material System

Terrain Creation Flow

How It Works

Lua Examples

Additional Exports

See Also

On this page