CFrame

Overview

CFrame is a data type that represents both position and rotation of an object in 3D space. Beyond simple coordinates, it includes directional information, making it useful for spatial placement and direction calculations.

Position data works like Vector3, allowing direct access to each X, Y, and Z values. Rotation is stored internally as a matrix, from which direction vectors like LookVector and RightVector are derived. These vectors are essential for tasks such as setting camera directions or aligning objects.

Constructors

new

Creates and returns a new CFrame.

Parameters

Return

CFrame	The created CFrame.

Code Samples

local CF = CFrame.new()

new

Creates a CFrame using the passed Vector3 value as position. No rotation information is included, and a coordinate system maintaining the default direction is returned.

Parameters

Vector3 Position	The Vector3 value representing the position to apply to the CFrame.

Return

CFrame	The created CFrame.

Code Samples

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

new

Places the CFrame at the specified position, then sets the direction to point toward a specific location. By default, the world's upward direction is calculated based on the Y-axis (0, 1, 0).

Parameters

Vector3 Position	The Vector3 value representing the position to apply to the CFrame.
Vector3 Look	The Vector3 value representing the target position the CFrame should look toward. The created CFrame's direction is set to point toward this location.

Return

CFrame	The created CFrame.

Code Samples

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

new

Creates the CFrame's position based on the passed X, Y, Z coordinates. No rotation information is included, and a coordinate system maintaining the default direction is returned.

Parameters

number x	The value of X coordinate.
number y	The value of Y coordinate.
number z	The value of Z coordinate.

Return

CFrame	The created CFrame.

Code Samples

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

lookAt

Places the CFrame at the specified position (at), then applies rotation to look toward a specific point (lookAt). By default, the world space upward direction is calculated based on the Y-axis (0, 1, 0), and passing an up value allows direct setting of the reference upward direction.

Parameters

Vector3 at	The Vector3 value representing the position to apply to the CFrame.
Vector3 lookAt	The Vector3 value representing the target position the CFrame should look toward. The created CFrame's direction is set to point toward this location.
Vector3 up	The Vector3 value to be used as the upward direction. Specifies the reference upward direction when calculating direction; if omitted, the default (0, 1, 0) is used.

Return

CFrame	The created 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

Receives rotation angles for the X, Y, and Z axes as radian values, then creates a CFrame with rotation applied in XYZ rotation order. The provided angles are applied sequentially in the specified axis order.

Parameters

number rx	Rotation angle to apply around the X-axis, in radians.
number ry	Rotation angle to apply around the Y-axis, in radians.
number rz	Rotation angle to apply around the Z-axis, in radians.

Return

CFrame	The created CFrame.

Code Samples

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

Angles

Returns the same result as calling fromEulerAnglesXYZ() and uses the same rotation calculation method.

Parameters

number rx	Rotation angle to apply around the X-axis, in radians.
number ry	Rotation angle to apply around the Y-axis, in radians.
number rz	Rotation angle to apply around the Z-axis, in radians.

Return

CFrame	The created CFrame.

Code Samples

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

fromEulerAnglesYXZ

Receives rotation angles for the X, Y, and Z axes as radian values, then creates a CFrame with rotation applied in YXZ rotation order. The provided angles are applied sequentially in the specified axis order.

Parameters

number rx	Rotation angle to apply around the X-axis, in radians.
number ry	Rotation angle to apply around the Y-axis, in radians.
number rz	Rotation angle to apply around the Z-axis, in radians.

Return

CFrame	The created CFrame.

Code Samples

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

fromOrientation

Returns the same result as calling fromEulerAnglesYXZ() and uses the same rotation calculation method.

Parameters

number rx	Rotation angle to apply around the X-axis, in radians.
number ry	Rotation angle to apply around the Y-axis, in radians.
number rz	Rotation angle to apply around the Z-axis, in radians.

Return

CFrame	The created CFrame.

Code Samples

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

fromMatrix

Creates a CFrame based on the movement position and vectors forming the rotation matrix. If the Z value is omitted, the remaining rotation axis is automatically compensated by normalizing the cross product of X and Y. This completes the necessary rotation information to create the CFrame.

Parameters

Vector3 pos	The Vector3 value representing the position shift of the CFrame.
Vector3 vx	The Vector3 value corresponding to the first column of the rotation matrix, defining the local X-axis direction.
Vector3 vy	The Vector3 value corresponding to the second column of the rotation matrix, defining the local Y-axis direction.
Vector3 vz	The Vector3 value corresponding to the third column of the rotation matrix, defining the local Z-axis direction. If omitted, the normalized cross product of X and Y is automatically used.

Return

CFrame	The created 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

Represents the identity CFrame with no position or rotation. Provided as a fixed constant value, it does not belong to a specific CFrame instance and is used as a global reference value.

Code Samples

local CFZero = CFrame.identity
print(CFZero)

Position

Vector3

The coordinates representing the position of the CFrame in 3D space.

Code Samples

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

Orientation

Vector3

Represents the rotational direction of the CFrame in 3D space. The direction is returned as Vector3 with the CFrame's rotation converted to Yaw, Pitch, and Roll.

This value must be configured in advance in the Workspace and cannot be modified at runtime while the game is running. Therefore, this property must be set during the Studio editing phase.

Code Samples

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

Rotation

Vector3

Represents the rotational direction of the CFrame in 3D space. Internally, the direction information is expressed through a rotation matrix based on 3×3 rotation.

Code Samples

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

X

number

The X-axis coordinate value where the CFrame is positioned in 3D space.

Code Samples

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

Y

number

The Y-axis coordinate value where the CFrame is positioned in 3D space.

Code Samples

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

Z

number

The Z-axis coordinate value where the CFrame is positioned in 3D space.

Code Samples

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

XVector

Vector3

Represents the vector corresponding to the X-axis in the CFrame's rotation direction. Internally, this is the same value as the first column of the rotation matrix and has the same direction as RightVector.

Code Samples

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

YVector

Vector3

Represents the vector for the Y-axis direction in the CFrame's rotation information. Internally, corresponds to the second column of the rotation matrix and has the same direction as UpVector.

Code Samples

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

ZVector

Vector3

Represents the vector corresponding to the Z-axis in the CFrame's rotation direction. Internally based on the third column of the rotation matrix, with a value opposite in direction to LookVector.

Code Samples

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

LookVector

Vector3

LookVector is a vector representing the forward direction the CFrame is facing. Internally based on the inverted value of the Z-axis component of the rotation matrix, it is used to intuitively express the direction an object is facing.

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

The vector representing the right direction referenced by the CFrame. Internally corresponds to the first column of the rotation matrix, representing the local X-axis of an object.

Code Samples

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

UpVector

Vector3

The vector representing the upward direction referenced by the CFrame. Internally corresponds to the second column of the rotation matrix, representing the local Y-axis of an object.

Code Samples

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

Methods

Inverse

Returns a new CFrame with the conversion inversely applied. A coordinate system with both position and rotation inverted, which can be used to reverse conversions or calculate relative positions.

Parameters

Return

CFrame	The created CFrame.

Code Samples

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

Lerp

Returns a new CFrame with position and rotation interpolated according to the alpha value between the current CFrame and the target CFrame. Alpha of 0 corresponds to the current CFrame, 1 corresponds to the goal CFrame.

Parameters

CFrame goal	The CFrame that is the target of interpolation. Position and rotation are interpolated from the current CFrame toward this CFrame.
number alpha	A numeric value representing the interpolation ratio. 0 corresponds to the current CFrame, 1 to the goal CFrame, and values between 0 and 1 represent intermediate states between the two CFrames.

Return

CFrame	Returns a new CFrame interpolated by the alpha ratio between the current CFrame and goal CFrame, with both position and rotation smoothly interpolated.

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

Converts local coordinates based on the CFrame to world coordinates. Reflects both the CFrame's position and rotation to return the actual coordinates in world space.

Parameters

Vector3 v3	The Vector3 value representing the relative position calculated based on the CFrame. The coordinate is interpreted as a position based on the CFrame's origin.

Return

Vector3	Returns the coordinates in world space calculated by applying the CFrame's position and rotation to the provided relative coordinates.

Code Samples

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

PointToObjectSpace

Converts world coordinates to the local coordinate system based on the CFrame. Reflects both the CFrame's position and rotation to return relative coordinates based on the object.

Parameters

Vector3 v3	The Vector3 value representing a position in world space. The coordinate is converted to a local coordinate based on the CFrame.

Return

Vector3	Returns the coordinates in local space calculated by applying the CFrame's position and rotation to the input world coordinates.

Code Samples

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

VectorToWorldSpace

Converts a direction vector based on the CFrame to a direction vector in the world coordinate system. Only rotation is applied in this process; position shift is not reflected.

Parameters

Vector3 v3	The Vector3 value representing the direction vector in local space based on the CFrame.

Return

Vector3	Returns the direction vector in world space calculated by applying the CFrame's rotation to the input direction vector.

Code Samples

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

VectorToObjectSpace

Converts a direction vector in world space to a direction vector in local space based on the CFrame. Only rotation is applied in this process; position shift is not reflected.

Parameters

Vector3 v3	The Vector3 value representing a direction in world space. The vector is converted to a local direction vector based on the CFrame.

Return

Vector3	Returns the direction vector in local space calculated by applying the CFrame's rotation to the provided direction vector.

Code Samples

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

ToEulerAnglesXYZ

Approximates and returns the rotation applied to the CFrame as angle values based on XYZ rotation order.

Parameters

Return

Tuple	Returns rotation angles for X-axis, Y-axis, and Z-axis in radians.

Code Samples

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

ToEulerAnglesYXZ

Approximates and returns the rotation applied to the CFrame as angle values based on YXZ rotation order.

Parameters

Return

Tuple	Returns rotation angles for X-axis, Y-axis, and Z-axis in radians.

Code Samples

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

ToOrientation

Returns the same result as calling ToEulerAnglesYXZ() and uses the same rotation order and calculation method.

Parameters

Return

Tuple	Returns rotation angles for X-axis, Y-axis, and Z-axis in radians.

Code Samples

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

See also

Coordinate System