BasePart
BasePart : PVInstance
Overview
BasePart는 Part, MeshPart 등 게임 공간(Workspace)에서 시각적으로 표시되고 물리 엔진의 영향을 받는 모든 3D 오브젝트의 기본이 되는 추상 클래스입니다.
개발 문서에서 "Part"라는 용어가 사용될 때는, 특정한 Part만이 아니라 대부분 BasePart 계열 객체를 의미하는 경우가 많습니다.
BasePart는 다양한 요소와 결합하여 기능을 확장할 수 있습니다. 예를 들어, 여러 BasePart를 하나의 Model에 묶어 함께 이동시키거나, SurfaceGui를 이용한 UI 표시, PointLight를 통한 조명, ParticleEmitter나 Beam 같은 VFX 추가도 가능합니다.
물리 장치(Constraint)와 결합하여 상호작용을 구현할 수도 있으며, LinearVelocity, AngularVelocity 등과 함께 물리적 움직임을 제어할 수 있습니다.
또한 BasePart가 Tool의 하위 객체이며 이름이 "Handle"일 경우, 캐릭터가 손에 들 수 있습니다.
Properties
CFrame
CFrame
CFrame은 월드 좌표계에서 BasePart의 위치와 회전을 정의하는 속성으로, Position 속성과 달리 회전과 방향까지 한 번에 지정할 수 있습니다.
또한 파트의 자식으로 Attachment를 추가하면, 해당 파트를 기준으로 한 상대 위치를 추적하는 데 활용할 수 있습니다.
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
파트가 물리적인 힘에 의해 움직일 수 있는지를 결정하는 속성입니다.
이 값이 true이면 해당 파트는 중력이나 충돌 등 물리 엔진의 영향을 받아도 위치와 회전이 변하지 않습니다. 다만, 스크립트를 통해 Position 또는 CFrame 값을 직접 수정하면 이동할 수 있습니다.
파트를 배치하면 Anchored 속성의 기본값이 true로 설정되어 고정된 상태가 됩니다. 이는 불필요한 물리 연산을 방지해 성능을 향상시키기 위한 것이므로, 배치한 파트가 물리의 영향을 받지 않는 경우 가장 먼저 이 속성을 확인하는 것이 좋습니다.
Code Samples
local Part = script.Parent
Part.Anchored = falseCanCollide
bool
파트가 다른 객체와 충돌 시 통과 가능한지를 결정하는 속성입니다.
이 값이 false이면 다른 파트나 캐릭터가 해당 파트를 자유롭게 통과할 수 있습니다. 게임 내에서 단순 장식용으로 배치된 오브젝트는 물리 연산이 불필요하므로, 성능 향상을 위해 CanCollide를 비활성화하는 것이 권장됩니다.
또한 충돌이 비활성화되어도 Touched 이벤트는 계속 발생할 수 있습니다. 이 경우 CanTouch 속성을 false로 설정하면 이벤트 발생을 차단할 수 있습니다.
Code Samples
local Part = script.Parent
Part.CanCollide = falseCanQuery
bool
현재 지원되지 않습니다.
Code Samples
CanTouch
bool
해당 파트가 Touched, TouchEnded와 같은 터치 이벤트를 발생시킬 수 있는지를 결정하는 속성입니다.
CanTouch와 CanCollide를 모두 false로 설정하면 파트 간 충돌 연산이 생략되어 성능이 향상됩니다. 단, 이 경우에도 Raycast를 통한 감지는 여전히 가능합니다.
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
파트의 가로·세로·높이 크기를 설정하는 속성입니다.
Code Samples
local Part = script.Parent
Part.Size = Vector3.new(50, 50, 50)AssemblyAngularVelocity
Vector3
현재 지원되지 않습니다.
Code Samples
AssemblyCenterOfMass
Vector3
현재 지원되지 않습니다.
Code Samples
AssemblyLinearVelocity
Vector3
해당 파트가 속한 어셈블리의 질량 중심에서의 선형 속도를 나타내는 속성입니다.
이 값을 직접 변경하면 물리적으로 부자연스러운 움직임이 발생할 수 있으므로, 지속적인 속도 제어가 필요하다면 VectorForce 인스턴스를, 순간적인 속도 변화가 필요하다면 ApplyImpulse() 함수를 사용하는 것이 권장됩니다.
Code Samples
local Part = script.Parent
print(Part.AssemblyLinearVelocity)AssemblyMass
number
현재 지원되지 않습니다.
Code Samples
BrickColor
BrickColor
파트의 기본 색상을 지정하는 속성으로, 설정된 Material의 질감에 색상이 함께 적용됩니다.
사전에 정의된 색상을 빠르게 선택할 수 있도록 제공되며, 더 정밀한 색상 조절이 필요하다면 Color 속성을 직접 설정할 수 있습니다. 이 경우 해당 값과 가장 유사한 BrickColor가 자동으로 적용됩니다.
Code Samples
local Part = script.Parent
Part.BrickColor = BrickColor.new("Really red")
if Part.BrickColor.Name == "Really red" then
print("Red!")
endCastShadow
bool
해당 파트에 그림자를 생성할지 여부를 설정하는 속성으로, 성능 최적화를 위해 기본값은 false이며 필요한 경우에만 활성화하는 것이 권장됩니다.
그림자 복잡도는 Lighting 서비스를 선택한 뒤, 프로퍼티 패널에서 Shadow Detail Level 값을 조정하여 전체 파트의 그림자 품질을 지정할 수 있습니다.
또한, 특정 파트를 선택한 후 프로퍼티 패널에서 Enable Mesh Shadow Details를 활성화하면 개별 메시 단위로 Mesh Shadow Detail Level을 설정할 수 있으며, 이 경우 Lighting 서비스의 전역 설정보다 해당 메시의 설정이 우선 적용됩니다.
그림자 복잡도 관련 설정은 런타임에서 변경할 수 없습니다.
Code Samples
local Part = script.Parent
print(Part.CastShadow)CenterOfMass
Vector3
현재 지원되지 않습니다.
Code Samples
CollisionGroup
string
파트를 특정 충돌 그룹에 지정하는 속성으로, 새로 생성된 파트는 기본적으로 Default 그룹에 속하며 빈 문자열은 허용되지 않습니다.
충돌 그룹 간에는 충돌 여부를 개별적으로 설정할 수 있으며, 이를 통해 특정 파트끼리만 부딪히거나 서로를 통과하도록 제어할 수 있습니다. 이 설정은 주로 게임 내에서 오브젝트 간의 상호작용 범위를 세분화하거나, 불필요한 물리 연산을 줄여 성능을 최적화하는 데 사용됩니다.
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
파트의 기본 색상을 지정하는 속성으로, 설정된 Material의 질감에 색상이 함께 적용됩니다.
이 값을 변경하면 BrickColor 속성이 이에 맞춰 가장 유사한 색상으로 자동 변경됩니다.
BrickColor 속성이 사전에 정의된 색상 중에서 선택하는 방식이라면, Color는 실수 값이나 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
현재 지원되지 않습니다.
Code Samples
CustomPhysicalProperties
PhysicalProperties
현재 지원되지 않습니다.
Code Samples
ExtentsCFrame
CFrame
현재 지원되지 않습니다.
Code Samples
ExtentsSize
Vector3
현재 지원되지 않습니다.
Code Samples
LocalTransparencyModifier
number
현재 지원되지 않습니다.
Code Samples
Locked
bool
스튜디오 편집 모드에서 뷰포트 내 해당 파트를 마우스로 클릭해 선택할 수 있는지 여부를 결정하는 속성입니다.
주로 건물, 지형, 장식 요소 등을 배치한 뒤, 의도치 않은 수정을 방지하기 위해 사용됩니다.
Code Samples
local Part = script.Parent
print(Part.Locked)CanClimb
bool
캐릭터가 해당 파트를 등반할 수 있는지를 결정하는 속성입니다.
CanClimb이 활성화된 Part에 캐릭터가 닿으면 Climbing 상태로 전환되어 벽을 오를 수 있습니다. 단, CanClimb이 켜져 있어도 캐릭터가 바라보는 벽의 경사가 GameSettings의 MaxSlopeAngle 값보다 작다면 Climbing 상태로 전환되지 않으며, 대신 경사면을 걷거나 뛰어 이동하게 됩니다.
기본값은 false이므로, 사다리처럼 등반이 필요한 오브젝트는 이 속성을 활성화해야 합니다.
Code Samples
Mass
number
현재 지원되지 않습니다.
Code Samples
Massless
bool
현재 지원되지 않습니다.
Code Samples
Material
Enum.Material
파트의 표면 질감을 설정하는 속성입니다.
Material과 Color를 적절히 조합하면 게임 내에서 다양한 분위기와 시각적 효과를 연출할 수 있습니다.
Code Samples
local Part = script.Parent
Part.Material = Enum.Material.StoneBrickMaterialVariant
string
사전에 정의된 기본 머티리얼을 변형한 MaterialVariant를 지정하는 속성입니다.
입력한 MaterialVariant 이름이 존재하면 해당 MaterialVariant로 적용되며, 동시에 해당 MaterialVariant가 속한 기본 머티리얼(Base Material)에 맞춰 Material 속성도 자동으로 변경됩니다.
Code Samples
local Part = script.Parent
print(Part.MaterialVariant)Position
Vector3
월드 좌표계에서 파트의 위치를 지정하는 속성입니다.
CFrame의 위치 값을 반영하며, CFrame이나 이 속성을 직접 변경하여 수정할 수 있습니다.
Code Samples
local Part = script.Parent
Part.Position = Vector3.new(0, 50, -500)ReceiveAge
number
현재 지원되지 않습니다.
Code Samples
Reflectance
number
현재 지원되지 않습니다.
Code Samples
ResizeIncrement
number
현재 지원되지 않습니다.
Code Samples
RootPriority
number
현재 지원되지 않습니다.
Code Samples
Rotation
Vector3
현재 지원되지 않습니다.
Code Samples
Orientation
Vector3
Vector3 값으로 파트의 X, Y, Z 축 회전을 도 단위로 지정하는 속성으로, 회전은 Y, X, Z 순서로 적용됩니다.
이 방식은 일반적인 오일러 각이 아닌 Tait-Bryan 각을 사용하며, 이는 각각 요(yaw), 피치(pitch), 롤(roll)을 나타냅니다.
CFrame.Angles() 생성자는 Z, Y, X 순으로 회전을 적용하므로 Orientation 속성과 작동 방식이 다릅니다. 보다 정밀한 회전 제어가 필요할 경우 CFrame을 직접 설정하는 것이 권장됩니다.
Code Samples
local Part = script.Parent
### Transparency
`number`
파트의 투명도를 설정하는 속성으로, 값은 0(완전 불투명)부터 1(완전 투명)까지 지정할 수 있습니다.
값이 1이면 파트는 전혀 렌더링되지 않으며, 0보다 크고 1보다 작은 경우에는 반투명 상태가 됩니다.
완전히 투명한 파트는 렌더링되지 않아 성능 부담이 없지만, 반투명 파트는 GPU 연산이 추가로 필요해 다수 사용 시 성능 저하를 유발할 수 있습니다. 
#### Code Samples
```lua
local Part = script.Parent
Part.Transparency = 0.5Methods
ApplyImpulse
파트에 순간적인 물리 힘을 가해 즉시 가속시키는 기능을 수행합니다.
힘은 항상 어셈블리의 질량 중심에 적용되므로 회전이 아닌 직선 이동만 발생하며, Anchored 속성이 false인 경우에만 동작합니다.
Parameters
Vector3 impulse
적용할 선형(직선) 물리 임펄스 벡터입니다.
Return
void
Code Samples
local Part = script.Parent
local Force = Vector3.new(0, 0, -200000)
wait(2)
Part.Anchored = false
Part:ApplyImpulse(Force)GetMass
현재 지원되지 않습니다.
Parameters
Return
number
Code Samples
Events
TouchEnded
두 파트가 서로 닿아 있는 상태에서 접촉이 해제될 때 호출됩니다.
발생 조건은 Touched 이벤트와 거의 동일하지만, 시점이 접촉 시작이 아닌 접촉 종료라는 점이 다릅니다.
물리적인 이동뿐 아니라, 스크립트로 Position 또는 CFrame 값을 변경하여 접촉이 해제된 경우에도 호출됩니다.
단, 에디터에서 미리 겹쳐 배치한 경우에는 발생하지 않으며, CanTouch 속성이 비활성화되어 있으면 이벤트가 실행되지 않습니다.
Parameters
BasePart otherPart
이벤트가 연결된 파트에 접촉 해제된 대상 파트입니다.
Code Samples
local Part = script.Parent
local function OnTouchEnded(otherPart)
print("[OnTouchEnded]", otherPart)
end
Part.TouchEnded:Connect(OnTouchEnded)Touched
이벤트가 연결된 파트가 다른 파트와 접촉할 때 실행됩니다.
물리적인 이동뿐 아니라, 스크립트로 Position 또는 CFrame 값을 변경하여 접촉이 발생한 경우에도 호출됩니다.
단, 에디터에서 미리 겹쳐 배치한 경우에는 발생하지 않으며, CanTouch 속성이 비활성화되어 있으면 이벤트가 실행되지 않습니다.
Parameters
BasePart otherPart
이벤트가 연결된 파트에 접촉한 대상 파트입니다.
Code Samples
local Part = script.Parent
local function OnTouched(otherPart)
print("[OnTouched]", otherPart)
end
Part.Touched:Connect(OnTouched)Last updated