CFrame

CFrame

Overview

Description

CFrame is a class in Roblox frequently used to represent position and orientation in 3D space.

Properties

identity

CFrame identity returns the identity matrix, which represents a position at (0, 0, 0) with no rotation.

Code Samples

local cf = CFrame.identity
print(cf)

Position

Vector3 Position returns the position of the CFrame as a Vector3.

Code Samples

local cf = CFrame.new(1, 2, 3)
print(cf.Position)  -- Output: (1, 2, 3)

Orientation

Vector3 Orientation returns the rotation of the CFrame as a Vector3 in terms of yaw, pitch, and roll.

Code Samples

local cf = CFrame.fromOrientation(math.rad(30), math.rad(45), math.rad(60))
print(cf.Orientation)

Rotation

Vector3 Represents the rotational matrix based on a 3x3 rotation.

Code Samples

local cf = CFrame.Angles(math.pi/2, 0, 0)
print(cf.Rotation)

X

number Returns the X coordinate of the CFrame.

Code Samples

local cf = CFrame.new(4, 5, 6)
print(cf.X)  -- Output: 4

Y

number Returns the Y coordinate of the CFrame.

Code Samples

local cf = CFrame.new(4, 5, 6)
print(cf.Y)  -- Output: 5

Z

number Returns the Z coordinate of the CFrame.

Code Samples

local cf = CFrame.new(4, 5, 6)
print(cf.Z)  -- Output: 6

XVector

Vector3 Returns the X axis vector of the CFrame.

Code Samples

local cf = CFrame.new()
print(cf.XVector)

YVector

Vector3 Returns the Y axis vector of the CFrame.

Code Samples

local cf = CFrame.new()
print(cf.YVector)

ZVector

Vector3 Returns the Z axis vector of the CFrame.

Code Samples

local cf = CFrame.new()
print(cf.ZVector)

LookVector

Vector3 Indicates the direction the camera is facing, based on the Z-axis.

Code Samples

local cf = CFrame.new()
print(cf.LookVector)

RightVector

Vector3 Indicates the camera's right-hand direction.

Code Samples

local cf = CFrame.new()
print(cf.RightVector)

UpVector

Vector3 Indicates the camera's upward direction.

Code Samples

local cf = CFrame.new()
print(cf.UpVector)

Constructors

new

Creates a basic CFrame object.

Parameters

None

Return

CFrame	A `CFrame` object

Code Samples

local cf = CFrame.new()
print(cf)

new

Creates a CFrame object using a Vector3 position.

Parameters

Vector3 Position	Position for the CFrame object

Return

CFrame	A `CFrame` object

Code Samples

local position = Vector3.new(1, 2, 3)
local cf = CFrame.new(position)
print(cf)

new

Creates a CFrame object using position and a look vector.

Parameters

Vector3 Position	The position of the CFrame.
Vector3 Look	The direction it is facing.

Return

CFrame	A `CFrame` object

Code Samples

local position = Vector3.new(1, 2, 3)
local lookAt = Vector3.new(0, 1, 0)
local cf = CFrame.new(position, lookAt)
print(cf)

new

Creates a CFrame using X, Y, and Z coordinates.

Parameters

number x	X coordinate
number y	Y coordinate
number z	Z coordinate

Return

CFrame	A `CFrame` object

Code Samples

local cf = CFrame.new(1, 2, 3)
print(cf)

lookAt

Generates a CFrame that points towards a target from a given position.

Parameters

Vector3 at	The position where the CFrame is located.
Vector3 lookAt	The position the CFrame should face.
Vector3 up	The up direction from the position.

Return

CFrame	A new CFrame oriented towards the lookAt point.

Code Samples

local cframe = CFrame.lookAt(Vector3.new(0, 0, 0), Vector3.new(1, 1, 1))

fromEulerAnglesXYZ

Creates a CFrame from Euler angles (in radians) using the XYZ rotation order.

Parameters

number rx	Rotation around the X-axis.
number ry	Rotation around the Y-axis.
number rz	Rotation around the Z-axis.

Return

CFrame	A new CFrame with the specified rotations.

Code Samples

local cframe = CFrame.fromEulerAnglesXYZ(1, 0.5, 0.25)

Angles

Creates a CFrame from Euler angles (in radians).

Parameters

number rx	Rotation around the X-axis.
number ry	Rotation around the Y-axis.
number rz	Rotation around the Z-axis.

Return

CFrame	A new CFrame with the specified rotations.

Code Samples

local cframe = CFrame.Angles(math.rad(90), math.rad(45), math.rad(30))

fromEulerAnglesYXZ

Creates a CFrame from Euler angles (in radians) using the YXZ rotation order.

Parameters

number rx	Rotation around the X-axis.
number ry	Rotation around the Y-axis.
number rz	Rotation around the Z-axis.

Return

CFrame	A new CFrame with the specified rotations.

Code Samples

local cframe = CFrame.fromEulerAnglesYXZ(1, 0.5, 0.25)

fromOrientation

Creates a CFrame from Euler angles (in radians) using XYZ orientation.

Parameters

number rx	Rotation around the X-axis.
number ry	Rotation around the Y-axis.
number rz	Rotation around the Z-axis.

Return

CFrame	A new CFrame with the specified rotations.

Code Samples

local cframe = CFrame.fromOrientation(1, 0.5, 0.25)

FromMatrix

Creates a CFrame from a position and three directional vectors.

Parameters

Vector3 pos	The position of the CFrame.
Vector3 vx	The X direction vector.
Vector3 vy	The Y direction vector.
Vector3 vz	The Z direction vector.

Return

CFrame	A new CFrame defined by the given position and vectors.

Code Samples

local cframe = CFrame.FromMatrix(Vector3.new(0, 0, 0), Vector3.new(1, 0, 0), Vector3.new(0, 1, 0), Vector3.new(0, 0, 1))

Methods

Inverse

Returns the inverse of the CFrame.

Parameters

None

Return

CFrame	The inverse `CFrame`.

Code Samples

local cf = CFrame.new(0, 5, 0)
local inverseCf = cf:Inverse()

Lerp

Interpolates between the current CFrame and the goal CFrame by the percentage alpha.

Parameters

CFrame goal	The target `CFrame` to interpolate toward.
number alpha	The weight for interpolation, ranging between 0 and 1.

Return

CFrame	The interpolated `CFrame`.

Code Samples

local cf1 = CFrame.new(0, 0, 0)
local cf2 = CFrame.new(10, 10, 10)
local result = cf1:Lerp(cf2, 0.5)

PointToWorldSpace

Converts a Vector3 point from object space to world space.

Parameters

Vector3 v3	The point in object space.

Return

Vector3	The point in world space.

Code Samples

local cf = CFrame.new(1, 2, 3)
local point = Vector3.new(4, 5, 6)
local worldPoint = cf:PointToWorldSpace(point)

PointToObjectSpace

Converts a Vector3 point from world space to object space.

Parameters

Vector3 v3	The point in world space.

Return

Vector3	The point in object space.

Code Samples

local cf = CFrame.new(1, 2, 3)
local worldPoint = Vector3.new(4, 5, 6)
local localPoint = cf:PointToObjectSpace(worldPoint)

VectorToWorldSpace

Converts a Vector3 direction from object space to world space.

Parameters

Vector3 v3	The direction in object space.

Return

Vector3	The direction in world space.

Code Samples

local cf = CFrame.new()
local dir = Vector3.new(1, 0, 0)
local worldDir = cf:VectorToWorldSpace(dir)

VectorToObjectSpace

Converts a Vector3 direction from world space to object space.

Parameters

Vector3 v3	The direction in world space.

Return

Vector3	The direction in object space.

Code Samples

local cf = CFrame.new()
local worldDir = Vector3.new(1, 0, 0)
local objectDir = cf:VectorToObjectSpace(worldDir)

ToEulerAnglesXYZ

Returns the three Euler angles corresponding to the CFrame in XYZ order.

Parameters

Return

Tuple	The three Euler angles: (rx, ry, rz).

Code Samples

local cf = CFrame.Angles(math.rad(30), math.rad(45), math.rad(60))
local rx, ry, rz = cf:ToEulerAnglesXYZ()

ToEulerAnglesYXZ

Returns the three Euler angles corresponding to the CFrame in YXZ order.

Parameters

Return

Tuple	The three Euler angles: (ry, rx, rz).

Code Samples

local cf = CFrame.Angles(math.rad(30), math.rad(45), math.rad(60))
local ry, rx, rz = cf:ToEulerAnglesYXZ()

ToOrientation

Returns the orientation of the CFrame as three angles.

Parameters

Return

Tuple	The tuple (rx, ry, rz) describing the orientation.

Code Samples

local cf = CFrame.Angles(math.rad(10), math.rad(20), math.rad(30))
local rx, ry, rz = cf:ToOrientation()

FromEulerAnglesYXZ

Creates a CFrame from three Euler angles in YXZ order.

Parameters

number rx	The rotation around the x-axis.
number ry	The rotation around the y-axis.
number rz	The rotation around the z-axis.

Return

CFrame	The resulting `CFrame`.

Code Samples

local cf = CFrame:FromEulerAnglesYXZ(math.rad(30), math.rad(45), math.rad(60))

FromEulerAnglesXYZ

Creates a CFrame from three Euler angles in XYZ order.

Parameters

number rx	The rotation around the x-axis.
number ry	The rotation around the y-axis.
number rz	The rotation around the z-axis.

Return

CFrame	The resulting `CFrame`.

Code Samples

local cf = CFrame:FromEulerAnglesXYZ(math.rad(30), math.rad(45), math.rad(60))