Terrain

顯示已棄用項目

*此內容是使用 AI(Beta 測試版)翻譯,可能含有錯誤。若要以英文檢視此頁面,請按一下這裡

無法建立

地形讓您創建動態變形環境,並且幾乎沒有延遲。目前基於 4×4×4 格子細胞,每個細胞都有一個數字介於 0 和 1之間,代表幾何應該佔用細胞的量,以及細胞的材料。占用率決定細胞是如何與周圍的細胞一起變形的,結果是沒有網格限制的錯覺。

欲了解更多信息,請參閱地形

概要

屬性

屬性 繼承自 BasePart屬性 繼承自 PVInstance

方法

方法 繼承自 BasePart方法 繼承自 PVInstance
  • 平行寫入

    獲得 PVInstance 的軸心。

  • PivotTo(targetCFrame : CFrame):()

    將 以及所有其子孫 轉換為指定的 位置,使旋轉點現在位於指定的 位置。

活動

活動 繼承自 BasePart

屬性

Decoration

無法建立指令碼
平行讀取

目前啟用或停用 草地 地形材料上的動畫草,雖然未來修改此屬性可能會控制額外的裝飾功能。

GrassLength

無法建立指令碼
平行讀取

草地 地形材料上指定動畫草的長度,假設 Decoration 已啟用。有效值介於 0.1 和 1 之間。

MaterialColors

BinaryString
無法建立指令碼
平行讀取

MaterialColors 代表材料顏色功能的編輯器,並且 不能被腳本編輯

要取得材料的顏色,使用:Terrain:GetMaterialColor()

要設置材料的顏色,使用:Terrain:SetMaterialColor()

MaxExtents

唯讀
未複製
平行讀取

顯示最大可編輯區域的邊界。

WaterColor

平行讀取

地形水的色調。

WaterReflectance

平行讀取

控制地形水反射的不透明程度。

WaterTransparency

平行讀取

地形水的透明度。

WaterWaveSize

平行讀取

以厘米設置地形水波的最大高度。目前受限於 0 和 1 之間。

WaterWaveSpeed

平行讀取

設定地形水波每分鐘移動上下的次數。目前限制在 0 和 100 之間。

方法

CellCenterToWorld

返回地形元素中心的世界位置(x,y,z)。

參數

預設值:""
預設值:""
預設值:""

返回

CellCornerToWorld

返回網格細胞的左下角位置(x, y, z)。

參數

預設值:""
預設值:""
預設值:""

返回

Clear

()

清除地形。


返回

()

CopyRegion

將一塊地形存入 TerrainRegion 對象中,以便稍後載回。注意:TerrainRegion資料不會在伺服器與客戶端之間複製。

參數

region: Region3int16
預設值:""

返回

範例程式碼

The following code will copy the whole Terrain and clear it. After 5 seconds it will paste the terrain back.

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

返回地形中非空白細胞數量。


返回

FillBall

()

在指定空間填滿一球滑順的地形。

參數

center: Vector3

地形球的中心位置。

預設值:""
radius: number

地形球的單位圓徑範圍。

預設值:""
material: Enum.Material

地形球的 Enum.Material

預設值:""

返回

()

範例程式碼

Terrain:FillBall() creates a ball of terrain given a center position, ball radius, and terrain materials.

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

()

用給定的位置、旋轉、尺寸和材料填滿一塊平滑的地形。

參數

cframe: CFrame

地形方磚塊的位置和方向。

預設值:""
size: Vector3

方塊的孔距大小 - 高度和寬度。

預設值:""
material: Enum.Material

地形方磚塊的 Enum.Material

預設值:""

返回

()

FillCylinder

()

在給定的空間中填滿平滑地形的筒體。空間使用 CFrame、高度和範圍來定義。


local Workspace = game:GetService("Workspace")
Workspace.Terrain:FillCylinder(CFrame.new(0, 50, 0), 5, 30, Enum.Material.Asphalt)

參數

cframe: CFrame

地形圓筒的位置和方向。

預設值:""
height: number

地形圓筒的厘米高度。

預設值:""
radius: number

地形圓筒的圓徑範圍,以磚格為單位。

預設值:""
material: Enum.Material

地形圓筒的 Enum.Material

預設值:""

返回

()

FillRegion

()

用平滑的地形填充 Region3 空間。

參數

region: Region3
預設值:""
resolution: number
預設值:""
material: Enum.Material
預設值:""

返回

()

FillWedge

()

填滿給定的 和區域的 和尺寸的楔形體積。楔子的方向與等值的 WedgePart 相同。

參數

cframe: CFrame

要填充的楔子位置和方向。

預設值:""
size: Vector3

要填充的楔子的尺寸。

預設值:""
material: Enum.Material

楔子將被填滿的材料。

預設值:""

返回

()

GetMaterialColor

平行寫入

返回指定地形材料的現有地形材料顏色。

參數

material: Enum.Material
預設值:""

返回

PasteRegion

()

將地形塊應用到地形對物件。注意:TerrainRegion資料不會在服務器和客戶端之間複製。

參數

預設值:""
corner: Vector3int16
預設值:""
pasteEmptyCells: boolean
預設值:""

返回

()

範例程式碼

Creates some terrain, copies it, then pastes it using the following API:

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

平行寫入

返回基於通道名稱的表格中的地形體積數據的區域。

參數

region: Region3

要讀取的目標區域必須與音箱網格對齊。如果區域過大,將發生錯誤;目前限制為 4194304 個音箱³。

預設值:""
resolution: number

音箱解析度。必須是 4。

預設值:""
channelIds: Array

需要從虛擬空間數據中訪問的通道ID(字串)列表。每個通道ID代表在 voxe體素 中儲存的數據類型。目前支持的ID是{"SolidMaterial", "SolidOccupancy", "LiquidOccupancy"}

預設值:""

返回

返回 voxel 數據作為基於 channelIds 輸入的辭典。鑰匙代表每個通道 ID 並將其值轉換為 3D 數據的陣列。

  • SolidMaterial — 虛擬物體的 Enum.Material 材料。請注意,Water 不再支持;相反,包含水的體素將有值 LiquidOccupancy
  • SolidOccupancy — 在 SolidMaterial 通頻道中指定的體素材料的使用率。這是一個介於 0(空)和 1(滿)之間的值。
  • LiquidOccupancy — 指定在 voxel 中 Water 材料的占用率為值在 0(沒有水)和 1(滿水)之間。如果 SolidOccupancy 是 1 和 SolidMaterial 不是 Air ,這將是 0。

辭典也包含一個 Size 值代表每個通道數據3D陣列大小的鑰匙。

範例程式碼

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

平行寫入

以表格形式返回特定區域的平滑地形。

參數

region: Region3

要讀取的目標區域必須與音箱網格對齊。如果區域過大,將發生錯誤。目前限制為 4194304 個音箱^3。

預設值:""
resolution: number

音箱解析度。必須是 4。

預設值:""

返回

以兩個 3D 陣列返回原始音箱數據。

  • materials - 來自目標區域的 3D 陣列 Enum.Material 。也包含尺寸欄位,與孤立陣列的尺寸相等。
  • occupancies - 來自目標區域的 3D 空間值數組。也包含一個大小欄位,等於叢集數組的尺寸。

範例程式碼

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

()

取代材料會將特定的 內的地形替換為另一種材料。本質上是在 Terrain 材料上的匹配和替換操作。

限制

當呼叫此方法時,resolution參數必須正確為 4。此外,區域 3 必須與地形材料網格對齊,即區域 3 的最小和最大點數必須是 4 的倍數。使用 Region3:ExpandToGrid() 將區域變更為與此功能相容。

參數

region: Region3

替換操作將發生的區域。

預設值:""
resolution: number

替換操作將發空間的解析度;目前這必須是正確的 4。

預設值:""
sourceMaterial: Enum.Material

將被替換的舊材料。

預設值:""
targetMaterial: Enum.Material

新的材料。

預設值:""

返回

()

範例程式碼

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.

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

()

設置目標地形材料的現有地形材料顏色。地形材料將向指定顏色移動其基礎顏色。

參數

material: Enum.Material
預設值:""
value: Color3
預設值:""

返回

()

WorldToCell

返回包含點 位置 的網格細胞位置。

參數

position: Vector3
預設值:""

返回

WorldToCellPreferEmpty

返回包含點位置的網格細胞位置,在位置位於網格邊緣時,優先使用空白網格細胞。

參數

position: Vector3
預設值:""

返回

WorldToCellPreferSolid

返回包含點位置的網格細胞位置,在位置位於網格邊緣時,優先使用非空白網格細胞。

參數

position: Vector3
預設值:""

返回

WriteVoxelChannels

()

使用沃塞爾通道數據辭典設置地形區域。

參數

region: Region3

要寫入的目標區域必須與音箱網格對齊。如果區域過大,將發生錯誤;目前限制為 4194304 個音箱³。

預設值:""
resolution: number

音箱解析度。必須是 4。

預設值:""
channels: Dictionary

ReadVoxelChannels() 返回值相似的音箱數據辭典。鑰匙代表每個通道ID,並以其各自的值作為3D數據的陣列。辭典可支持單個或多個通道輸入。

  • SolidMaterial — 虛擬物體的 Enum.Material 材料。請注意,Water 不再支持;相反,只包含水的體素應該輸入為 SolidMaterial = Enum.Material.Air, LiquidOccupancy = x,其中 x 是介於 0(獨家)和 1(包括)之間的數字。
  • SolidOccupancy — 在 SolidMaterial 通頻道中指定的物體素材料的使用率。這應該是 0(空)和 1(滿)之間的值。
  • LiquidOccupancy — 指定在 voxel 中 Water 材料的占用率為值在 0(沒有水)和 1(滿水)之間。如果 SolidOccupancy 是 1 和 SolidMaterial 不是 Air ,這將是 0。
預設值:""

返回

()

範例程式碼

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

()

使用表格格式設置特定區域的平滑地形。

參數

region: Region3

要寫入的目標區域必須與音量網格對齊。如果區域過大,將發生錯誤。

預設值:""
resolution: number

音箱解析度。必須是 4。

預設值:""
materials: Array

3D枚列的 Enum.Material. 維度必須與目標區域在瓦斯中的大小完全匹配。

預設值:""
occupancy: Array

3D 的 voxel 佔用量處理 (數字介於 0 和 1之間)。維度必須與目標區域在 voxels 的大小相匹配。

預設值:""

返回

()

範例程式碼

Example

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.

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

活動