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, 
Attachments and 
Cameras.
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[]
| 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 Z, X, Y order using the angles (
rx,ry,rz). CFrame.fromEulerAnglesXYZ(rx: number, ry: number, rz: number)CFrame.Angles- Creates a CFrame rotated around the three axes, relative to the CFrame, in Z, Y, X 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
vZis excluded, the third column is calculated asvX:Cross(vY).Unit. CFrame.lookAt(at: Vector3, lookAt: Vector3, up: Vector3)- Creates a CFrame with the position
atand facing towardslookAtwith the optional parameterupspecifying the upward direction.
Properties[]
- identity CFrame
- A CFrame with no translation or rotation. Note that this is a constant and must be accessed globally through the CFrame global, 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
goalby the fractionalpha. CFrame:Orthonormalize(): CFrame- Returns a CFrame that went through the Gram-Schmidt process.
CFrame:ToWorldSpace(cf: CFrame): CFrame- Returns a CFrame transformed from Object to World coordinates. Equivalent to
CFrame * cf. Also works with tuples. CFrame:ToObjectSpace(cf: CFrame): CFrame- Returns a CFrame transformed from World to Object coordinates. Equivalent to
CFrame:Inverse() * cf. Also works with tuples. CFrame:PointToWorldSpace(v3: Vector3): Vector3- Returns a Vector3 transformed from Object to World coordinates. Also works with tuples.
CFrame:PointToObjectSpace(v3: Vector3): Vector3- Returns a Vector3 transformed from World to Object coordinates. Also works with tuples.
CFrame:VectorToWorldSpace(v3: Vector3): Vector3- Returns a Vector3 rotated from Object to World coordinates. Also works with tuples.
CFrame:VectorToObjectSpace(v3: Vector3): Vector3- Returns a Vector3 rotated from World to Object coordinates. Also works with tuples.
CFrame:GetComponents(): TupleCFrame: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 Z, X, Y 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 Z, Y, X 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[]
- (originalCFrame)
- (endPos, endFocus)
- (modelCoord)
- (boundingBoxCFrame)
- (viewFrame)
- (viewFrame, hitFrame)
- (targetCFrame)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (cframe)
- (target)
- (target)
- (target)
- (cframe)
- (cframe)
- (rotation)
- (rotation)
- (innerTransform, outerTransform)
- (meshQueryTransform)
- (handleWorldCF, cameraWorldCF)
- (attachmentCF, handleCF)
- (innerTransform, outerTransform)
- (meshqueryTransform)
- (handleWorldCF, cameraWorldCF)
- (attachmentCF, handleCF)
- (cframe)
- (value)
- (cframe)
- (cframe)
- (value)
- (value)
- (value)
- (camera)
- (camera)
- (camera)
- (camera)
- (camera)
- (camera)
- (camera)
- (removed)
- (position) (removed)
- (removed)
- (cframe) (removed)
- (cframe) (removed)
- (removed)
- (target) (removed)
- (removed)
- (originalCFrame) (removed)
External links[]
- CFrames on the Roblox Creator Documentation
- CFrame data type on the Roblox Creator Documentation
| Basic Lua types | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Roblox types |
| ||||||||||||||||||||||||||
| API reference only | |||||||||||||||||||||||||||