GeometryService

Returns a table of Constraints and Attachments which you may choose to preserve, along with their respective parents. Iterating over this table lets you decide whether to reparent recommended constraints and attachments to their respective parents.

Parameters

Returns

local GeometryService = game:GetService("GeometryService")

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

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

local constraintOptions = {
	tolerance = 0.1,
	weldConstraintPreserve = Enum.WeldConstraintPreserve.All,
	dropAttachmentsWithoutConstraints = false,
}

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

	-- Calculate constraints/attachments to either preserve or drop
	local recommendedTable = GeometryService:CalculateConstraintsToPreserve(mainPart, newParts, constraintOptions)

	-- Preserve constraints/attachments based on recommended table
	for _, item in pairs(recommendedTable) do
		if item.Attachment then
			item.Attachment.Parent = item.AttachmentParent
			if item.Constraint then
				item.Constraint.Parent = item.ConstraintParent
			end
		elseif item.NoCollisionConstraint then
			local newNoCollision = Instance.new("NoCollisionConstraint")
			newNoCollision.Part0 = item.NoCollisionPart0
			newNoCollision.Part1 = item.NoCollisionPart1
			newNoCollision.Parent = item.NoCollisionParent
		elseif item.WeldConstraint then
			local newWeldConstraint = Instance.new("WeldConstraint")
			newWeldConstraint.Part0 = item.WeldConstraintPart0
			newWeldConstraint.Part1 = item.WeldConstraintPart1
			newWeldConstraint.Parent = item.WeldConstraintParent
		end
	end

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

Creates one or more PartOperations from the intersecting geometry of the main part and 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, IntersectAsync() is called using the purple block and an array containing the blue block. The resulting PartOperation resolves into a shape of the intersecting geometry of both parts.

Notes

• Compared to BasePart:IntersectAsync(), 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 an intersect 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.PurpleBlock
local otherParts = { workspace.BlueBlock }

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

-- Perform intersect operation in pcall() since it's asyncronous
local success, newParts = pcall(function()
	return GeometryService:IntersectAsync(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

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

Creates one or more PartOperations from the main part plus 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, UnionAsync() is called using the blue block and an array containing the purple cylinder. The resulting PartOperation resolves into a shape of the combined geometry of both parts.

Notes

• Compared to BasePart:UnionAsync(), 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 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 union 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.BlueBlock
local otherParts = { workspace.PurpleCylinder }

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

-- Perform union operation in pcall() since it's asyncronous
local success, newParts = pcall(function()
	return GeometryService:UnionAsync(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