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

 RightVector UpVector –LookVector† XVector R00 R10 R20 YVector R01 R11 R21 ZVector R02 R12 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 ) 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, ) 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, ) 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.