CFrame

CFrame

Overview

Description

CFrame is a class 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 CFZero = CFrame.identity
print(CFZero)

Position

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

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.Position)

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(20, 90, 60)
print(CF.Orientation)

Rotation

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

Code Samples

local CF = CFrame.Angles(0, 45, 0)
print(CF.Rotation)

X

number Returns the X coordinate of the CFrame.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.X)

Y

number Returns the Y coordinate of the CFrame.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.Y)

Z

number Returns the Z coordinate of the CFrame.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.Z)

XVector

Vector3 Returns the X axis vector of the CFrame.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.XVector)

YVector

Vector3 Returns the Y axis vector of the CFrame.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.YVector)

ZVector

Vector3 Returns the Z axis vector of the CFrame.

Code Samples

local CF = CFrame.new(10, 50, 20)
print(CF.ZVector)

LookVector

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

Code Samples

local Part = script.Parent
local Workspace = game:GetService("Workspace")
local SpawnLocation = Workspace.SpawnLocation

local CF = CFrame.lookAt(Part.Position, SpawnLocation.Position)
print(CF.LookVector)

RightVector

Vector3 Indicates the camera's right-hand direction.

Code Samples

local Part = script.Parent
local CF = Part.CFrame
print(CF.RightVector)

UpVector

Vector3 Indicates the camera's upward direction.

Code Samples

local Part = script.Parent
local CF = Part.CFrame
print(CF.UpVector)

Constructors

new

Creates a basic CFrame object.

Parameters

None

Return

CFrame	A `CFrame` object

Code Samples

local CF = CFrame.new()

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(10, 50, 20)
local CF = CFrame.new(Position)

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(10, 50, 20)
local LookAt = Vector3.new(0, 30, 0)
local CF = CFrame.new(Position, LookAt)

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(10, 50, 20)

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 Part = script.Parent
local Workspace = game:GetService("Workspace")
local SpawnLocation = Workspace.SpawnLocation

local CF = CFrame.lookAt(Part.Position, SpawnLocation.Position)

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 C = 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 CF = CFrame.Angles(0, 40, 0)

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 C = 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 C = 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 Position = Vector3.new(0, 50, 0)
local RightVector = Vector3.new(1, 0, 0)
local UpVector = Vector3.new(0, 1, 0)
local BackVector = Vector3.new(0, 0, 1)

local CF = CFrame.fromMatrix(Position, RightVector, UpVector, BackVector)

Methods

Inverse

Returns the inverse of the CFrame.

Parameters

None

Return

CFrame	The inverse `CFrame`.

Code Samples

local CF = CFrame.new(0, 50, 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 Alpha = 0.5

local Result = CF1:Lerp(CF2, Alpha)

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(10, 0, 0)
local LocalPoint = Vector3.new(15, 0, 0)
local WorldPoint = CF:PointToWorldSpace(LocalPoint)

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(25, 0, 0)
local WorldPoint = Vector3.new(35, 0, 0)
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 LocalDir = Vector3.new(1, 0, 0)
local WorldDir = CF:VectorToWorldSpace(LocalDir)

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 LocalDir = 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 X, Y, Z = 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 X, Y, Z = 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 X, Y, Z = CF:ToOrientation()