CFrame

Summary

Properties

Properties of a `CFrame`.

• Position: Vector3
• Rotation: CFrame
• X, Y, Z: Number
• LookVector, RightVector, UpVector: Vector3
• XVector, YVector, ZVector: Vector3

Constants

Constants of a `CFrame`.

• identity: CFrame

Constructors

Constructors of a `CFrame`.

• new: CFrame
• Angles: CFrame
• fromAxisAngle: CFrame
• fromEulerAnglesXYZ: CFrame
• fromEulerAnglesYXZ: CFrame
• fromMatrix: CFrame
• fromOrientation: CFrame
• lookAt: CFrame

Methods

Methods of a `CFrame`.

• GetComponents: ...Number
• Inverse: CFrame
• Lerp: CFrame
• PointToObjectSpace: Vector3
• PointToWorldSpace: Vector3
• ToEulerAnglesXYZ: Number, Number, Number
• ToEulerAnglesYXZ: Number, Number, Number
• ToObjectSpace: CFrame
• ToOrientation: Number, Number, Number
• ToWorldSpace: CFrame
• VectorToObjectSpace: Vector3
• VectorToWorldSpace: Vector3

Properties

Position

Vector3

The position component of the CFrame.

Rotation

CFrame

The rotation component of the CFrame, with its position reset to the origin.

X

Number

The X coordinate of the CFrame position.

Y

Number

The Y coordinate of the CFrame position.

Z

Number

The Z coordinate of the CFrame position.

LookVector

Vector3

The normalized forward direction of the CFrame.

RightVector

Vector3

The normalized right direction of the CFrame.

UpVector

Vector3

The normalized up direction of the CFrame.

XVector

Vector3

The X basis vector of the rotation matrix. Equivalent to RightVector.

YVector

Vector3

The Y basis vector of the rotation matrix. Equivalent to UpVector.

ZVector

Vector3

The Z basis vector of the rotation matrix. Equivalent to -LookVector.

Constants

identity

CFrame

CFrame.identity

The CFrame at (0, 0, 0) with no rotation.

Constructors

new

CFrame

CFrame.new()

CFrame.new(position: Vector3)

CFrame.new(x: Number, y: Number, z: Number)

Creates a CFrame at the origin, from a position vector, or from three position coordinates.

Parameters

• position: Vector3 — the position of the CFrame.
• x: Number — the X position.
• y: Number — the Y position.
• z: Number — the Z position.

Angles

CFrame

CFrame.Angles(rotationX: Number, rotationY: Number, rotationZ: Number)

Creates a CFrame rotated by the supplied angles in radians.

Parameters

• rotationX: Number — the X-axis rotation in radians.
• rotationY: Number — the Y-axis rotation in radians.
• rotationZ: Number — the Z-axis rotation in radians.

fromAxisAngle

CFrame

CFrame.fromAxisAngle(axis: Vector3, angle: Number)

Creates a CFrame rotated around axis by angle radians.

Parameters

• axis: Vector3 — the axis of rotation.
• angle: Number — the rotation angle in radians.

fromEulerAnglesXYZ

CFrame

CFrame.fromEulerAnglesXYZ(rotationX: Number, rotationY: Number, rotationZ: Number)

Creates a CFrame using Euler rotations in XYZ order.

Parameters

• rotationX: Number — the X-axis rotation in radians.
• rotationY: Number — the Y-axis rotation in radians.
• rotationZ: Number — the Z-axis rotation in radians.

fromEulerAnglesYXZ

CFrame

CFrame.fromEulerAnglesYXZ(rotationX: Number, rotationY: Number, rotationZ: Number)

Creates a CFrame using Euler rotations in YXZ order.

Parameters

• rotationX: Number — the X-axis rotation in radians.
• rotationY: Number — the Y-axis rotation in radians.
• rotationZ: Number — the Z-axis rotation in radians.

fromMatrix

CFrame

CFrame.fromMatrix(position: Vector3, vX: Vector3, vY: Vector3, vZ: Vector3)

Creates a CFrame from a position and its three rotation basis vectors.

Parameters

• position: Vector3 — the position of the CFrame.
• vX: Vector3 — the X basis vector.
• vY: Vector3 — the Y basis vector.
• vZ: Vector3 — the Z basis vector.

fromOrientation

CFrame

CFrame.fromOrientation(rotationX: Number, rotationY: Number, rotationZ: Number)

Creates a CFrame from X, Y, and Z orientation angles in radians.

Parameters

• rotationX: Number — the X-axis rotation in radians.
• rotationY: Number — the Y-axis rotation in radians.
• rotationZ: Number — the Z-axis rotation in radians.

lookAt

CFrame

CFrame.lookAt(position: Vector3, target: Vector3)

Creates a CFrame at position oriented toward target.

Parameters

• position: Vector3 — the position of the CFrame.
• target: Vector3 — the point toward which the CFrame faces.

Methods

GetComponents

...Number

cframe:GetComponents()

Returns the position and rotation-matrix components of the CFrame.

Inverse

CFrame

cframe:Inverse()

Returns the inverse transformation of cframe.

Lerp

CFrame

cframe:Lerp(goal: CFrame, alpha: Number)

Interpolates between cframe and goal.

Parameters

• goal: CFrame — the target transformation.
• alpha: Number — the interpolation amount, from 0 to 1.

PointToObjectSpace

Vector3

cframe:PointToObjectSpace(point: Vector3)

Converts a world-space point to the CFrame’s object space.

Parameters

• point: Vector3 — the world-space point.

PointToWorldSpace

Vector3

cframe:PointToWorldSpace(point: Vector3)

Converts an object-space point to world space.

Parameters

• point: Vector3 — the object-space point.

ToEulerAnglesXYZ

Number, Number, Number

cframe:ToEulerAnglesXYZ()

Returns the CFrame rotation as X, Y, and Z Euler angles in radians.

ToEulerAnglesYXZ

Number, Number, Number

cframe:ToEulerAnglesYXZ()

Returns the CFrame rotation as X, Y, and Z Euler angles in radians, using YXZ order.

ToObjectSpace

CFrame

cframe:ToObjectSpace(other: CFrame)

Converts other into cframe’s object space.

Parameters

• other: CFrame — the world-space transformation.

ToOrientation

Number, Number, Number

cframe:ToOrientation()

Returns the CFrame rotation as X, Y, and Z orientation angles in radians.

ToWorldSpace

CFrame

cframe:ToWorldSpace(other: CFrame)

Converts other from cframe’s object space to world space.

Parameters

• other: CFrame — the object-space transformation.

VectorToObjectSpace

Vector3

cframe:VectorToObjectSpace(vector: Vector3)

Converts a world-space direction vector to object space without applying position.

Parameters

• vector: Vector3 — the world-space direction vector.

VectorToWorldSpace

Vector3

cframe:VectorToWorldSpace(vector: Vector3)

Converts an object-space direction vector to world space without applying position.

Parameters

• vector: Vector3 — the object-space direction vector.

Position and rotation example

A CFrame stores position and rotation together. Angles use radians, so math.rad makes degree values easier to read:

local position = CFrame.new(0, 5, 0)
local quarterTurn = CFrame.Angles(0, math.rad(90), 0)
local transform = position * quarterTurn

local part = workspace:FindFirstChild("MyPart")
if part then
    part.CFrame = transform
end

Multiplication composes transforms. In this example, the Part is placed five studs above the origin and rotated 90 degrees around the Y axis.

Operators

The following expressions completed successfully in both Script and LocalScript:

cframe + vector3
cframe - vector3
cframe * otherCFrame
cframe * vector3

Addition and subtraction translate the CFrame. Multiplication composes two CFrames or transforms a Vector3 point.

Testing Notes

These observations were revalidated in both Script and LocalScript in Vortex Studio 0.3.4.

CFrame.fromMatrix requires all three basis vectors. Calling it without vZ fails because the current implementation indexes the missing argument.

The lowercase aliases components, toEulerAnglesXYZ, and toEulerAnglesYXZ are also exposed; this reference uses the canonical names.

The position-and-rotation example was revalidated in Vortex Studio 0.3.8. It produced position (0, 5, 0) and a LookVector of approximately (-1, 0, 0).