CFrame

Overview

CFrame은 3차원 공간에서 객체의 위치와 회전을 동시에 표현하기 위한 데이터 타입입니다. 단순한 좌표 정보뿐만 아니라 방향 정보까지 포함하고 있어, 공간 배치나 방향 계산이 필요한 다양한 상황에서 활용됩니다.

위치 정보는 Vector3와 동일한 방식으로 다룰 수 있으며, X, Y, Z 값에 개별적으로 접근하는 것도 가능합니다. 회전 정보는 내부적으로 행렬 형태로 관리되며, 이를 기반으로 LookVector, RightVector와 같은 방향 벡터들이 계산됩니다. 이러한 벡터들은 카메라 방향 설정이나 오브젝트 정렬과 같은 작업에서 매우 중요한 역할을 합니다.

Constructors

new

새로운 CFrame를 생성하여 반환합니다.

Parameters

Return

CFrame	생성된 CFrame입니다.

Code Samples

local CF = CFrame.new()

new

전달된 Vector3 값을 위치로 사용하는 CFrame을 생성합니다. 회전 정보는 포함되지 않으며, 기본 방향을 유지한 상태의 좌표계가 반환됩니다.

Parameters

Vector3 Position	CFrame에 적용할 위치를 나타내는 Vector3 값입니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local Position = Vector3.new(10, 50, 20)
local CF = CFrame.new(Position)

new

지정한 위치에 CFrame을 배치한 뒤, 특정 지점을 향하도록 방향을 설정합니다. 기본적으로 월드의 위쪽 방향은 Y축(0, 1, 0)을 기준으로 계산됩니다.

Parameters

Vector3 Position	CFrame에 적용할 위치를 나타내는 Vector3 값입니다.
Vector3 Look	CFrame이 바라보도록 설정할 목표 위치를 나타내는 Vector3 값입니다. 생성된 CFrame은 이 지점을 향하도록 방향이 설정됩니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local Position = Vector3.new(10, 50, 20)
local LookAt = Vector3.new(0, 30, 0)
local CF = CFrame.new(Position, LookAt)

new

전달된 X, Y, Z 좌표를 기반으로 CFrame의 위치를 설정합니다. 회전 정보는 포함되지 않으며, 기본 방향을 유지한 상태의 좌표계가 반환됩니다.

Parameters

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

Return

CFrame	생성된 CFrame입니다.

Code Samples

local CF = CFrame.new(10, 50, 20)

lookAt

지정한 위치(at)에 CFrame을 배치한 뒤, 특정 지점(lookAt)을 바라보도록 회전을 적용합니다. 기본적으로 월드 공간의 위쪽 방향은 Y축(0, 1, 0)을 기준으로 계산되며, up 값을 전달하면 기준이 되는 위쪽 방향을 직접 설정할 수 있습니다.

Parameters

Vector3 at	CFrame에 적용할 위치를 나타내는 Vector3 값입니다.
Vector3 lookAt	CFrame이 바라보도록 설정할 목표 위치를 나타내는 Vector3 값입니다. 생성된 CFrame은 이 지점을 향하도록 방향이 설정됩니다.
Vector3 up	위쪽 방향으로 사용할 Vector3 값입니다. 방향 계산 시 기준이 되는 상단 방향을 지정하며, 생략할 경우 기본값으로 (0, 1, 0)이 사용됩니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local Part = script.Parent
local Workspace = game:GetService("Workspace")
local SpawnLocation = Workspace.SpawnLocation

local CF = CFrame.lookAt(Part.Position, SpawnLocation.Position)

fromEulerAnglesXYZ

전달된 X, Y, Z 축에 대한 회전 각도를 라디안 값으로 받아, XYZ 회전 순서를 기준으로 회전이 적용된 CFrame을 생성합니다. 입력된 각도는 지정된 축 순서에 따라 순차적으로 적용됩니다.

Parameters

number rx	X축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number ry	Y축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number rz	Z축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local CF = CFrame.fromEulerAnglesXYZ(1, 0.5, 0.25)

Angles

fromEulerAnglesXYZ()를 호출한 것과 같은 결과를 반환하며, 동일한 회전 계산 방식을 사용합니다.

Parameters

number rx	X축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number ry	Y축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number rz	Z축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local CF = CFrame.Angles(0, math.rad(40), 0)

fromEulerAnglesYXZ

전달된 X, Y, Z 축에 대한 회전 각도를 라디안 값으로 받아, YXZ 회전 순서를 기준으로 회전이 적용된 CFrame을 생성합니다. 입력된 각도는 지정된 축 순서에 따라 순차적으로 적용됩니다.

Parameters

number rx	X축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number ry	Y축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number rz	Z축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local CF = CFrame.fromEulerAnglesYXZ(1, 0.5, 0.25)

fromOrientation

fromEulerAnglesYXZ()를 호출한 것과 같은 결과를 반환하며, 동일한 회전 계산 방식을 사용합니다.

Parameters

number rx	X축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number ry	Y축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.
number rz	Z축을 기준으로 적용할 회전 각도입니다. 라디안 단위로 지정합니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local CF = CFrame.fromOrientation(1, 0.5, 0.25)

fromMatrix

이동 위치와 회전 행렬을 구성하는 벡터들을 기반으로 CFrame을 생성합니다. 만약 Z 값이 생략되면, X와 Y의 외적을 정규화하여 나머지 회전 축을 자동으로 보완합니다. 이를 통해 필요한 회전 정보가 완성된 CFrame이 생성됩니다.

Parameters

Vector3 pos	CFrame의 위치 이동을 나타내는 Vector3 값입니다.
Vector3 vx	회전 행렬의 첫 번째 열(column)에 해당하는 Vector3 값입니다. 로컬 X축 방향을 정의합니다.
Vector3 vy	회전 행렬의 두 번째 열(column)에 해당하는 Vector3 값입니다. 로컬 Y축 방향을 정의합니다.
Vector3 vz	회전 행렬의 세 번째 열(column)에 해당하는 Vector3 값입니다. 로컬 Z축 방향을 정의합니다. 생략할 경우, X와 Y의 외적을 정규화한 값이 자동으로 사용됩니다.

Return

CFrame	생성된 CFrame입니다.

Code Samples

local Position = Vector3.new(0, 50, 0)
local RightVector = Vector3.new(1, 0, 0)
local UpVector = Vector3.new(0, 1, 0)
local BackVector = Vector3.new(0, 0, 1)

local CF = CFrame.fromMatrix(Position, RightVector, UpVector, BackVector)

Properties

identity

CFrame

위치와 회전이 전혀 없는 단위(identity)의 CFrame을 의미합니다. 고정된 상수 값으로 제공되며, 특정 CFrame 인스턴스에 속하지 않고 전역 기준 값으로 사용됩니다.

Code Samples

local CFZero = CFrame.identity
print(CFZero)

Position

Vector3

CFrame이 나타내는 3차원 공간상의 위치 좌표입니다.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.Position)

Orientation

Vector3

CFrame이 나타내는 3차원 공간상의 회전 방향을 의미합니다. 해당 방향은 CFrame의 회전을 요(Yaw), 피치(Pitch), 롤(Roll) 기준으로 변환한 Vector3 형태로 반환됩니다.

이 값은 Workspace에서 사전에 구성해야 하며, 게임 실행 중에는 런타임에서 수정할 수 없습니다. 따라서 해당 속성은 반드시 스튜디오 편집 단계에서 미리 설정해야 합니다.

Code Samples

local CF = CFrame.fromOrientation(20, 90, 60)
print(CF.Orientation)

Rotation

Vector3

CFrame이 나타내는 3차원 공간상의 회전 방향을 의미합니다. 해당 방향은 내부적으로 3×3 회전을 기반으로 한 회전 행렬을 통해 해당 방향 정보를 표현합니다.

Code Samples

local CF = CFrame.Angles(0, math.rad(45), 0)
print(CF.Rotation)

X

number

CFrame이 위치한 3차원 공간의 X축 좌표 값입니다.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.X)

Y

number

CFrame이 위치한 3차원 공간의 Y축 좌표 값입니다.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.Y)

Z

number

CFrame이 위치한 3차원 공간의 Z축 좌표 값입니다.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.Z)

XVector

Vector3

CFrame의 회전 방향 중 X축에 해당하는 벡터를 나타냅니다. 내부적으로는 회전 행렬의 첫 번째 열과 같은 값이며, RightVector와 동일한 방향을 가집니다.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.XVector)

YVector

Vector3

CFrame 회전 정보 중 Y축 방향을 나타내는 벡터입니다. 내부적으로는 회전 행렬의 두 번째 열에 해당하며, UpVector와 같은 방향을 가집니다.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.YVector)

ZVector

Vector3

CFrame의 회전 방향 중 Z축에 해당하는 벡터를 나타냅니다. 내부적으로는 회전 행렬의 세 번째 열을 기준으로 하며, LookVector와는 반대 방향의 값을 가집니다.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.ZVector)

LookVector

Vector3

LookVector는 CFrame이 향하고 있는 전방 방향을 나타내는 벡터입니다. 내부적으로는 회전 행렬의 Z축 성분을 반전한 값을 기반으로 하며, 객체가 바라보는 방향을 직관적으로 표현하는 데 사용됩니다.

Code Samples

local Part = script.Parent
local Workspace = game:GetService("Workspace")
local SpawnLocation = Workspace.SpawnLocation

local CF = CFrame.lookAt(Part.Position, SpawnLocation.Position)
print(CF.LookVector)

RightVector

Vector3

CFrame이 기준으로 삼는 오른쪽 방향을 나타내는 벡터입니다. 내부적으로는 회전 행렬의 첫 번째 열에 해당하며, 객체의 로컬 X축 방향을 표현합니다.

Code Samples

local Part = script.Parent
local CF = Part.CFrame
print(CF.RightVector)

UpVector

Vector3

CFrame이 기준으로 삼는 위쪽 방향을 나타내는 벡터입니다. 내부적으로는 회전 행렬의 두 번째 열에 해당하며, 객체의 로컬 Y축 방향을 표현합니다.

Code Samples

local Part = script.Parent
local CF = Part.CFrame
print(CF.UpVector)

Methods

Inverse

CFrame의 변환을 반대로 적용한 새로운 CFrame을 반환합니다. 위치와 회전이 모두 반전된 좌표계로, 변환을 되돌리거나 상대적인 위치 계산에 활용할 수 있습니다.

Parameters

Return

CFrame	생성된 CFrame입니다.

Code Samples

local CF = CFrame.new(0, 50, 0)
local InverseCF = CF:Inverse()

Lerp

현재 CFrame과 목표 CFrame 사이를 기준으로 alpha 값에 따라 위치와 회전을 보간한 새로운 CFrame을 반환합니다. alpha가 0이면 현재 CFrame, 1이면 목표 CFrame에 해당합니다.

Parameters

CFrame goal	보간의 목표가 되는 CFrame입니다. 현재 CFrame에서 이 CFrame을 향해 위치와 회전이 보간됩니다.
number alpha	보간 비율을 나타내는 숫자 값입니다. 0이면 현재 CFrame, 1이면 goal CFrame에 해당하며, 0과 1 사이의 값은 두 CFrame 사이의 중간 상태를 의미합니다.

Return

CFrame	현재 CFrame과 goal CFrame 사이를 alpha 비율만큼 보간한 새로운 CFrame을 반환합니다. 위치와 회전이 함께 부드럽게 보간됩니다.

Code Samples

local CF1 = CFrame.new(0, 0, 0)
local CF2 = CFrame.new(10, 10, 10)
local Alpha = 0.5

local Result = CF1:Lerp(CF2, Alpha)

PointToWorldSpace

CFrame을 기준으로 한 로컬 좌표를 월드 좌표계로 변환합니다. CFrame의 위치와 회전을 모두 반영하여, 월드 공간에서의 실제 좌표를 반환합니다.

Parameters

Vector3 v3	CFrame을 기준으로 계산된 상대 위치를 나타내는 Vector3 값입니다. 해당 좌표는 CFrame의 원점을 기준으로 한 위치로 해석됩니다.

Return

Vector3	입력된 상대 좌표에 CFrame의 위치와 회전을 적용하여 계산된 월드 공간상의 좌표를 반환합니다.

Code Samples

local CF = CFrame.new(10, 0, 0)
local LocalPoint = Vector3.new(15, 0, 0)
local WorldPoint = CF:PointToWorldSpace(LocalPoint)

PointToObjectSpace

CFrame을 기준으로 월드 좌표를 로컬 좌표계로 변환합니다. CFrame의 위치와 회전을 모두 반영하여, 객체 기준의 상대 좌표를 반환합니다.

Parameters

Vector3 v3	월드 공간상의 위치를 나타내는 Vector3 값입니다. 해당 좌표는 CFrame을 기준으로 한 로컬 좌표로 변환됩니다.

Return

Vector3	입력된 월드 좌표에 CFrame의 위치와 회전을 적용하여 계산된 로컬 공간상의 좌표를 반환합니다.

Code Samples

local CF = CFrame.new(25, 0, 0)
local WorldPoint = Vector3.new(35, 0, 0)
local LocalPoint = CF:PointToObjectSpace(WorldPoint)

VectorToWorldSpace

CFrame을 기준으로 한 방향 벡터를 월드 좌표계의 방향 벡터로 변환합니다. 이 과정에서는 회전만 적용되며, 위치 이동은 반영되지 않습니다.

Parameters

Vector3 v3	CFrame을 기준으로 한 로컬 공간의 방향 벡터를 나타내는 Vector3 값입니다.

Return

Vector3	입력된 방향 벡터에 CFrame의 회전을 적용하여 계산된 월드 공간상의 방향 벡터를 반환합니다.

Code Samples

local CF = CFrame.new()
local LocalDir = Vector3.new(1, 0, 0)
local WorldDir = CF:VectorToWorldSpace(LocalDir)

VectorToObjectSpace

CFrame을 기준으로 월드 공간의 방향 벡터를 로컬 공간의 방향 벡터로 변환합니다. 이 과정에서는 회전만 적용되며, 위치 이동은 반영되지 않습니다.

Parameters

Vector3 v3	월드 공간에서의 방향을 나타내는 Vector3 값입니다. 해당 벡터는 CFrame을 기준으로 한 로컬 방향 벡터로 변환됩니다.

Return

Vector3	입력된 방향 벡터에 CFrame의 회전을 적용하여 계산된 로컬 공간상의 방향 벡터를 반환합니다.

Code Samples

local CF = CFrame.new()
local WorldDir = Vector3.new(1, 0, 0)
local LocalDir = CF:VectorToObjectSpace(WorldDir)

ToEulerAnglesXYZ

CFrame에 적용된 회전을 XYZ 회전 순서 기준의 각도 값으로 근사 변환하여 반환합니다.

Parameters

Return

Tuple	X축, Y축, Z축에 대한 회전 각도를 라디안 단위로 각각 반환합니다.

Code Samples

local CF = CFrame.Angles(math.rad(30), math.rad(45), math.rad(60))
local X, Y, Z = CF:ToEulerAnglesXYZ()

ToEulerAnglesYXZ

CFrame에 적용된 회전을 YXZ 회전 순서 기준의 각도 값으로 근사 변환하여 반환합니다.

Parameters

Return

Tuple	X축, Y축, Z축에 대한 회전 각도를 라디안 단위로 각각 반환합니다.

Code Samples

local CF = CFrame.Angles(math.rad(30), math.rad(45), math.rad(60))
local X, Y, Z = CF:ToEulerAnglesYXZ()

ToOrientation

ToEulerAnglesYXZ()를 호출한 경우와 같은 결과를 반환하며, 동일한 회전 순서와 계산 방식을 사용합니다.

Parameters

Return

Tuple	X축, Y축, Z축에 대한 회전 각도를 라디안 단위로 각각 반환합니다.

Code Samples

local CF = CFrame.Angles(math.rad(10), math.rad(20), math.rad(30))
local X, Y, Z = CF:ToOrientation()

See also

좌표계