Roblox Wiki
Roblox Wiki
Roblox Wiki
38,933
pages
in: Roblox types, Reference types

CFrame

View source

The CFrame data type, short for coordinate frame, contains 3D positional and rotational data. It has two components: the positional component (X, Y, Z) and the rotational component (R00, R01, R02, R10 ... R21, R22). Unlike Vector3 which is used to represent rotations as Euler angles, CFrame's rotational component uses a 3×3 rotation matrix. CFrames also offer more functionality that deals with rotations than Vector3.

Usage[]

CFrame, along with Vector3, is used by properties in Roblox API that determine the location and orientation of objects, such as parts, Attachment light iconAttachment dark iconAttachments and Camera light iconCamera dark iconCameras.

To avoid gimbal lock, CFrame is preferred over Vector3 or other representations of Euler angles because CFrames use a rotation matrix which does not encounter gimbal lock.

Data type[]

Rotation matrix components
RightVector UpVector -LookVector
XVector R00 R01 R02
YVector R10 R11 R12
ZVector R20 R21 R22

Constructors[]

There are many constructors for CFrame. Constructors that take angle parameters uses radians, not degrees. Constructors also take other forms of rotation besides Euler angles and rotation matrix: axis-angle, and quaternion.

CFrame.new()
Creates an identity CFrame.
CFrame.new(v: Vector3)
Creates CFrame from the position of the Vector3 v.
CFrame.new(x: number, y: number, z: number)
Creates CFrame from the coordinates (x, y, z).
CFrame.new(x: number, y: number, z: number, qX: number, qY: number, qZ: number, qW: number)
Creates CFrame from position (x, y, z) and quaternion (qX, qY, qZ, qW).
CFrame.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)
Creates CFrame from position (x, y, z) and rotation matrix (R00, R01, R02, R10, R11, R12, R20, R21, R22).
CFrame.fromEulerAnglesYXZ(rx: number, ry: number, rz: number)
CFrame.fromOrientation
Creates a CFrame rotated around the three axes, relative to the CFrame, in Y, X, Z order using the angles (rx, ry, rz).
CFrame.fromEulerAnglesXYZ(rx: number, ry: number, rz: number)
CFrame.Angles(rx: number, ry: number, rz: number)
Creates a CFrame rotated around the three axes, relative to the CFrame, in X, Y, Z order using the angles (rx, ry, rz).
CFrame.fromEulerAngles(rx: number, ry: number, rz: number, order: Enum.RotationOrder)
Creates a CFrame rotated around the three axes, relative to the CFrame, in the specified order using the angles (rx, ry, rz)
CFrame.fromAxisAngle(v: Vector3, r: number)
Creates a rotated CFrame from a unit vector and a rotation in radians.
CFrame.fromMatrix(pos: Vector3, vX: Vector3, vY: Vector3, vZ: Vector3)
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.fromRotationBetweenVectors(from: Vector3, to: Vector3)
Creates a CFrame that represents the rotation needed to rotate from from to to, given a position of zero.
CFrame.lookAt(at: Vector3, lookAt: Vector3, up: Vector3)
Creates a CFrame with the position at and facing towards lookAt with the optional parameter up specifying the upward direction.
CFrame.lookAlong(at: Vector3, direction: Vector3, up: Vector3)
Creates a CFrame with the position at and facing along direction with the optional parameter up specifying the upward direction. This is equivalent to CFrame.lookAt(at, at + direction, up).

Properties[]

identity CFrame
A CFrame with no translation or rotation. Note that this is a constant and must be accessed through the CFrame global, and not a CFrame object itself.
Position Vector3
The positional component of the CFrame.
Rotation CFrame
A copy of the CFrame with no translation.
X number
The positional component of the CFrame on the X axis.
Y number
The positional component of the CFrame on the Y axis.
Z number
The positional component of the CFrame on the Z axis.
LookVector Vector3
The front-facing directional vector of the CFrame.
RightVector Vector3
The right-facing directional vector of the CFrame.
UpVector Vector3
The up-facing directional vector of the CFrame.
XVector Vector3
The first column in the rotation matrix of the CFrame.
YVector Vector3
The second column in the rotation matrix of the CFrame.
ZVector Vector3
The third column in the rotation matrix of the CFrame.

Methods[]

There are many methods of CFrame that can be used instead of having to calculate the results. Some methods of CFrame use the terms World and Object, both of which are used to distinguish positional data that is a vector of the place's origin ("World") from other positional data that is a vector of another position ("Object"). Some other methods convert the CFrame's rotational data to other forms of rotational data: the components of its rotation matrix, Euler angles or axis-angle.

CFrame:Inverse(): CFrame
Returns the inverse of the CFrame.
CFrame:Lerp(goal: CFrame, alpha: number): CFrame
Returns a CFrame interpolated between itself and goal by the fraction alpha.
CFrame:Orthonormalize(): CFrame
Returns a CFrame that went through the Gram-Schmidt process. It returns a CFrame that is a copy of the original CFrame, except that it ensures each Vector3 representing the rotation matrix is orthagonal the others, and has a length of one stud.
CFrame:ToWorldSpace(...: CFrame): ...CFrame
Returns the CFrames transformed from Object to World coordinates. Equivalent to CFrame * cf.
CFrame:ToObjectSpace(...: CFrame): ...CFrame
Returns the CFrames transformed from World to Object coordinates. Equivalent to CFrame:Inverse() * cf.
CFrame:PointToWorldSpace(...: Vector3): ...Vector3
Returns the Vector3s transformed from Object to World coordinates.
CFrame:PointToObjectSpace(...: Vector3): ...Vector3
Returns the Vector3s transformed from World to Object coordinates.
CFrame:VectorToWorldSpace(...: Vector3): ...Vector3
Returns the Vector3s rotated from Object to World coordinates.
CFrame:VectorToObjectSpace(...: Vector3): ...Vector3
Returns the Vector3s rotated from World to Object coordinates.
CFrame:GetComponents(): Tuple
CFrame:components
Returns all components of the CFrame in the following order: x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22.
CFrame:ToEulerAnglesYXZ(): (number, number, number)
CFrame:ToOrientation
Returns approximate angles of the part's orientation that could be used to generate the CFrame by applying the angles in Y, X, Z order.
CFrame:ToEulerAnglesXYZ(): (number, number, number)
Returns approximate angles of the part's orientation that could be used to generate the CFrame by applying the angles in X, Y, Z order.
CFrame:ToAxisAngle(cf: CFrame)
Returns the orientation of the CFrame in axis-angle representation.

Operators[]

CFrame * CFrame: CFrame
Returns composition of two CFrames.
CFrame * Vector3: Vector3
Returns Vector3 transformed from Object to World coordinates.
CFrame + Vector3: CFrame
Returns CFrame translated by Vector3.
CFrame - Vector3: CFrame
Returns CFrame translated by -Vector3.

Referenced by[]


External links[]


Data types
Basic Lua types
nil · boolean · number · string · function · userdata · thread · table
Roblox types
Colors
BrickColor · Color3 · ColorSequence · ColorSequenceKeypoint
Sequences
NumberSequence · NumberSequenceKeypoint
Events
RBXScriptSignal · RBXScriptConnection
Vectors
Vector2 · Vector3 · Vector2int16 · Vector3int16
Instances
Instance
Internal types
BinaryString · ContentId · ProtectedString · QDir · QFont
Other types
Axes · CatalogSearchParams · CFrame · DateTime · DockWidgetPluginGuiInfo · Enum · Faces · FloatCurveKey · NumberRange · OverlapParams · Path2DControlPoint · PathWaypoint · PhysicalProperties · Random · Ray · RaycastParams · RaycastResult · RbxLibrary · Rect · Region3 · Region3int16 · RotationCurveKey · Secret · SecurityCapabilities · SharedTable · StamperController · TweenInfo · UDim · UDim2 · UniqueId
API reference only
double · float · int · int64 · void · Tuple · Variant
Community content is available under CC-BY-SA unless otherwise noted.