PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience
I want to find out more Accept
Collapse Sidebar
  1. API REFERENCE
  2. BasePart

SubtractAsync

BasePart

This is a server-only function that uses articles/3D Modeling with Parts|CSG to subtract the geometry of a table of BasePart|BaseParts from the calling BasePart.

The following properties from the calling part will be applied to the resulting part:
  • Color
  • Material
  • Reflectance
  • Transparency
  • Anchored
  • CanCollide
  • Density
  • Friction
  • Elasticity
  • FrictionWeight
  • ElasticityWeight

The resulting union instance will have a null parent and will be named “Union”. If the resulting union’s PartOperation/UsePartColor is false, it is rendered with face colors. Face colors of the result come from colors of its constituent parts. Its PartOperation/UsePartColor|UsePartColor property defaults to false and its PartOperation/CollisionFidelity|CollisionFidelity matches the provided enum.

The original parts remain in the same state and location in the game’s tree as before operation.

The code snippet below demonstrates how to perform the operation as described above:

local part = workspace.Part1
local otherParts = {workspace.Part2, workspace.Part3, workspace.Part4}
 
-- Perform union operation
local newUnion = part:SubtractAsync(otherParts)

The image below visualizes parts before and after the operation. The red negated parts are subtracted from the grey part.

SubtractAsync Visualization

Potential Errors

  • There is a limit to how many parts can be generated. If a union operation would result in a part with more than 5000 triangles, it will fail and Studio will alert you to the error in the Output window.
  • A part made with solid modeling can only use one color and material. If you union two parts with different colors/materials, the result will use the characteristics of just one of the parts.
  • A unioned or negated part can only be scaled uniformly (all of the dimensions must be scaled at the same proportion). If you need to change the size of just one part in a solid model construction, it may be easier to un-union that part, resize it, and then redo the union process.
  • This function can only be called from the server. It cannot be called by the client.
  • All parts must be supported by CSG. Only `BasePart|BaseParts` are supported, not `Terrain` or meshes. If A union operation involving any non-supported part will fail and Studio will alert you to the error in the Output window.
  • The resulting union cannot be empty due to subtractions. If a union operation would result in an empty part, it will fail and Studio will alert you to the error in the Output window.

Solid-Modeling Playground

Now that you understand basic in-game solid modeling, experience it within a sample place!

Rotating Windows

Blast pieces out of rotating windows or fuse new material onto them. Includes a helper module script that rebuilds mechanisms with constraints and attachments!

See also

  • articles/In Game Solid Modeling, create custom plugins for solid modeling techniques like unions, negations, and separations
  • articles/3D Modeling with Parts, how to combine and subtract parts to create complex solid shapes
  • articles/Making an Arch, make an arch for your environment using the Negate tool

Parameters

Name Type Default Description

parts

Objects

The objects taking part in the subtraction

collisionfidelity

CollisionFidelity
Default

renderFidelity

RenderFidelity
Automatic

Returns

Return Type Summary

Instance

The resulting union from the subtraction operation

Code Samples

Basic In-Game Subtract Operation

This example assumes there are three parts named Part1, Part2, and Part3 in the Workspace. It creates a union by subtracting Part2 and Part3 from Part1, destroys the original parts, and inserts the resulting UnionOperation.

Expand 
local part = workspace.Part1
local otherParts = {workspace.Part2, workspace.Part3}

-- Perform subtract operation
local newUnion = part:SubtractAsync(otherParts)

-- Destroy source parts
part:Destroy()
for _, otherPart in pairs(otherParts) do
	otherPart:Destroy()
end

-- Insert new union into workspace
newUnion.Parent = workspace
Copy Code Light Theme

CSG Operations - Subtraction

Let’s test out in-game solid modeling with a quick demo script! You can copy and paste this into a Script within ServerScriptService, or wherever is most convenient.

In this example, a basic order of operations occurs:

  1. A red glass window is created in the center of the place (lines 2-10).
  2. A smaller block is created in the center of the window part (lines 13-19).
  3. After 2 seconds, BasePart/SubtractAsync|SubtractAsync() is called on the window, using the smaller block as the part to subtract.
  1. If successful, the resulting part is returned with a name of Union. This instance will not be parented to the workspace, so it’s your job to parent it back into the game world.
Expand 
-- Create a basic window part
local window = Instance.new("Part")
window.Size = Vector3.new(10, 16, 0.5)
window.Material = "Glass"
window.BrickColor = BrickColor.new("Persimmon")
window.Reflectance = 0.2
window.Transparency = 0.5
window.Position = Vector3.new(0, 8, 0)
window.Anchored = true
window.Parent = game.Workspace
 
-- Create a part to subtract from window
local subBlock = Instance.new("Part")
subBlock.Size = Vector3.new(4, 4, 4)
subBlock.Material = "SmoothPlastic"
subBlock.CanCollide = false
subBlock.Position = Vector3.new(0, 8, 0)
subBlock.Anchored = true
subBlock.Parent = game.Workspace
 
wait(2)
 
-- Subtract smaller block from window
local success, newUnion = pcall(function()
	return window:SubtractAsync({subBlock})
end)
 
if success and newUnion then
	newUnion.Position = window.Position
	newUnion.Anchored = true
	newUnion.Parent = game.Workspace
	-- Remove original parts
	window:Destroy()
	subBlock:Destroy()
end
Copy Code Light Theme