# 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

### Anchored

`boolean`

파트가 물리적인 힘에 의해 움직일 수 있는지를 결정하는 속성입니다.

이 값이 true이면 해당 파트는 중력이나 충돌 등 물리 엔진의 영향을 받아도 위치와 회전이 변하지 않습니다.\
다만, 스크립트를 통해 Position 또는 CFrame 값을 직접 수정하면 이동할 수 있습니다.

파트를 배치하면 Anchored 속성의 기본값이 true로 설정되어 고정된 상태가 됩니다. 이는 불필요한 물리 연산을 방지해 성능을 향상시키기 위한 것이므로, 배치한 파트가 물리의 영향을 받지 않는 경우 가장 먼저 이 속성을 확인하는 것이 좋습니다.

#### Code Samples

```lua
local Part = script.Parent

Part.Anchored = false
```

### AssemblyLinearVelocity

`Vector3`

해당 파트가 속한 어셈블리의 질량 중심에서의 선형 속도를 나타내는 속성입니다.

이 값을 직접 변경하면 물리적으로 부자연스러운 움직임이 발생할 수 있으므로, 지속적인 속도 제어가 필요하다면 VectorForce 인스턴스를, 순간적인 속도 변화가 필요하다면 ApplyImpulse() 함수를 사용하는 것이 권장됩니다.

#### Code Samples

```lua
local Part = script.Parent

print(Part.AssemblyLinearVelocity)
```

### AssemblyRootPart

`BasePart`

해당 파트가 속한 어셈블리에서 기준이 되는 루트 파트를 나타내는 속성입니다. Weld나 Joint 등으로 연결된 파트들은 동일한 AssemblyRootPart를 공유하며, 어셈블리의 물리 계산 기준으로 사용됩니다.

#### Code Samples

### BrickColor

`BrickColor`

파트의 기본 색상을 지정하는 속성으로, 설정된 Material의 질감에 색상이 함께 적용됩니다.

사전에 정의된 색상을 빠르게 선택할 수 있도록 제공되며, 더 정밀한 색상 조절이 필요하다면 Color 속성을 직접 설정할 수 있습니다. 이 경우 해당 값과 가장 유사한 BrickColor가 자동으로 적용됩니다.

#### Code Samples

```lua
local Part = script.Parent

Part.BrickColor = BrickColor.new("Really red")

if Part.BrickColor.Name == "Really red" then
    print("Red!")
end
```

### CanClimb

`boolean`

캐릭터가 해당 파트를 등반할 수 있는지를 결정하는 속성입니다.

CanClimb이 활성화된 Part에 캐릭터가 닿으면 Climbing 상태로 전환되어 벽을 오를 수 있습니다. 단, CanClimb이 켜져 있어도 캐릭터가 바라보는 벽의 경사가 GameSettings의 MaxSlopeAngle 값보다 작다면 Climbing 상태로 전환되지 않으며, 대신 경사면을 걷거나 뛰어 이동하게 됩니다.

기본값은 false이므로, 사다리처럼 등반이 필요한 오브젝트는 이 속성을 활성화해야 합니다.

#### Code Samples

### CanCollide

`boolean`

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

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

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

#### Code Samples

```lua
local Part = script.Parent

Part.CanCollide = false
```

### CanQuery

`boolean`

현재 지원되지 않습니다.

#### Code Samples

### CanTouch

`boolean`

해당 파트가 Touched, TouchEnded와 같은 터치 이벤트를 발생시킬 수 있는지를 결정하는 속성입니다.

CanTouch와 CanCollide를 모두 false로 설정하면 파트 간 충돌 연산이 생략되어 성능이 향상됩니다. 단, 이 경우에도 Raycast를 통한 감지는 여전히 가능합니다.

#### Code Samples

```lua
local Part = script.Parent

local function OnTouched(otherPart)
    print(Part.Name, "Touched :", otherPart.Name)
end
Part.Touched:Connect(OnTouched)

Part.CanTouch = false
```

### CastShadow

`boolean`

해당 파트에 그림자를 생성할지 여부를 설정하는 속성으로, 성능 최적화를 위해 기본값은 false이며 필요한 경우에만 활성화하는 것이 권장됩니다.

그림자 복잡도는 Lighting 서비스를 선택한 뒤, 프로퍼티 패널에서 Shadow Detail Level 값을 조정하여 전체 파트의 그림자 품질을 지정할 수 있습니다.

또한, 특정 파트를 선택한 후 프로퍼티 패널에서 Enable Mesh Shadow Details를 활성화하면 개별 메시 단위로 Mesh Shadow Detail Level을 설정할 수 있으며, 이 경우 Lighting 서비스의 전역 설정보다 해당 메시의 설정이 우선 적용됩니다.

그림자 복잡도 관련 설정은 런타임에서 변경할 수 없습니다.

#### Code Samples

```lua
local Part = script.Parent

print(Part.CastShadow)
```

### CFrame

`CFrame`

CFrame은 월드 좌표계에서 BasePart의 위치와 회전을 정의하는 속성으로, Position 속성과 달리 회전과 방향까지 한 번에 지정할 수 있습니다.

또한 파트의 자식으로 Attachment를 추가하면, 해당 파트를 기준으로 한 상대 위치를 추적하는 데 활용할 수 있습니다.

#### Code Samples

```lua
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)
```

### CollisionObjectType

`string`

파트가 사용 중인 충돌 프로필에 의해 결정되는 충돌 오브젝트 타입의 표시 이름을 나타내는 읽기 전용 속성입니다.

CollisionProfile이 변경되면 해당 프로필이 지정한 ObjectType에 맞춰 이 값도 함께 갱신되며, 레이캐스트나 오버랩 질의에서 어떤 채널로 분류되는지를 확인하는 용도로 사용할 수 있습니다.

#### Code Samples

### CollisionProfile

`string`

파트에 적용할 충돌 프로필의 이름을 지정하는 속성으로, 기본값은 "BlockAll"입니다.

충돌 프로필은 다른 채널과의 충돌 반응(Block, Overlap, Ignore)을 일괄로 정의해 둔 프리셋이며, 등록되지 않은 프로필 이름을 지정하면 변경이 무시되고 이전 값이 유지됩니다. 등록된 프로필 목록은 PhysicsService의 GetCollisionProfiles() 등을 통해 확인할 수 있습니다.

#### Code Samples

### Color

`Color3`

파트의 기본 색상을 지정하는 속성으로, 설정된 Material의 질감에 색상이 함께 적용됩니다.

이 값을 변경하면 BrickColor 속성이 이에 맞춰 가장 유사한 색상으로 자동 변경됩니다.

BrickColor 속성이 사전에 정의된 색상 중에서 선택하는 방식이라면, Color는 실수 값이나 RGB를 통해 색상을 직접 지정할 때 사용됩니다.

#### Code Samples

```lua
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`

파트에 커스텀하게 물리 속성을 지정합니다. CustomPhysicalProperties를 활성화 하고 사용할 수 있습니다. CustomPhysicalProperties를 수정하면 CurrentPhysicalProperties에 적용됩니다.

#### Code Samples

### IsTouchingBodyPart

`boolean`

캐릭터의 신체 부위와 접촉 중인지 여부를 나타냅니다.

#### Code Samples

### Locked

`boolean`

스튜디오 편집 모드에서 뷰포트 내 해당 파트를 마우스로 클릭해 선택할 수 있는지 여부를 결정하는 속성입니다.

주로 건물, 지형, 장식 요소 등을 배치한 뒤, 의도치 않은 수정을 방지하기 위해 사용됩니다.

#### Code Samples

```lua
local Part = script.Parent

print(Part.Locked)
```

### Material

`Enum.Material`

파트의 표면 질감을 설정하는 속성입니다.

Material과 Color를 적절히 조합하면 게임 내에서 다양한 분위기와 시각적 효과를 연출할 수 있습니다.

#### Code Samples

```lua
local Part = script.Parent

Part.Material = Enum.Material.StoneBrick
```

### MaterialVariant

`string`

사전에 정의된 기본 머티리얼을 변형한 MaterialVariant를 지정하는 속성입니다.

입력한 MaterialVariant 이름이 존재하면 해당 MaterialVariant로 적용되며, 동시에 해당 MaterialVariant가 속한 기본 머티리얼(Base Material)에 맞춰 Material 속성도 자동으로 변경됩니다.

#### Code Samples

```lua
local Part = script.Parent

print(Part.MaterialVariant)
```

### Orientation

`Vector3`

Vector3 값으로 파트의 X, Y, Z 축 회전을 도 단위로 지정하는 속성으로, 회전은 Y, X, Z 순서로 적용됩니다.

이 방식은 일반적인 오일러 각이 아닌 Tait-Bryan 각을 사용하며, 이는 각각 요(yaw), 피치(pitch), 롤(roll)을 나타냅니다.

CFrame.Angles() 생성자는 Z, Y, X 순으로 회전을 적용하므로 Orientation 속성과 작동 방식이 다릅니다. 보다 정밀한 회전 제어가 필요할 경우 CFrame을 직접 설정하는 것이 권장됩니다.

#### Code Samples

```lua
local Part = script.Parent
Part.Orientation = Vector3.new(45, 0, 0)
```

### Position

`Vector3`

월드 좌표계에서 파트의 위치를 지정하는 속성입니다.

CFrame의 위치 값을 반영하며, CFrame이나 이 속성을 직접 변경하여 수정할 수 있습니다.

#### Code Samples

```lua
local Part = script.Parent
Part.Position = Vector3.new(0, 50, -500)'
```

### Size

`Vector3`

파트의 가로·세로·높이 크기를 설정하는 속성입니다.

#### Code Samples

```lua
local Part = script.Parent

Part.Size = Vector3.new(50, 50, 50)
```

### Transparency

`number`

파트의 투명도를 설정하는 속성으로, 값은 0(완전 불투명)부터 1(완전 투명)까지 지정할 수 있습니다.

값이 1이면 파트는 전혀 렌더링되지 않으며, 0보다 크고 1보다 작은 경우에는 반투명 상태가 됩니다.

완전히 투명한 파트는 렌더링되지 않아 성능 부담이 없지만, 반투명 파트는 GPU 연산이 추가로 필요해 다수 사용 시 성능 저하를 유발할 수 있습니다.

또한 Transparency가 0.01을 초과해 반투명으로 분류되면 알파 블렌딩이 활성화되기 때문에, 이때부터 알파 채널을 포함한 텍스처가 정상적으로 표현됩니다. 즉, 텍스처 자체에 투명도가 포함되어 있어도 파트가 불투명 판정(0.01 이하)이면 알파 채널이 무시되며, 반투명 판정일 때만 알파 정보가 렌더링에 반영됩니다.

#### Code Samples

```lua
local Part = script.Parent

Part.Transparency = 0.5
```

## Methods

### ApplyImpulse

파트에 순간적인 물리 힘을 가해 즉시 가속시키는 기능을 수행합니다.

힘은 항상 어셈블리의 질량 중심에 적용되므로 회전이 아닌 직선 이동만 발생하며, Anchored 속성이 false인 경우에만 동작합니다.

#### Parameters

| `Vector3` InImpulse | 적용할 선형(직선) 물리 임펄스 벡터입니다. |
| ------------------- | ------------------------ |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local Part = script.Parent

local Force = Vector3.new(0, 0, -200000)

wait(2)
Part.Anchored = false
Part:ApplyImpulse(Force)
```

### GetCollisionProfile

파트에 현재 적용된 충돌 프로필의 이름을 반환합니다.

CollisionProfile 속성을 통해 직접 조회하는 것과 동일한 값을 얻을 수 있으며, 파트가 유효한 충돌 컴포넌트를 가지고 있지 않다면 빈 문자열이 반환됩니다.

#### Parameters

#### Return

| `string` | 현재 파트에 설정된 충돌 프로필의 이름입니다. |
| -------- | ------------------------- |

#### Code Samples

### GetMass

파트의 질량 값을 반환합니다.

#### Parameters

#### Return

| `number` | 파트의 질량입니다. |
| -------- | ---------- |

#### Code Samples

```lua
local Part = script.Parent

print(Part:GetMass())
```

### SetCollisionProfile

파트에 적용할 충돌 프로필을 지정한 이름으로 변경합니다.

입력한 이름이 등록된 충돌 프로필일 때만 적용되며, 적용 시 PartComponent와 CollisionComponent의 프로필이 함께 갱신되고 CollisionObjectType과 CollisionEnabled 값도 새 프로필에 맞춰 다시 계산됩니다. 등록되지 않은 이름을 전달하면 변경이 무시되고 경고 로그가 출력됩니다.

#### Parameters

| `string` InProfileName | 적용할 충돌 프로필의 이름입니다. 사전에 등록된 프로필 이름이어야 하며, 그렇지 않으면 변경이 무시됩니다. |
| ---------------------- | ----------------------------------------------------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

## Events

### Touched

이벤트가 연결된 파트가 다른 파트와 접촉할 때 실행됩니다.

물리적인 이동뿐 아니라, 스크립트로 Position 또는 CFrame 값을 변경하여 접촉이 발생한 경우에도 호출됩니다.

단, 에디터에서 미리 겹쳐 배치한 경우에는 발생하지 않으며, CanTouch 속성이 비활성화되어 있으면 이벤트가 실행되지 않습니다.

#### Parameters

| `BasePart` otherPart | 이벤트가 연결된 파트에 접촉한 대상 파트입니다. |
| -------------------- | -------------------------- |

#### Code Samples

```lua
local Part = script.Parent

local function OnTouched(otherPart)
    print("[OnTouched]", otherPart)
end
Part.Touched:Connect(OnTouched)
```

### TouchEnded

두 파트가 서로 닿아 있는 상태에서 접촉이 해제될 때 호출됩니다.

발생 조건은 Touched 이벤트와 거의 동일하지만, 시점이 접촉 시작이 아닌 접촉 종료라는 점이 다릅니다.

물리적인 이동뿐 아니라, 스크립트로 Position 또는 CFrame 값을 변경하여 접촉이 해제된 경우에도 호출됩니다.

단, 에디터에서 미리 겹쳐 배치한 경우에는 발생하지 않으며, CanTouch 속성이 비활성화되어 있으면 이벤트가 실행되지 않습니다.

#### Parameters

| `BasePart` otherPart | 이벤트가 연결된 파트에 접촉 해제된 대상 파트입니다. |
| -------------------- | ----------------------------- |

#### Code Samples

```lua
local Part = script.Parent

local function OnTouchEnded(otherPart)
    print("[OnTouchEnded]", otherPart)
end
Part.TouchEnded:Connect(OnTouchEnded)
```

## See also

{% content-ref url="/pages/bgjSknJ1HR0zuAxjnU3P" %}
[파트](/korean/manual/studio-manual/object/part.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/korean/development/api-reference/classes/basepart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.