PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar
  1. apireference
  2. basepart

UnionAsync

BasePart

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


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:UnionAsync(otherParts)

The image below visualizes parts before and after the operation. The green parts are combined with the grey part.

Union 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

List of Part|Parts that are unioned with the calling part

collisionfidelity

CollisionFidelity
Default

Optional enum/CollisionFidelity|enum argument that specifies how similar the collision model of this solid model is, compared to the actual geometry of the solid model. Defaults to Enum.CollisionFidelity.Default

  • Default - detailed geometry based on convex decomp representation
  • Hull - convex hull of the result
  • Box - bounding box

renderFidelity

RenderFidelity
Automatic

Optional enum/RenderFidelity|enum argument that specifies the level of detail that solid-modeled parts will be shown in

  • Automatic - Dynamically control a solid-modeled part’s level of detail depending on its distance from the camera (see table above)
  • Precise - Specifically set a solid-modeled part’s level of detail regardless of its distance from the camera (lowest, medium, or highest)

Returns

Return Type Summary

Instance

Resulting UnionOperation with default name “Union”

Code Samples

Basic In-Game Union Operation

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

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

-- Perform union operation
local newUnion = part:UnionAsync(otherParts)

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

-- Insert new union into workspace
newUnion.Parent = workspace