# Model

Model : `PVInstance`

## Overview

Model은 여러 객체를 하나의 그룹으로 묶어 관리하는 컨테이너로, 주로 BasePart 모음을 다루는 데 사용됩니다.

위치나 구조적으로 연관된 파트를 함께 담는 데 적합하며, 단순히 스크립트처럼 물리적 형태가 없는 요소를 묶을 경우에는 Folder를 사용하는 것이 더 알맞습니다.

여러 오브젝트를 하나로 묶어 물리 효과를 함께 적용하거나, 동시에 이동·회전·삭제 등의 작업을 수행할 수 있도록 지원합니다. 이를 통해 개별 오브젝트를 일일이 제어하지 않고도 하나의 단위처럼 다룰 수 있습니다.

## Properties

### PrimaryPart

`BasePart`

모델에서 기준 역할을 하는 BasePart를 지정하는 속성입니다.

PrimaryPart로 지정할 수 있는 대상은 반드시 해당 모델의 하위 BasePart여야 합니다. 하위 파트가 아닌 BasePart는 지정할 수 없습니다.

Character Model의 경우 PrimaryPart는 HumanoidRootPart입니다.

#### Code Samples

```lua
local Model = script.Parent

Model.PrimaryPart = Model.Part
```

### WorldPivot

`CFrame`

PrimaryPart가 없는 모델의 회전 중심점을 정의합니다. 모델에 PrimaryPart가 있으면, 피벗은 그 파트의 기준점으로 대체되며 이 속성은 무시됩니다.

#### Code Samples

```lua
local Model = script.Parent

print(Model.WorldPivot)
```

## Methods

### GetPivot

Model의 현재 Pivot의 CFrame 정보를 가져옵니다.

#### Parameters

#### Return

| `CFrame` | Model Pivot의 CFrame 입니다. |
| -------- | ------------------------ |

#### Code Samples

### MoveTo

Model의 현재 Pivot을 기준으로, 내부의 BasePart들을 Anchored 여부와 상관없이 지정한 목표 위치로 즉시 이동합니다. 단, 목표 위치에 BasePart 등의 장애물이 존재할 경우, Model은 장애물과 겹치지 않도록 수직으로 상승한 위치로 자동 조정되어 이동합니다.

또한 MoveTo는 위치만 이동시키는 기능이기 때문에, 목표 지점으로 이동하더라도 기존 회전값은 그대로 유지됩니다.

만약 목표 위치의 장애물 고려가 필요하지 않거나, 회전값 적용이 필요한 경우에는 PivotTo 기능 사용을 권장합니다.

#### Parameters

| `Vector3` InPosition | 이동 될 목표 위치 좌표값입니다. |
| -------------------- | ------------------ |

#### Return

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

#### Code Samples

```lua
local Model = script.Parent

local Destination = Vector3.new(100, 0, 100)
Model:MoveTo(Destination)
```

### PivotTo

Model의 현재 Pivot을 기준으로, 내부의 BasePart들을 Anchored 여부와 상관없이 지정한 목표 위치로 즉시 이동합니다. MoveTo와 다르게, 목표 위치에 BasePart 등의 장애물이 존재하더라도 충돌 여부를 검사하지 않으며, 장애물과 겹치는 이동을 허용합니다.

또한 PivotTo는 CFrame을 매개변수로 받아 위치와 회전을 모두 적용시키는 기능입니다.

만약 목표 위치의 장애물 고려가 필요하거나, 위치값 적용만 필요한 경우에는 MoveTo 기능 사용을 권장합니다.

#### Parameters

| `CFrame` InTargetCFrame | 이동 될 목표 CFrame값 입니다. |
| ----------------------- | -------------------- |

#### Return

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

#### Code Samples

```lua
local Model = script.Parent

local Destination = CFrame.new(Vector3.new(100, 0, 100)) * CFrame.Angles(0, math.rad(180), 0)  -- xyz 순으로 100, 0, 100 위치값, y 축으로 180도 회전값을 적용
Model:PivotTo(Destination)
```

### SetPrimaryPartCFrame

모델의 중심 역할을 하는 PrimaryPart의 위치와 회전을 지정하는 기능입니다.

PrimaryPart의 CFrame이 변경되면, 모델에 포함된 모든 파트가 동일하게 따라 움직이며, 각 파트가 PrimaryPart로부터 가지고 있던 상대적인 방향과 거리 관계는 변하지 않습니다. 즉, 모델 전체를 한 번에 이동 시키거나 회전시킬 때 사용하는 핵심 메커니즘입니다.

단, 모델에 PrimaryPart가 지정되어 있지 않는 상태에서 이 함수를 실행하는 순간 오류가 발생합니다.

#### Parameters

| `CFrame` InNewCFrame | 설정할 CFrame입니다. |
| -------------------- | -------------- |

#### Return

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

#### Code Samples

## Events

## See also