Class Terrain

Represents a single terrain object.

Namespace: FlaxEngine
Assembly: FlaxEngine.CSharp.dll
Syntax
[Unmanaged]
public sealed class Terrain : PhysicsColliderActor, ISerializable

Constructors

Terrain()

Initializes a new instance of the Terrain.

Declaration
public Terrain()

Fields

MaxLODs

The maximum amount of levels of detail for the terrain chunks.

Declaration
public const int MaxLODs = 6
Field Value
System.Int32

MaxSplatmapsCount

The terrain splatmaps amount limit. Each splatmap can hold up to 4 layer weights.

Declaration
public const int MaxSplatmapsCount = 2
Field Value
System.Int32

PatchChunksCount

The constant amount of terrain chunks per terrain patch object.

Declaration
public const int PatchChunksCount = 16
Field Value
System.Int32

PatchEdgeChunksCount

The constant amount of terrain chunks on terrain patch object edge.

Declaration
public const int PatchEdgeChunksCount = 4
Field Value
System.Int32

UnitsPerVertex

The constant amount of units per terrain geometry vertex (can be adjusted per terrain instance using non-uniform scale factor).

Declaration
public const float UnitsPerVertex = 100F
Field Value
System.Single

Properties

BoundsExtent

Gets or 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
[EditorOrder(120)]
[EditorDisplay("Terrain", null)]
[Unmanaged]
public Vector3 BoundsExtent { get; set; }
Property Value
Vector3

ChunkSize

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

Declaration
[Unmanaged]
public int ChunkSize { get; }
Property Value
System.Int32

CollisionLOD

Gets or sets the terrain geometry LOD index used for collision.

Declaration
[EditorOrder(500)]
[Limit(-1F, 100F, 0.1F)]
[EditorDisplay("Collision", "Collision LOD")]
[Unmanaged]
public int CollisionLOD { get; set; }
Property Value
System.Int32

DrawModes

The draw passes to use for rendering this object.

Declaration
[EditorOrder(115)]
[EditorDisplay("Terrain", null)]
[Unmanaged]
public DrawPass DrawModes { get; set; }
Property Value
DrawPass

ForcedLOD

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

Declaration
[EditorOrder(60)]
[Limit(-1F, 100F, 0.1F)]
[EditorDisplay("Terrain", "Forced LOD")]
[Unmanaged]
public int ForcedLOD { get; set; }
Property Value
System.Int32

LODBias

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

Declaration
[EditorOrder(50)]
[Limit(-100F, 100F, 0.1F)]
[EditorDisplay("Terrain", "LOD Bias")]
[Unmanaged]
public int LODBias { get; set; }
Property Value
System.Int32

LODCount

Gets the terrain Level Of Detail count.

Declaration
[Unmanaged]
public int LODCount { get; }
Property Value
System.Int32

LODDistribution

Gets or 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
[EditorOrder(70)]
[Limit(0F, 5F, 0.01F)]
[EditorDisplay("Terrain", "LOD Distribution")]
[Unmanaged]
public float LODDistribution { get; set; }
Property Value
System.Single

Material

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

Declaration
[EditorOrder(100)]
[EditorDisplay("Terrain", null)]
[Unmanaged]
public MaterialBase Material { get; set; }
Property Value
MaterialBase

PatchesCount

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

Declaration
[Unmanaged]
public int PatchesCount { get; }
Property Value
System.Int32

PhysicalMaterials

Gets or 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
[EditorOrder(520)]
[EditorDisplay("Collision", null)]
[Collection(MinCount = 8, MaxCount = 8)]
[Unmanaged]
public JsonAssetReference<PhysicalMaterial>[] PhysicalMaterials { get; set; }
Property Value
JsonAssetReference<PhysicalMaterial>[]

ScaleInLightmap

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

Declaration
[EditorOrder(110)]
[Limit(0F, 10000F, 0.1F)]
[EditorDisplay("Terrain", "Scale In Lightmap")]
[Unmanaged]
public float ScaleInLightmap { get; set; }
Property Value
System.Single

Methods

AddPatch(ref Int2)

Adds the patch.

Declaration
[Unmanaged]
public void AddPatch(ref Int2 patchCoord)
Parameters
Int2 patchCoord

The patch location (x and z).

AddPatches(ref Int2)

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

Declaration
[Unmanaged]
public void AddPatches(ref Int2 numberOfPatches)
Parameters
Int2 numberOfPatches

The number of patches (x and z axis).

DrawChunk(ref RenderContext, ref Int2, ref Int2, MaterialBase, Int32)

Draws the terrain chunk.

Declaration
[Unmanaged]
public void DrawChunk(ref RenderContext renderContext, ref Int2 patchCoord, ref Int2 chunkCoord, MaterialBase material, int lodIndex = 0)
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.
System.Int32 lodIndex

The LOD index.

DrawPatch(ref RenderContext, ref Int2, MaterialBase, Int32)

Draws the terrain patch.

Declaration
[Unmanaged]
public void DrawPatch(ref RenderContext renderContext, ref Int2 patchCoord, MaterialBase material, int lodIndex = 0)
Parameters
RenderContext renderContext

The rendering context.
Int2 patchCoord

The patch location (x and z).
MaterialBase material

The material to use for rendering.
System.Int32 lodIndex

The LOD index.

GetChunkBounds(Int32, Int32, out BoundingBox)

Gets the terrain chunk world bounds at the given index.

Declaration
[Unmanaged]
public void GetChunkBounds(int patchIndex, int chunkIndex, out BoundingBox bounds)
Parameters
System.Int32 patchIndex

The zero-based index of the terrain patch in the terrain patches collection.
System.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(ref Int2, ref Int2)

Gets the chunk material that overrides the terrain default one.

Declaration
[Unmanaged]
public MaterialBase GetChunkOverrideMaterial(ref Int2 patchCoord, ref Int2 chunkCoord)
Parameters
Int2 patchCoord

The patch coordinates (x and z).
Int2 chunkCoord

The chunk coordinates (x and z).
Returns
MaterialBase

The value.

GetPatch(ref Int2)

Gets the patch at the given location.

Declaration
[Unmanaged]
public TerrainPatch GetPatch(ref Int2 patchCoord)
Parameters
Int2 patchCoord

The patch location (x and z).
Returns
TerrainPatch

The patch.

GetPatch(Int32)

Gets the patch at the given index.

Declaration
[Unmanaged]
public TerrainPatch GetPatch(int index)
Parameters
System.Int32 index

The index.
Returns
TerrainPatch

The patch.

GetPatch(Int32, Int32)

Gets the patch at the given location.

Declaration
[Unmanaged]
public TerrainPatch GetPatch(int x, int z)
Parameters
System.Int32 x

The patch location x.
System.Int32 z

The patch location z.
Returns
TerrainPatch

The patch.

GetPatchBounds(Int32, out BoundingBox)

Gets the terrain patch world bounds at the given index.

Declaration
[Unmanaged]
public void GetPatchBounds(int patchIndex, out BoundingBox bounds)
Parameters
System.Int32 patchIndex

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

The patch world bounds.

GetPatchCoord(Int32, out Int2)

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

Declaration
[Unmanaged]
public void GetPatchCoord(int patchIndex, out Int2 patchCoord)
Parameters
System.Int32 patchIndex

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

The patch location (x and z).

GetPatchIndex(ref Int2)

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

Declaration
[Unmanaged]
public int GetPatchIndex(ref Int2 patchCoord)
Parameters
Int2 patchCoord

The patch location (x and z).
Returns
System.Int32

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

HasPatch(ref Int2)

Checks if terrain has the patch at the given coordinates.

Declaration
[Unmanaged]
public bool HasPatch(ref Int2 patchCoord)
Parameters
Int2 patchCoord

The patch location (x and z).
Returns
System.Boolean

True if has patch added, otherwise false.

RayCast(Ray, out Single, out Int2, out Int2, Single)

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

Declaration
[Unmanaged]
public bool RayCast(Ray ray, out float resultHitDistance, out Int2 resultPatchCoord, out Int2 resultChunkCoord, float maxDistance = 3.40282347E+38F)
Parameters
Ray ray

The ray to test.
System.Single 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.
System.Single maxDistance

The maximum distance the ray should check for collisions.
Returns
System.Boolean

True if ray hits an object, otherwise false.

RayCast(Vector3, Vector3, out Single, out TerrainChunk, Single)

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

Declaration
[Unmanaged]
public bool RayCast(Vector3 origin, Vector3 direction, out float resultHitDistance, out TerrainChunk resultChunk, float maxDistance = 3.40282347E+38F)
Parameters
Vector3 origin

The origin of the ray.
Vector3 direction

The normalized direction of the ray.
System.Single 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.
System.Single maxDistance

The maximum distance the ray should check for collisions.
Returns
System.Boolean

True if ray hits an object, otherwise false.

RemovePatch(ref Int2)

Removes the patch.

Declaration
[Unmanaged]
public void RemovePatch(ref Int2 patchCoord)
Parameters
Int2 patchCoord

The patch location (x and z).

SetChunkOverrideMaterial(ref Int2, ref Int2, MaterialBase)

Sets the chunk material to override the terrain default one.

Declaration
[Unmanaged]
public void SetChunkOverrideMaterial(ref Int2 patchCoord, ref 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.

Setup(Int32, Int32)

Setups the terrain. Clears the existing data.

Declaration
[Unmanaged]
public void Setup(int lodCount = 6, int chunkSize = 127)
Parameters
System.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).
System.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(ref Int2, Int32, Single*, Byte*, Boolean)

Setups the terrain patch using the specified heightmap data.

Declaration
[Unmanaged]
public bool SetupPatchHeightMap(ref Int2 patchCoord, int heightMapLength, float *heightMap, byte *holesMask = default(byte *), bool forceUseVirtualStorage = false)
Parameters
Int2 patchCoord

The patch coordinates (x and z).
System.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.
System.Single* heightMap

The height map. Each array item contains a height value.
System.Byte* holesMask

The holes mask (optional). Normalized to 0-1 range values with holes mask per-vertex. Must match the heightmap dimensions.
System.Boolean 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
System.Boolean

True if failed, otherwise false.

SetupPatchHeightMap(ref Int2, Single[], Byte[], Boolean)

Setups the terrain patch using the specified heightmap data.

Declaration
public bool SetupPatchHeightMap(ref Int2 patchCoord, float[] heightMap, byte[] holesMask = null, bool forceUseVirtualStorage = false)
Parameters
Int2 patchCoord

The patch location (x and z coordinates).
System.Single[] heightMap

The height map. Each array item contains a height value (2D inlined array). It should has size equal (chunkSize*4+1)^2.
System.Byte[] holesMask

The holes mask (optional). Normalized to 0-1 range values with holes mask per-vertex. Must match the heightmap dimensions.
System.Boolean 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
System.Boolean

True if failed, otherwise false.

SetupPatchSplatMap(ref Int2, Int32, Color32[], Boolean)

Setups the terrain patch using the specified heightmap data.

Declaration
public bool SetupPatchSplatMap(ref Int2 patchCoord, int index, Color32[] splatMap, bool forceUseVirtualStorage = false)
Parameters
Int2 patchCoord

The patch location (x and z coordinates).
System.Int32 index

The zero-based index of the splatmap texture.
Color32[] splatMap

The splat map. Each array item contains 4 layer weights. 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.
System.Boolean 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
System.Boolean

True if failed, otherwise false.

SetupPatchSplatMap(ref Int2, Int32, Int32, Color32*, Boolean)

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

Declaration
[Unmanaged]
public bool SetupPatchSplatMap(ref Int2 patchCoord, int index, int splatMapLength, Color32*splatMap, bool forceUseVirtualStorage = false)
Parameters
Int2 patchCoord

The patch coordinates (x and z).
System.Int32 index

The zero-based index of the splatmap texture.
System.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.
System.Boolean 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
System.Boolean

True if failed, otherwise false.

Extension Methods

See Also