BasePart

Show Deprecated
Not Creatable
Not Browsable

BasePart is an abstract base class for in-world objects that render and are physically simulated while in the Workspace. There are several implementations of BasePart, the most common is Part, which can be one of three shapes. Others include WedgePart, MeshPart, SpawnLocation, and the singleton Terrain object within the Workspace. Most of the time, when documentation refers to a part, most BasePart implementations will work and not just Part.

BaseParts other than Terrain can be edited using the various studio tools. They are available via either the insert menu, or the Object Insert menu. Terrain is modified using a different set of tools. For more information, see Terrain.

For information on how BaseParts are grouped into simulated rigid bodies, see Understanding Assemblies.

MeshParts can be imported from a 3D Model file.

There are many different objects that interact with BasePart (other than Terrain):

  • They may be grouped within a Model, which allows several BasePart to be moved at the same time using SetPrimaryPartCFrame.
  • A Decal applies a stretched image texture to the faces of a part, though the exact mapping depends on the type of part.
  • A Texture applies a tiled image texture to the faces of a part much like a Decal.
  • A SurfaceGui renders GuiObjects on the face of a part.
  • An Attachment can be added to specify a CFrames relative to a parent BasePart. These are often used by physics Constraint objects, such as RopeConstraint and HingeConstraint.
  • ParticleEmitter emit particles uniformly in the volume of the BasePart to which they are parented.
  • Light objects like PointLight emit light from the center of a BasePart.
  • When played, a Sound parented to a BasePart will be physically located at the part's position.
  • As a sibling of a Humanoid, they can be used as limbs of a character and also animated when joined using Motor6D. If not a sibling of a Humanoid, BasePart can still be animated using an AnimationController.
  • If parented to a Tool and given the name "Handle", a BasePart can be held by characters.
  • You can make BasePart interactive by adding a ClickDetector.

Summary

Properties

Determines whether a part is immovable by physics.

The angular velocity of the part's assembly.

NOT REPLICATED

The center of mass of the part's assembly in world space.

READ ONLY
NOT REPLICATED

The linear velocity of the part's assembly.

NOT REPLICATED

The total mass of the part's assembly.

READ ONLY
NOT REPLICATED

A reference to the root part of the assembly.

READ ONLY
NOT REPLICATED

Determines the type of surface for the Back face of a part (+Z direction).

Determines the type of surface for the Bottom face of a part (-Y direction).

Determines the color of a part.

NOT REPLICATED

Determines the position and rotation of a part in the world.

Determines whether a part may collide with other parts.

Determines whether the part is considered during spatial query operations.

Determines if the part will trigger Touched and TouchEnded events on other BaseParts with TouchTransmitters.

Determines whether or not a part casts a shadow.

Describes the world position in which a part's center of mass is located.

READ ONLY
NOT REPLICATED

Describes the name of a part's collision group.

NOT REPLICATED

Describes the automatically set ID number of a part's collision group.

NOT REPLICATED

Determines the color of a part.

NOT REPLICATED

Determines several physical properties of a part.

Determines the type of surface for the Front face of a part (-Z direction).

Determines the type of surface for the Left face of a part (-X direction).

Determines whether a part is selectable in Studio.

Describes the mass of the part, the product of its density and volume.

READ ONLY
NOT REPLICATED

Determines whether the part contributes to the total mass or inertia of its rigid body.

Determines the texture and default physical properties of a part.

The name of MaterialVariant.

NOT REPLICATED

Describes the position of the part in the world.

NOT REPLICATED

Specifies the offset of the part's pivot from its CFrame.

Describes the position of the part in the world.

NOT REPLICATED

Determines how much a part reflects the skybox.

Describes the smallest change in size allowable by the Resize method.

READ ONLY
NOT REPLICATED

Describes the faces on which a part may be resized.

READ ONLY
NOT REPLICATED

Determines the type of surface for the Right face of a part (+X direction).

The main rule in determining the root part of an assembly.

The rotation of the part in degrees for the three axes.

NOT REPLICATED

Determines the dimensions of a part (length, width, height).

NOT REPLICATED

Determines the type of surface for the Top face of a part (+Y direction).

Determines how much a part can be seen through (the inverse of part opacity).

Events


Fired when a part stops touching another part.


Fired when a part comes in contact with another part.

Methods


Apply an angular impulse to the assembly.

ApplyImpulse(impulse: Vector3): nil  

Apply an impulse to the assembly at the assembly's center of mass.

ApplyImpulseAtPosition(impulse: Vector3, position: Vector3): nil  

Apply an impulse to the assembly at specified position.


Breaks any surface connection with any adjacent part, including Weld and other JointInstance.


Returns whether the parts can collide with each other.


Checks whether you can set a part's network ownership.


Returns a table of parts connected to the the object by any kind of rigid joint.


Return all Joints or Constraints that is connected to this Part.


Returns the value of the Mass property.


Returns the current player who is the network owner of this part, or nil in case of the server.


Returns true if the game engine automatically decides the network owner for this part.


Returns the base part of an assembly of parts.


Returns a table of all BasePart.CanCollide true parts that intersect with this part.


Returns the linear velocity of the part's assembly at the given position relative to this part.


Returns true if the object is connected to a part that will hold it in place (eg an BasePart.Anchored part), otherwise returns false.


Creates a joint on any side of the object that has a surface ID that can make a joint.

Resize(normalId: NormalId, deltaAmount: number): boolean  

Changes the size of an object just like using the Studio resize tool.

SetNetworkOwner(playerInstance: Player): nil  

Sets the given player as network owner for this and all connected parts.


Lets the game engine dynamically decide who will handle the part's physics (one of the clients or the server).

SubtractAsync(parts: Objects, collisionfidelity: CollisionFidelity, renderFidelity: RenderFidelity): Instance  YIELDS

Creates a new UnionOperation which occupies the same space as the part minus the space(s) occupied by the parts in the given array.

UnionAsync(parts: Objects, collisionfidelity: CollisionFidelity, renderFidelity: RenderFidelity): Instance  YIELDS

Performs a Union operation on the calling BasePart and the list of parts passed in as the first parameter.

Properties

Anchored

The Anchored property determines whether the part will be immovable by physics. When enabled, a part will never change position due to gravity, other parts collisions, overlapping other parts, or any other physics-related causes. A part that is not anchored is called unanchored. As a result, two anchored parts will never fire the BasePart.Touched event on each other. An anchored part may still be moved by changing its BasePart.CFrame or BasePart.Position, and it still may have a nonzero BasePart.AssemblyLinearVelocity and BasePart.AssemblyAngularVelocity. Finally, if an unanchored part is joined with an anchored part through an object like a Weld, it too will act anchored. If such a joint breaks the part may be affected by physics again. See Understanding Assemblies for more on this.

Network ownership cannot be set on anchored parts. If a part's anchored status changes on the server, the network ownership of that part will be affected.

AssemblyAngularVelocity

Not Replicated

The angular velocity vector of this part's assembly. It's the rate of change of orientation in radians per second.

Angular velocity is the same at every point of the assembly.

Setting the velocity directly may lead to unrealistic motion. Using Torque or AngularVelocity constraint is preferred, or use BasePart:ApplyAngularImpulse() if you want instantaneous change in velocity.

AssemblyCenterOfMass

Read Only
Not Replicated

A position calculated via the mass and position of all the parts in the assembly.

If the assembly has an anchored part, that part's center of mass will be the assembly's center of mass, and the assembly will have infinite mass.

Knowing the center of mass can help the assembly maintain stability. A force applied to the center of mass will not cause angular acceleration, only linear. An assembly with a low center of mass will have a better time staying upright under the effect of gravity.

AssemblyLinearVelocity

Not Replicated

The linear velocity vector of this part's assembly. It's the rate of change in position of the assembly's center of mass in studs per second.

If you want to know the velocity at a point other than the assembly's center of mass, use BasePart:GetVelocityAtPosition().

Setting the velocity directly may lead to unrealistic motion. Using a VectorForce constraint is preferred, or use BasePart:ApplyImpulse() if you want instantaneous change in velocity.

AssemblyMass

Read Only
Not Replicated

The sum of the mass of all the parts in this part's assembly. Parts that are Massless and are not the assembly's root part will not contribute to the AssemblyMass.

If the assembly has an anchored part, the assembly's mass is considered infinite. Constraints and other physical interactions between unanchored assemblies with a large difference in mass may cause instabilities.

AssemblyRootPart

Read Only
Not Replicated

This property indicates the BasePart automatically chosen to represent the Assembly|assembly's root part. It is the same part that's returned when developers call BasePart:GetRootPart().

The root part can be changed by changing the RootPriority of the parts in the assembly.

Parts that all share the same AssemblyRootPart are in the same assembly.

For more information on root parts, see Understanding Assemblies.

BackSurface

The BackSurface property determines the type of surface used for the +Z direction of a part. When two parts' faces are placed next to each other, they may create a joint between them. If set to Motor, the BasePart.BackSurfaceInput determines how a motor joint should behave.

Most SurfaceTypes render a texture on the part face if the BasePart.Material is set to Plastic. Some SurfaceTypes - Hinge, Motor and SteppingMotor - will render a 3D adornment instead. If this property is selected in the Properties window, it will be highlighted in the game world similar to that of a SurfaceSelection.

BottomSurface

The BottomSurface property determines the type of surface used for the -Y direction of a part. When two parts' faces are placed next to each other, they may create a joint between them. If set to Motor, the BasePart.BottomSurfaceInput determines how a motor joint should behave.

Most SurfaceTypes render a texture on the part face if the BasePart.Material is set to Plastic. Some SurfaceTypes - Hinge, Motor and SteppingMotor - will render a 3D adornment instead. If this property is selected in the Properties window, it will be highlighted in the game world similar to that of a SurfaceSelection.

BrickColor

Not Replicated

The BrickColor property determines the color of a part. If the part has a BasePart.Material, this also determines the color used when rendering the material texture. For more control over the color, the BasePart.Color property can be used (it is a Color3 variant of this property). If Color set, this property will use the closest BrickColor.

Other visual properties of a part are determined by BasePart.Transparency and BasePart.Reflectance.

CFrame

The CFrame property determines both the position and orientation of a part relative to the world. The part is rendered such that the CFrame is the center of the rendered 3D model (with one exception outlined below). For keeping track of positions relative to a part's CFrame, an Attachment is useful. Most visual flair objects (such as particles and lights) will render at a part's CFrame.

When setting CFrame, other joined parts are also moved relative to the part whose CFrame was set. This could be used for teleporting a player's character, however it is recommended to use Model:SetPrimaryPartCFrame() instead if you want to move an entire model. Unlike BasePart.Position, setting CFrame will always move the part to the exact given CFrame; in other words: no overlap checking is done when setting CFrame. If two collidable parts happen to overlap and one is not BasePart.Anchored, the physics solver will attempt to resolve the overlap.

In online sessions, a part may be rendered differently than its CFrame may suggest (e.g., for tweening the different CFrames received from the server). Use BasePart:GetRenderCFrame() to get the apparent CFrame.

CanCollide

CanCollide determines whether a part will physically interact with other parts. When disabled, other parts can pass through the brick uninterrupted. Parts used for decoration usually have CanCollide disabled, as they need not be considered by the physics engine.

If a part is not BasePart.Anchored and has CanCollide disabled, it may fall out of the world to be eventually destroyed by Workspace.FallenPartsDestroyHeight.

When CanCollide is disabled, parts may still fire the BasePart.Touched event (as well the other parts touching them). You can disable this with BasePart.CanTouch.

More information on collisions, see Detecting Collisions and Collision Filtering.

CanQuery

CanQuery determines whether the part is considered during spatial query operations, such as GetPartBoundsInBox or Raycast. CanCollide must also be disabled when disabling CanQuery. These functions will never include parts whose CanQuery and CanCollide is false.

Beyond this property, it is also possible to blacklist parts which are descendants of a given list of parts using an OverlapParams or RaycastParams object when calling the spatial query functions.

CanTouch

This property determines if the part will trigger Touched and TouchEnded events on other BaseParts with TouchTransmitters.

A BasePart's Touched or TouchEnded event will only fire if otherPart has CanTouch set to true.

When false, a touch event cannot be setup for the part. Attempting to do so will throw an error. If the property is set to false after a touch event is connected, the event will be disconnected and TouchTransmitter removed.

The two images below demonstrate how the property behaves using a non-colliding part with a script telling it to turn green when touched. First, on the left, we drop parts that are CanTouch. On the right, we drop parts that are not CanTouch.

Collision Groups

This collision logic can be enabled and disabled for Collision Filtering|Collision Groups using the Workspace.TouchesUseCollisionGroups property. In this case, when TouchesUseCollisionGroups is true parts in different groups set to not collide will ignore collisions and touch events - thereby ignoring this property

Performance

There is a small performance gain on parts that have both CanTouch and CanCollide set to false, as these parts will never need to compute any kind of part to part collisions. However, they can still be hit by Raycasts and OverlapParams queries.

CastShadow

Determines whether or not a part casts a shadow.

Note that this feature is not designed for performance enhancement. It should only be disabled on parts where you want to hide the shadows the part casts. Disabling this property for a given part may cause visual artifacts on the shadows cast upon that part.

The following image shows a red part with CastShadow disabled and a blue part with CastShadow enabled. Note the tapering artifact on the shadow cast on the red part.

An artifacted shadow on a red part and a normal shadow on a blue
part.

CenterOfMass

Read Only
Not Replicated

The CenterOfMass property describes the local position of a part's center of mass. If this is a single part assembly, this is the AssemblyCenterOfMass converted from world space to local. On simple Parts, the center of mass is always (0,0,0). It can vary for WedgePart or MeshPart however.

CollisionGroup

Not Replicated

The CollisionGroup property describes the name of the part's collision group. Parts start off in the default group whose name is "Default". This value cannot be empty.

CollisionGroupId

Not Replicated

The BasePart.CollisionGroupId property describes the ID number of the part's collision group. Parts start off in the "Default" group whose ID is 0. If a part is unregistered, the value becomes -1. This value cannot be less than -1 and it cannot exceed PhysicsService:GetMaxCollisionGroups(). Invalid IDs are clamped.

Although this property can be directly changed, it's recommended that you specify the collision group by setting BasePart.CollisionGroup to the collision group's name.

Color

Not Replicated

The Color property determines the color of a part. If the part has a BasePart.Material, this also determines the color used when rendering the material texture. If this property is set, BasePart.BrickColor will use the closest BrickColor to the Color3 value.

Other visual properties of a part are determined by BasePart.Transparency and BasePart.Reflectance.

CurrentPhysicalProperties

Read Only
Not Replicated

CustomPhysicalProperties

CustomPhysicalProperties lets you customize various physical aspects of a part, such as its's density, friction, and elasticity.

If enabled, this property let's you configure these physical properties. If disabled, these physical properties are determined by the BasePart.Material of the part. The page for Material contains list of the various part materials.

FrontSurface

The FrontSurface property determines the type of surface used for the -Z direction of a part. When two parts' faces are placed next to each other, they may create a joint between them. If set to Motor, the BasePart.FrontSurfaceInput determines how a motor joint should behave.

Most SurfaceTypes render a texture on the part face if the BasePart.Material is set to Plastic. Some SurfaceTypes including Hinge, Motor, and SteppingMotor render a 3D adornment instead. If this property is selected in the Properties window, it will be highlighted in the game world similar to that of a SurfaceSelection.

LeftSurface

The LeftSurface property determines the type of surface used for the -X direction of a part. When two parts' faces are placed next to each other, they may create a joint between them. If set to Motor, the BasePart.LeftSurfaceInput determines how a motor joint should behave.

Most SurfaceTypes render a texture on the part face if the BasePart.Material is set to Plastic. Some SurfaceTypes including Hinge, Motor, and SteppingMotor render a 3D adornment instead. If this property is selected in the Properties window, it will be highlighted in the game world similar to that of a SurfaceSelection.

Locked

The Locked property determines whether a part (or a model it is contained within) may be selected in Roblox Studio by clicking on it. This property is most often enabled on parts within environment models that aren't being edited at the moment. Roblox Studio has a Lock/Unlock All tool that can toggle the Locked state of every part descendant in a model at once.

Mass

Read Only
Not Replicated

Mass is a read-only property that describes the product of a part's volume and density. It is returned by the GetMass function.

Massless

If this property is enabled, the part will not contribute to the total mass or inertia of its assembly as long as it is welded to another part that has mass.

Massles property in property window

If the part is its own root part according to AssemblyRootPart then this will be ignored for that part, and it will still contribute mass and inertia to its assembly like a normal part. Parts that are massless should never become an assembly root part unless all other parts in the assembly are also massless.

This might be useful for things like optional accessories on vehicles that you don't want to affect the handling of the car or a massless render mesh welded to a simpler collision mesh.

See also:

Material

The Material property allows a builder to set a part's texture and default physical properties (in the case that BasePart.CustomPhysicalProperties is unset). The default Plastic material has a very light texture, and the SmoothPlastic material has no texture at all. Some material textures like DiamondPlate and Granite have very visible textures. Each material's texture reflects sunlight differently, especially Foil.

Setting this property then enabling BasePart.CustomPhysicalProperties will use the default physical properties of a material. For instance, DiamondPlate is a very dense material while Wood is very light. A part's density determines whether it will float in terrain water.

The Glass material changes rendering behavior on moderate graphics settings. It applies a bit of reflectiveness (similar to BasePart.Reflectance) and perspective distortion. The effect is especially pronounced on sphere-shaped parts (set BasePart.Shape to Ball). Semitransparent objects and Glass parts behind Glass are not visible.

MaterialVariant

Not Replicated

The system searches the MaterialVariant instance with specified MaterialVariant name and BasePart.Material type. If it successfully finds a matching MaterialVariant instance, it uses this MaterialVariant instance to replace the default material. Default material can be the built-in material or an override MaterialVariant specified in MaterialService.

Orientation

Not Replicated

The Orientation property describes the part's rotation in degrees around the X, Y and Z axes using a Vector3. The rotations are applied in Y → X → Z order. This differs from proper Euler angles, and is instead Tait–Bryan angles which describe yaw, pitch and roll. It is also worth noting how this property differs from the CFrame.Angles() constructor, which applies rotations in a different order (Z → Y → X). For better control over the rotation of a part, it is recommended that BasePart.CFrame is set instead.

When setting this property any Welds or Motor6Ds connected to this part will have the matching C0 or C1 property updated and to allow the part to move relative to any other parts it is joined to.

WeldConstraints will also be temporarily disabled and re-enabled during the move.

PivotOffset

This property specifies the offset of the part's pivot from its CFrame, that is part:GetPivot() is the same as part.CFrame * part.PivotOffset.

This is convenient for setting the pivot to a location in local space, but setting a part's pivot to a location in world space can be done as follows:


1local part = workspace.BluePart
2local desiredPivotCFrameInWorldSpace = CFrame.new(0, 10, 0)
3part.PivotOffset = part.CFrame:ToObjectSpace(desiredPivotCFrameInWorldSpace)
4

Position

Not Replicated

The Position property describes the coordinates of a part using a Vector3. It reflects the position of the part's BasePart.CFrame, however it can also be set.

When setting this property any Welds or Motor6Ds connected to this part will have the matching C0 or C1 property updated and to allow the part to move relative to any other parts it is joined to.

WeldConstraints will also be temporarily disabled and re-enabled during the move.

Reflectance

The Reflectance property determines how much a part reflects the skybox. A value of 0 indicates the part is not reflective at all, and a value of 1 indicates the part should fully reflect.

Reflectance is not affected by BasePart.Transparency, unless the part is fully transparent, in which case reflectance will not render at all. Reflectance may or may not be ignored depending on the BasePart.Material of the part.

ResizeIncrement

Read Only
Not Replicated

The ResizeIncrement property is a read-only property that describes the smallest change in size allowable by the BasePart:Resize() method. It differs between implementations of the BasePart abstract class. For instance, Part has this set to 1 and TrussPart has this set to 2 (since individual truss sections are 2x2x2 in size).

ResizeableFaces

Read Only
Not Replicated

The ResizeableFaces property (with an e, not ResizableFaces) describes using a Faces object the different faces on which a part may be resized. For most implementations of BasePart, such as Part and WedgePart, this property includes all faces. However, TrussPart will set its ResizeableFaces set to only two faces since those kinds of parts must have two BasePart.Size dimensions of length 2. This property is most commonly used with tools used for building and manipulating parts and has little use outside of that context. The Handles class, which has the Handles.Faces property, can be used in conjunction with this property to display only the handles on faces that can be resized on a part.

RightSurface

The RightSurface property determines the type of surface used for the +X direction of a part. When two parts' faces are placed next to each other, they may create a joint between them. If set to Motor, the BasePart.RightSurfaceInput determines how a motor joint should behave.

Most SurfaceTypes render a texture on the part face if the BasePart.Material is set to Plastic. Some SurfaceTypes including Hinge, Motor, and SteppingMotor will render a 3D adornment instead. If this property is selected in the Properties window, it will be highlighted in the game world similar to that of a SurfaceSelection.

RootPriority

This property is the main rule in determining the root part of an assembly. It is an integer between -127 and 127 that takes precedence over all other rules for root part sort (including the weird rules based on part size). A part with a higher RootPriority will take priority over other unanchored parts with equal Massless values and a lower RootPriority.

RootPriority in Properties window

Use this to control which part of an assembly is the root part and keep the root part stable if size changes.

See also:

Rotation

Not Replicated

The rotation of the part in degrees for the three axes.

When setting this property any Welds or Motor6Ds connected to this part will have the matching C0 or C1 property updated and to allow the part to move relative to any other parts it is joined to.

WeldConstraints will also be temporarily disabled and re-enabled during the move.

Not Replicated

The Size property determines the dimensions of a part. The individual dimensions can go as low as 0.001 and as high as 2048 (or 2^11). Size dimensions below 0.05 are only represented visually, and the part will be simulated as if its dimensions are still at 0.05. The size of the part is used in determining its mass, which is given by BasePart:GetMass(). The BasePart.Shape of a part can apply some restrictions on Size - namely, a Ball must have the same 3 dimensions. A part's Size is used by a variety of other objects:

TopSurface

The TopSurface property determines the type of surface used for the +Y direction of a part. When two parts' faces are placed next to each other, they may create a joint between them. If set to Motor, the BasePart.TopSurfaceInput determines how a motor joint should behave.

Most SurfaceTypes render a texture on the part face if the BasePart.Material is set to Plastic. Some SurfaceTypes - Hinge, Motor and SteppingMotor - will render a 3D adornment instead. If this property is selected in the Properties window, it will be highlighted in the game world similar to that of a SurfaceSelection.

Transparency

The Transparency property controls the visibility of a part on a scale of 0 to 1, where 0 is completely visible (opaque), and a value of 1 is completely invisible (not rendered at all).

BasePart.Reflectance can reduce the overall transparency of a brick if set to a value close to 1.

While fully transparent parts are not rendered at all, partially transparent objects have some significant rendering costs. Having many translucent parts may slow down the game's performance.

When transparent parts overlap, render order can act unpredictable - try to keep semi-transparent parts from overlapping to avoid this.

The BasePart.LocalTransparencyModifier is a multiplier to Transparency that is only visible to the local client.

Events

TouchEnded

Fired when a part stops touching another part. This event fires under similar conditions to those of BasePart.Touched.

Parameters

otherPart: BasePart

Code Samples

Touching Parts Count

1local part = script.Parent
2
3local billboardGui = Instance.new("BillboardGui")
4billboardGui.Size = UDim2.new(0, 200, 0, 50)
5billboardGui.Adornee = part
6billboardGui.AlwaysOnTop = true
7billboardGui.Parent = part
8
9local tl = Instance.new("TextLabel")
10tl.Size = UDim2.new(1, 0, 1, 0)
11tl.BackgroundTransparency = 1
12tl.Parent = billboardGui
13
14local numTouchingParts = 0
15
16local function onTouch(otherPart)
17 print("Touch started: " .. otherPart.Name)
18 numTouchingParts = numTouchingParts + 1
19 tl.Text = numTouchingParts
20end
21
22local function onTouchEnded(otherPart)
23 print("Touch ended: " .. otherPart.Name)
24 numTouchingParts = numTouchingParts - 1
25 tl.Text = numTouchingParts
26end
27
28part.Touched:Connect(onTouch)
29part.TouchEnded:Connect(onTouchEnded)

Touched

The Touched event fires when a part comes in contact with another part. For instance, if PartA bumps into PartB, then PartA.Touched fires with PartB, and PartB fires with PartA.

This event only fires as a result of physics movement, so it will not fire if the CFrame property was changed such that the part overlaps another part. This also means that at least one of the parts involved must not be BasePart.Anchored at the time of the collision.

Many types of parts are removed or destroyed as soon as they hit another part. This means that it is possible for the other part's Instance.Parent to be nil. Be sure to check that otherPart.Parent is not nil before using it, such as calling Instance:FindFirstChild().

Parameters

otherPart: BasePart

The other part that came in contact with the given part.


Code Samples

Touching Parts Count

1local part = script.Parent
2
3local billboardGui = Instance.new("BillboardGui")
4billboardGui.Size = UDim2.new(0, 200, 0, 50)
5billboardGui.Adornee = part
6billboardGui.AlwaysOnTop = true
7billboardGui.Parent = part
8
9local tl = Instance.new("TextLabel")
10tl.Size = UDim2.new(1, 0, 1, 0)
11tl.BackgroundTransparency = 1
12tl.Parent = billboardGui
13
14local numTouchingParts = 0
15
16local function onTouch(otherPart)
17 print("Touch started: " .. otherPart.Name)
18 numTouchingParts = numTouchingParts + 1
19 tl.Text = numTouchingParts
20end
21
22local function onTouchEnded(otherPart)
23 print("Touch ended: " .. otherPart.Name)
24 numTouchingParts = numTouchingParts - 1
25 tl.Text = numTouchingParts
26end
27
28part.Touched:Connect(onTouch)
29part.TouchEnded:Connect(onTouchEnded)
Touch Blink

1local part = script.Parent
2
3local pointLight = Instance.new("PointLight")
4pointLight.Brightness = 0
5pointLight.Range = 12
6pointLight.Parent = part
7
8local touchNo = 0
9local function blink()
10 -- Advance touchNo to tell other blink() calls to stop early
11 touchNo = touchNo + 1
12 -- Save touchNo locally so we can tell when it changes globally
13 local myTouchNo = touchNo
14 for i = 1, 0, -0.1 do
15 -- Stop early if another blink started
16 if touchNo ~= myTouchNo then
17 break
18 end
19 -- Update the blink animation
20 part.Reflectance = i
21 pointLight.Brightness = i * 2
22 task.wait(0.05)
23 end
24end
25
26part.Touched:Connect(blink)
Model Touched

1local model = script.Parent
2
3local function onModelTouched(part)
4 -- Filter any instances of the model coming in contact with itself
5 if part:IsDescendantOf(model) then
6 return
7 end
8 print(model:GetFullName(), "was touched by", part:GetFullName())
9end
10
11for _, child in pairs(model:GetChildren()) do
12 if child:IsA("BasePart") then
13 child.Touched:Connect(onModelTouched)
14 end
15end

Methods

ApplyAngularImpulse

Applies an instant angular force impulse to this part's assembly, causing the assembly to spin.

The resulting angular velocity from the impulse relies on the assembly's mass. So a higher impulse is required to move more massive assemblies. Impulses are useful for cases where you want a force applied instantly, such as an explosion or collision.

If the part is owned by the server, this function must be called on a server Script. If the part is owned by a client, this function can be called on a LocalScript or server Script.

Parameters

impulse: Vector3

A force vector to be applied to the assembly as an impulse.


Returns

No return.

ApplyImpulse

This function applies an instant force impulse to this part's assembly.

The force is applied at the assembly's center of mass, so the resulting movement will only be linear.

The resulting velocity from the impulse relies on the assembly's mass. So a higher impulse is required to move more massive assemblies. Impulses are useful for cases where you want a force applied instantly, such as an explosion or collision.

If the part is owned by the server, this function must be called on a server Script. If the part is owned by a client, this function can be called on a LocalScript or server Script.

Parameters

impulse: Vector3

A force vector to be applied to the assembly as an impulse.


Returns

No return.

ApplyImpulseAtPosition

This function applies an instant force impulse to this part's assembly, at the specified position in world space.

If the position is not at the assembly's center of mass, the impulse will cause a positional and rotational movement.

The resulting velocity from the impulse relies on the assembly's mass. So a higher impulse is required to move more massive assemblies. Impulses are useful for cases where developers want a force applied instantly, such as an explosion or collision.

If the part is owned by the server, this function must be called on a server Script. If the part is owned by a client, this function can be called on a LocalScript or server Script.

Parameters

impulse: Vector3

A force vector to be applied to the assembly as an impulse.

position: Vector3

The position, in world space, to apply the impulse.


Returns

No return.

BreakJoints

Breaks any surface connection with any adjacent part, including Weld and other JointInstance.


Returns

No return.

CanCollideWith

Returns whether the parts can collide with each other or not. This function takes into account the collision groups of the two parts. This function will error if the specified part is not a BasePart.

Parameters

part: BasePart

The specified part being checked for collidability.


Returns

Whether the parts can collide with each other.

CanSetNetworkOwnership

The CanSetNetworkOwnership function checks whether you can set a part's network ownership.

The function's return value verifies whether or not you can call BasePart:SetNetworkOwner() or BasePart:SetNetworkOwnershipAuto() without encountering an error. It returns true if you can modify/read the network ownership, or returns false and the reason you can't, as a string.


Returns

Whether you can modify or read the network ownership and the reason.

Code Samples

Check if a Part's Network Ownership Can Be Set

1local part = workspace:FindFirstChild("Part")
2
3if part and part:IsA("BasePart") then
4 local canSet, errorReason = part:CanSetNetworkOwnership()
5 if canSet then
6 print(part:GetFullName() .. "'s Network Ownership can be changed!")
7 else
8 warn("Cannot change the Network Ownership of " .. part:GetFullName() .. " because: " .. errorReason)
9 end
10end

GetConnectedParts

Returns a table of parts connected to the the object by any kind of rigid joint.

If recursive is true this function will return all of the parts in the assembly rigidly connected to the BasePart.

Rigid Joints

When a joint connects two parts together (Part0 → Part1), a joint is rigid if the physics of Part1 are completely locked down by Part0. This only applies to the following joint types:

Parameters

recursive: boolean

A table of parts connected to the the object by any kind of joint.

Default Value: "false"

Returns

GetJoints

Return all Joints or Constraints that is connected to this Part.


Returns

An array of all Joints or Constraints connected to the Part.

GetMass

GetMass returns the value of the read-only Mass property.

This function predates the Mass property. It remains supported for backward-compatibility; you should use the Mass property directly.


Returns

The part's mass.

Code Samples

Finding a Part's Mass

1local myPart = Instance.new("Part")
2myPart.Size = Vector3.new(4, 6, 4)
3myPart.Anchored = true
4myPart.Parent = workspace
5
6local myMass = myPart:GetMass()
7
8print("My part's mass is " .. myMass)

GetNetworkOwner

Returns the current player who is the network owner of this part, or nil in case of the server.


Returns

The current player who is the network owner of this part, or nil in case of the server.

GetNetworkOwnershipAuto

Returns true if the game engine automatically decides the network owner for this part.


Returns

Whether the game engine automatically decides the network owner for this part.

GetRootPart

Returns the base part of an assembly. When moving an assembly of parts using a CFrame. it is important to move this base part (this will move all other parts connected to it accordingly).

More information is available in the Understanding Assemblies article.

This function predates the AssemblyRootPart property. It remains supported for backward-compatibility; you should use the AssemblyRootPart property directly.


Returns

The base part of an assembly (a collection of parts connected together).

GetTouchingParts

Returns a table of all parts that are physically interacting with this part. If the part itself has CanCollide set to false, then this function returns an empty table unless the part has a TouchInterest object parented to it (meaning something is connected to its Touched event). Parts that are adjacent but not intersecting are not considered touching. This function predates the WorldRoot:GetPartsInPart() function, which provides more flexibility and avoids the special TouchInterest rules described above. Use WorldRoot:GetPartsInPart() instead.


Returns

A table of all parts that intersect and can collide with this part.

GetVelocityAtPosition

Returns the linear velocity of the part's assembly at the given position relative to this part. It can be used to identify the linear velocity of parts in an assembly other than the root part. If the assembly has no angular velocity, than the linear velocity will always be the same for every position.

Parameters

position: Vector3

Returns

IsGrounded

Returns true if the object is connected to a part that will hold it in place (eg an BasePart.Anchored part), otherwise returns false. In an assembly that has an BasePart.Anchored part, every other part is grounded.


Returns

Whether the object is connected to a part that will hold it in place.

MakeJoints

Creates a joint on any side of the Part that has a SurfaceType that can make a joint it will create a joint with any adjacent parts.

Joints will be created between the sides and any planar touching surfaces, depending on the sides' surfaces.

  • Smooth surfaces will not create joints
  • Glue surfaces will create a Glue joint
  • Weld will create a Weld joint with any surface except for Unjoinable
  • Studs, Inlet, or Universal will each create a Snap joint with either of other the other two surfaces (e.g. Studs with Inlet and Universal)
  • Hinge and Motor surfaces create Rotate and RotateV joint instances

Unlike Model:MakeJoints(), this function requires an array of parts as a parameter. This array is given as follows:


1part:MakeJoints({part1, part2, part3})
2

Joints are broken if enough force is applied to them due to an Explosion, unless a ForceField object is parented to the BasePart or ancestor Model. For this reason, they are often used to make simple destructible buildings and other models.


Returns

No return.

Resize

Changes the size of an object just like using the Studio resize tool.

Parameters

normalId: NormalId

The side to resize.

deltaAmount: number

How much to grow/shrink on the specified side.


Returns

Whether the part is resized.

SetNetworkOwner

Sets the given player as network owner for this and all connected parts. When playerInstance is nil, the server will be the owner instead of a player.

Parameters

playerInstance: Player

The player being given network ownership of the part.

Default Value: "nil"

Returns

No return.

SetNetworkOwnershipAuto

Lets the game engine dynamically decide who will handle the part's physics (one of the clients or the server).


Returns

No return.

SubtractAsync

Yields

SubtractAsync creates new UnionOperation which occupies the same space as the part minus the space(s) occupied by the parts in the given array. It does this by invoking the real-time CSG solver. Similar to Clone, the returned object has no Parent set.

The following image depicts an example of a SubtractAsync operation: the yellow part on the left has SubtractAsync called with a table containing the two pink parts. The resulting UnionOperation is moved to the right, as it would otherwise overlap the original part and not be visible. Notice the missing concave pieces that match the spaces once occupied by the pink parts.

An
example of a SubtractAsync operation: the left depicts a yellow part with
two pink parts, which are then subtracted from the yellow part using
SubtractAsync. The resulting UnionOperation is visible on the right


1local yellowPart = workspace.YellowPart
2local pinkParts = {workspace.PinkPart, workspace.PinkPart2}
3local union = yellowPart:SubtractAsync(pinkParts)
4union.Parent = workspace
5

Parameters

parts: Objects

The objects taking part in the subtraction.

collisionfidelity: CollisionFidelity

The value of CollisionFidelity in the resulting UnionOperation.

Default Value: "Default"
renderFidelity: RenderFidelity

The value of RenderFidelity in the resulting RenderFidelity.

Default Value: "Automatic"

Returns

The resulting union from the subtraction operation.

UnionAsync

Yields

This is a server-only function that uses 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 UsePartColor property defaults to false and its 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:


1local part = workspace.Part1
2local otherParts = {workspace.Part2, workspace.Part3, workspace.Part4}
3
4-- Perform union operation
5local newUnion = part:UnionAsync(otherParts)
6

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

Union Visualization

Note that if a NegateOperation is provided, it will also be unioned additively. For subtraction, use BasePart:SubtractAsync().

The original parts remain unchanged following a successful union operation. In most cases, you should destroy all of the original parts and parent the returned UnionOperation to the same place as the calling BasePart.

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

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

Parameters

parts: Objects

List of Parts that are unioned with the calling part.

collisionfidelity: CollisionFidelity

Optional 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.
Default Value: "Default"
renderFidelity: RenderFidelity

Optional 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).
Default Value: "Automatic"

Returns

Resulting UnionOperation with default name “Union”.

Code Samples

Basic In-Game Union Operation

1local part = workspace.Part1
2local otherParts = { workspace.Part2, workspace.Part3 }
3
4local newUnion = part:UnionAsync(otherParts)
5
6-- Destroy source parts
7part:Destroy()
8for _, otherPart in pairs(otherParts) do
9 otherPart:Destroy()
10end
11
12-- Insert new union into workspace
13newUnion.Parent = workspace