33 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Terrain

Inherits from: BasePart → PVInstance → Instance → Object

The Terrain class lets you create dynamically morphable environments. It is 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.

Inherits from: BasePart

Memory category: Instances

Tags: NotCreatable

Properties

Name	Type / Returns	Description
Terrain.Decoration	boolean	Enables or disables terrain decoration.
Terrain.GrassLength	float	Specifies the length of animated grass.
Terrain.IsSmooth	boolean	Returns `true` if the game is using the smooth terrain system.
Terrain.MaterialColors	BinaryString	Represents the editor for the Material Color feature and cannot be edited by scripts.
Terrain.MaxExtents	Region3int16	Displays the boundaries of the largest possible editable region.
Terrain.WaterColor	Color3	The tint of `Terrain` water.
Terrain.WaterReflectance	float	Controls how opaque `Terrain` water reflections are.
Terrain.WaterTransparency	float	The transparency of `Terrain` water.
Terrain.WaterWaveSize	float	Sets the maximum height of `Terrain` water waves in studs.
Terrain.WaterWaveSpeed	float	Sets how many times `Terrain` water waves will move up and down per minute.

Inherited from BasePart

Name	Type / Returns	Description
BasePart.Anchored	boolean	Determines whether a part is immovable by physics.
BasePart.AssemblyAngularVelocity	Vector3	The angular velocity of the part's assembly.
BasePart.AssemblyCenterOfMass	Vector3	The center of mass of the part's assembly in world space.
BasePart.AssemblyLinearVelocity	Vector3	The linear velocity of the part's assembly.
BasePart.AssemblyMass	float	The total mass of the part's assembly.
BasePart.AssemblyRootPart	BasePart	A reference to the root part of the assembly.
BasePart.AudioCanCollide	boolean	Determines whether the part will physically interact with audio simulation, similar to `CastShadow` for lighting.
BasePart.BackParamA	float	Determines the first parameter for the SurfaceType on the Back face of a part.
BasePart.BackParamB	float	Determines the second parameter for the SurfaceType on the Back face of a part.
BasePart.BackSurface	SurfaceType	Determines the type of surface for the back face of a part.
BasePart.BackSurfaceInput	InputType	Determines the kind of input for the Back face of a part.
BasePart.BottomParamA	float	Determines the first parameter for the SurfaceType on the Bottom face of a part.
BasePart.BottomParamB	float	Determines the second parameter for the SurfaceType on the Bottom face of a part.
BasePart.BottomSurface	SurfaceType	Determines the type of surface for the bottom face of a part.
BasePart.BottomSurfaceInput	InputType	Determines the kind of input for the Bottom face of a part.
BasePart.BrickColor	BrickColor	Determines the color of a part.
BasePart.brickColor	BrickColor
BasePart.CanCollide	boolean	Determines whether a part may collide with other parts.
BasePart.CanQuery	boolean	Determines whether the part is considered during spatial query operations.
BasePart.CanTouch	boolean	Determines if `Touched` and `TouchEnded` events fire on the part.
BasePart.CastShadow	boolean	Determines whether or not a part casts a shadow.
BasePart.CenterOfMass	Vector3	Describes the world position in which a part's center of mass is located.
BasePart.CFrame	CFrame	Determines the position and orientation of the `BasePart` in the world.
BasePart.CollisionGroup	string	Describes the name of a part's collision group.
BasePart.CollisionGroupId	int	Describes the automatically set ID number of a part's collision group.
BasePart.Color	Color3	Determines the color of a part.
BasePart.CurrentPhysicalProperties	PhysicalProperties	Indicates the current physical properties of the part.
BasePart.CustomPhysicalProperties	PhysicalProperties	Determines several physical properties of a part.
BasePart.Elasticity	float	Used to control the Elasticity of the part, but it no longer does anything.
BasePart.EnableFluidForces	boolean	Used to enable or disable aerodynamic forces on parts and assemblies.
BasePart.ExtentsCFrame	CFrame	The `CFrame` of the physical extents of the `BasePart`.
BasePart.ExtentsSize	Vector3	The actual physical size of the `BasePart` as regarded by the physics engine.
BasePart.Friction	float	Used to control the Friction of the part, but now it no longer does anything.
BasePart.FrontParamA	float	Determines the first parameter for the SurfaceType on the Front face of a part.
BasePart.FrontParamB	float	Determines the second parameter for the SurfaceType on the Front face of a part.
BasePart.FrontSurface	SurfaceType	Determines the type of surface for the front face of a part.
BasePart.FrontSurfaceInput	InputType	Determines the kind of input for the Front face of a part (-Z direction).
BasePart.LeftParamA	float	Determines the first parameter for the SurfaceType on the Left face of a part.
BasePart.LeftParamB	float	Determines the second parameter for the SurfaceType on the Left face of a part.
BasePart.LeftSurface	SurfaceType	Determines the type of surface for the left face of a part.
BasePart.LeftSurfaceInput	InputType	Determines the kind of input for the Left face of a part.
BasePart.LocalTransparencyModifier	float	Determines a multiplier for `BasePart.Transparency` that is only visible to the local client.
BasePart.Locked	boolean	Determines whether a part is selectable in Studio.
BasePart.Mass	float	Describes the mass of the part, the product of its density and volume.
BasePart.Massless	boolean	Determines whether the part contributes to the total mass or inertia of its rigid body.
BasePart.Material	Material	Determines the texture and default physical properties of a part.
BasePart.MaterialVariant	string	The name of `MaterialVariant`.
BasePart.Orientation	Vector3	Describes the rotation of the part in the world.
BasePart.PivotOffset	CFrame	Specifies the offset of the part's pivot from its `CFrame`.
BasePart.Position	Vector3	Describes the position of the part in the world.
BasePart.ReceiveAge	float	Time since last recorded physics update.
BasePart.Reflectance	float	Determines how much a part reflects the skybox.
BasePart.ResizeableFaces	Faces	Describes the faces on which a part may be resized.
BasePart.ResizeIncrement	int	Describes the smallest change in size allowable by the `Resize()` method.
BasePart.RightParamA	float	Determines the first parameter for the SurfaceType on the Right face of a part.
BasePart.RightParamB	float	Determines the second parameter for the SurfaceType on the Right face of a part.
BasePart.RightSurface	SurfaceType	Determines the type of surface for the right face of a part.
BasePart.RightSurfaceInput	InputType	Determines the kind of input for the Right face of a part (-X direction).
BasePart.RootPriority	int	The main rule in determining the root part of an assembly.
BasePart.Rotation	Vector3	The rotation of the part in degrees for the three axes.
BasePart.RotVelocity	Vector3	Determines a part's change in orientation over time.
BasePart.Size	Vector3	Determines the dimensions of a part (length, height, width).
BasePart.SpecificGravity	float	The ratio of the part's density to the density of water determined by the `BasePart.Material`.
BasePart.TopParamA	float	Determines the first parameter for the SurfaceType on the Top face of a part.
BasePart.TopParamB	float	Determines the second parameter for the SurfaceType on the Top face of a part.
BasePart.TopSurface	SurfaceType	Determines the type of surface for the top face of a part.
BasePart.TopSurfaceInput	InputType	Determines the kind of input for the Top face of a part (+Y direction).
BasePart.Transparency	float	Determines how much a part can be seen through (the inverse of part opacity).
BasePart.Velocity	Vector3	Determines a part's change in position over time.

Inherited from PVInstance

Name	Type / Returns	Description
PVInstance.Origin	CFrame	Editor-only property that reads and sets the world `CFrame` of the `PVInstance`'s pivot, moving the entire instance when changed from the Studio Properties window.
PVInstance.Pivot Offset	CFrame	Editor-only property that displays and edits the pivot's `CFrame` relative to the instance, moving only the pivot and leaving the instance in place.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

Terrain.Decoration

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

Field	Value
type	boolean
tags	["NotScriptable"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Terrain.GrassLength

Specifies the length of animated grass on the Grass terrain material, assuming Decoration is enabled. Valid values are between 0.1 and 1.

Field	Value
type	float
tags	["NotScriptable"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Terrain.IsSmooth

Deprecated. The legacy terrain engine has been removed, so this property will always be true.

Returns true if the game is using the smooth terrain system.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated","Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}
capabilities	["Environment"]

Terrain.MaterialColors

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().

Field	Value
type	BinaryString
tags	["NotScriptable"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Terrain.MaxExtents

Displays the boundaries of the largest possible editable region as a Region3int16. The returned value spans from (-32000, -32000, -32000) to (32000, 32000, 32000) in cell coordinates, where each cell is 4 studs wide. This corresponds to a world-space volume of -128,000 to 128,000 studs on each axis. The property is read-only.

Field	Value
type	Region3int16
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}
capabilities	["Environment"]

Terrain.WaterColor

The tint color applied to Terrain water. This Color3 value is blended with the water's base appearance to shift its overall hue. The default value is [0.05, 0.33, 0.36] (a dark teal).

Field	Value
type	Color3
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Terrain.WaterReflectance

Controls how opaque the reflections on Terrain water are, on a scale of 0 (no reflections) to 1 (fully opaque reflections). The default value is 1.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Terrain.WaterTransparency

The transparency of Terrain water, on a scale of 0 (fully opaque) to 1 (fully transparent). The default value is 0.3.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Terrain.WaterWaveSize

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

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Terrain.WaterWaveSpeed

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

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Environment"]

Methods

Name	Type / Returns	Description
Terrain:AutowedgeCell	boolean	Obsolete function which no longer does anything.
Terrain:AutowedgeCells	()	Obsolete function which no longer does anything.
Terrain:CellCenterToWorld	Vector3	Returns the world position of the center of the terrain cell.
Terrain:CellCornerToWorld	Vector3	Returns the position of the lower-left-forward corner of the grid cell.
Terrain:Clear	()	Clears all terrain.
Terrain:ConvertToSmooth	()	Transforms the legacy terrain engine into the new terrain engine.
Terrain:CopyRegion	TerrainRegion	Stores a chunk of terrain into a `TerrainRegion` object so it can be loaded back later.
Terrain:CountCells	int	Returns the number of non-empty cells in the terrain.
Terrain:FillBall	()	Fills a ball of smooth terrain in a given space.
Terrain:FillBlock	()	Fills a block of smooth terrain with a given location, rotation, size, and material.
Terrain:FillCylinder	()	Fills a cylinder of smooth terrain in a given space.
Terrain:FillRegion	()	Fills a `Region3` space with smooth terrain.
Terrain:FillWedge	()	Fills a wedge-shaped volume of terrain with the given `Material`.
Terrain:GetCell	Tuple	Returns the closest cell material from the legacy terrain engine that matches the smooth terrain voxel specified.
Terrain:GetMaterialColor	Color3	Returns current terrain material color for specified terrain material.
Terrain:GetWaterCell	Tuple	Returns `true` if the cell is a water cell.
Terrain:PasteRegion	()	Applies a chunk of terrain to the `Terrain` object.
Terrain:ReadVoxelChannels	Dictionary	Returns a region of terrain voxel data in table format based on the channel names.
Terrain:ReadVoxels	Tuple	Returns a certain region of smooth terrain in table format.
Terrain:ReplaceMaterial	()	Replaces the terrain of a material within a region with another material.
Terrain:SetCell	()	Sets the occupancy and material of a specific terrain voxel.
Terrain:SetCells	()	Sets the occupancy and material of all terrain voxels in a specific region.
Terrain:SetMaterialColor	()	Sets current terrain material color for specified terrain material.
Terrain:SetWaterCell	()	Sets the specified terrain voxel's material to water and sets its occupancy to `1`.
Terrain:WorldToCell	Vector3	Returns the grid cell location that contains the position point.
Terrain:WorldToCellPreferEmpty	Vector3	Returns the grid cell location that contains the position point, preferring empty grid cells when position is on a grid edge.
Terrain:WorldToCellPreferSolid	Vector3	Returns the grid cell location that contains the point position, preferring non-empty grid cells when position is on a grid edge.
Terrain:WriteVoxelChannels	()	Sets a region of terrain using a dictionary of voxel channel data.
Terrain:WriteVoxels	()	Sets a certain region of smooth terrain using table format.

Inherited from BasePart

Name	Type / Returns	Description
BasePart:AngularAccelerationToTorque	Vector3	Returns the torque needed to achieve a given angular acceleration on this part's assembly, optionally accounting for gyroscopic effects.
BasePart:ApplyAngularImpulse	()	Apply an angular impulse to the assembly.
BasePart:ApplyImpulse	()	Apply an impulse to the assembly at the assembly's `center of mass`.
BasePart:ApplyImpulseAtPosition	()	Apply an impulse to the assembly at specified position.
BasePart:BreakJoints	()	Breaks any surface connection with any adjacent part, including `Weld` and other `JointInstance`.
BasePart:breakJoints	()
BasePart:CanCollideWith	boolean	Returns whether the parts can collide with each other.
BasePart:CanSetNetworkOwnership	Tuple	Checks whether you can set a part's network ownership.
BasePart:GetClosestPointOnSurface	Vector3	Returns the closest point on the part's surface to the given point.
BasePart:GetConnectedParts	List	Returns a table of parts connected to the object by any kind of rigid joint.
BasePart:GetJoints	Instances	Return all Joints or Constraints that is connected to this Part.
BasePart:GetMass	float	Returns the value of the `Mass` property.
BasePart:getMass	float
BasePart:GetNetworkOwner	Instance	Returns the current player who is the network owner of this part, or `nil` in case of the server.
BasePart:GetNetworkOwnershipAuto	boolean	Returns true if the game engine automatically decides the network owner for this part.
BasePart:GetNoCollisionConstraints	Instances	Returns the enabled `NoCollisionConstraint` objects currently registered for this part in its physics world.
BasePart:GetRenderCFrame	CFrame	OBSOLETE. Returns a CFrame describing where the part is being rendered at.
BasePart:GetRootPart	Instance	Returns the base part of an assembly of parts.
BasePart:GetTouchingParts	Instances	Returns a table of all `BasePart.CanCollide` true parts that intersect with this part.
BasePart:GetVelocityAtPosition	Vector3	Returns the linear velocity of the part's assembly at the given position relative to this part.
BasePart:IntersectAsync	Instance	Creates a new `IntersectOperation` from the overlapping geometry of the part and the other parts in the given array.
BasePart:IsGrounded	boolean	Returns true if the object is connected to a part that will hold it in place (eg an `Anchored` part), otherwise returns false.
BasePart:MakeJoints	()	Creates a joint on any side of the object that has a surface ID that can make a joint.
BasePart:makeJoints	()
BasePart:Resize	boolean	Changes the size of an object just like using the Studio resize tool.
BasePart:resize	boolean
BasePart:SetNetworkOwner	()	Sets the given player as network owner for this and all connected parts.
BasePart:SetNetworkOwnershipAuto	()	Lets the game engine dynamically decide who will handle the part's physics (one of the clients or the server).
BasePart:SubtractAsync	Instance	Creates a new `UnionOperation` from the part, minus the geometry occupied by the parts in the given array.
BasePart:TorqueToAngularAcceleration	Vector3	Returns the angular acceleration that would result from applying a given torque to this part's assembly, optionally accounting for gyroscopic effects.
BasePart:UnionAsync	Instance	Creates a new `UnionOperation` from the part, plus the geometry occupied by the parts in the given array.

Inherited from PVInstance

Name	Type / Returns	Description
PVInstance:GetPivot	CFrame	Gets the pivot of a `PVInstance`.
PVInstance:PivotTo	()	Transforms the `PVInstance` along with all of its descendant `PVInstances` such that the pivot is now located at the specified `CFrame`.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

Terrain:AutowedgeCell

Deprecated. This item is a deprecated function of a legacy Terrain engine that has been removed. Do not use it for new work.

Obsolete function which no longer does anything.

Parameters

Name	Type	Description
x	int	The X coordinate of the terrain cell.
y	int	The Y coordinate of the terrain cell.
z	int	The Z coordinate of the terrain cell.

Returns

Type	Description
boolean	Always returns `true`; the function no longer performs any operation.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:AutowedgeCells

Deprecated. This item is a deprecated function of a legacy Terrain engine that has been removed. Do not use it for new work.

Obsolete function which no longer does anything. It was part of the legacy terrain engine that has since been removed, so calling it on a region has no effect.

Parameters

Name	Type	Default	Description
region	Region3int16		The `Region3int16` specifying the region of terrain cells to process.

Returns

Type	Description
()

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:CellCenterToWorld

Returns the world position of the center of the terrain cell at grid coordinates (x, y, z). Each terrain cell is 4×4×4 studs, so this method returns the position of the lower-left-forward corner of the cell plus an offset of (2, 2, 2) studs.

Parameters

Name	Type	Description
x	int	The X coordinate of the terrain cell in grid space.
y	int	The Y coordinate of the terrain cell in grid space.
z	int	The Z coordinate of the terrain cell in grid space.

Returns

Type	Description
Vector3	The world-space `Vector3` position at the center of the specified cell.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:CellCornerToWorld

Returns the world position of the lower-left-forward corner of the terrain cell at grid coordinates (x, y, z). Each terrain cell is 4×4×4 studs, so the corner position is (x * 4, y * 4, z * 4).

Parameters

Name	Type	Description
x	int	The X coordinate of the terrain cell in grid space.
y	int	The Y coordinate of the terrain cell in grid space.
z	int	The Z coordinate of the terrain cell in grid space.

Returns

Type	Description
Vector3	The world-space `Vector3` position of the lower-left-forward corner of the specified cell.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:Clear

Clears the entire terrain, removing all material and occupancy data from every voxel. After calling this method, the Terrain object contains no geometry until new terrain is written via methods such as FillBlock() or WriteVoxels().

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:ConvertToSmooth

Deprecated. Since all places now automatically use the new terrain engine, this method is obsolete.

Transforms the legacy terrain engine into the new terrain engine. All places now automatically use the new terrain engine, so this method is obsolete.

Returns

Type	Description
()

Field	Value
tags	["Deprecated"]
security	PluginSecurity
thread safety	Unsafe
capabilities	["Environment"]

Terrain:CopyRegion

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

Parameters

Name	Type	Default	Description
region	Region3int16		The `Region3int16` defining the area of terrain to copy, in cell coordinates.

Returns

Type	Description
TerrainRegion	A `TerrainRegion` containing the copied voxel data from the specified region.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Code samples: View on Creator Hub (Terrain-CopyRegion1).

Terrain:CountCells

Returns the approximate number of non-empty cells in the terrain. A cell is considered non-empty when it has a material other than Air and an occupancy greater than zero. This count is an approximation and can be used to quickly gauge how much terrain geometry exists in the place.

Returns

Type	Description
int	The approximate number of non-empty terrain cells.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:FillBall

Fills a spherical volume of smooth terrain centered at center with the given radius (in studs) and Material. Voxels within the sphere are set to full occupancy with the specified material. Existing terrain inside the sphere is overwritten.

Parameters

Name	Type	Description
center	Vector3	The position of the center of the terrain ball.
radius	float	The radius in studs of the terrain ball.
material	Material	The `Material` of the terrain ball.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:FillBlock

Fills an oriented rectangular volume of smooth terrain at the position and rotation specified by cframe, with the dimensions given by size (in studs), using the specified Material. Because the block is oriented by a CFrame, it can be rotated to any angle. Existing terrain inside the volume is overwritten.

Parameters

Name	Type	Description
cframe	CFrame	The 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 block.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:FillCylinder

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

Parameters

Name	Type	Description
cframe	CFrame	The position and orientation of the terrain cylinder.
height	float	The height in studs of the terrain cylinder.
radius	float	The radius in studs of the terrain cylinder.
material	Material	The `Material` of the terrain cylinder.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:FillRegion

Fills an axis-aligned Region3 volume of smooth terrain with the specified Material at full occupancy. The resolution parameter must be exactly 4. The region must be aligned to the voxel grid; use Region3:ExpandToGrid() to align a region before calling.

Parameters

Name	Type	Description
region	Region3	The `Region3` to fill, which must be aligned to the voxel grid.
resolution	float	The voxel resolution; must be exactly `4`.
material	Material	The `Material` to fill the region with.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:FillWedge

This method 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.

Parameters

Name	Type	Description
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

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:GetCell

Deprecated. This item is a deprecated function of a legacy Terrain engine that has been removed. Do not use it for new work.

Returns the closest cell material from the legacy terrain engine that matches the smooth terrain voxel specified.

Parameters

Name	Type	Description
x	int	The X coordinate of the terrain cell.
y	int	The Y coordinate of the terrain cell.
z	int	The Z coordinate of the terrain cell.

Returns

Type	Description
Tuple	A tuple containing the legacy cell material, block type, and orientation of the specified cell.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:GetMaterialColor

Returns the current Color3 color for the specified terrain Material. This color represents the tint applied to the material's base texture. Passing Air or Water throws an error because those materials do not support custom colors.

Parameters

Name	Type	Default	Description
material	Material		The `Material` whose terrain color to retrieve.

Returns

Type	Description
Color3	The `Color3` representing the current color tint of the specified material.

Field	Value
security	None
thread safety	Safe
capabilities	["Environment"]

Terrain:GetWaterCell

Deprecated. This item is a deprecated function of a legacy Terrain engine that has been removed. Do not use it for new work.

Returns true if the cell is a water cell.

Parameters

Name	Type	Description
x	int	The X coordinate of the terrain cell.
y	int	The Y coordinate of the terrain cell.
z	int	The Z coordinate of the terrain cell.

Returns

Type	Description
Tuple	A tuple containing whether the cell has water, the water force, and the water direction.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:PasteRegion

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

Parameters

Name	Type	Description
region	TerrainRegion	The `TerrainRegion` to paste, previously obtained from `Terrain:CopyRegion()`.
corner	Vector3int16	The `Vector3int16` cell coordinate at which to place the lower-left-forward corner of the region.
pasteEmptyCells	boolean	Whether to overwrite existing terrain with empty (air) cells from the region.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Code samples: View on Creator Hub (Terrain-PasteRegion1).

Terrain:ReadVoxelChannels

Returns voxel data from a region of terrain, separated by channel. Unlike ReadVoxels(), this method lets you specify exactly which channels to read (SolidMaterial, SolidOccupancy, and/or LiquidOccupancy), and returns a dictionary keyed by channel ID. The region must be aligned to the voxel grid, resolution must be 4, and the region cannot exceed 4,194,304 voxels.

Parameters

Name	Type	Description
region	Region3	Target region to read from. Must be aligned to the voxel grid. Will throw an error if region is too large; limit is currently 4194304 voxels³.
resolution	float	Voxel resolution. Must be 4.
channelIds	Array	Array of channel IDs (strings) that need to be accessed from the voxel data. Each channel ID represents a type of data that's stored in voxel. Current supported IDs are `{"SolidMaterial", "SolidOccupancy", "LiquidOccupancy"}`.

Returns

Type Description

Dictionary Returns voxel data as a dictionary based on the channelIds input. Keys represent each channel ID with their respective value as an array of 3D data. - SolidMaterial — The Material material of the voxel. Note that Water is not supported anymore; instead, a voxel that contains water will have a value of LiquidOccupancy. - SolidOccupancy — The occupancy of the voxel's material as specified in the SolidMaterial channel. This is a value between 0 (empty) and 1 (full). - LiquidOccupancy — Specifies the occupancy of the Water material in a voxel as a value between 0 (no water) and 1 (full of water). If the SolidOccupancy is 1 and the SolidMaterial is not Air, this will be 0. The dictionary also contains a Size key with a value representing the 3D array size of each channel data.

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Safe
capabilities	["Environment"]

Code samples: View on Creator Hub (terrain-readvoxelchannels-code-example).

Terrain:ReadVoxels

Returns the voxel data for a region of smooth terrain as two 3D arrays: materials (an array of Material values) and occupancies (an array of numbers between 0 and 1). The region must be aligned to the voxel grid, resolution must be 4, and the region cannot exceed 4,194,304 voxels. For more granular channel control, see ReadVoxelChannels().

Parameters

Name	Type	Default	Description
region	Region3		Target region to read from. Must be aligned to the voxel grid. Will throw an error if region is too large. The limit is currently 4194304 voxels³.
resolution	float		Voxel resolution. Must be `4`.

Returns

Type	Description
Tuple	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.

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Safe
capabilities	["Environment"]

Code samples: View on Creator Hub (terrain-readvoxels-code-example).

Terrain:ReplaceMaterial

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

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

Parameters

Name	Type	Description
region	Region3	The region in which the replacement operation will occur.
resolution	float	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

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Code samples: View on Creator Hub (terrain-replacematerial).

Terrain:SetCell

Deprecated. This item is a deprecated function of a legacy Terrain engine that has been removed. Do not use it for new work.

Sets the occupancy of the specified terrain voxel to 1 and sets its material to the closest smooth terrain material that matches the cell material.

Parameters

Name	Type	Description
x	int	The X coordinate of the terrain cell.
y	int	The Y coordinate of the terrain cell.
z	int	The Z coordinate of the terrain cell.
material	CellMaterial	The `CellMaterial` to set for the cell.
block	CellBlock	The `CellBlock` shape type for the cell.
orientation	CellOrientation	The `CellOrientation` rotation for the cell.

Returns

Type	Description
()

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:SetCells

Deprecated. This item is a deprecated function of a legacy Terrain engine that has been removed. Do not use it for new work.

Sets the occupancy of all terrain voxels in the specified region to 1 and sets their materials to the closest smooth terrain material that matches the cell material.

Parameters

Name	Type	Description
region	Region3int16	The `Region3int16` specifying the area of terrain cells to set.
material	CellMaterial	The `CellMaterial` to apply to all cells in the region.
block	CellBlock	The `CellBlock` shape type to apply to all cells in the region.
orientation	CellOrientation	The `CellOrientation` rotation to apply to all cells in the region.

Returns

Type	Description
()

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:SetMaterialColor

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

Parameters

Name	Type	Default	Description
material	Material		The `Material` whose terrain color to change.
value	Color3		The `Color3` to apply as the new color tint for the material.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:SetWaterCell

Deprecated. This item is a deprecated function of a legacy Terrain engine that has been removed. Do not use it for new work.

Sets the specified terrain voxel's material to water and sets its occupancy to 1.

Parameters

Name	Type	Description
x	int	The X coordinate of the terrain cell.
y	int	The Y coordinate of the terrain cell.
z	int	The Z coordinate of the terrain cell.
force	WaterForce	The `WaterForce` value representing the water force in the cell.
direction	WaterDirection	The `WaterDirection` value representing the water flow direction.

Returns

Type	Description
()

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:WorldToCell

Returns the grid cell location that contains the point position.

Parameters

Name	Type	Default	Description
position	Vector3		The world-space `Vector3` to convert to a cell coordinate.

Returns

Type	Description
Vector3	A `Vector3` representing the grid cell coordinates containing the given position.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:WorldToCellPreferEmpty

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

Parameters

Name	Type	Default	Description
position	Vector3		The world-space `Vector3` to convert to a cell coordinate.

Returns

Type	Description
Vector3	A `Vector3` representing the grid cell coordinates, biased toward an empty (air) neighbor when the position lies on a cell boundary.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:WorldToCellPreferSolid

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

Parameters

Name	Type	Default	Description
position	Vector3		The world-space `Vector3` to convert to a cell coordinate.

Returns

Type	Description
Vector3	A `Vector3` representing the grid cell coordinates, biased toward a non-empty (solid) neighbor when the position lies on a cell boundary.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Environment"]

Terrain:WriteVoxelChannels

Sets a region of terrain using a dictionary of per-channel voxel data, the inverse of ReadVoxelChannels(). The channels dictionary maps channel ID strings (SolidMaterial, SolidOccupancy, and/or LiquidOccupancy) to their respective 3D data arrays. You may write one or more channels in a single call. The region must be aligned to the voxel grid, resolution must be 4, and the region cannot exceed 4,194,304 voxels.

Parameters

Name	Type	Description
region	Region3	Target region to write to. Must be aligned to the voxel grid. Will throw an error if region is too large; limit is currently 4194304 voxels³.
resolution	float	Voxel resolution. Must be `4`.
channels	Dictionary	Dictionary of voxel data similar to the return value of `ReadVoxelChannels()`. Keys represent each channel ID with their respective value as an array of 3D data. The dictionary can support single or multiple channel inputs. - `SolidMaterial` — The `Material` material of the voxel. Note that `Water` is not supported anymore; instead, a voxel that contains only water should be entered as `SolidMaterial = Enum.Material.Air, LiquidOccupancy = x`, where `x` is a number between `0` (exclusive) and `1` (inclusive). - `SolidOccupancy` — The occupancy of the voxel's material as specified in the `SolidMaterial` channel. This should be a value between `0` (empty) and `1` (full). - `LiquidOccupancy` — Specifies the occupancy of the `Water` material in a voxel as a value between `0` (no water) and `1` (full of water). If the `SolidOccupancy` is 1 and the `SolidMaterial` is not `Air`, this will be `0`.

Returns

Type	Description
()

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Code samples: View on Creator Hub (terrain-writevoxelchannels-example).

Terrain:WriteVoxels

Sets a region of smooth terrain from two 3D arrays: materials (an array of Material values) and occupancy (an array of numbers between 0 and 1). Both arrays must have dimensions that exactly match the target region in voxels. The region must be aligned to the voxel grid, resolution must be 4, and the region cannot exceed 4,194,304 voxels. For more granular channel control, see WriteVoxelChannels().

Parameters

Name	Type	Description
region	Region3	Target region to write to. Must be aligned to the voxel grid. Will throw an error if region is too large.
resolution	float	Voxel resolution. Must be `4`.
materials	Array	3D array of `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

Type	Description
()

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Unsafe
capabilities	["Environment"]

Code samples: View on Creator Hub (terrain-writevoxels-example).

Events

Inherited from BasePart

Name	Type / Returns	Description
BasePart.LocalSimulationTouched		Fires on the local client when another part comes in contact with this part.
BasePart.OutfitChanged		Fires when the part's appearance changes due to a `Shirt`.
BasePart.StoppedTouching		Fires on the local client when a part stops touching another part.
BasePart.Touched		Fires when a part touches another part as a result of physical movement.
BasePart.TouchEnded		Fires when a part stops touching another part as a result of physical movement.

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.