PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar

CFrame

CFrame

This page isn’t a tutorial! Here, you will find a technical description of the CFrame data type. To learn the basics in friendly manner, see articles/Understanding CFrame|Understanding CFrames 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.

RightVectorUpVector–LookVector
XVectorR00R10R20
YVectorR01R11R21
ZVectorR02R12R22

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

Constructors

CFrame.new ( )

Creates a blank identity CFrame.

CFrame.new ( Vector3 pos )

Creates a CFrame from a Vector3

CFrame.new ( Vector3 pos, Vector3 lookAt )

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.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].


Finding a LookAt Vector

This example uses DataType/CFrame|CFrame.fromMatrix() to create a CFrame located at eye with it’s lookVector pointing towards the target position.

Properties

Vector3 CFrame.Position

The 3D position of the CFrame

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(-r02, -r12, -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, r10, r20)

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, r21)

Vector3 CFrame.XVector

Equivalent to the first/top row of the rotation matrix, or Vector3.new(r00, r10, r20)

Vector3 CFrame.YVector

Equivalent to the second/middle row of the rotation matrix, or Vector3.new(r01, r11, r21)

Vector3 CFrame.ZVector

Equivalent to the third/bottom row of the rotation matrix, or Vector3.new(r02, r12, r22)

Functions

CFrame CFrame:Inverse ( )

Returns the inverse of this 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 CFrame, if angles were applied in Z, Y, X order

number , number , number CFrame:ToEulerAnglesYXZ ( )

Returns approximate angles that could be used to generate CFrame, if angles were applied in Z, X, Y order

number , number , number CFrame:ToOrientation ( )

Returns approximate angles that could be used to generate 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.