Terrain

Mostrar obsoleto
No creable

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.

Resumen

Propiedades

Propiedades heredados de BasePartPropiedades heredados de PVInstance

Métodos

Métodos heredados de BasePartMétodos heredados de PVInstance

Eventos

Eventos heredados de BasePart

Propiedades

Decoration

No programable
Leer paralelo

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

GrassLength

No programable
Leer paralelo

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

MaterialColors

BinaryString
No programable
Leer paralelo

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

Solo lectura
No replicado
Leer paralelo

Displays the boundaries of the largest possible editable region.

WaterColor

Leer paralelo

The tint of the Terrain water.

WaterReflectance

Leer paralelo

Controls how opaque the Terrain's water reflections are.

WaterTransparency

Leer paralelo

The transparency of the Terrain water.

WaterWaveSize

Leer paralelo

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

WaterWaveSpeed

Leer paralelo

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

Métodos

CellCenterToWorld

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

Parámetros


Devuelve

CellCornerToWorld

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

Parámetros


Devuelve

Clear

void

Clears the terrain.


Devuelve

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.

Parámetros

region: Region3int16

Devuelve

Muestras de código

Terrain:CopyRegion

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

CountCells

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


Devuelve

FillBall

void

Fills a ball of smooth terrain in a given space.

Parámetros

center: Vector3

The position of the center of the terrain ball.

radius: number

The radius in studs of the terrain ball.

material: Enum.Material

The Enum.Material of the terrain ball.


Devuelve

void

Muestras de código

Filling a Ball of Terrain

local Workspace = game:GetService("Workspace")
-- Creates a ball of grass at (0,0,-10) with a radius of 10 studs
Workspace.Terrain:FillBall(Vector3.new(0, 0, -10), 10, Enum.Material.Grass)

FillBlock

void

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

Parámetros

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: Enum.Material

The Enum.Material of the terrain block.


Devuelve

void

FillCylinder

void

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

Usage


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

Parámetros

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: Enum.Material

The Enum.Material of the terrain cylinder.


Devuelve

void

FillRegion

void

Fills a Region3 space with smooth terrain.

Parámetros

region: Region3
resolution: number
material: Enum.Material

Devuelve

void

FillWedge

void

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

Parámetros

cframe: CFrame

The position and orientation of the wedge to fill.

size: Vector3

The size of the wedge to fill.

material: Enum.Material

The material with which the wedge will be filled.


Devuelve

void

GetMaterialColor

Escribir paralelo

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

Parámetros

material: Enum.Material

Devuelve

PasteRegion

void

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

Parámetros

corner: Vector3int16
pasteEmptyCells: bool

Devuelve

void

Muestras de código

Create, Copy and Paste Terrain

--[[
Note: The use of int16 variants for these API is the result of legacy code.
The underlying voxel grid system uses Vector3int32 (Vector3).
]]
local Workspace = game:GetService("Workspace")
local Terrain = Workspace.Terrain
-- Create a simple terrain region (a 10x10x10 block of grass)
local initialRegion = Region3.new(Vector3.zero, Vector3.one * 10)
Terrain:FillRegion(initialRegion, 4, Enum.Material.Grass)
-- Copy the region using Terrain:CopyRegion
local copyRegion = Region3int16.new(Vector3int16.new(0, 0, 0), Vector3int16.new(10, 10, 10))
local copiedRegion = Terrain:CopyRegion(copyRegion)
-- Define where to paste the region (in this example, offsetting by 5 studs on the X-axis)
local newRegionCorner = Vector3int16.new(5, 0, 0)
-- Paste the region using Terrain:PasteRegion
Terrain:PasteRegion(copiedRegion, newRegionCorner, true)

ReadVoxelChannels

Escribir paralelo

Returns a region of terrain voxel data in table format based on the channel names.

Parámetros

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: number

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"}.


Devuelve

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 Enum.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.

Muestras de código

Terrain:ReadVoxelChannels()

local REGION_START = Vector3.new(-20, -20, -20)
local REGION_END = Vector3.new(20, 20, 20)
local function printRegion(terrain, region)
local channelOutput = terrain:ReadVoxelChannels(region, 4, {"SolidOccupancy", "SolidMaterial", "LiquidOccupancy"})
local size = channelOutput.Size
for x = 1, size.X do
for y = 1, size.Y do
for z = 1, size.Z do
print(("(%2i, %2i, %2i): %.2f %s %.2f"):format(x, y, z, channelOutput.SolidOccupancy[x][y][z], channelOutput.SolidMaterial[x][y][z].Name, channelOutput.LiquidOccupancy[x][y][z]))
end
end
end
end
local region = Region3.new(REGION_START, REGION_END)
printRegion(workspace.Terrain, region)

ReadVoxels

Escribir paralelo

Returns a certain region of smooth terrain in table format.

Parámetros

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^3.

resolution: number

Voxel resolution. Must be 4.


Devuelve

Returns raw voxel data as two 3D arrays.

  • materials - 3D array of Enum.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.

Muestras de código

Terrain:ReadVoxels() Code Example

local REGION_START = Vector3.new(-20, -20, -20)
local REGION_END = Vector3.new(20, 20, 20)
local function printRegion(terrain, region)
local materials, occupancies = terrain:ReadVoxels(region, 4)
local size = materials.Size -- Same as occupancies.Size
for x = 1, size.X, 1 do
for y = 1, size.Y, 1 do
for z = 1, size.Z, 1 do
print(("(%2i, %2i, %2i): %.2f %s"):format(x, y, z, occupancies[x][y][z], materials[x][y][z].Name))
end
end
end
end
local region = Region3.new(REGION_START, REGION_END)
printRegion(workspace.Terrain, region)

ReplaceMaterial

void

ReplaceMaterial replaces terrain of a certain Enum.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.

Parámetros

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: Enum.Material

The old material that shall be replaced.

targetMaterial: Enum.Material

The new material.


Devuelve

void

Muestras de código

Terrain:ReplaceMaterial

local Workspace = game:GetService("Workspace")
local terrain = Workspace.Terrain
local region = Region3.new(Vector3.new(-20, -20, -20), Vector3.new(20, 20, 20))
local resolution = 4
local materialToReplace = Enum.Material.Grass
local replacementMaterial = Enum.Material.Asphalt
terrain:ReplaceMaterial(region, resolution, materialToReplace, replacementMaterial)

SetMaterialColor

void

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

Parámetros

material: Enum.Material
value: Color3

Devuelve

void

WorldToCell

Returns the grid cell location that contains the point position.

Parámetros

position: Vector3

Devuelve

WorldToCellPreferEmpty

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

Parámetros

position: Vector3

Devuelve

WorldToCellPreferSolid

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

Parámetros

position: Vector3

Devuelve

WriteVoxelChannels

void

Sets a region of terrain using a dictionary of voxel channel data.

Parámetros

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: number

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 Enum.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.

Devuelve

void

Muestras de código

Terrain:WriteVoxelChannels()

local region = Region3.new(Vector3.new(0, 0, 0), Vector3.new(64, 32, 64))
local RESOLUTION = 4
local OCC_EPSILON = 1/256
local function generateRandomTerrainInRegion(regionInput)
local region = regionInput:ExpandToGrid(4)
local size = region.Size / 4
local solidMaterials = {}
local solidOccupancies = {}
local waterOcc = {}
for x = 1, size.X do
table.insert(solidMaterials, {})
table.insert(solidOccupancies, {})
table.insert(waterOcc, {})
for y = 1, size.Y do
table.insert(solidMaterials[x], {})
table.insert(solidOccupancies[x], {})
table.insert(waterOcc[x], {})
for z = 1, size.Z do
local mat = if math.random() < 0.5 then Enum.Material.Air else Enum.Material.Sand
local occ = 0
local water = math.random()
if mat == Enum.Material.Sand then
occ = math.random() / 2 + 0.5
if occ > 1 - OCC_EPSILON then
water = 0 -- Solids cannot contain water
end
else
occ = 0
end
table.insert(solidMaterials[x][y], mat)
table.insert(solidOccupancies[x][y], occ)
table.insert(waterOcc[x][y], water)
end
end
end
return {SolidMaterial = solidMaterials, SolidOccupancy = solidOccupancies, LiquidOccupancy = waterOcc}
end
local regionContent = generateRandomTerrainInRegion(region)
workspace.Terrain:WriteVoxelChannels(region, 4, regionContent)

WriteVoxels

void

Sets a certain region of smooth terrain using table format.

Parámetros

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.


Devuelve

void

Muestras de código

Example

local Workspace = game:GetService("Workspace")
local terrain = Workspace.Terrain
local resolution = 4
local region = Region3.new(Vector3.new(0, 0, 0), Vector3.new(16, 28, 20)):ExpandToGrid(resolution)
local materials = {
{
{
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
},
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud },
{ Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air },
},
{
{
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
},
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Mud, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Mud },
{ Enum.Material.Air, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Air },
},
{
{
Enum.Material.CrackedLava,
Enum.Material.Sand,
Enum.Material.Sand,
Enum.Material.Sand,
Enum.Material.CrackedLava,
},
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Mud, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Mud },
{ Enum.Material.Air, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Snow, Enum.Material.Air },
},
{
{
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
Enum.Material.CrackedLava,
},
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock, Enum.Material.Rock },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand, Enum.Material.Sand },
{ Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud, Enum.Material.Mud },
{ Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air, Enum.Material.Air },
},
}
local occupancies = {
{
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 0.5, 0.5, 0.5, 0.5, 0.5 },
{ 0, 0, 0, 0, 0 },
},
{
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 0.5, 1, 1, 1, 0.5 },
{ 0, 1, 1, 1, 0 },
},
{
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 0.5, 1, 1, 1, 0.5 },
{ 0, 1, 1, 1, 0 },
},
{
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 1, 1, 1, 1, 1 },
{ 0.5, 0.5, 0.5, 0.5, 0.5 },
{ 0, 0, 0, 0, 0 },
},
}
terrain:WriteVoxels(region, resolution, materials, occupancies)
Maximum Region Size

local REGION_START = Vector3.new(-20, -20, -20)
local REGION_END = Vector3.new(20, 20, 20)
local CFRAME = CFrame.new(0, 20, 0)
local SIZE = 50
local function getRegionVolumeVoxels(region)
local resolution = 4
local size = region.Size
return (size.x / resolution) * (size.y / resolution) * (size.z / resolution)
end
local function isRegionTooLargeForReadWriteVoxels(region)
return getRegionVolumeVoxels(region) > 4194304
end
local function isRegionTooLarge(region)
return getRegionVolumeVoxels(region) > 67108864
end
-- Helper function to get an axis-aligned Region3 from the given cframe and size
local function getAABBRegion(cframe, size)
local inv = cframe:Inverse()
local x = size * inv.RightVector
local y = size * inv.UpVector
local z = size * inv.LookVector
local w = math.abs(x.X) + math.abs(x.Y) + math.abs(x.Z)
local h = math.abs(y.X) + math.abs(y.Y) + math.abs(y.Z)
local d = math.abs(z.X) + math.abs(z.Y) + math.abs(z.Z)
local pos = cframe.Position
local halfSize = Vector3.new(w, h, d) / 2
return Region3.new(pos - halfSize, pos + halfSize):ExpandToGrid(4)
end
-- Specific functions for checking individual methods
local function isRegionTooLargeForFillBall(cframe, radius)
local diameter = radius * 2
return isRegionTooLarge(getAABBRegion(cframe, Vector3.new(diameter, diameter, diameter)))
end
local function isRegionTooLargeForFillBlock(cframe, size)
return isRegionTooLarge(getAABBRegion(cframe, size))
end
local function isRegionTooLargeForFillCylinder(cframe, height, radius)
local diameter = radius * 2
return isRegionTooLarge(getAABBRegion(cframe, Vector3.new(diameter, height, diameter)))
end
local function isRegionTooLargeForFillRegion(region)
return isRegionTooLarge(region)
end
local function isRegionTooLargeForFillWedge(cframe, size)
return isRegionTooLarge(getAABBRegion(cframe, size))
end
local function isRegionTooLargeForReplaceMaterial(region)
return isRegionTooLarge(region)
end
local region = Region3.new(REGION_START, REGION_END)
print(isRegionTooLargeForReadWriteVoxels(region))
print(isRegionTooLargeForFillBall(CFRAME, SIZE))
print(isRegionTooLargeForFillBlock(CFRAME, SIZE))
print(isRegionTooLargeForFillCylinder(CFRAME, SIZE, SIZE))
print(isRegionTooLargeForFillRegion(region))
print(isRegionTooLargeForFillWedge(CFRAME, SIZE))
print(isRegionTooLargeForReplaceMaterial(region))

Eventos