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 = false

CanCollide

bool

파트가 다른 객체와 충돌 시 통과 가능한지를 결정하는 속성입니다.

이 값이 false이면 다른 파트나 캐릭터가 해당 파트를 자유롭게 통과할 수 있습니다. 게임 내에서 단순 장식용으로 배치된 오브젝트는 물리 연산이 불필요하므로, 성능 향상을 위해 CanCollide를 비활성화하는 것이 권장됩니다.

또한 충돌이 비활성화되어도 Touched 이벤트는 계속 발생할 수 있습니다. 이 경우 CanTouch 속성을 false로 설정하면 이벤트 발생을 차단할 수 있습니다.

Code Samples

local Part = script.Parent

Part.CanCollide = false

CanQuery

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 = false

Size

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!")
end

CastShadow

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 = FallGroup

Color

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) -- Red

CurrentPhysicalProperties

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.StoneBrick

MaterialVariant

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.5

Methods

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)