CFrame

Show Deprecated

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. It includes essential arithmetic operations for working with 3D data on Roblox.


-- Create a CFrame at a certain position and Euler rotation (XYZ).
local cf = CFrame.new(0, 5, 0) * CFrame.fromEulerAnglesXYZ(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()).

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.

RightVectorUpVector–LookVector
XVectorR00R01R02
YVectorR10R11R12
ZVectorR20R21R22

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

Math Operations

The following math operations are valid for the CFrame data type:

OperationDescription
CFrame * CFrameProduces a new CFrame representing the composition of the two CFrames.
CFrame * Vector3Produces a Vector3 transformed from object to world coordinates.
CFrame + Vector3Produces a CFrame translated in world space by the Vector3.
CFrame - Vector3Produces a CFrame translated in world space by the negative Vector3.

Summary

Constructors

new()  

new(pos: Vector3)  

new(pos: Vector3, lookAt: Vector3)  

new(x: number, y: number, z: number)  

new(x: number, y: number, z: number, qX: number, qY: number, qZ: number, qW: number)  

new(x: number, y: number, z: number, R00: number, R01: number, R02: number, R10: number, R11: number, R12: number, R20: number, R21: number, R22: number)  

lookAt(at: Vector3, lookAt: Vector3, up: Vector3)  

Angles(rx: number, ry: number, rz: number)  

fromOrientation(rx: number, ry: number, rz: number)  

fromMatrix(pos: Vector3, vX: Vector3, vY: Vector3, vZ: Vector3)  

Properties

An identity CFrame with no translation or rotation.

The 3D position of the CFrame.

A copy of the CFrame with no translation.

The X coordinate of the position.

The Y coordinate of the position.

The Z coordinate of the position.

The forward-direction component of the CFrame object's orientation.

The right-direction component of the CFrame object's orientation.

The up-direction component of the CFrame object's orientation.

Equivalent to the first row of the rotation matrix.

Equivalent to the second/middle row of the rotation matrix.

Equivalent to the third/bottom row of the rotation matrix.

Methods


Returns the inverse of the CFrame.

Lerp(goal: CFrame, alpha: number): CFrame  

Returns a CFrame interpolated between itself and goal by the fraction alpha.


Returns an orthonormalized copy of the CFrame.


Returns a CFrame transformed from object to world space.


Returns a CFrame transformed from world to object space.


Returns a Vector3 transformed from object to world space.


Returns a Vector3 transformed from world to object space.


Returns a Vector3 rotated from object to world space.


Returns a Vector3 rotated from world to object space.


Returns the values x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 where R00-R22 represent the 3×3 rotation matrix of the CFrame, and x y z represent its position.


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


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


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


Returns a tuple of a Vector3 and a number which represent the rotation of the CFrame in the axis-angle representation.

Math Operations

*  

*  

+  

-  

Constructors

new

new

Parameters

pos: Vector3

new

Parameters

pos: Vector3
lookAt: Vector3

new

Parameters

new

Parameters

new

Parameters

R00: number
R01: number
R02: number
R10: number
R11: number
R12: number
R20: number
R21: number
R22: number

lookAt

Parameters

lookAt: Vector3
Default Value: Vector3.new(0, 1, 0)

fromEulerAnglesXYZ

Parameters

rx: number
ry: number
rz: number

fromEulerAnglesYXZ

Parameters

rx: number
ry: number
rz: number

Angles

Parameters

rx: number
ry: number
rz: number

fromOrientation

Parameters

rx: number
ry: number
rz: number

fromAxisAngle

Parameters

fromMatrix

Parameters

Properties

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.


print(CFrame.identity) --> 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1

Position

The 3D position of the CFrame.

Rotation

A copy of the CFrame with no translation.

The X coordinate of the position.

The Y coordinate of the position.

The Z coordinate of the position.

LookVector

The forward-direction component of the CFrame object's orientation. Equivalent to:

Vector3.new(-r02, -r12, -r22)

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


cf = cf + cf.LookVector * n -- Move CFrame forward "n" units

RightVector

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

Vector3.new(r00, r10, r20)

UpVector

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

Vector3.new(r01, r11, r21)

XVector

Equivalent to the first row of the rotation matrix, or:

Vector3.new(r00, r01, r02)

YVector

Equivalent to the second/middle row of the rotation matrix, or:

Vector3.new(r10, r11, r12)

ZVector

Equivalent to the third/bottom row of the rotation matrix, or:

Vector3.new(r20, r21, r22)

Methods

Inverse

Returns the inverse of the CFrame.

Returns

Lerp

Returns a CFrame interpolated between itself and goal by the fraction alpha.

Parameters

goal: CFrame
alpha: number

Returns

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

ToWorldSpace

Returns a CFrame transformed from object to world space. Equivalent to:

CFrame * cf

Parameters

cf: CFrame

Returns

ToObjectSpace

Returns a CFrame transformed from world to object space. Equivalent to:

CFrame:Inverse() * cf

Parameters

cf: CFrame

Returns

PointToWorldSpace

Returns a Vector3 transformed from object to world space. Equivalent to:

CFrame * v3

Parameters

Returns

PointToObjectSpace

Returns a Vector3 transformed from world to object space. Equivalent to:

CFrame:Inverse() * v3

Parameters

Returns

VectorToWorldSpace

Returns a Vector3 rotated from object to world space. Equivalent to:

(CFrame - CFrame.Position) * v3

Parameters

Returns

VectorToObjectSpace

Returns a Vector3 rotated from world to object space. Equivalent to:

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

Parameters

Returns

GetComponents

Returns the values x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 where R00-R22 represent the 3×3 rotation matrix of the CFrame, and x y z represent its position.

Returns

ToEulerAnglesXYZ

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

ToEulerAnglesYXZ

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

ToOrientation

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

ToAxisAngle

Returns a tuple of a Vector3 and a number which represent the rotation of the CFrame in the axis-angle representation.

components

Equivalent to CFrame:GetComponents().

Returns

Math Operations