GeometryService:SubtractAsync

Creates one or more PartOperations from the main part minus the geometry occupied by other parts in the given array. Only primitive Parts and PartOperations are supported, not Terrain or MeshParts. Similar to Clone(), the returned parts have no set Parent.

The following properties from the main part (part) are applied to the resulting PartOperations:

• Color, Material, MaterialVariant, Reflectance, Transparency
• CanCollide
• Anchored, Density, Elasticity, ElasticityWeight, Friction, FrictionWeight

In the following image comparison, SubtractAsync() is called using the blue cylinder and an array containing the purple block. The resulting PartOperation resolves into a shape that omits the block's geometry from that of the cylinder.

Notes

• Compared to BasePart:SubtractAsync(), this method differs as follows:

  • The input parts do not need to be parented to the scene, allowing for background operations.
  • When the SplitApart option is set to true (default), each distinct body will be returned in its own PartOperation.
  • Each of the returned parts are in the coordinate space of the main part. This means that the (0, 0, 0) of any returned part is not necessarily at the center of its body.
  • It's possible to call this method on the client, but with some limitations. First, it currently must be done with objects created on the client. Secondly, there is no replication available from client to the server.

• The original parts remain intact following a successful operation. In most cases, you should parent the returned PartOperations to the same place as the main part, then Destroy() all of the original parts.

• By default, the face colors of the resulting PartOperations are borrowed from the Color property of the original parts, although you can enable their UsePartColor property to change them to a specific color.

• If a subtract operation would result in any PartOperations with more than 20,000 triangles, they will be simplified to 20,000. This will result in an error with code -14.

• If the main part is moving during the calculation of the operation, you can set the resulting parts to the updated CFrame of the main part, since the returned parts are in the same coordinate space as the main part.

• If using this method with a PartOperation as the main part, you can substitute the geometry of another PartOperation via SubstituteGeometry(), making it easier to utilize the geometry of the operation but maintain properties, attributes, tags, and children of the main part such as Attachments, Constraints, ParticleEmitters, light objects, and decals. This approach also circumvents the potential "flicker" of completely replacing the original PartOperation with another.

Parameters

Returns

local GeometryService = game:GetService("GeometryService")

local mainPart = workspace.BlueCylinder
local otherParts = { workspace.PurpleBlock }

local options = {
	CollisionFidelity = Enum.CollisionFidelity.Default,
	RenderFidelity = Enum.RenderFidelity.Automatic,
	SplitApart = true,
}

-- Perform subtract operation in pcall() since it's asyncronous
local success, newParts = pcall(function()
	return GeometryService:SubtractAsync(mainPart, otherParts, options)
end)

if success and newParts then
	-- Loop through resulting parts to reparent/reposition
	for _, newPart in pairs(newParts) do
		newPart.Parent = mainPart.Parent
		newPart.CFrame = mainPart.CFrame
		newPart.Anchored = mainPart.Anchored
	end

	-- Destroy original parts
	mainPart.Parent = nil
	mainPart:Destroy()
	for _, otherPart in pairs(otherParts) do
		otherPart.Parent = nil
		otherPart:Destroy()
	end
end