CFrame

Creates an identity CFrame with position (0, 0, 0) and no rotation (identity rotation matrix). This is equivalent to CFrame.identity.

Returns a CFrame positioned at pos with no rotation (identity rotation matrix). The orientation defaults to the identity, meaning the local axes align with the world axes.

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.

Returns a CFrame positioned at (x, y, z) with no rotation (identity rotation matrix). This is equivalent to CFrame.new(Vector3.new(x, y, z)).

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.

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]]

Returns a new CFrame with the position of at and facing towards lookAt, optionally specifying the upward direction (up) with a default of (0, 1, 0).

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

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

-- Rotate a direction to face another direction
local from = Vector3.new(0, 1, 0)
local to = Vector3.new(1, 0, 0)
local cf = CFrame.fromRotationBetweenVectors(from, to)
print(cf * from) --> approximately (1, 0, 0)

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

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

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

Equivalent to fromEulerAnglesXYZ().

Equivalent to fromEulerAnglesYXZ().

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

-- Rotate 90 degrees around the Y axis
local cf = CFrame.fromAxisAngle(Vector3.yAxis, math.rad(90))

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.

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.

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.

The positional component of the CFrame as a Vector3. Equivalent to Vector3.new(cf.X, cf.Y, cf.Z).

A copy of the CFrame with the positional component set to (0, 0, 0), retaining only the rotational component. Useful for isolating a CFrame object's orientation independent of its position.

The X component of the CFrame object's world-space position. Equivalent to CFrame.Position.X.

The Y component of the CFrame object's world-space position. Equivalent to CFrame.Position.Y.

The Z component of the CFrame object's world-space position. Equivalent to CFrame.Position.Z.

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.

The right-direction component of the CFrame object's orientation. Equivalent to XVector or the first 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.RightVector)  --> (1, 0, 0)
print(cf.XVector)      --> (1, 0, 0)
print(R00, R10, R20)   --> (1 0 0)

The up-direction component of the CFrame object's orientation. Equivalent to YVector or the second 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.UpVector)    --> (0, 1, 0)
print(cf.YVector)     --> (0, 1, 0)
print(R01, R11, R21)  --> (0 1 0)

The X component of the CFrame object's orientation. Equivalent to RightVector or the first 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.XVector)      --> (1, 0, 0)
print(cf.RightVector)  --> (1, 0, 0)
print(R00, R10, R20)   --> (1 0 0)

The Y component of the CFrame object's orientation. Equivalent to UpVector or the second 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.YVector)     --> (0, 1, 0)
print(cf.UpVector)    --> (0, 1, 0)
print(R01, R11, R21)  --> (0 1 0)

The Z component of the CFrame object's orientation. Equivalent to the negated LookVector or the 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.ZVector)      --> (0, 0, 1)
print(-cf.LookVector)  --> (0, 0, 1)
print(R02, R12, R22)   --> (0 0 1)

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.

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.

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.

Receives one or more CFrame objects and returns them transformed from object to world space. Equivalent to:

CFrame * cf

local cf = CFrame.new(5, 10, 0)

local offset = CFrame.new(0, 2, 0)

-- Output world space of offset CFrame relative to calling CFrame
print(cf:ToWorldSpace(offset))  --> 5, 12, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1

Receives one or more CFrame objects and returns them transformed from world to object space. Equivalent to:

CFrame:Inverse() * cf

Receives one or more Vector3 objects and returns them transformed from object to world space. Equivalent to:

CFrame * v3

local cf = CFrame.new(5, 10, 0)

-- Output core world space of the CFrame
print(cf:PointToWorldSpace())  --> 5, 10, 0
-- Output world space of a Vector3 (0, 4, 0) relative to the CFrame (object space)
print(cf:PointToWorldSpace(Vector3.new(0, 4, 0)))  --> 5, 14, 0

Receives one or more Vector3 objects and returns them transformed from world to object space. Equivalent to:

CFrame:Inverse() * v3

Receives one or more Vector3 objects and returns them rotated from object to world space. Equivalent to:

(CFrame - CFrame.Position) * v3

Receives one or more Vector3 objects and returns them rotated from world to object space. Equivalent to:

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

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.

local cf = CFrame.new(1, 2, 3) * CFrame.fromEulerAnglesXYZ(0, math.rad(90), 0)
local x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22 = cf:GetComponents()

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.

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.

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.

Returns the approximate angles, in radians, that could be used to generate the CFrame using RotationOrder.YXZ. Equivalent to CFrame:ToEulerAnglesYXZ().

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().

Equivalent to CFrame:GetComponents().

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.

Returns the angle, in radians, between the orientation of one CFrame and another. This function does not take the position of either CFrame into account and only looks at the relative orientation.