CFrame¶
A data type that represents both a 3D position and orientation.
Description¶
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 and includes essential arithmetic operations for working with 3D data on Roblox.
-- Create a CFrame at a certain position and Euler rotation
local cf = CFrame.new(0, 5, 0) * CFrame.fromEulerAngles(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()). For more information on how the Roblox Engine performs
rotations, see RotationOrder.
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.
| XVector, RightVector | YVector, UpVector | ZVector, -LookVector† |
|---|---|---|
| R00 | R01 | R02 |
| R10 | R11 | R12 |
| R20 | R21 | R22 |
Datatype.CFrame.LookVector|LookVector represents the negated
column components. The Datatype.CFrame.LookVector|LookVector is
useful because many Class.Instance|Instances such as the
Class.Camera|Camera and Class.Attachment|Attachments
treat that vector as the direction the instance is pointing.Constructors¶
new Supported Returns a blank identity CFrame.
Returns a blank identity CFrame.
Creates an identity CFrame with position (0, 0, 0) and no
rotation (identity rotation matrix). This is equivalent to
CFrame.identity.
new Supported Returns a CFrame with no rotation with the position of the provided Vector3.
new Supported Returns a CFrame with the position of the first Vector3 and an orientation pointed toward the second.
Returns a CFrame with the position of the first Vector3 and an orientation pointed toward the second.
Returns a new CFrame located at pos and facing towards
lookAt, assuming that (0, 1, 0) is considered "up" in world space.
This constructor overload has been replaced by CFrame.lookAt(), which accomplishes a similar goal. It remains for the sake of backward compatibility.
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, use CFrame.fromMatrix() 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.
new Supported Returns a CFrame with a position comprised of the provided x, y, and z components.
new Supported Returns a CFrame from position (x, y, z) and quaternion (qX, qY, qZ, qW).
Returns a CFrame from position (x, y, z) and quaternion
(qX, qY, qZ, qW). The quaternion is expected to be of unit length
to represent a valid rotation. If this isn't the case, the quaternion will
be normalized.
new Supported Returns a CFrame from position (x, y, z) with an orientation specified by the rotation matrix.
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)
Returns a CFrame from position (x, y, z) with an
orientation specified by the rotation matrix.
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]]
lookAt Supported Returns a CFrame with the position of the first Vector3 and an orientation pointed toward the second.
lookAlong Not yet Returns a CFrame with the position of the first Vector3 and an orientation directed along the second.
Returns a CFrame with the position of the first Vector3 and an orientation directed along the second.
Returns a new CFrame with the position of at and facing along
direction, optionally specifying the upward direction (up) with a
default of (0, 1, 0).
This constructor is equivalent to CFrame.lookAt(at, at + direction).
fromRotationBetweenVectors Not yet Returns a CFrame representing the orientation needed to rotate from the first Vector3 to the second, with the position…
Returns a CFrame representing the orientation needed to rotate from the first Vector3 to the second, with the position set to zero.
Returns a CFrame whose rotation represents the shortest-arc
rotation that aligns vector from with vector to. The input vectors do
not need to be unit length; they are normalized internally. The resulting
CFrame has its position set to (0, 0, 0).
fromEulerAngles Not yet Returns a rotated CFrame from angles rx, ry, and rz in radians. Rotations are applied in the optional RotationOrder wit…
CFrame.fromEulerAngles(rx: number, ry: number, rz: number, order: RotationOrder = Enum.RotationOrder.XYZ)
Returns a rotated CFrame from angles rx, ry, and rz in
radians. Rotations are applied in the optional RotationOrder with a
default of XYZ, equivalent to:
local rx, ry, rz = math.rad(30), math.rad(45), math.rad(60)
local cframe = CFrame.fromEulerAngles(rx, 0, 0) -- X
* CFrame.fromEulerAngles(0, ry, 0) -- Y
* CFrame.fromEulerAngles(0, 0, rz) -- Z
local rx_out, ry_out, rz_out = cframe:ToEulerAnglesXYZ()
print(string.format("rx: %.2f, ry: %.2f, rz: %.2f", math.deg(rx_out), math.deg(ry_out), math.deg(rz_out))) --> rx: 30.00, ry: 45.00, rz: 60.00
fromEulerAnglesXYZ Supported Returns a rotated CFrame from angles rx, ry, and rz in radians using RotationOrder.XYZ.
Returns a rotated CFrame from angles rx, ry, and rz in
radians using RotationOrder.XYZ, equivalent to:
local rx, ry, rz = math.rad(30), math.rad(45), math.rad(60)
local cframe = CFrame.fromEulerAngles(rx, 0, 0) -- X
* CFrame.fromEulerAngles(0, ry, 0) -- Y
* CFrame.fromEulerAngles(0, 0, rz) -- Z
local rx_out, ry_out, rz_out = cframe:ToEulerAnglesXYZ()
print(string.format("rx: %.2f, ry: %.2f, rz: %.2f", math.deg(rx_out), math.deg(ry_out), math.deg(rz_out))) --> rx: 30.00, ry: 45.00, rz: 60.00
fromEulerAnglesYXZ Not yet Returns a rotated CFrame from angles rx, ry, and rz in radians using RotationOrder.YXZ.
Returns a rotated CFrame from angles rx, ry, and rz in
radians using RotationOrder.YXZ, equivalent to:
local rx, ry, rz = math.rad(30), math.rad(45), math.rad(60)
local cframe = CFrame.fromEulerAngles(0, ry, 0) -- Y
* CFrame.fromEulerAngles(rx, 0, 0) -- X
* CFrame.fromEulerAngles(0, 0, rz) -- Z
local rx_out, ry_out, rz_out = cframe:ToEulerAnglesYXZ()
print(string.format("rx: %.2f, ry: %.2f, rz: %.2f", math.deg(rx_out), math.deg(ry_out), math.deg(rz_out))) --> rx: 30.00, ry: 45.00, rz: 60.00
Angles Supported Equivalent to fromEulerAnglesXYZ().
Equivalent to fromEulerAnglesXYZ().
fromOrientation Not yet Equivalent to fromEulerAnglesYXZ().
Equivalent to fromEulerAnglesYXZ().
fromAxisAngle Supported Returns a rotated CFrame from a unit Vector3 and a rotation in radians.
Returns a rotated CFrame from a unit Vector3 and a rotation in radians.
Returns a CFrame rotated r radians around the axis v. The
axis vector is normalized internally, so it does not need to be unit
length. The resulting CFrame has no translation (position is
(0, 0, 0)). A positive angle represents a counter-clockwise rotation
when looking from the tip of the axis vector toward the origin (right-hand
rule).
fromMatrix Not yet Returns a CFrame from a translation and the columns of a rotation matrix.
Returns 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.
Constants¶
identity Not yet An identity CFrame with no translation or rotation.
Properties¶
identity Not yet An identity CFrame with no translation or rotation.
Position Not yet The 3D position of the CFrame.
Rotation Not yet A copy of the CFrame with no translation.
X Supported The X coordinate of the position.
The X coordinate of the position.
The X component of the CFrame object's world-space position.
Equivalent to CFrame.Position.X.
Y Supported The Y coordinate of the position.
The Y coordinate of the position.
The Y component of the CFrame object's world-space position.
Equivalent to CFrame.Position.Y.
Z Supported The Z coordinate of the position.
The Z coordinate of the position.
The Z component of the CFrame object's world-space position.
Equivalent to CFrame.Position.Z.
LookVector Supported The forward-direction component of the CFrame object's orientation, equivalent to the negated form of ZVector.
The forward-direction component of the CFrame object's orientation, equivalent to the negated ZVector or the negated third column of the rotation matrix.
local cf = CFrame.new(0, 0, 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()
print(cf.LookVector) --> (-0, -0, -1)
print(-cf.ZVector) --> (-0, -0, -1)
print(-R02, -R12, -R22) --> (-0 -0 -1)
Adding a CFrame object's LookVector to itself produces a CFrame moved forward in whichever direction it's facing by 1 unit.
RightVector Not yet The right-direction component of the CFrame object's orientation.
UpVector Not yet The up-direction component of the CFrame object's orientation.
XVector Not yet Equivalent to RightVector.
Equivalent to RightVector.
The X component of the CFrame object's orientation. Equivalent to RightVector or the first column of the rotation matrix.
YVector Not yet Equivalent to UpVector.
ZVector Not yet The Z component of the CFrame object's orientation. Equivalent to the third column of the rotation matrix.
The Z component of the CFrame object's orientation. Equivalent to the negated LookVector or the third column of the rotation matrix.
Methods¶
Inverse Supported Returns the inverse of the CFrame.
Returns the inverse of the CFrame.
Returns the inverse of the CFrame, representing the
transformation that undoes the original. For any CFrame cf,
the expression cf * cf:Inverse() produces the identity
CFrame. The inverse reverses both the rotation (transposing the
rotation matrix) and the translation.
Lerp Supported Returns a CFrame interpolated between itself and goal by the fraction alpha.
Returns a CFrame interpolated between itself and goal by the
fraction alpha. The positional component is interpolated linearly while
the rotational component is interpolated using spherical linear
interpolation (slerp), producing a constant-speed rotation along the
shortest arc. An alpha of 0 returns the original CFrame and
an alpha of 1 returns goal.
Orthonormalize Not yet Returns an orthonormalized copy of the CFrame.
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.
ToWorldSpace Supported Receives one or more CFrame objects and returns them transformed from object to world space.
Receives one or more CFrame objects and returns them transformed from object to world space. Equivalent to:
CFrame * cf
ToObjectSpace Supported Receives one or more CFrame objects and returns them transformed from world to object space.
Receives one or more CFrame objects and returns them transformed from world to object space. Equivalent to:
CFrame:Inverse() * cf
PointToWorldSpace Supported Receives one or more Vector3 objects and returns them transformed from object to world space.
Receives one or more Vector3 objects and returns them transformed from object to world space. Equivalent to:
CFrame * v3
PointToObjectSpace Supported Receives one or more Vector3 objects and returns them transformed from world to object space.
Receives one or more Vector3 objects and returns them transformed from world to object space. Equivalent to:
CFrame:Inverse() * v3
VectorToWorldSpace Supported Receives one or more Vector3 objects and returns them rotated from object to world space.
Receives one or more Vector3 objects and returns them rotated from object to world space. Equivalent to:
(CFrame - CFrame.Position) * v3
VectorToObjectSpace Supported Receives one or more Vector3 objects and returns them rotated from world to object space.
Receives one or more Vector3 objects and returns them rotated from world to object space. Equivalent to:
(CFrame:Inverse() - CFrame:Inverse().Position) * v3
GetComponents Not yet Returns the values x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, and R22, where x y z represent the position of the…
Returns the values x, y, z, R00, R01, R02, R10, R11,
R12, R20, R21, and R22, where x y z represent the position
of the CFrame and R00‑R22 represent its 3×3 rotation
matrix.
Returns the 12 numeric components of the CFrame as a tuple:
x, y, z (position), followed by R00, R01, R02, R10, R11,
R12, R20, R21, R22 (the 3×3 rotation matrix in row-major
order). This is the reverse of the 12-argument CFrame.new()
constructor.
ToEulerAngles Not yet Returns approximate angles that could be used to generate the CFrame using the optional RotationOrder.
Returns approximate angles that could be used to generate the
CFrame using the optional RotationOrder. If you don't
provide order, the method uses RotationOrder.XYZ.
ToEulerAnglesXYZ Supported Returns the approximate angles (in radians) that could be used to generate the CFrame using RotationOrder.XYZ.
Returns the approximate angles (in radians) that could be used to generate the CFrame using RotationOrder.XYZ.
Returns the approximate angles, in radians, that could be used to generate the CFrame using RotationOrder.XYZ. The three returned values represent rotations around the X, Y, and Z axes respectively. Due to the nature of Euler angle decomposition, the angles are approximate and subject to gimbal lock near pitch angles of ±90 degrees.
ToEulerAnglesYXZ Not yet Returns the approximate angles (in radians) that could be used to generate the CFrame using RotationOrder.YXZ.
Returns the approximate angles (in radians) that could be used to generate the CFrame using RotationOrder.YXZ.
Returns the approximate angles, in radians, that could be used to generate the CFrame using RotationOrder.YXZ. The three returned values represent rotations around the X, Y, and Z axes respectively. Due to the nature of Euler angle decomposition, the angles are approximate and subject to gimbal lock near pitch angles of ±90 degrees.
ToOrientation Not yet Returns the approximate angles (in radians) that could be used to generate the CFrame using the YXZ rotation order.
Returns the approximate angles (in radians) that could be used to generate the CFrame using the YXZ rotation order.
Returns the approximate angles, in radians, that could be used to generate the CFrame using RotationOrder.YXZ. Equivalent to CFrame.ToEulerAnglesYXZ().
ToAxisAngle Not yet Returns a tuple containing a unit Vector3 axis and a rotation angle in radians.
Returns a tuple containing a unit Vector3 axis and a rotation angle in radians.
Returns a unit Vector3 representing the axis of rotation and a number representing the angle of rotation in radians. A positive angle represents counter-clockwise rotation when looking from the tip of the axis vector toward the origin (right-hand rule). This is the inverse of CFrame.fromAxisAngle().
components Supported Equivalent to CFrame.GetComponents().
Equivalent to CFrame.GetComponents().
FuzzyEq Not yet Returns true if the other CFrame is sufficiently close to this CFrame in both position and rotation.
Returns true if the other CFrame is sufficiently close to
this CFrame in both position and rotation. The epsilon value
is used to control the tolerance for this similarity; this value is
optional and should be a small positive value if provided. The similarity
for position is component-wise while rotation uses a fast approximation of
the angle difference.
AngleBetween Not yet Returns the angle, in radians, between the orientation of one CFrame and another.
Math operations¶
* Check Produces a new CFrame representing the composition of the two CFrames.
Produces a new CFrame representing the composition of the two CFrames.
Composes two CFrame transformations, producing a new CFrame that applies the right operand's transform in the left operand's local space. This is equivalent to CFrame.ToWorldSpace() and is the standard way to combine translations and rotations.
* Check Produces a Vector3 transformed from object to world coordinates.
Produces a Vector3 transformed from object to world coordinates.
Transforms a Vector3 from the CFrame object's local (object) space into world space, applying both rotation and translation. Equivalent to CFrame.PointToWorldSpace().
+ Check Produces a CFrame translated in world space by the Vector3.
- Check Produces a CFrame translated in world space by the negative Vector3.
Nova binding inventory¶
| Library | Members |
|---|---|
Angles, fromAxisAngle, fromEulerAnglesXYZ, lookAt, new |
Inverse, X, Y, Z, components, inverse, lerp, lookVector, p, pointToObjectSpace, pointToWorldSpace, toEulerAnglesXYZ, toObjectSpace, toWorldSpace, vectorToObjectSpace, vectorToWorldSpace, x, y, z |
Roblox reference: CFrame