Terrain

Show Deprecated
Not Creatable

Terrain lets you create dynamically morphable environments with little to no lag. It is currently based on a 4×4×4 grid of cells, where each cell has a number between 0 and 1 representing how much the geometry should occupy the cell, and the material of the cell. The occupancy determines how the cell will morph together with surrounding cells, and the result is the illusion of having no grid constraint.

For more information, see Terrain.

Summary

Properties

Enables or disables terrain decoration.

NOT SCRIPTABLE
MaterialColors: BinaryString

MaterialColors represents the editor for the Material Color feature, and cannot be edited by scripts.

To get the color of a material, use: Terrain:GetMaterialColor() To set the color of a material, use: Terrain:SetMaterialColor()

NOT SCRIPTABLE

Displays the boundaries of the largest possible editable region.

READ ONLY
NOT REPLICATED

The tint of the Terrain water.

Controls how opaque the Terrain's water reflections are.

The transparency of the Terrain water.

Sets the maximum height of the Terrain water waves in studs.

Sets how many times the Terrain water waves will move up and down per minute.

Events

Methods


Returns the world position of the center of the terrain cell (x, y, z).


Returns the position of the lower-left-forward corner of the grid cell (x, y, z).

Clear(): void  

Clears the terrain.


Stores a chunk of terrain into a TerrainRegion object so it can be loaded back later. Note: TerrainRegion data does not replicate between server and client.


Returns the number of non-empty cells in the Terrain.

FillBall(center: Vector3, radius: number, material: Material): void  

Fills a ball of smooth terrain in a given space.

FillBlock(cframe: CFrame, size: Vector3, material: Material): void  

Fills a block of smooth terrain with a given location, rotation, size, and material.

FillCylinder(cframe: CFrame, height: number, radius: number, material: Material): void  

Fills a cylinder of smooth terrain in a given space.

FillRegion(region: Region3, resolution: number, material: Material): void  

Fills a Region3 space with smooth terrain.

FillWedge(cframe: CFrame, size: Vector3, material: Material): void  

Fills a wedge-shaped volume of Terrain with the given Material and the area's CFrame and Size.


Returns current terrain material color for specified terrain material.

HideTerrainRegion(): void  


PasteRegion(region: TerrainRegion, corner: Vector3int16, pasteEmptyCells: boolean): void  

Applies a chunk of terrain to the Terrain object. Note: TerrainRegion data does not replicate between server and client.

ReadVoxels(region: Region3, resolution: number): Tuple  CUSTOM LUA STATE

Returns a certain region of smooth terrain in table format.

ReplaceMaterial(region: Region3, resolution: number, sourceMaterial: Material, targetMaterial: Material): void  

Replaces the terrain of a material within a region with another material.

SetMaterialColor(material: Material, value: Color3): void  

Sets current terrain material color for specified terrain material.

SetTerrainRegion(cframe: CFrame, size: Vector3): void  


SetWireframeRegion(cframe: CFrame, size: Vector3): void  


ShowTerrainRegion(): void  


WorldToCell(position: Vector3): Vector3  

Returns the grid cell location that contains the point position.


Returns the grid cell location that contains the point position, preferring empty grid cells when position is on a grid edge.


Returns the grid cell location that contains the point position, preferring non-empty grid cells when position is on a grid edge.

WriteVoxels(region: Region3, resolution: number, materials: Array, occupancy: Array): void  CUSTOM LUA STATE

Sets a certain region of smooth terrain using table format.

Properties

Decoration

Not Scriptable

Currently enables or disables geometric grass on the Grass terrain material, although future modifications of this property may control additional decorative features.

LastUsedModificationMethod

Hidden
Not Replicated

MaterialColors

BinaryString
Not Scriptable

MaterialColors represents the editor for the Material Color feature, and cannot be edited by scripts.

To get the color of a material, use: Terrain:GetMaterialColor()

To set the color of a material, use: Terrain:SetMaterialColor()

MaxExtents

Read Only
Not Replicated

Displays the boundaries of the largest possible editable region.

ShorelinesUpgraded

WaterColor

The tint of the Terrain water.

WaterReflectance

Controls how opaque the Terrain's water reflections are.

WaterTransparency

The transparency of the Terrain water.

WaterWaveSize

Sets the maximum height of the Terrain water waves in studs. This is currently constrained to between 0 and 1.

WaterWaveSpeed

Sets how many times the Terrain water waves will move up and down per minute. This is currently constrained to between 0 and 100.

Events

Methods

CanShorelinesBeUpgraded

Roblox Script Security

Returns

CellCenterToWorld

Returns the world position of the center of the terrain cell (x, y, z).

Parameters


Returns

CellCornerToWorld

Returns the position of the lower-left-forward corner of the grid cell (x, y, z).

Parameters


Returns

Clear

void

Clears the terrain.


Returns

void

CopyRegion

Stores a chunk of terrain into a TerrainRegion object so it can be loaded back later. Note: TerrainRegion data does not replicate between server and client.

Parameters

region: Region3int16

Code Samples

Terrain:CopyRegion

1local terrainRegion = workspace.Terrain:CopyRegion(workspace.Terrain.MaxExtents)
2workspace.Terrain:Clear()
3task.wait(5)
4workspace.Terrain:PasteRegion(terrainRegion, workspace.Terrain.MaxExtents.Min, true)

CountCells

Returns the number of non-empty cells in the Terrain.


Returns

FillBall

void

Fills a ball of smooth terrain in a given space.

Parameters

center: Vector3

The position of the center of the terrain ball.

radius: number

The radius in studs of the terrain ball.

material: Material

The Material of the terrain ball.


Returns

void

No return.

Code Samples

Terrain:FillBall

1workspace.Terrain:FillBall(Vector3.new(0, 0, 0), 5, Enum.Material.Grass)

FillBlock

void

Fills a block of smooth terrain with a given location, rotation, size, and material.

Parameters

cframe: CFrame

The cframe (position and orientation) of the terrain block.

size: Vector3

The size in studs of the square block - both the height and width.

material: Material

The Material of the terrain ball.


Returns

void

No return.

FillCylinder

void

Fills a cylinder of smooth terrain in a given space. The space is defined using a CFrame, height, and radius.

Usage


1workspace.Terrain:FillCylinder(CFrame.new(0, 50, 0), 5, 30, Enum.Material.Asphalt)
2

Parameters

cframe: CFrame

The CFrame (position and orientation) of the terrain cylinder.

height: number

The height in studs of the terrain cylinder.

radius: number

The radius in studs of the terrain cylinder.

material: Material

The Material of the terrain cylinder.


Returns

void

No return.

FillRegion

void

Fills a Region3 space with smooth terrain.

Parameters

region: Region3
resolution: number
material: Material

Returns

void

FillWedge

void

FillWedge fills a wedge-shaped volume of Terrain with the given Material and the area's CFrame and Size. The orientation of the wedge is the same as an equivalent WedgePart.

The results of a call to Terrain:FillWedge with CFrame (0, 50, 0), Size (20, 20, 20), and Material Asphalt

In the image above, a floating chunk of Terrain was created by calling this function as in the following code. A transparent, pink part with the Front surface marked with a Motor indicates the provided CFrame and Size.


1workspace.Terrain:FillWedge(CFrame.new(0, 50, 0), Vector3.new(20, 20, 20), Enum.Material.Asphalt)
2

Parameters

cframe: CFrame

The position and orientation of the wedge to fill.

size: Vector3

The size of the wedge to fill.

material: Material

The material with which the wedge will be filled.


Returns

void

GetMaterialColor

Returns the current terrain material color for the specified terrain material.

Parameters

material: Material

Returns

HideTerrainRegion

void
Roblox Script Security

Returns

void

PasteRegion

void

Applies a chunk of terrain to the Terrain object. Note: TerrainRegion data does not replicate between server and client.

Parameters

corner: Vector3int16
pasteEmptyCells: boolean

Returns

void

Code Samples

Terrain:PasteRegion

1local terrainRegion = workspace.Terrain:CopyRegion(workspace.Terrain.MaxExtents)
2workspace.Terrain:Clear()
3task.wait(5)
4local corner = Vector3int16.new(-32000, -32000, -32000)
5local pasteEmptyRegion = false
6workspace.Terrain:PasteRegion(terrainRegion, corner, pasteEmptyRegion)

ReadVoxels

Custom Lua State

Returns a certain region of smooth terrain in table format.

Parameters

region: Region3

Target region to write to. Must be aligned to the voxel grid. Will throw an error if region is too large.

resolution: number

Voxel resolution. Must be 4.


Returns

Returns raw voxel data as two 3D arrays.

  • materials - 3D array of Material from the target area. Also contains a Size field, equal to the dimensions of the nested arrays.
  • occupancies - 3D array of occupancy values from the target area. Also contains a Size field, equal to the dimensions of the nested arrays.

Code Samples

Terrain:ReadVoxels() Code Example

1local REGION_START = Vector3.new(-20, -20, -20)
2local REGION_END = Vector3.new(20, 20, 20)
3
4local function printRegion(terrain, region)
5 local materials, occupancies = terrain:ReadVoxels(region, 4)
6
7 local size = materials.Size -- Same as occupancies.Size
8
9 for x = 1, size.X, 1 do
10 for y = 1, size.Y, 1 do
11 for z = 1, size.Z, 1 do
12 print(("(%2i, %2i, %2i): %.2f %s"):format(x, y, z, occupancies[x][y][z], materials[x][y][z].Name))
13 end
14 end
15 end
16end
17
18local region = Region3.new(REGION_START, REGION_END)
19
20printRegion(workspace.Terrain, region)

ReplaceMaterial

void

ReplaceMaterial replaces terrain of a certain Material within a Region3 with another material. Essentially, it is a find-and-replace operation on Terrain materials.

Constraints

When calling this method, the resolution parameter must be exactly 4. Additionally, the Region3 must be aligned to the terrain materials grid, i.e. the components of the Region3's minimum and maximum points must be divisible by 4. Use Region3:ExpandToGrid() to make a region compatible with this function.

Parameters

region: Region3

The region in which the replacement operation will occur.

resolution: number

The resolution at which the replacement operation will take place; at the moment this must be exactly 4.

sourceMaterial: Material

The old material that shall be replaced.

targetMaterial: Material

The new material.


Returns

void

Code Samples

Terrain:ReplaceMaterial

1local MIN = Vector3.new(-20, -20, -20)
2local MAX = Vector3.new(20, 20, 20)
3local materialToReplace = Enum.Material.Grass
4local replacementMaterial = Enum.Material.Asphalt
5
6workspace.Terrain:ReplaceMaterial(Region3.new(MIN, MAX), 4, materialToReplace, replacementMaterial)

SetMaterialColor

void

Sets current terrain material color for specified terrain material. Terrain material will shift its base color toward specified color.

Parameters

material: Material
value: Color3

Returns

void

SetTerrainRegion

void
Roblox Script Security

Parameters

cframe: CFrame
size: Vector3

Returns

void

SetWireframeRegion

void
Roblox Script Security

Parameters

cframe: CFrame
size: Vector3

Returns

void

ShowTerrainRegion

void
Roblox Script Security

Returns

void

WorldToCell

Returns the grid cell location that contains the point position.

Parameters

position: Vector3

Returns

WorldToCellPreferEmpty

Returns the grid cell location that contains the point position, preferring empty grid cells when position is on a grid edge.

Parameters

position: Vector3

Returns

WorldToCellPreferSolid

Returns the grid cell location that contains the point position, preferring non-empty grid cells when position is on a grid edge.

Parameters

position: Vector3

Returns

WriteVoxels

void
Custom Lua State

Sets a certain region of smooth terrain using table format.

Parameters

region: Region3

Target region to write to. Must be aligned to the voxel grid. Will throw an error if region is too large.

resolution: number

Voxel resolution. Must be 4.

materials: Array

3D array of Enum.Material. Dimensions must exactly match the size of the target region in voxels.

occupancy: Array

3D array of voxel occupancies (number between 0 and 1). Dimensions must exactly match the size of the target region in voxels.


Returns

void

Code Samples

Maximum Region Size

1local REGION_START = Vector3.new(-20, -20, -20)
2local REGION_END = Vector3.new(20, 20, 20)
3
4local CFRAME = CFrame.new(0, 20, 0)
5local SIZE = 50
6
7local function getRegionVolumeVoxels(region)
8 local resolution = 4
9 local size = region.Size
10 return (size.x / resolution) * (size.y / resolution) * (size.z / resolution)
11end
12
13local function isRegionTooLargeForReadWriteVoxels(region)
14 return getRegionVolumeVoxels(region) > 4194304
15end
16
17local function isRegionTooLarge(region)
18 return getRegionVolumeVoxels(region) > 67108864
19end
20
21-- Helper function to get an axis-aligned Region3 from the given cframe and size
22local function getAABBRegion(cframe, size)
23 local inv = cframe:Inverse()
24 local x = size * inv.RightVector
25 local y = size * inv.UpVector
26 local z = size * inv.LookVector
27
28 local w = math.abs(x.X) + math.abs(x.Y) + math.abs(x.Z)
29 local h = math.abs(y.X) + math.abs(y.Y) + math.abs(y.Z)
30 local d = math.abs(z.X) + math.abs(z.Y) + math.abs(z.Z)
31
32 local pos = cframe.Position
33 local halfSize = Vector3.new(w, h, d) / 2
34
35 return Region3.new(pos - halfSize, pos + halfSize):ExpandToGrid(4)
36end
37
38-- Specific functions for checking individual methods
39
40local function isRegionTooLargeForFillBall(cframe, radius)
41 local diameter = radius * 2
42 return isRegionTooLarge(getAABBRegion(cframe, Vector3.new(diameter, diameter, diameter)))
43end
44
45local function isRegionTooLargeForFillBlock(cframe, size)
46 return isRegionTooLarge(getAABBRegion(cframe, size))
47end
48
49local function isRegionTooLargeForFillCylinder(cframe, height, radius)
50 local diameter = radius * 2
51 return isRegionTooLarge(getAABBRegion(cframe, Vector3.new(diameter, height, diameter)))
52end
53
54local function isRegionTooLargeForFillRegion(region)
55 return isRegionTooLarge(region)
56end
57
58local function isRegionTooLargeForFillWedge(cframe, size)
59 return isRegionTooLarge(getAABBRegion(cframe, size))
60end
61
62local function isRegionTooLargeForReplaceMaterial(region)
63 return isRegionTooLarge(region)
64end
65
66local region = Region3.new(REGION_START, REGION_END)
67
68print(isRegionTooLargeForReadWriteVoxels(region))
69print(isRegionTooLargeForFillBall(CFRAME, SIZE))
70print(isRegionTooLargeForFillBlock(CFRAME, SIZE))
71print(isRegionTooLargeForFillCylinder(CFRAME, SIZE, SIZE))
72print(isRegionTooLargeForFillRegion(region))
73print(isRegionTooLargeForFillWedge(CFRAME, SIZE))
74print(isRegionTooLargeForReplaceMaterial(region))
Example

1local region = Region3.new(Vector3.new(0, 0, 0), Vector3.new(16, 28, 20)):ExpandToGrid(4)
2local RESOLUTION = 4
3local materials = {
4 {
5 {
6 Enum.Material.CrackedLava,
7 Enum.Material.CrackedLava,
8 Enum.Material.CrackedLava,
9 Enum.Material.CrackedLava,
10 Enum.Material.CrackedLava,
11 },
12 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
13 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
14 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
15 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
16 { Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud },
17 { Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air },
18 },
19 {
20 {
21 Enum.Material.CrackedLava,
22 Enum.Material.CrackedLava,
23 Enum.Material.CrackedLava,
24 Enum.Material.CrackedLava,
25 Enum.Material.CrackedLava,
26 },
27 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
28 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
29 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
30 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
31 { Enum.Material.Mud, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Mud },
32 { Enum.Material.Air, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Air },
33 },
34 {
35 {
36 Enum.Material.CrackedLava,
37 Enum.Material.Sand,
38 Enum.Material.Sand,
39 Enum.Material.Sand,
40 Enum.Material.CrackedLava,
41 },
42 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
43 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
44 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
45 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
46 { Enum.Material.Mud, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Mud },
47 { Enum.Material.Air, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Air },
48 },
49 {
50 {
51 Enum.Material.CrackedLava,
52 Enum.Material.CrackedLava,
53 Enum.Material.CrackedLava,
54 Enum.Material.CrackedLava,
55 Enum.Material.CrackedLava,
56 },
57 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
58 { Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
59 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
60 { Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
61 { Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud },
62 { Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air },
63 },
64}
65
66local occupancies = {
67 {
68 { 1, 1, 1, 1, 1 },
69 { 1, 1, 1, 1, 1 },
70 { 1, 1, 1, 1, 1 },
71 { 1, 1, 1, 1, 1 },
72 { 1, 1, 1, 1, 1 },
73 { 0.5, 0.5, 0.5, 0.5, 0.5 },
74 { 0, 0, 0, 0, 0 },
75 },
76 {
77 { 1, 1, 1, 1, 1 },
78 { 1, 1, 1, 1, 1 },
79 { 1, 1, 1, 1, 1 },
80 { 1, 1, 1, 1, 1 },
81 { 1, 1, 1, 1, 1 },
82 { 0.5, 1, 1, 1, 0.5 },
83 { 0, 1, 1, 1, 0 },
84 },
85 {
86 { 1, 1, 1, 1, 1 },
87 { 1, 1, 1, 1, 1 },
88 { 1, 1, 1, 1, 1 },
89 { 1, 1, 1, 1, 1 },
90 { 1, 1, 1, 1, 1 },
91 { 0.5, 1, 1, 1, 0.5 },
92 { 0, 1, 1, 1, 0 },
93 },
94 {
95 { 1, 1, 1, 1, 1 },
96 { 1, 1, 1, 1, 1 },
97 { 1, 1, 1, 1, 1 },
98 { 1, 1, 1, 1, 1 },
99 { 1, 1, 1, 1, 1 },
100 { 0.5, 0.5, 0.5, 0.5, 0.5 },
101 { 0, 0, 0, 0, 0 },
102 },
103}
104
105workspace.Terrain:WriteVoxels(region, RESOLUTION, materials, occupancies)