CFrame
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.
RightVector | UpVector | –LookVector† | |
---|---|---|---|
XVector | R00 | R01 | R02 |
YVector | R10 | R11 | R12 |
ZVector | R20 | R21 | R22 |
† 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:
Operation | Description |
---|---|
CFrame * CFrame | Produces a new CFrame representing the composition of the two CFrames. |
CFrame * Vector3 | Produces a Vector3 transformed from object to world coordinates. |
CFrame + Vector3 | Produces a CFrame translated in world space by the Vector3. |
CFrame - Vector3 | Produces a CFrame translated in world space by the negative Vector3. |
Summary
Constructors
Properties
Methods
Returns a CFrame interpolated between itself and goal by the fraction alpha.
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.
Math Operations
Constructors
new
Properties
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
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)