Class Terrain

Represents a single terrain object.

Terrain
Terrain
Terrain
Terrain
Terrain
Assembly: FlaxEngine.dll
File: Engine/Terrain/Terrain.h
Syntax
public class Terrain : public PhysicsColliderActor

Constructors

~Terrain()

Finalizes an instance of the Terrain class.

Declaration
public ~Terrain()

DEPRECATED("Use PhysicalMaterials instead.") JsonAssetReference<PhysicalMaterial>& GetPhysicalMaterial()

Gets the physical material used to define the terrain collider physical properties. [Deprecated on 16.02.2024, expires on 16.02.2026]

Declaration
public DEPRECATED("Use PhysicalMaterials instead.") JsonAssetReference<PhysicalMaterial>& GetPhysicalMaterial()
Parameters
"Use PhysicalMaterials instead." Terrain_DEPRECATED__Use_PhysicalMaterials_instead___

Fields

DrawModes

The draw passes to use for rendering this object.

Declaration
public DrawPass DrawModes = DrawPass::Default
Field Value
DrawPass

Material

The default material used for terrain rendering (chunks can override this).

Declaration
public AssetReference<MaterialBase> Material
Field Value
AssetReference<MaterialBase>

Methods

AddPatch(const Int2& patchCoord)

Adds the patch.

Declaration
public void AddPatch(const Int2& patchCoord)
Parameters
Int2 patchCoord

The patch location (x and z).

AddPatches(const Int2& numberOfPatches)

Adds the patches to the terrain (clears existing ones).

Declaration
public void AddPatches(const Int2& numberOfPatches)
Parameters
Int2 numberOfPatches

The number of patches (x and z axis).

BeginPlay(SceneBeginData* data)

Called when adding object to the game.

Declaration
protected virtual void BeginPlay(SceneBeginData* data) override
Parameters
SceneBeginData data

The initialization data (e.g. used to collect joints to link after begin).
Overrides

CacheNeighbors()

Caches the neighbor chunks of this terrain.

Declaration
public void CacheNeighbors()

ClosestPoint(const Vector3& point, Vector3& result)

Gets a point on the collider that is closest to a given location. Can be used to find a hit location or position to apply explosion force or any other special effects.

Declaration
public virtual void ClosestPoint(const Vector3& point, Vector3& result) const final
Parameters
Vector3 point

The position to find the closest point to it.
Vector3 result

The result point on the collider that is closest to the specified location.
Overrides

ContainsPoint(const Vector3& point)

Checks if a point is inside the collider.

Declaration
public virtual bool ContainsPoint(const Vector3& point) const final
Parameters
Vector3 point

The point to check if is contained by the collider shape (in world-space).
Returns
bool

True if collider shape contains a given point, otherwise false.
Overrides

Deserialize(DeserializeStream& stream, ISerializeModifier* modifier)

Deserializes object from the input stream.

Declaration
public virtual void Deserialize(DeserializeStream& stream, ISerializeModifier* modifier) override
Parameters
DeserializeStream stream

The input stream.
ISerializeModifier modifier

The deserialization modifier object. Always valid.
Overrides

Draw(RenderContext& renderContext)

Draws this actor. Called by Scene Rendering service. This call is more optimized than generic Draw (eg. geometry is rendered during all pass types but other actors are drawn only during GBufferFill pass).

Declaration
public virtual void Draw(RenderContext& renderContext) override
Parameters
RenderContext renderContext

The rendering context.
Overrides

Draw(RenderContextBatch& renderContextBatch)

Draws this actor. Called by Scene Rendering service. This call is more optimized than generic Draw (eg. geometry is rendered during all pass types but other actors are drawn only during GBufferFill pass).

Declaration
public virtual void Draw(RenderContextBatch& renderContextBatch) override
Parameters
RenderContextBatch renderContextBatch

The rendering context batch (eg, main view and shadow projections).
Overrides

DrawChunk(const RenderContext& renderContext, const Int2& patchCoord, const Int2& chunkCoord, MaterialBase* material, int32 lodIndex = 0)

Draws the terrain chunk.

Declaration
public void DrawChunk(const RenderContext& renderContext, const Int2& patchCoord, const Int2& chunkCoord, MaterialBase* material, int32 lodIndex = 0) const
Parameters
RenderContext renderContext

The rendering context.
Int2 patchCoord

The patch location (x and z).
Int2 chunkCoord

The chunk location (x and z).
MaterialBase material

The material to use for rendering.
int32 lodIndex

The LOD index.

DrawPatch(const RenderContext& renderContext, const Int2& patchCoord, MaterialBase* material, int32 lodIndex = 0)

Draws the terrain patch.

Declaration
public void DrawPatch(const RenderContext& renderContext, const Int2& patchCoord, MaterialBase* material, int32 lodIndex = 0) const
Parameters
RenderContext renderContext

The rendering context.
Int2 patchCoord

The patch location (x and z).
MaterialBase material

The material to use for rendering.
int32 lodIndex

The LOD index.

EndPlay()

Called when removing object from the game.

Declaration
protected virtual void EndPlay() override
Overrides

GetAttachedRigidBody()

Gets the attached rigid body.

Declaration
public virtual RigidBody* GetAttachedRigidBody() const override
Returns
RigidBody

The rigid body or null.
Overrides

GetBoundsExtent()

Gets the terrain chunks bounds extent. Values used to expand terrain chunks bounding boxes. Use it when your terrain material is performing vertex offset operations on a GPU.

Declaration
public Vector3 GetBoundsExtent() const
Returns
Vector3

GetChunkBounds(int32 patchIndex, int32 chunkIndex, BoundingBox& bounds)

Gets the terrain chunk world bounds at the given index.

Declaration
public void GetChunkBounds(int32 patchIndex, int32 chunkIndex, BoundingBox& bounds) const
Parameters
int32 patchIndex

The zero-based index of the terrain patch in the terrain patches collection.
int32 chunkIndex

The zero-based index of the terrain chunk in the terrain patch chunks collection (in range 0-15).
BoundingBox bounds

The chunk world bounds.

GetChunkOverrideMaterial(const Int2& patchCoord, const Int2& chunkCoord)

Gets the chunk material that overrides the terrain default one.

Declaration
public MaterialBase* GetChunkOverrideMaterial(const Int2& patchCoord, const Int2& chunkCoord) const
Parameters
Int2 patchCoord

The patch coordinates (x and z).
Int2 chunkCoord

The chunk coordinates (x and z).
Returns
MaterialBase

The value.

GetChunkSize()

Gets the terrain chunk vertices amount per edge (square).

Declaration
public int32 GetChunkSize() const
Returns
int32

GetCollisionLOD()

Gets the terrain geometry LOD index used for collision.

Declaration
public int32 GetCollisionLOD() const
Returns
int32

GetForcedLOD()

Gets the terrain forced Level Of Detail index. Allows to bind the given chunks LOD to show. Value -1 disables this feature.

Declaration
public int32 GetForcedLOD() const
Returns
int32

GetLODBias()

Gets the terrain Level Of Detail bias value. Allows to increase or decrease rendered terrain quality.

Declaration
public int32 GetLODBias() const
Returns
int32

GetLODCount()

Gets the terrain Level Of Detail count.

Declaration
public int32 GetLODCount() const
Returns
int32

GetLODDistribution()

Gets the terrain LODs distribution parameter. Adjusts terrain chunks transitions distances. Use lower value to increase terrain quality or higher value to increase performance.

Declaration
public float GetLODDistribution() const
Returns
float

GetPatch(const Int2& patchCoord)

Gets the patch at the given location.

Declaration
public TerrainPatch* GetPatch(const Int2& patchCoord) const
Parameters
Int2 patchCoord

The patch location (x and z).
Returns
TerrainPatch

The patch.

GetPatch(int32 index)

Gets the patch at the given index.

Declaration
public TerrainPatch* GetPatch(int32 index) const
Parameters
int32 index

The index.
Returns
TerrainPatch

The patch.

GetPatch(int32 x, int32 z)

Gets the patch at the given location.

Declaration
public TerrainPatch* GetPatch(int32 x, int32 z) const
Parameters
int32 x

The patch location x.
int32 z

The patch location z.
Returns
TerrainPatch

The patch.

GetPatchBounds(int32 patchIndex, BoundingBox& bounds)

Gets the terrain patch world bounds at the given index.

Declaration
public void GetPatchBounds(int32 patchIndex, BoundingBox& bounds) const
Parameters
int32 patchIndex

The zero-based index of the terrain patch in the terrain patches collection.
BoundingBox bounds

The patch world bounds.

GetPatchCoord(int32 patchIndex, Int2& patchCoord)

Gets the terrain patch coordinates (x and z) at the given index.

Declaration
public void GetPatchCoord(int32 patchIndex, Int2& patchCoord) const
Parameters
int32 patchIndex

The zero-based index of the terrain patch in the terrain patches collection.
Int2 patchCoord

The patch location (x and z).

GetPatchesCount()

Gets the terrain patches count. Each patch contains 16 chunks arranged into a 4x4 square.

Declaration
public int32 GetPatchesCount() const
Returns
int32

GetPatchIndex(const Int2& patchCoord)

Gets the zero-based index of the terrain patch in the terrain patches collection.

Declaration
public int32 GetPatchIndex(const Int2& patchCoord) const
Parameters
Int2 patchCoord

The patch location (x and z).
Returns
int32

The zero-based index of the terrain patch in the terrain patches collection. Returns -1 if patch coordinates are invalid.

GetPhysicalMaterials()

Gets the list with physical materials used to define the terrain collider physical properties - each for terrain layer (layer index matches index in this array).

Declaration
public Array<JsonAssetReference<PhysicalMaterial>, FixedAllocation<8>> GetPhysicalMaterials() const
Returns
Array<JsonAssetReference<PhysicalMaterial>, FixedAllocation<8>>

GetScaleInLightmap()

Gets the terrain scale in lightmap (applied to all the chunks). Use value higher than 1 to increase baked lighting resolution.

Declaration
public float GetScaleInLightmap() const
Returns
float

HasPatch(const Int2& patchCoord)

Checks if terrain has the patch at the given coordinates.

Declaration
public bool HasPatch(const Int2& patchCoord) const
Parameters
Int2 patchCoord

The patch location (x and z).
Returns
bool

True if has patch added, otherwise false.

IntersectsItself(const Ray& ray, Real& distance, Vector3& normal)

Determines if there is an intersection between the current object and a ray.

Declaration
public virtual bool IntersectsItself(const Ray& ray, Real& distance, Vector3& normal) override
Parameters
Ray ray

The ray to test.
Real distance

When the method completes, contains the distance of the intersection (if any valid).
Vector3 normal

When the method completes, contains the intersection surface normal vector (if any valid).
Returns
bool

True whether the two objects intersected, otherwise false.
Overrides

OnActiveInTreeChanged()

Called when actor active in tree state gets changed.

Declaration
protected virtual void OnActiveInTreeChanged() override
Overrides

OnDebugDrawSelected()

Draws debug shapes for the selected actor and all child scripts.

Declaration
public virtual void OnDebugDrawSelected() override
Overrides

OnDisable()

Called when actor gets removed from game systems. Occurs on EndPlay event or when actor gets inactivated in hierarchy. Use this event to unregister object from other game system (eg. audio).

Declaration
protected virtual void OnDisable() override
Overrides

OnEnable()

Called when actor gets added to game systems. Occurs on BeginPlay event or when actor gets activated in hierarchy. Use this event to register object to other game system (eg. audio).

Declaration
protected virtual void OnEnable() override
Overrides

OnLayerChanged()

Called when layer gets changed.

Declaration
public virtual void OnLayerChanged() override
Overrides

OnPhysicsSceneChanged(PhysicsScene* previous)

Declaration
protected virtual void OnPhysicsSceneChanged(PhysicsScene* previous) override
Parameters
PhysicsScene previous

Overrides

OnTransformChanged()

Called when actor transform gets changed.

Declaration
protected virtual void OnTransformChanged() override
Overrides

RayCast(const Ray& ray, float& resultHitDistance, Int2& resultPatchCoord, Int2& resultChunkCoord, float maxDistance=MAX_float)

Performs a raycast against this terrain collision shape. Returns the hit chunk.

Declaration
public bool RayCast(const Ray& ray, float& resultHitDistance, Int2& resultPatchCoord, Int2& resultChunkCoord, float maxDistance=MAX_float) const
Parameters
Ray ray

The ray to test.
float resultHitDistance

The raycast result hit position distance from the ray origin. Valid only if raycast hits anything.
Int2 resultPatchCoord

The raycast result hit terrain patch coordinates (x and z). Valid only if raycast hits anything.
Int2 resultChunkCoord

The raycast result hit terrain chunk coordinates (relative to the patch, x and z). Valid only if raycast hits anything.
float maxDistance

The maximum distance the ray should check for collisions.
Returns
bool

True if ray hits an object, otherwise false.

RayCast(const Vector3& origin, const Vector3& direction, float& resultHitDistance, float maxDistance=MAX_float)

Performs a raycast against this collider shape.

Declaration
public virtual bool RayCast(const Vector3& origin, const Vector3& direction, float& resultHitDistance, float maxDistance=MAX_float) const final
Parameters
Vector3 origin

The origin of the ray.
Vector3 direction

The normalized direction of the ray.
float resultHitDistance

The raycast result hit position distance from the ray origin. Valid only if raycast hits anything.
float maxDistance

The maximum distance the ray should check for collisions.
Returns
bool

True if ray hits an object, otherwise false.
Overrides

RayCast(const Vector3& origin, const Vector3& direction, float& resultHitDistance, TerrainChunk*& resultChunk, float maxDistance=MAX_float)

Performs a raycast against this terrain collision shape. Returns the hit chunk.

Declaration
public bool RayCast(const Vector3& origin, const Vector3& direction, float& resultHitDistance, TerrainChunk*& resultChunk, float maxDistance=MAX_float) const
Parameters
Vector3 origin

The origin of the ray.
Vector3 direction

The normalized direction of the ray.
float resultHitDistance

The raycast result hit position distance from the ray origin. Valid only if raycast hits anything.
TerrainChunk resultChunk

The raycast result hit chunk. Valid only if raycast hits anything.
float maxDistance

The maximum distance the ray should check for collisions.
Returns
bool

True if ray hits an object, otherwise false.

RayCast(const Vector3& origin, const Vector3& direction, RayCastHit& hitInfo, float maxDistance=MAX_float)

Performs a raycast against this collider, returns results in a RaycastHit structure.

Declaration
public virtual bool RayCast(const Vector3& origin, const Vector3& direction, RayCastHit& hitInfo, float maxDistance=MAX_float) const final
Parameters
Vector3 origin

The origin of the ray.
Vector3 direction

The normalized direction of the ray.
RayCastHit hitInfo

The result hit information. Valid only when method returns true.
float maxDistance

The maximum distance the ray should check for collisions.
Returns
bool

True if ray hits an object, otherwise false.
Overrides

RemoveLightmap()

Removes the lightmap data from the terrain.

Declaration
public void RemoveLightmap()

RemovePatch(const Int2& patchCoord)

Removes the patch.

Declaration
public void RemovePatch(const Int2& patchCoord)
Parameters
Int2 patchCoord

The patch location (x and z).

Serialize(SerializeStream& stream, const void* otherObj)

Serializes object to the output stream compared to the values of the other object instance (eg. default class object). If other object is null then serialize all properties.

Declaration
public virtual void Serialize(SerializeStream& stream, const void* otherObj) override
Parameters
SerializeStream stream

The output stream.
void otherObj

The instance of the object to compare with and serialize only the modified properties. If null, then serialize all properties.
Overrides

SetBoundsExtent(const Vector3& value)

Sets the terrain chunks bounds extent. Values used to expand terrain chunks bounding boxes. Use it when your terrain material is performing vertex offset operations on a GPU.

Declaration
public void SetBoundsExtent(const Vector3& value)
Parameters
Vector3 value

SetChunkOverrideMaterial(const Int2& patchCoord, const Int2& chunkCoord, MaterialBase* value)

Sets the chunk material to override the terrain default one.

Declaration
public void SetChunkOverrideMaterial(const Int2& patchCoord, const Int2& chunkCoord, MaterialBase* value)
Parameters
Int2 patchCoord

The patch coordinates (x and z).
Int2 chunkCoord

The chunk coordinates (x and z).
MaterialBase value

The value to set.

SetCollisionLOD(int32 value)

Sets the terrain geometry LOD index used for collision.

Declaration
public void SetCollisionLOD(int32 value)
Parameters
int32 value

SetForcedLOD(int32 value)

Sets the terrain forced Level Of Detail index. Allows to bind the given chunks LOD to show. Value -1 disables this feature.

Declaration
public void SetForcedLOD(int32 value)
Parameters
int32 value

SetLODBias(int32 value)

Sets the terrain Level Of Detail bias value. Allows to increase or decrease rendered terrain quality.

Declaration
public void SetLODBias(int32 value)
Parameters
int32 value

SetLODDistribution(float value)

Sets the terrain LODs distribution parameter. Adjusts terrain chunks transitions distances. Use lower value to increase terrain quality or higher value to increase performance.

Declaration
public void SetLODDistribution(float value)
Parameters
float value

SetPhysicalMaterials(const Array<JsonAssetReference<PhysicalMaterial>, FixedAllocation<8>>& value)

Sets the list with physical materials used to define the terrain collider physical properties - each for terrain layer (layer index matches index in this array).

Declaration
public void SetPhysicalMaterials(const Array<JsonAssetReference<PhysicalMaterial>, FixedAllocation<8>>& value)
Parameters
Array<JsonAssetReference<PhysicalMaterial>, FixedAllocation<8>> value

SetScaleInLightmap(float value)

Sets the terrain scale in lightmap (applied to all the chunks). Use value higher than 1 to increase baked lighting resolution.

Declaration
public void SetScaleInLightmap(float value)
Parameters
float value

Setup(int32 lodCount=6, int32 chunkSize=127)

Setups the terrain. Clears the existing data.

Declaration
public void Setup(int32 lodCount=6, int32 chunkSize=127)
Parameters
int32 lodCount

The LODs count. The actual amount of LODs may be lower due to provided chunk size (each LOD has 4 times less quads).
int32 chunkSize

The size of the chunk (amount of quads per edge for the highest LOD). Must be power of two minus one (eg. 63 or 127).

SetupPatchHeightMap(const Int2& patchCoord, int32 heightMapLength, const float* heightMap, const byte* holesMask=nullptr, bool forceUseVirtualStorage=false)

Setups the terrain patch using the specified heightmap data.

Declaration
public bool SetupPatchHeightMap(const Int2& patchCoord, int32 heightMapLength, const float* heightMap, const byte* holesMask=nullptr, bool forceUseVirtualStorage=false)
Parameters
Int2 patchCoord

The patch coordinates (x and z).
int32 heightMapLength

The height map array length. It must match the terrain descriptor, so it should be (chunkSize*4+1)^2. Patch is a 4 by 4 square made of chunks. Each chunk has chunkSize quads on edge.
float heightMap

The height map. Each array item contains a height value.
byte holesMask

The holes mask (optional). Normalized to 0-1 range values with holes mask per-vertex. Must match the heightmap dimensions.
bool forceUseVirtualStorage

If set to true patch will use virtual storage by force. Otherwise it can use normal texture asset storage on drive (valid only during Editor). Runtime-created terrain can only use virtual storage (in RAM).
Returns
bool

True if failed, otherwise false.

SetupPatchSplatMap(const Int2& patchCoord, int32 index, int32 splatMapLength, const Color32* splatMap, bool forceUseVirtualStorage=false)

Setups the terrain patch layer weights using the specified splatmaps data.

Declaration
public bool SetupPatchSplatMap(const Int2& patchCoord, int32 index, int32 splatMapLength, const Color32* splatMap, bool forceUseVirtualStorage=false)
Parameters
Int2 patchCoord

The patch coordinates (x and z).
int32 index

The zero-based index of the splatmap texture.
int32 splatMapLength

The splatmap map array length. It must match the terrain descriptor, so it should be (chunkSize*4+1)^2. Patch is a 4 by 4 square made of chunks. Each chunk has chunkSize quads on edge.
Color32 splatMap

The splat map. Each array item contains 4 layer weights.
bool forceUseVirtualStorage

If set to true patch will use virtual storage by force. Otherwise it can use normal texture asset storage on drive (valid only during Editor). Runtime-created terrain can only use virtual storage (in RAM).
Returns
bool

True if failed, otherwise false.

UpdateBounds()

Updates the cached bounds of the actor. Updates the cached world bounds for every patch and chunk.

Declaration
public void UpdateBounds()

UpdateLayerBits()

Updates the collider shapes collisions/queries layer mask bits.

Declaration
public void UpdateLayerBits()

See Also