Vector3

Overview

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

Constructors

new

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

Parameters

Parameter	Description
number x	X축 좌표 값입니다.
number y	Y축 좌표 값입니다.
number z	Z축 좌표 값입니다.

Return

Return	Description
Vector3	생성된 Vector3입니다.

Code Samples

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

Properties

X

number

X축 좌표 값입니다.

Code Samples

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

Y

number

Y축 좌표 값입니다.

Code Samples

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

Z

number

Z축 좌표 값입니다.

Code Samples

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

zero

Vector3

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

Code Samples

local ZeroVector = Vector3.zero
print(ZeroVector)

one

Vector3

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

Code Samples

local OneVector = Vector3.one
print(OneVector)

xAxis

Vector3

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

Code Samples

local XAxis = Vector3.xAxis
print(XAxis) 

yAxis

Vector3

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

Code Samples

local YAxis = Vector3.yAxis
print(YAxis) 

zAxis

Vector3

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

Code Samples

local ZAxis = Vector3.zAxis
print(ZAxis) 

Unit

Vector3

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

Code Samples

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

Magnitude

number

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

Code Samples

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

Methods

Abs

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

Parameters

Return

Vector3	생성된 Vector3입니다.

Code Samples

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

Angle

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

Parameters

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

Return

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

Code Samples

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

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

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

Cross

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

Parameters

Vector3 otherVector	외적을 계산할 대상 Vector3입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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 otherVector	거리를 계산할 대상 Vector3입니다.

Return

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

Code Samples

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

Dot

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

Parameters

Vector3 otherVector	내적을 계산할 대상 Vector3입니다.

Return

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

Code Samples

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

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

FuzzyEq

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

Parameters

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

Return

bool	두 벡터의 제곱 크기 차이가 벡터 크기에 비례한 epsilon 허용 오차 범위 이내일 경우 true를 반환합니다. 그 외의 경우에는 false를 반환합니다.

Code Samples

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 goal	보간의 대상이 되는 목표 Vector3입니다.
number alpha	보간 비율을 나타내는 값입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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 otherVector	비교 대상이 되는 다른 Vector3입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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 otherVector	비교 대상이 되는 다른 Vector3입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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 target	이동할 목표가 되는 Vector3입니다.
number maxDelta	한 번의 연산에서 이동할 수 있는 최대 거리입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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 inNormal	반사의 기준이 되는 법선(Vector3)입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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 axis	회전의 기준이 되는 축 Vector3입니다.
number radians	회전할 각도를 라디안 단위로 지정하는 값입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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

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

Slerp

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

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

Parameters

Vector3 goal	보간의 대상이 되는 목표 Vector3입니다.
number alpha	보간 비율을 나타내는 값입니다.

Return

Vector3	생성된 Vector3입니다.

Code Samples

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 

See also

좌표계