Skip to content

SgTerrain

Heightmap-based terrain with chunked LOD. Samples elevation from a linked Image heightmap item and renders with a configurable material.

Typical uses:

  • Outdoor landscapes from grayscale heightmaps
  • Large walkable ground with physics heightfield colliders

Inherits from

SceneObject

Usage

local SgTerrain = require 'engine/sceneobjects/sgterrain'

Reference

create

static create(self, options, parent)

Create a new terrain object in the scenegraph.

Parameters

  • self
  • options (table): A table of options to fill the parameters
  • parent (SceneObject): The parent scene object to add this to

Returns

  • Promise: promise which will resolve to the created object

Example

SgTerrain.create({
    active = true,
    name = "Ground",
    transform = Transform.new(),
    layers = {1},
    heightmap = heightmapItem,
    material = grassMaterial,
    size = Vector2.new(256, 256),
    resolution = Vector2.new(257, 257),
    heightScale = 50,
    heightOffset = 0,
    chunkSize = 64,
    lodLevels = 4,
    lodDistances = "0,80,200,500",
    uvScale = Vector2.new(0.1, 0.1),
    generateNormals = true
})

Properties

You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.

Property Type Default Description
active Boolean true Indicates if the 3D object is currently active or inactive. When set to true, the object is active.
static Boolean false Marks the object as immovable during play. Static objects ignore transform changes at runtime and use a fixed physics collider with zero mass.
transform Transform Transform.new() Describes the object's transformation attributes including its position, rotation, and scale in the 3D space.
layers Layers [0] Defines the layers that the 3D object is part of. Layers are used for managing object interactions and visibility in the scene.
tags Tags [] Lists tags associated with the 3D object. Tags are useful for categorizing and searching objects in the scene.
receiveShadow Boolean false Determines whether the object can receive shadows from other objects. Set to true if the object should display shadows cast upon it.
castShadow Boolean false Controls whether the object casts shadows in the presence of light sources. Set to true to enable shadow casting from this object.
rendered Boolean true When disabled, the object and its descendants are not drawn, but may still simulate physics or run scripts.
size Vector2d Vector2.new(256, 256) World size of the terrain along local X and Z in meters.
resolution Vector2d Vector2.new(257, 257) Height sample count along X and Z. Should match or exceed heightmap detail.
heightScale Float 50 Maximum elevation in meters when heightmap value is 1.0.
heightOffset Float 0 Base elevation added to all samples in meters.
chunkSize Integer 64 Vertices per chunk edge. Smaller chunks give finer-grained LOD but more draw calls.
lODLevels Integer 4 Number of resolution levels per chunk, including the highest-detail level.
lODDistances String 0,80,200,500 Comma-separated camera distances at which each LOD level activates.
uVScale Vector2d Vector2.new(0.1, 0.1) World meters per texture repeat. Smaller values tile the material more densely.
generateNormals Boolean true Recompute vertex normals from the height field.
physicsEnabled Boolean false Turns physics simulation on or off for this object. When disabled, the object keeps its visual transform but does not participate in collisions or forces.