# Vector3

## Overview

Vector3는 X, Y, Z의 세 축 값을 통해 3차원 공간상의 벡터를 표현하는 데이터 타입으로, 위치, 방향, 속도, 힘과 같은 다양한 3D 데이터를 다루는 데 사용되며, 공간 내 좌표 및 이동 계산, 물리 연산 등 여러 시스템 전반에서 핵심적으로 활용됩니다.

## Constructors

### new

전달된 X, Y, Z 값을 기반으로 새로운 벡터를 생성하여 반환합니다.

#### Parameters

| `number` x | X축 좌표 값입니다. |
| ---------- | ----------- |
| `number` y | Y축 좌표 값입니다. |
| `number` z | Z축 좌표 값입니다. |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local Vector = Vector3.new(1, 2, 3)
print(Vector)
```

## Properties

### Magnitude

`number`

Vector3의 크기를 나타내는 값입니다.

#### Code Samples

```lua
local Vector = Vector3.new(100, 50, 200)
print(Vector.Magnitude) --> Output: 229.128784
```

### one

`Vector3`

모든 축 값이 1으로 구성된 벡터입니다. (1, 1, 1)

#### Code Samples

```lua
local OneVector = Vector3.one
print(OneVector)
```

### Unit

`Vector3`

원본과 동일한 방향은 유지하되, 크기는 제거하고 길이를 1로 맞춘 Vector3입니다.

#### Code Samples

```lua
local Vector = Vector3.new(100, 50, 200)
print(Vector.Unit) --> Output: 0.436436, 0.218218, 0.872872
```

### X

`number`

X축 좌표 값입니다.

#### Code Samples

```lua
local Vector = Vector3.new(10, 5, 8)
print(Vector.X)
```

### xAxis

`Vector3`

X축 방향으로만 1의 값을 가지며, 나머지 축 값은 모두 0으로 설정된 Vector3입니다. (1, 0, 0)

#### Code Samples

```lua
local XAxis = Vector3.xAxis
print(XAxis)
```

### Y

`number`

Y축 좌표 값입니다.

#### Code Samples

```lua
local Vector = Vector3.new(10, 5, 8)
print(Vector.Y)
```

### yAxis

`Vector3`

Y축 방향으로만 1의 값을 가지며, 나머지 축 값은 모두 0으로 설정된 Vector3입니다. (0, 1, 0)

#### Code Samples

```lua
local YAxis = Vector3.yAxis
print(YAxis)
```

### Z

`number`

Z축 좌표 값입니다.

#### Code Samples

```lua
local Vector = Vector3.new(10, 5, 8)
print(Vector.Z)
```

### zAxis

`Vector3`

Z축 방향으로만 1의 값을 가지며, 나머지 축 값은 모두 0으로 설정된 Vector3입니다. (0, 0, 1)

#### Code Samples

```lua
local ZAxis = Vector3.zAxis
print(ZAxis)
```

### zero

`Vector3`

모든 축 값이 0으로 구성된 벡터입니다. (0, 0, 0)

#### Code Samples

```lua
local ZeroVector = Vector3.zero
print(ZeroVector)
```

## Methods

### Abs

벡터의 각 좌표 값을 음수 여부와 관계없이 양수 값으로 처리한 뒤, 새로운 벡터를 반환합니다.

#### Parameters

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local v = Vector3.new(-2, 4, -6)
print("Abs:", v:Abs()) --> Output: 2, 4, 6
```

### Angle

두 벡터가 이루는 각도를 라디안으로 계산하고, 기준 축이 있을 경우 방향성까지 함께 고려한 값을 반환합니다.

#### Parameters

| `Value` InOtherValue | 각도를 계산할 대상 Vector3입니다.                                                   |
| -------------------- | ------------------------------------------------------------------------ |
| `Value` AxisValue    | 각도의 방향을 판단하기 위한 기준 축 Vector3입니다. 축을 제공하지 않을 경우, 두 벡터 사이의 절대적인 각도만 계산됩니다. |

#### Return

| `number` | 두 벡터가 이루는 각도를 라디안 단위로 반환합니다. |
| -------- | ---------------------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Angle:", a:Angle(b) -- Output: 1.570796
```

### Ceil

벡터의 각 좌표 값을 올림 처리한 뒤, 새로운 벡터를 반환합니다.

#### Parameters

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local v = Vector3.new(-2.6, 5.1, 8.8)
print("Ceil:", v:Ceil()) --> Output: -2, 6, 9
```

### ClampMagnitude

벡터 길이가 maxLength를 넘지 않도록 크기를 제한한 새로운 벡터를 반환합니다.

#### Parameters

| `number` MaxLength | 벡터의 길이를 제한하기 위한 최대 값입니다. |
| ------------------ | ------------------------ |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local v = Vector3.new(10, 0, 0)
print("ClampMagnitude", v:ClampMagnitude(3)) --> Output: 3, 0, 0
```

### Cross

두 벡터의 외적 결과를 새로운 벡터로 반환합니다.

#### Parameters

| `Value` InOtherValue | 외적을 계산할 대상 Vector3입니다. |
| -------------------- | ---------------------- |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Cross:", a:Cross(b)) --> Output: 0, 0, 1
```

### Distance

두 벡터 사이의 거리를 반환합니다.

#### Parameters

| `Vector3` OtherValue | 거리를 계산할 대상 Vector3입니다. |
| -------------------- | ---------------------- |

#### Return

| `number` | 두 벡터의 직선 거리를 숫자 값으로 반환합니다. |
| -------- | -------------------------- |

#### Code Samples

```lua
local a = Vector3.new(0, 0, 0)
local b = Vector3.new(3, 4, 0)
print("Distance:", a:Distance(b)) --> Output: 5
```

### Dot

두 벡터의 내적 값을 스칼라로 반환합니다.

#### Parameters

| `Value` InOtherValue | 내적을 계산할 대상 Vector3입니다. |
| -------------------- | ---------------------- |

#### Return

| `number` | 두 벡터의 내적 결과를 스칼라 값으로 반환합니다. |
| -------- | --------------------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 2, 3)
local b = Vector3.new(4, 5, 6)
print("Dot:", a:Dot(b)) --> Output: 32
```

### Floor

기존 벡터의 각 좌표 값을 내림 처리한 뒤, 새로운 벡터를 반환합니다.

#### Parameters

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local v = Vector3.new(-2.6, 5.1, 8.8)
print("Floor:", v:Floor()) --> Output: -3, 5, 8
```

### FuzzyEq

두 벡터의 크기를 제곱한 값을 서로 비교했을 때, 벡터의 크기를 기준으로 계산된 epsilon 범위 안에 있으면 같은 벡터로 보고 true를 반환합니다.

#### Parameters

| `Value` InOtherValue | 비교할 대상 Vector3입니다.                                                                   |
| -------------------- | ------------------------------------------------------------------------------------ |
| `number` Epsilon     | 허용 오차를 나타내는 값입니다. 이 값은 벡터의 크기에 비례하여 적용되며, 두 벡터의 제곱 크기 차이가 이 범위 안에 있는지를 판단하는 데 사용됩니다. |

#### Return

| `boolean` | 두 벡터의 제곱 크기 차이가 벡터 크기에 비례한 epsilon 허용 오차 범위 이내일 경우 true를 반환합니다. |
| --------- | --------------------------------------------------------------- |

#### Code Samples

```lua
local a = Vector3.new(1.0001, 2.0001, 3.0001)
local b = Vector3.new(1.0002, 2.0002, 3.0002)
print("FuzzyEq:", a:FuzzyEq(b)) --> Output: false
```

### Lerp

현재 벡터와 목표 벡터 사이를 선형 보간 방식으로 alpha 비율에 따라 계산한 위치를 새로운 벡터로 반환합니다.

#### Parameters

| `Vector3` GoalValue | 보간의 대상이 되는 목표 Vector3입니다. |
| ------------------- | ------------------------- |
| `number` Alpha      | 보간 비율을 나타내는 값입니다.         |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local a = Vector3.new(0, 0, 0)
local b = Vector3.new(10, 10, 10)
print("Lerp:", a:Lerp(b, 0.3)) --> Output: 3, 3, 3
```

### Max

두 벡터의 X, Y, Z 값을 각각 비교한 뒤, 각 축마다 더 높은 값을 선택해 조합한 새로운 벡터로 반환합니다.

#### Parameters

| `Vector3` OtherValue | 비교 대상이 되는 다른 Vector3입니다. |
| -------------------- | ------------------------ |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 5, 3)
local b = Vector3.new(4, 2, 6)
print("Max:", a:Max(b)) --> Output: 4, 5, 6
```

### Min

두 벡터의 X, Y, Z 값을 각각 비교한 뒤, 각 축마다 더 낮은 값을 선택해 조합한 새로운 벡터로 반환합니다.

#### Parameters

| `Vector3` OtherValue | 비교 대상이 되는 다른 Vector3입니다. |
| -------------------- | ------------------------ |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 5, 3)
local b = Vector3.new(4, 2, 6)
print("Min:", a:Min(b)) --> Output: 1, 2, 3
```

### MoveTowards

현재 벡터에서 목표 벡터로 maxDelta 거리만큼 이동한 새로운 벡터를 반환합니다.

#### Parameters

| `Vector3` TargetValue | 이동할 목표가 되는 Vector3입니다.       |
| --------------------- | ---------------------------- |
| `number` MaxDelta     | 한 번의 연산에서 이동할 수 있는 최대 거리입니다. |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local a = Vector3.new(0, 0, 0)
local b = Vector3.new(10, 0, 0)
print("MoveTowards:", a:MoveTowards(b, 3)) --> Output: 3, 0, 0
```

### Reflect

벡터를 주어진 노멀 벡터를 기준으로 반사하여 새로운 벡터를 반환합니다.

#### Parameters

| `Vector3` NormalValue | 반사의 기준이 되는 법선(Vector3)입니다. |
| --------------------- | -------------------------- |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local v = Vector3.new(1, -1, 0)
local n = Vector3.new(0, 1, 0)
print("Reflect", v:Reflect(n)) --> Output: 1, 1, 0
```

### Rotate

제공된 축(axis)을 기준으로 벡터를 radians 만큼 회전시킨 새로운 벡터를 반환합니다.

#### Parameters

| `Vector3` AxisValue | 회전의 기준이 되는 축 Vector3입니다.   |
| ------------------- | -------------------------- |
| `number` Radians    | 회전할 각도를 라디안 단위로 지정하는 값입니다. |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local v = Vector3.new(1, 0, 0)
local axis = Vector3.new(0, 1, 0)
print("Rotate:", v:Rotate(axis, math.rad(90))) --> Output: 0, 0, -1
```

### Sign

기존 벡터의 각 좌표가 음수인지, 0인지, 양수인지에 따라 각각 -1, 0, 1로 변환하여, 그 결과를 새로운 벡터로 반환합니다.

#### Parameters

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local v = Vector3.new(-2.6, 5.1, 0)
print("Sign:", v:Sign()) --> Output: -1, 1, 0
```

### Slerp

현재 벡터와 목표 벡터 사이를 구면 선형 보간 방식으로 alpha 비율에 따라 계산한 위치를 새로운 벡터로 반환합니다.

Lerp는 직선 경로를 따라 보간하지만, Slerp는 단위 구면 위의 곡선을 따라 보간하기 때문에 회전 방향 변화가 더 부드럽고 일정합니다.

#### Parameters

| `Vector3` GoalValue | 보간의 대상이 되는 목표 Vector3입니다. |
| ------------------- | ------------------------- |
| `number` Alpha      | 보간 비율을 나타내는 값입니다.         |

#### Return

| `Vector3` | 생성된 Vector3입니다. |
| --------- | --------------- |

#### Code Samples

```lua
local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Slerp:", a:Slerp(b, 0.5)) --> Output: 0.707107, 0.707107, 0
```

## Events

## See also

{% content-ref url="/pages/mC9duPphkAklv8ZEUCpW" %}
[좌표계](/korean/manual/studio-manual/get-started/coordinate-system.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/datatype/vector3.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.