CFrame

This page is not a tutorial!
Here, you will find a technical description of the CFrame data type. To learn the basics in a friendly manner, see articles/Understanding CFrame|Understanding CFrames instead!

To learn more about CFrame math operations, beyond the basic descriptions covered on this page, see articles/CFrame Math Operations|CFrame Math Operations instead!

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

-- A canonical method of creating a CFrame at a certain position and Euler rotation (XYZ).
local cf = CFrame.new(0, 5, 0) * CFrame.Angles(math.rad(45), 0, 0)

The CFrameValue object can be used to store exactly one CFrame value in a Roblox object.

Components

Positional

The positional component is available as a datatype/Vector3 in the Position property. In addition, the components of a CFrame’s position are also available in the X, Y and Z properties like a Vector3. A CFrame placed at a specific position without any rotation can be constructed using CFrame.new(Vector3) or CFrame.new(X, Y, Z).

Rotational

CFrame stores 3D rotation data in a 3-by-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. They use radians as their unit (for conversion to degrees, use math.rad/math.deg).

The matrix below represents the components of a CFrame’s rotation matrix and their relationship with the various vector properties available (LookVector, RightVector, etc). Although the individual components of the rotation matrix are rarely useful by themselves, the vector properties which derive from them are much more useful.

	RightVector	UpVector	–LookVector^†
XVector	R00	R01	R02
YVector	R10	R11	R12
ZVector	R20	R21	R22

†Unlike RightVector and UpVector, LookVector represents the negated right/third column components.

Constructors

CFrame.new ( )
Creates a blank identity CFrame.

CFrame.new ( Vector3 pos )
Returns a CFrame with no rotation with the position of the provided Vector3.

CFrame.new ( Vector3 pos, Vector3 lookAt )
This constructor overload has been replaced by `CFrame.lookAt`, which accomplishes a similar goal. It remains for the sake of backward compatibility. Creates a new CFrame located at `pos` and facing towards `lookAt`, assuming that (0, 1, 0) is considered “up”. 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, it’s recommended you use `CFrame.fromMatrix` instead 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.

CFrame.new ( number x, number y, number z )
Creates a CFrame from position (x, y, z).

CFrame.new ( number x, number y, number z, number qX, number qY, number qZ, number qW )
Creates a CFrame from position (x, y, z) and quaternion (qX, qY, qZ, qW).

CFrame.new ( number x, number y, number z, number R00, number R01, number R02, number R10, number R11, number R12, number R20, number R21, number R22 )
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]].

CFrame.lookAt ( Vector3 at, Vector3 lookAt, Vector3 up = Vector3.new(0, 1, 0) )
Creates a new CFrame located at `at` and facing towards `lookAt`, optionally specifying the upward direction (by default, (0, 1, 0)). This function replaces the `CFrame.new(Vector3, Vector3)` constructor (see above) which accomplished a similar task. This function allows you to specify the `up` Vector, using the same default as the old constructor.

CFrame.fromEulerAnglesXYZ ( number rx, number ry, number rz )
Creates a rotated CFrame using angles (rx, ry, rz) in radians. Rotations are applied in Z, Y, X order.

CFrame.fromEulerAnglesYXZ ( number rx, number ry, number rz )
Creates a rotated CFrame using angles (rx, ry, rz) in radians. Rotations are applied in Y, X, Z order.

CFrame.Angles ( number rx, number ry, number rz )
Equivalent to fromEulerAnglesXYZ.

CFrame.fromOrientation ( number rx, number ry, number rz )
Equivalent to fromEulerAnglesYXZ.

CFrame.fromAxisAngle ( Vector3 v, number r )
Creates a rotated CFrame from a Unit Vector3 and a rotation in radians.

CFrame.fromMatrix ( Vector3 pos, Vector3 vX, Vector3 vY, Vector3 vZ )
Creates 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].

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 will occasionally be necessary when when incrementally updating a CFrame and using it with them.

Properties

CFrame CFrame.identity
An identity CFrame, one with no translation or rotation. This API member is a constant, and must be accessed through the `CFrame` global as opposed to an individual `CFrame` object. print(CFrame.identity) --> 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1

Vector3 CFrame.Position
The 3D position of the CFrame.

CFrame CFrame.Rotation
A copy of the CFrame with no translation.

number CFrame.X
The x-coordinate of the position.

number CFrame.Y
The y-coordinate of the position.

number CFrame.Z
The z-coordinate of the position.

Vector3 CFrame.LookVector
The forward-direction component of the CFrame’s orientation. Equivalent to: `Vector3.new(-r20, -r21, -r22)`. Adding a CFrame’s LookVector to itself would produce a CFrame moved forward in whichever direction the CFrame is facing by 1 unit: cf = cf + cf.LookVector * n -- Move cf forward n units

Vector3 CFrame.RightVector
The right-direction component of the CFrame’s orientation. Equivalent to the first/left column of the rotation matrix, or `Vector3.new(r00, r01, r02)`.

Vector3 CFrame.UpVector
The up-direction component of the CFrame’s orientation. Equivalent to the second/middle column of the rotation matrix, or `Vector3.new(r01, r11, r12)`.

Vector3 CFrame.XVector
Equivalent to the first column of the rotation matrix, or `Vector3.new(r00, r01, r02)`.

Vector3 CFrame.YVector
Equivalent to the second/middle column of the rotation matrix, or `Vector3.new(r10, r11, r12)`.

Vector3 CFrame.ZVector
Equivalent to the third/bottom row of the rotation matrix, or `Vector3.new(r20, r21, r22)`.

Functions

CFrame CFrame:Inverse ( )
Returns the inverse of the CFrame.

CFrame CFrame:Lerp ( CFrame goal, number alpha )
Returns a CFrame interpolated between this CFrame and the goal by the fraction alpha.

CFrame CFrame:ToWorldSpace ( CFrame cf )
Returns a CFrame transformed from Object to World space. Equivalent to [CFrame * cf].

CFrame CFrame:ToObjectSpace ( CFrame cf )
Returns a CFrame transformed from World to Object space. Equivalent to [CFrame:inverse() * cf].

Vector3 CFrame:PointToWorldSpace ( Vector3 v3 )
Returns a Vector3 transformed from Object to World space. Equivalent to [CFrame * v3].

Vector3 CFrame:PointToObjectSpace ( Vector3 v3 )
Returns a Vector3 transformed from World to Object space. Equivalent to [CFrame:inverse() * v3].

Vector3 CFrame:VectorToWorldSpace ( Vector3 v3 )
Returns a Vector3 rotated from Object to World space. Equivalent to [(CFrame - CFrame.p) *v3].

Vector3 CFrame:VectorToObjectSpace ( Vector3 v3 )
Returns a Vector3 rotated from World to Object space. Equivalent to [(CFrame:inverse() - CFrame:inverse().p) * v3].

Tuple CFrame:GetComponents ( )
Returns the values: x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22, where R00-R22 represent the 3x3 rotation matrix of the CFrame, and xyz represent the position of the CFrame.

number , number , number CFrame:ToEulerAnglesXYZ ( )
Returns approximate angles that could be used to generate the CFrame, if angles were applied in Z, Y, X order.

number , number , number CFrame:ToEulerAnglesYXZ ( )
Returns approximate angles that could be used to generate the CFrame, if angles were applied in Z, X, Y order.

number , number , number CFrame:ToOrientation ( )
Returns approximate angles that could be used to generate the CFrame, if angles were applied in Z, X, Y order. Equivalent to toEulerAnglesYXZ.

Vector3 , number CFrame:ToAxisAngle ( )
Returns a tuple of a Vector3 and a number which represent the rotation of the CFrame in the axis-angle representation.

Tuple CFrame:components ( )
Returns all 12 numerical components of the CFrame in the following order: x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22 = cf:components() (See the Rotational Component section above)

Math Operations

CFrame *CFrame CFrame**
Returns the composition of two CFrames. Proceeding CFrames are offset in relative object space by preceding CFrames when multiplied together.

Vector3 *CFrame Vector3**
Returns the Vector3 transformed from Object to World coordinates.

CFrame CFrame + Vector3
Returns the CFrame translated in world space by the Vector3.

CFrame CFrame - Vector3
Returns the CFrame translated in world space by the negative Vector3.