CFrame

A CFrame, short for Coordinate Frame, is a data type used to rotate and position 3D objects. As either an object property or a standalone unit, a CFrame contains global X, Y, and Z coordinates as well as rotation data for each axis. In addition, CFrames contain helpful functions for working with objects in the 3D space.

If you’re new to CFrames, please see the articles/Understanding CFrame|Understanding CFrames article.

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 CFrame located at pos with it’s lookVector pointing towards the lookAt position.

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 Z, X, Y 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].

Properties

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.

Vector3 CFrame.RightVector
The right-direction component of the CFrame’s orientation.

Vector3 CFrame.UpVector
The up-direction component of the CFrame’s orientation.

Vector3 CFrame.Position
The 3D position of the CFrame

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

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.