22 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

CFrame

The CFrame data type, short for coordinate frame, describes a 3D position and orientation. It is made up of a positional component and a rotational component and includes essential arithmetic operations for working with 3D data on Roblox.

-- Create a CFrame at a certain position and Euler rotation
local cf = CFrame.new(0, 5, 0) * CFrame.fromEulerAngles(math.rad(45), 0, 0)

For an introduction to the CFrame data type, see CFrames.

Positional Component

The positional component is available as a Vector3. In addition, the components of a CFrame object's position are also available in the X, Y and Z properties like a Vector3.

Rotational Component

CFrame stores 3D rotation data in a 3×3 rotation matrix. These values are returned by the CFrame:GetComponents() function after the x, y and z positional values. This matrix is used internally when doing calculations involving rotations, using radians as their unit (for conversion from one to the other, use math.rad() or math.deg()). For more information on how the Roblox Engine performs rotations, see RotationOrder.

The table below represents the components of a CFrame object's rotation matrix and their relationship with the available vector properties such as LookVector and RightVector. Although the individual components of the rotation matrix are rarely useful by themselves, the vector properties which derive from them are much more useful.

^† Unlike the others, Datatype.CFrame.LookVector|LookVector represents the negated column components. The Datatype.CFrame.LookVector|LookVector is useful because many Class.Instance|Instances such as the Class.Camera|Camera and Class.Attachment|Attachments treat that vector as the direction the instance is pointing.

Constructors

CFrame.new

Creates an identity CFrame with position (0, 0, 0) and no rotation (identity rotation matrix). This is equivalent to CFrame.identity.

CFrame.new

Returns a CFrame positioned at pos with no rotation (identity rotation matrix). The orientation defaults to the identity, meaning the local axes align with the world axes.

Parameters

CFrame.new

Returns a new CFrame located at pos and facing towards lookAt, assuming that (0, 1, 0) is considered "up" in world space.

This constructor overload has been replaced by CFrame.lookAt(), which accomplishes a similar goal. It remains for the sake of backward compatibility.

At high pitch angles (around 82 degrees), you may experience numerical instability. If this is an issue, or if you require a different "up" vector, use CFrame.fromMatrix() to more accurately construct the CFrame. Additionally, if lookAt is directly above pos (pitch angle of 90 degrees), the "up" vector switches to the X axis.

Parameters

CFrame.new

Returns a CFrame positioned at (x, y, z) with no rotation (identity rotation matrix). This is equivalent to CFrame.new(Vector3.new(x, y, z)).

Parameters

CFrame.new

Returns a CFrame from position (x, y, z) and quaternion (qX, qY, qZ, qW). The quaternion is expected to be of unit length to represent a valid rotation. If this isn't the case, the quaternion will be normalized.

Parameters

CFrame.new

Creates a CFrame from position (x, y, z) with an orientation specified by the rotation matrix.

[[R00 R01 R02] [R10 R11 R12] [R20 R21 R22]]

Parameters

CFrame.lookAt

Returns a new CFrame with the position of at and facing towards lookAt, optionally specifying the upward direction (up) with a default of (0, 1, 0).

Parameters

CFrame.lookAlong

Returns a new CFrame with the position of at and facing along direction, optionally specifying the upward direction (up) with a default of (0, 1, 0).

This constructor is equivalent to CFrame.lookAt(at, at + direction).

Parameters

CFrame.fromRotationBetweenVectors

Returns a CFrame whose rotation represents the shortest-arc rotation that aligns vector from with vector to. The input vectors do not need to be unit length; they are normalized internally. The resulting CFrame has its position set to (0, 0, 0).

-- Rotate a direction to face another direction
local from = Vector3.new(0, 1, 0)
local to = Vector3.new(1, 0, 0)
local cf = CFrame.fromRotationBetweenVectors(from, to)
print(cf * from) --> approximately (1, 0, 0)

Parameters

CFrame.fromEulerAngles

Returns a rotated CFrame from angles rx, ry, and rz in radians. Rotations are applied in the optional RotationOrder with a default of XYZ, equivalent to:

local rx, ry, rz = math.rad(30), math.rad(45), math.rad(60)
local cframe = CFrame.fromEulerAngles(rx, 0, 0) -- X
               * CFrame.fromEulerAngles(0, ry, 0) -- Y
               * CFrame.fromEulerAngles(0, 0, rz) -- Z
local rx_out, ry_out, rz_out = cframe:ToEulerAnglesXYZ()
print(string.format("rx: %.2f, ry: %.2f, rz: %.2f", math.deg(rx_out), math.deg(ry_out), math.deg(rz_out))) --> rx: 30.00, ry: 45.00, rz: 60.00

Parameters

CFrame.fromEulerAnglesXYZ

Returns a rotated CFrame from angles rx, ry, and rz in radians using RotationOrder.XYZ, equivalent to:

local rx, ry, rz = math.rad(30), math.rad(45), math.rad(60)
local cframe = CFrame.fromEulerAngles(rx, 0, 0) -- X
               * CFrame.fromEulerAngles(0, ry, 0) -- Y
               * CFrame.fromEulerAngles(0, 0, rz) -- Z
local rx_out, ry_out, rz_out = cframe:ToEulerAnglesXYZ()
print(string.format("rx: %.2f, ry: %.2f, rz: %.2f", math.deg(rx_out), math.deg(ry_out), math.deg(rz_out))) --> rx: 30.00, ry: 45.00, rz: 60.00

Parameters

CFrame.fromEulerAnglesYXZ

Returns a rotated CFrame from angles rx, ry, and rz in radians using RotationOrder.YXZ, equivalent to:

local rx, ry, rz = math.rad(30), math.rad(45), math.rad(60)
local cframe = CFrame.fromEulerAngles(0, ry, 0) -- Y
               * CFrame.fromEulerAngles(rx, 0, 0) -- X
               * CFrame.fromEulerAngles(0, 0, rz) -- Z
local rx_out, ry_out, rz_out = cframe:ToEulerAnglesYXZ()
print(string.format("rx: %.2f, ry: %.2f, rz: %.2f", math.deg(rx_out), math.deg(ry_out), math.deg(rz_out))) --> rx: 30.00, ry: 45.00, rz: 60.00

Parameters

CFrame.Angles

Equivalent to fromEulerAnglesXYZ().

Parameters

CFrame.fromOrientation

Equivalent to fromEulerAnglesYXZ().

Parameters

CFrame.fromAxisAngle

Returns a CFrame rotated r radians around the axis v. The axis vector is normalized internally, so it does not need to be unit length. The resulting CFrame has no translation (position is (0, 0, 0)). A positive angle represents a counter-clockwise rotation when looking from the tip of the axis vector toward the origin (right-hand rule).

-- Rotate 90 degrees around the Y axis
local cf = CFrame.fromAxisAngle(Vector3.yAxis, math.rad(90))

Parameters

CFrame.fromMatrix

Returns a CFrame from a translation and the columns of a rotation matrix. If vZ is excluded, the third column is calculated as vX:Cross(vY).Unit.

Parameters

Properties

CFrame.identity

An identity CFrame with no translation or rotation. This property is a constant and must be accessed globally as opposed to through an individual CFrame object.

CFrame.Position

The positional component of the CFrame as a Vector3. Equivalent to Vector3.new(cf.X, cf.Y, cf.Z).

CFrame.Rotation

A copy of the CFrame with the positional component set to (0, 0, 0), retaining only the rotational component. Useful for isolating a CFrame object's orientation independent of its position.

CFrame.X

The X component of the CFrame object's world-space position. Equivalent to CFrame.Position.X.

CFrame.Y

The Y component of the CFrame object's world-space position. Equivalent to CFrame.Position.Y.

CFrame.Z

The Z component of the CFrame object's world-space position. Equivalent to CFrame.Position.Z.

CFrame.LookVector

The forward-direction component of the CFrame object's orientation, equivalent to the negated ZVector or the negated third column of the rotation matrix.

local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

print(cf.LookVector)     --> (-0, -0, -1)
print(-cf.ZVector)       --> (-0, -0, -1)
print(-R02, -R12, -R22)  --> (-0 -0 -1)

Adding a CFrame object's LookVector to itself produces a CFrame moved forward in whichever direction it's facing by 1 unit.

CFrame.RightVector

The right-direction component of the CFrame object's orientation. Equivalent to XVector or the first column of the rotation matrix.

local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

print(cf.RightVector)  --> (1, 0, 0)
print(cf.XVector)      --> (1, 0, 0)
print(R00, R10, R20)   --> (1 0 0)

CFrame.UpVector

The up-direction component of the CFrame object's orientation. Equivalent to YVector or the second column of the rotation matrix.

local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

print(cf.UpVector)    --> (0, 1, 0)
print(cf.YVector)     --> (0, 1, 0)
print(R01, R11, R21)  --> (0 1 0)

CFrame.XVector

The X component of the CFrame object's orientation. Equivalent to RightVector or the first column of the rotation matrix.

local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

print(cf.XVector)      --> (1, 0, 0)
print(cf.RightVector)  --> (1, 0, 0)
print(R00, R10, R20)   --> (1 0 0)

CFrame.YVector

The Y component of the CFrame object's orientation. Equivalent to UpVector or the second column of the rotation matrix.

local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

print(cf.YVector)     --> (0, 1, 0)
print(cf.UpVector)    --> (0, 1, 0)
print(R01, R11, R21)  --> (0 1 0)

CFrame.ZVector

The Z component of the CFrame object's orientation. Equivalent to the negated LookVector or the third column of the rotation matrix.

local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

print(cf.ZVector)      --> (0, 0, 1)
print(-cf.LookVector)  --> (0, 0, 1)
print(R02, R12, R22)   --> (0 0 1)

Methods

CFrame:Inverse

Returns the inverse of the CFrame, representing the transformation that undoes the original. For any CFrame cf, the expression cf * cf:Inverse() produces the identity CFrame. The inverse reverses both the rotation (transposing the rotation matrix) and the translation.

Returns

CFrame:Lerp

Returns a CFrame interpolated between itself and goal by the fraction alpha. The positional component is interpolated linearly while the rotational component is interpolated using spherical linear interpolation (slerp), producing a constant-speed rotation along the shortest arc. An alpha of 0 returns the original CFrame and an alpha of 1 returns goal.

Parameters

Returns

CFrame:Orthonormalize

Returns an orthonormalized copy of the CFrame. The BasePart.CFrame property automatically applies orthonormalization, but other APIs which take CFrames do not, so this method is occasionally necessary when incrementally updating a CFrame and using it with them.

Returns

CFrame:ToWorldSpace

Receives one or more CFrame objects and returns them transformed from object to world space. Equivalent to:

CFrame * cf

local cf = CFrame.new(5, 10, 0)

local offset = CFrame.new(0, 2, 0)

-- Output world space of offset CFrame relative to calling CFrame
print(cf:ToWorldSpace(offset))  --> 5, 12, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1

Parameters

Returns

CFrame:ToObjectSpace

Receives one or more CFrame objects and returns them transformed from world to object space. Equivalent to:

CFrame:Inverse() * cf

Parameters

Returns

CFrame:PointToWorldSpace

Receives one or more Vector3 objects and returns them transformed from object to world space. Equivalent to:

CFrame * v3

local cf = CFrame.new(5, 10, 0)

-- Output core world space of the CFrame
print(cf:PointToWorldSpace())  --> 5, 10, 0
-- Output world space of a Vector3 (0, 4, 0) relative to the CFrame (object space)
print(cf:PointToWorldSpace(Vector3.new(0, 4, 0)))  --> 5, 14, 0

Parameters

Returns

CFrame:PointToObjectSpace

Receives one or more Vector3 objects and returns them transformed from world to object space. Equivalent to:

CFrame:Inverse() * v3

Parameters

Returns

CFrame:VectorToWorldSpace

Receives one or more Vector3 objects and returns them rotated from object to world space. Equivalent to:

(CFrame - CFrame.Position) * v3

Parameters

Returns

CFrame:VectorToObjectSpace

Receives one or more Vector3 objects and returns them rotated from world to object space. Equivalent to:

(CFrame:Inverse() - CFrame:Inverse().Position) * v3

Parameters

Returns

CFrame:GetComponents

Returns the 12 numeric components of the CFrame as a tuple: x, y, z (position), followed by R00, R01, R02, R10, R11, R12, R20, R21, R22 (the 3×3 rotation matrix in row-major order). This is the reverse of the 12-argument CFrame.new() constructor.

local cf = CFrame.new(1, 2, 3) * CFrame.fromEulerAnglesXYZ(0, math.rad(90), 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

Returns

CFrame:ToEulerAngles

Returns approximate angles that could be used to generate the CFrame using the optional RotationOrder. If you don't provide order, the method uses RotationOrder.XYZ.

Parameters

Returns

CFrame:ToEulerAnglesXYZ

Returns the approximate angles, in radians, that could be used to generate the CFrame using RotationOrder.XYZ. The three returned values represent rotations around the X, Y, and Z axes respectively. Due to the nature of Euler angle decomposition, the angles are approximate and subject to gimbal lock near pitch angles of ±90 degrees.

Returns

CFrame:ToEulerAnglesYXZ

Returns the approximate angles, in radians, that could be used to generate the CFrame using RotationOrder.YXZ. The three returned values represent rotations around the X, Y, and Z axes respectively. Due to the nature of Euler angle decomposition, the angles are approximate and subject to gimbal lock near pitch angles of ±90 degrees.

Returns

CFrame:ToOrientation

Returns the approximate angles, in radians, that could be used to generate the CFrame using RotationOrder.YXZ. Equivalent to CFrame:ToEulerAnglesYXZ().

Returns

CFrame:ToAxisAngle

Returns a unit Vector3 representing the axis of rotation and a number representing the angle of rotation in radians. A positive angle represents counter-clockwise rotation when looking from the tip of the axis vector toward the origin (right-hand rule). This is the inverse of CFrame.fromAxisAngle().

Returns

CFrame:components

Equivalent to CFrame:GetComponents().

Returns

CFrame:FuzzyEq

Returns true if the other CFrame is sufficiently close to this CFrame in both position and rotation. The epsilon value is used to control the tolerance for this similarity; this value is optional and should be a small positive value if provided. The similarity for position is component-wise while rotation uses a fast approximation of the angle difference.

Parameters

Returns

CFrame:AngleBetween

Returns the angle, in radians, between the orientation of one CFrame and another. This function does not take the position of either CFrame into account and only looks at the relative orientation.

Parameters

Returns

Constants

CFrame.identity

An identity CFrame with no translation or rotation. This property is a constant and must be accessed globally as opposed to through an individual CFrame object.

Operators

CFrame * CFrame (multiplication)

Composes two CFrame transformations, producing a new CFrame that applies the right operand's transform in the left operand's local space. This is equivalent to CFrame:ToWorldSpace() and is the standard way to combine translations and rotations.

CFrame * Vector3 (multiplication)

Transforms a Vector3 from the CFrame object's local (object) space into world space, applying both rotation and translation. Equivalent to CFrame:PointToWorldSpace().

CFrame + Vector3 (addition)

Produces a CFrame with its position offset by the Vector3 in world space. The orientation remains unchanged. Only the translational component is affected; rotation is preserved as-is.

CFrame - Vector3 (subtraction)

Produces a CFrame with its position offset by the negated Vector3 in world space. The orientation remains unchanged. Equivalent to CFrame + (-v).