Terrain:FillBall() has an arbitrary radius limit of 812

[Maelstorm_1973]

Problem

When using scripts to generate terrain, I discovered that Terrain:FillBall() has an arbitrary radius limit of 812. Any attempt to exceed 812 in the radius field throws an error Extents are too large. Additionally, this limit is not mentioned anywhere in the documentation.

What I expect to happen is that there is no limit or that the limit is very large (> 4096).

Not sure why this is in place (I suspect it’s for performance reasons), but since I’m running this from the Studio command line (game is not running), performance shouldn’t be an issue as I just let the machine crunch the numbers and it finishes when it finishes.

Parameter	Value
Area	Engine: Studio
Type	Terrain
First Noticed	Today (12 Aug 2023)
Frequency	Constant
Impact	Moderate

Visuals

As one can see in the above illustration, a radius value of 812 works. However when one tries 813 as a radius value, an error is thrown.

The above image shows that there is no mention of this limit in the documentation.

Reproduction

The steps to reproduce this is as follows:

1. In Studio, start with a baseplate template.
2. Remove the baseplate and spawn location.
3. Enter the following command on the command line: game.Workspace.Terrain:FillBall(Vector3.new(0, 0, 0), 813, Enum.Material.Rock)
4. Observe the error.

Note: You can change 813 to 812 and it will generate the terrain sphere.

Workaround

I have developed the following function to get around this:

local function generateTerrainSphere(center, radius, material)
	local terrain = game.Workspace.Terrain
	if radius > 812 then
		for y = 0, radius, 1 do
			local x = math.sqrt((radius * radius) - (y * y))
			local vp = Vector3.new(center.X, center.Y + y, center.Z)
			local vm = Vector3.new(center.X, center.Y - y, center.Z)
			if x > 0 then
				terrain:FillCylinder(CFrame.new(vp), 1, x, material)
				terrain:FillCylinder(CFrame.new(vm), 1, x, material)
			end
		end
	else
		terrain:FillBall(center, radius, material)
	end
end

[ProtoValence (Valence)]

This is indeed done for performance reasons, we currently set the limit of any operation to a volume of 67108864 (1024 * 64 * 1024) voxels. In this case the volume we would need to process for a sphere of radius 812 studs can be calculated as follows.

812 stud radius * 2= 1624 stud diameter
1624 stud diameter * 1/4 voxel per stud = 406 voxels
406 ^ 3 voxels = 66923416 voxels

This is just barely under the limit, 813 pushes it over this limit. The current limit means that we maximally process 128 MB of Voxel Terrain at a time. A radius of 4096 would require at least 8 GB of RAM in order to process. We want to make sure these kinda of operations won’t crash mobile devices, and so unfortunately the radius needs to be limited.

If we were to change this in the future, we would likely add an API that lets you fill a part of a sphere given thats sphere’s radius and center. Then you can fill the sphere one chunk at a time (think of the sphere as being cut by a coordinate grid along all axes). You can already technically try an approach like this with read and write voxels. You would need to use the following steps:

1. Take the bounding box of your sphere and cut that bounding box into a bunch of evenly sized smaller regions. Make sure to save the central point in voxel space.
2. Iterate through the regions and for each region call readVoxels, then iterate through the voxels in that region and check whether the voxel’s coordinates are inside or outside your radius (check the distance between it and the center you defined earlier). Then write the voxels back.
3. Voila, you have a made sphere by putting together smaller pieces.

[Maelstorm_1973]

I figured figured that it was for performance reasons why this limitation exists. It just struck me as odd that 812 would be a limit as it seemed arbitrary. As you can see with my workaround above, I used a method from Calculus to build a sphere larger than the limit allows by filling in the sphere one disk as a time, which is also constructing a terrain sphere in parts like you mentioned.

Thank you for the confirmation and the clarification.