地形允许您创建动态可变环境，几乎没有延迟。目前基于 4×4×4 格子细胞,每个细胞都有一个数字介于 0 和 1 之间,代表几何应占用细胞的量,以及细胞的材料。占用率决定了细胞是如何与周围的细胞一起变形的，结果是没有网格限制的错觉。
了解更多信息，请参阅地形。
概要
属性
启用或禁用地形装饰。
指定动画草的长度。
MaterialColors 代表材料颜色精选能的编辑器，并且 不能由脚本编辑 。
要获取材料的颜色，请使用： Terrain:GetMaterialColor() 要设置材料的颜色，请使用： Terrain:SetMaterialColor()
显示最大可编辑区域的边界。
地形水的色调。
控制地形水反射的不透明程度。
地形水的透明度。
将地形水波的最大高度设置为螺柱。
设置地形水波每分钟移动上下的次数。
决定零件是否因物理原因无法移动。
零件装配的角速度。
零件在世界空间的质量中心。
零件装配的线速度。
零件装配的总质量。
对装配的根部分的参考。
决定零件是否会物理地与音频模拟进行交互，类似于 CastShadow 对于照明。
确定零件后面的表面类型。
确定零件底部面的表面类型。
决定零件的颜色。
确定世界中 BasePart 的位置和方向。
决定零件是否可能与其他零件发生碰撞。
决定零件在空间查询操作中是否被考虑。
决定是否 Touched 和 TouchEnded 事件在部分上发射。
决定零件是否投射阴影。
描述零件的质量中心所在的世界位置。
描述零件碰撞群组的名称。
决定零件的颜色。
指示零件的当前物理属性。
确定零件的几个物理属性。
用于启用或禁用零件和装配件的空气动力。
物理尺寸的 BasePart 在物理引擎中被视为实际尺寸。
确定零件前面的表面类型。
确定零件左侧面的表面类型。
确定一个乘数 BasePart.Transparency ，仅对本地客户可见。
决定是否在工作室中选择零件。
描述零件的质量、密度和体积的产品。
决定零件是否会对其刚性身体的总质量或惯性贡献。
确定零件的纹理和默认物理属性。
MaterialVariant 的名称。
描述世界中零件的旋转。
指定零件的支点与其 CFrame 的偏移。
描述零件在世界上的位置。
上次记录的物理更新时间。
决定零件是否反映了天空盒。
描述 Resize() 方法允许的最小变更的尺寸。
描述可以调整零件大小的面。
确定零件右侧的表面类型。
确定装配根部分的主规则。
零件在三个轴上的旋转度。
确定零件的尺寸（长度、宽度、高度）。
确定零件顶部面的表面类型。
决定零件可以通过多少（零件不透明度的反转）。
方法
返回地形元素中心的世界坐标(x,y,z)。
返回网格元素的左下角的位置(x,y,z)。
清除地形。
将一块地形存入 TerrainRegion 对象中，以便稍后可以加载回来。注意：TerrainRegion数据不会在服务器和客户端之间复制。
返回地形中非空的细胞数量。
在给定的空间中填充一球光滑的地形。
用给定的位置、旋转、大小和材料填充一个平滑地块。
在给定的空间中填充一个光滑的地形圆柱。
用平滑的地形填充一个 Region3 空间。
用给定的 Enum.Material 和地区的 CFrame 和 Size 填充一个楔形体积的地形。
返回指定地形材料的当前地形材料颜色。
将地形块应用到地形对象。注意：TerrainRegion数据不会在服务器和客户端之间复制。
返回基于通道名称的表格中的地形体素数据区域。
返回表格中的特定平滑地形区域。
- ReplaceMaterial(region : Region3,resolution : number,sourceMaterial : Enum.Material,targetMaterial : Enum.Material):()
用另一种材料替换区域内物质的地形。
设置当前地形材料颜色为指定地形材料。
返回包含点 位置 的网格细胞位置。
返回包含点位置的网格细胞位置，在位置位于网格边缘时，优先使用空的网格细胞。
返回包含点位置的网格细胞位置，在位置位于网格边缘时，优先使用非空的网格细胞。
使用声量通道数据的词典设置地形区域。
使用表格格式设置特定区域的平滑地形。
对装配应用角动力。
在装配的 center of mass 应用脉冲到装配。
在指定位置应用脉冲到装配。
返回零件是否可以相互碰撞。
检查您是否可以设置零件的网络所有权。
返回一个包含任何类型刚性连接头的对象与零件之间的表。
返回连接到该部分的所有关节或约束。
返回 Mass 属性的值。
返回当前网络所有者为该部分的网络所有者的现有玩家，或 nil 在服务器的情况下。
如果游戏引擎自动决定此部分的网络所有者，返回真值。
返回装配零件的基础部分。
返回与此部分交叉的所有 BasePart.CanCollide 真零件的表。
返回零件在给定位置对这个零件的线速度。
如果对象连接到一个部件，可以将其固定在那里（例如 Anchored 部件），则返回真值；否则返回错误值。
像使用 Studio 缩放工具一样，改变对象的大小。
将指定的玩家设置为网络所有者，用于此网络和所有连接的零件。
让游戏引擎动态决定谁将处理零件的物理（客户端之一或服务器）。
- IntersectAsync(parts : Instances,collisionfidelity : Enum.CollisionFidelity,renderFidelity : Enum.RenderFidelity):Instance
从零件和给定数组列中的其他零件的重叠几何中创建一个新的 IntersectOperation 。
- SubtractAsync(parts : Instances,collisionfidelity : Enum.CollisionFidelity,renderFidelity : Enum.RenderFidelity):Instance
从零件中创建一个新的 UnionOperation ，减去给定数组列中零件所占的几何图形。
- UnionAsync(parts : Instances,collisionfidelity : Enum.CollisionFidelity,renderFidelity : Enum.RenderFidelity):Instance
从零件中创建一个新的 UnionOperation ，加上给定数组列中零件所占的几何图形。
获取 PVInstance 的枢轴。
将 以及所有其子孙 转换为位于指定 的位置，使旋转点现在位于指定的 。
属性
MaterialColors
MaterialColors 代表材料颜色精选能的编辑器，并且 不能由脚本编辑 。
要获取材料的颜色，请使用： Terrain:GetMaterialColor()
要设置材料的颜色，请使用： Terrain:SetMaterialColor()
方法
CellCenterToWorld
返回地形元素中心的世界坐标(x,y,z)。
参数
返回
CellCornerToWorld
返回网格元素的左下角的位置(x,y,z)。
参数
返回
Clear
清除地形。
返回
CopyRegion
将一块地形存入 TerrainRegion 对象中，以便稍后可以加载回来。注意：TerrainRegion数据不会在服务器和客户端之间复制。
参数
返回
代码示例
The following code will copy the whole Terrain and clear it. After 5 seconds it will paste the terrain back.
local terrainRegion = workspace.Terrain:CopyRegion(workspace.Terrain.MaxExtents)
workspace.Terrain:Clear()
task.wait(5)
workspace.Terrain:PasteRegion(terrainRegion, workspace.Terrain.MaxExtents.Min, true)FillBall
在给定的空间中填充一球光滑的地形。
参数
返回
代码示例
Terrain:FillBall() creates a ball of terrain given a center position, ball radius, and terrain materials.
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
用给定的位置、旋转、大小和材料填充一个平滑地块。
参数
返回
FillCylinder
在给定的空间中填充一个光滑的地形圆柱。空间使用 CFrame、高度和半径进行定义。
参数
返回
FillWedge
FillWedge() 填充一个楔形体积的 Terrain 与给定的 Enum.Material 和区域的 CFrame 和尺寸。楔子的方向与等值的 WedgePart 相同。
参数
要填充的楔子的位置和方向。
要填充的楔子的尺寸。
楔子将被填充的材料。
返回
PasteRegion
将地形块应用到地形对象。注意：TerrainRegion数据不会在服务器和客户端之间复制。
参数
返回
代码示例
Creates some terrain, copies it, then pastes it using the following API:
--[[
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
返回基于通道名称的表格中的地形体素数据区域。
参数
从哪里阅读目标区域。必须与声量网格对齐。如果区域太大，将发生错误；目前限制为 4194304 声量³。
体素分辨率。必须为 4。
需要从声量数据中访问的通道ID列表（字符串）。每个通道ID代表在体素中存储的数据类型。目前支持的ID是{"SolidMaterial", "SolidOccupancy", "LiquidOccupancy"}。
返回
返回 voxel 数据作为基于 channelIds 输入的词典。钥匙代表每个通道 ID 与其相应值作为 3D 数据的阵列。
- SolidOccupancy — 像体素材料的占用率，如在 SolidMaterial 通频道中指定的。这是一个值为 0（空）和 1（满）之间的数值。
词典还包含一个 Size 值为每个通道数据 3D 阵列大小的键。
代码示例
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
返回表格中的特定平滑地形区域。
参数
从哪里阅读目标区域。必须与声量网格对齐。如果区域太大，将发生错误。限制目前为 4194304 声量^3。
体素分辨率。必须为 4。
返回
返回原始声量数据为两个 3D 阵列。
- materials - 从目标区域的 3D 阵列 Enum.Material 。还包含一个大小字段，与嵌套阵列的尺寸相等。
- occupancies - 来自目标区域的 3D 占用值阵列。还包含一个大小字段，与嵌套阵列的尺寸相等。
代码示例
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
替换材料将特定 内的地形替换为另一种材料。本质上，它是在 Terrain 材料上的匹配和替换操作。
限制
当调用此方法时，resolution参数必须为准确的 4。此外，区域 3 必须与地形材质网格对齐，即区域 3 的最小和最大点的组件必须被 4 分割。使用 Region3:ExpandToGrid() 将区域与此函数兼容。
参数
替换操作将发生的区域。
替换操作将发场景的解析度；目前这必须是准确的 4。
将被替换的旧材料。
新的材料。
返回
代码示例
This code sample demonstrates the usage of Terrain:ReplaceMaterial() by replacing grass near the game origin with asphalt. It does this by constructing a Region3 using two Vector3s.
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
设置当前地形材料颜色为指定地形材料。地形材料将向指定颜色转移其基色。
参数
返回
WorldToCellPreferEmpty
返回包含点位置的网格细胞位置，在位置位于网格边缘时，优先使用空的网格细胞。
参数
返回
WorldToCellPreferSolid
返回包含点位置的网格细胞位置，在位置位于网格边缘时，优先使用非空的网格细胞。
参数
返回
WriteVoxelChannels
使用声量通道数据的词典设置地形区域。
参数
要写入的目标区域必须与声量网格对齐。如果区域太大，将发生错误；目前限制为 4194304 声量³。
体素分辨率。必须为 4。
与 ReadVoxelChannels() 返回值相似的声量数据词典。钥匙代表每个通道ID与其相应值作为3D数据阵列。词典可支持单个或多个通道输入。
- SolidMaterial — 声量的Enum.Material 材料。请注意，Water 不再支持；相反，只包含水的体素应该输入为 SolidMaterial = Enum.Material.Air, LiquidOccupancy = x，其中 x 是一个数字，介于 0（专用）和 1（包括）之间。
- SolidOccupancy — 像体素材料的占用率，如在 SolidMaterial 通频道中指定的。这应该是在 0（空）和 1（满）之间的值。
返回
代码示例
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
使用表格格式设置特定区域的平滑地形。
参数
要写入的目标区域必须与声量网格对齐。如果区域太大，将抛出错误。
体素分辨率。必须为 4。
3D枚列的 Enum.Material. 维度必须与目标区域在像素上的大小完全匹配。
3D 阵列的声量占用（数字在 0 和 1 之间）。维度必须与目标区域在声量上的大小匹配。
返回
代码示例
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)Many terrain methods throw an error if their given region size is too large. The limit is currently 4194304 voxels^3 for ReadVoxels() and WriteVoxels(), and 67108864 voxels^3 for other methods. For methods that take a cframe + size combination (e.g. FillBlock, FillCylinder etc.), then the region volume is calculated from the AABB of the target area.
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))