BasePart
BasePart : PVInstance
Overview
BasePart is an abstract base class for all 3D objects, such as Part and MeshPart, that are visually displayed in the game space (Workspace) and affected by the physics engine.
In the developer documentation, the term "Part" typically refers to objects of the BasePart family, rather than a single, specific Part.
The functionality of BasePart can be extended through the combination with various elements. For example, multiple BaseParts can be grouped into a single model for collective movement. Or it can be used with SurfaceGui for UI display, used with PointLight for lighting, or used to add VFX such as ParticleEmitter or Beam.
It can also be combined with physics constraints to implement interactions or control physical movements with LinearVelocity, AngularVelocity, etc.
If a BasePart is a child object of a Tool and named "Handle," a character can hold it in hand.
Properties
CFrame
CFrame
The CFrame property defines the position and rotation of a BasePart in the world coordinate system, allowing both position and orientation to be specified simultaneously, unlike the Position property.
When an Attachment is parented to a part, it can also be used to track positions relative to the part.
Code Samples
local Part = script.Parent
-- Position
Part.CFrame = CFrame.new(200, 50, 300)
-- Angle
local Rotation = CFrame.Angles(0, 0, 30)
Part.CFrame = Part.CFrame * Rotation
-- Position & Angle
Part.CFrame = CFrame.new(200, 50, 300) * CFrame.Angles(0, 40, 0)
-- LookAt
local TargetPosition = Vector3.new(0, 30, 0)
Part.CFrame = CFrame.lookAt(Part.Position, TargetPosition)Anchored
bool
This property determines whether a part can be moved by physical forces.
If this value is set to true, the part will not change position or rotation even when affected by the physics engine (e.g., gravity or collisions). However, it can still be moved by directly modifying the Position or CFrame values via scripts.
When a part is placed, its Anchored property is set to true by default, making it fixed. This improves performance by preventing unnecessary physics calculations, so it is recommended to check this property first for parts that should not be affected by physics.
Code Samples
local Part = script.Parent
Part.Anchored = falseCanCollide
bool
This property determines whether a part can be passed through during collisions with other objects.
If this value is set to false, other parts or characters can pass through the part freely. For decorative objects that do not require physics calculations, it is recommended to disable CanCollide in order to improve performance.
Even with collisions disabled, the Touched event can still trigger. Setting CanTouch to false can prevent these events from triggering.
Code Samples
local Part = script.Parent
Part.CanCollide = falseCanQuery
bool
Currently not supported.
Code Samples
CanTouch
bool
This property determines whether the part can trigger touch events such as Touched or TouchEnded.
Setting both CanTouch and CanCollide to false skips collision calculations between parts, thereby improving performance. However, detection via Raycast still remains possible.
Code Samples
local Part = script.Parent
local function OnTouched(otherPart)
print(Part.Name, "Touched :", otherPart.Name)
end
Part.Touched:Connect(OnTouched)
Part.CanTouch = falseSize
Vector3
This property sets the width, height, and depth of a part.
Code Samples
local Part = script.Parent
Part.Size = Vector3.new(50, 50, 50)AssemblyAngularVelocity
Vector3
Currently not supported.
Code Samples
AssemblyCenterOfMass
Vector3
Currently not supported.
Code Samples
AssemblyLinearVelocity
Vector3
This property represents the linear velocity at the center of mass of the assembly to which the part belongs.
Since manually adjusting this value can cause unnatural physical movements, it is recommended to use a VectorForce instance for continuous velocity control and to use the ApplyImpulse() function for instantaneous velocity changes.
Code Samples
local Part = script.Parent
print(Part.AssemblyLinearVelocity)AssemblyMass
number
Currently not supported.
Code Samples
BrickColor
BrickColor
This property specifies the part's base color. The color is applied in conjunction with the texture of the specified material.
Predefined colors can be quickly selected, but for more precise color adjustments, the Color property can be set manually. In this case, the closest matching BrickColor is automatically applied.
Code Samples
local Part = script.Parent
Part.BrickColor = BrickColor.new("Really red")
if Part.BrickColor.Name == "Really red" then
print("Red!")
endCastShadow
bool
This property determines whether the part casts shadows. For performance optimization, the default is false, and it should only be enabled when necessary.
For shadow complexity, select the Lighting service and adjust the Shadow Detail Level in the properties panel to set the shadow quality for all parts.
Additionally, you can select a specific part and enable Enable Mesh Shadow Details in the properties panel to set the Mesh Shadow Detail Level for each mesh. In this case, the mesh's settings override the global Lighting service settings.
Shadow complexity settings cannot be changed at runtime.
Code Samples
local Part = script.Parent
print(Part.CastShadow)CenterOfMass
Vector3
Currently not supported.
Code Samples
CollisionGroup
string
This property assigns a part to a specific collision group. Newly created parts belong to the Default group by default, and empty strings are not allowed.
Collisions between groups can be individually configured, allowing control over which parts collide or pass through each other. This setting is mainly used to refine interaction ranges between objects in a game or to reduce unnecessary physics calculations for performance optimization.
Code Samples
local Part = script.Parent
local PhysicsService = game:GetService("PhysicsService")
local DefaultGroup = "Default"
local FallGroup = "Fall"
PhysicsService:RegisterCollisionGroup(FallGroup)
wait(2)
PhysicsService:CollisionGroupSetCollidable(DefaultGroup, FallGroup, false)
Part.CollisionGroup = FallGroupColor
Color3
This property specifies the part's base color. The color is applied in conjunction with the texture of the specified material.
Changing this value automatically updates the BrickColor property to the closest matching color. While the BrickColor property uses a method of selecting from predefined colors, Color is used to manually specify colors using float values or RGB.
Code Samples
local Part = script.Parent
wait(2)
Part.Color = Color3.new(0, 0, 1) -- Blue
wait(2)
Part.Color = Color3.fromRGB(255, 0, 0) -- RedCurrentPhysicalProperties
PhysicalProperties
Currently not supported.
Code Samples
CustomPhysicalProperties
PhysicalProperties
Currently not supported.
Code Samples
ExtentsCFrame
CFrame
Currently not supported.
Code Samples
ExtentsSize
Vector3
Currently not supported.
Code Samples
LocalTransparencyModifier
number
Currently not supported.
Code Samples
Locked
bool
This property determines whether the part can be selected by clicking it in the viewport in Studio's edit mode.
This is mainly used to prevent unintended modifications after placing buildings, terrain, or decorative elements.
Code Samples
local Part = script.Parent
print(Part.Locked)CanClimb
bool
This property determines whether a character can climb the part.
If a character touches a part with CanClimb enabled, the character enters the Climbing state and can climb the wall. However, if the slope of the wall the character faces is less than the MaxSlopeAngle defined in GameSettings, the character will not enter the Climbing state and will instead walk or run on the slope.
The default is false; therefore, this property must be enabled for objects like ladders that require climbing.
Code Samples
Mass
number
Currently not supported.
Code Samples
Massless
bool
Currently not supported.
Code Samples
Material
Enum.Material
This property sets the surface texture of a part.
Combining material and color appropriately can create various atmospheres and visual effects in the game.
Code Samples
local Part = script.Parent
Part.Material = Enum.Material.StoneBrickMaterialVariant
string
This property specifies a MaterialVariant, which is a modified version of a predefined base material.
If the provided MaterialVariant name exists, the MaterialVariant is applied, and at the same time, the Material property is automatically updated to match the base material to which the MaterialVariant belongs.
Code Samples
local Part = script.Parent
print(Part.MaterialVariant)Position
Vector3
This property specifies the position of a part in the world coordinate system.
It reflects the position value of CFrame and can be modified by manually changing either CFrame or this property.
Code Samples
local Part = script.Parent
Part.Position = Vector3.new(0, 50, -500)ReceiveAge
number
Currently not supported.
Code Samples
Reflectance
number
Currently not supported.
Code Samples
ResizeIncrement
number
Currently not supported.
Code Samples
RootPriority
number
Currently not supported.
Code Samples
Rotation
Vector3
Currently not supported.
Code Samples
Vector3
This property specifies the rotation of a part along the X, Y, and Z axes in degrees as a Vector3 value, with rotations applied in the order of Y, X, Z.
Unlike typical Euler angles, this method uses Tait-Bryan angles, representing yaw, pitch, and roll respectively.
The CFrame.Angles() constructor applies rotations in the order Z, Y, X, so it behaves differently from the Orientation property. For more precise rotation control, it is recommended to set the CFrame manually.
Code Samples
local Part = script.Parent
Part.Orientation = Vector3.new(45, 0, 0)Transparency
number
This property sets the transparency of a part, with values ranging from 0 (fully opaque) to 1 (fully transparent).
If the value is 1, the part is not rendered at all. If the value is greater than 0 and smaller than 1, it becomes translucent.
As fully transparent parts are not subject to rendering, they do not cause performance overhead, but translucent parts can impact performance if used extensively as they require additional GPU calculations.
Code Samples
local Part = script.Parent
Part.Transparency = 0.5Methods
ApplyImpulse
This performs a function of instantly accelerating a part by applying an instantaneous physical force.
The force is always applied at the assembly's center of mass, causing only linear movement without rotation, and it only works if the Anchored property is false.
Parameters
Vector3 impulse
The linear physical impulse vector to apply.
Return
void
Code Samples
local Part = script.Parent
local Force = Vector3.new(0, 0, -200000)
wait(2)
Part.Anchored = false
Part:ApplyImpulse(Force)GetMass
Currently not supported.
Parameters
Return
number
Code Samples
Events
TouchEnded
This event is triggered when two parts that are touching each other stop making contact.
The conditions for triggering are almost the same as the Touched event, except that the timing is when contact ends rather than when it begins.
It is called not only when parts physically move apart but also when the contact is broken by changing the Position or CFrame values through a script.
However, the event does not trigger if the parts were initially overlapping in the editor, and it will not run if the CanTouch property is disabled.
Parameters
BasePart otherPart
The part that stopped touching the event-connected part.
Code Samples
local Part = script.Parent
local function OnTouchEnded(otherPart)
print("[OnTouchEnded]", otherPart)
end
Part.TouchEnded:Connect(OnTouchEnded)Touched
This event is triggered when the connected part comes into contact with another part.
It is called not only when the parts physically move but also when contact occurs due to changes in Position or CFrame values by a script.
However, the event does not trigger if the parts were initially overlapping in the editor, and it will not run if the CanTouch property is disabled.
Parameters
BasePart otherPart
The part that touched the part to which the event is connected.
Code Samples
local Part = script.Parent
local function OnTouched(otherPart)
print("[OnTouched]", otherPart)
end
Part.Touched:Connect(OnTouched)Last updated