WriteVoxels

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Function of:

Description:

Sets a certain region of smooth terrain using the table format

Parameters

Name	Type	Default	Description
Name region	Type Region3	Default	Summary Target region to write to. Must be aligned to the voxel grid. Will throw an error if region is too large.
Name resolution	Type float	Default	Summary Voxel resolution. Must be 4
Name materials	Type Array	Default	Summary 3D array of Enum.Material. Dimensions must exactly match the size of the target region in voxels.
Name occupancy	Type Array	Default	Summary 3D array of voxel occupancies (number between 0 and 1). Dimensions must exactly match the size of the target region in voxels.

Returns

Return Type	Summary
Return Type void	Summary

Code Samples

Example

			
			
				Example

			
			
			
				Expected Output
			
			
				Expand
				
			
		

			
			local region = Region3.new(Vector3.new(0, 0, 0), Vector3.new(16, 28, 20)):ExpandToGrid(4)
local resolution = 4
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},
    },
}
 
game:GetService("Workspace").Terrain:WriteVoxels(region, resolution, materials, occupancies)
		

			
		

			
				
				Copy Code
			
			
				Light Theme
				
					
					
				
			
		

Maximum Region Size

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

				Expected Output
			
				Expand
				
			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, height, 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
		
				Copy Code
			
				Light Theme

WriteVoxels

Parameters

region

resolution

materials

occupancy

Returns

void

Code Samples

Example

Maximum Region Size