CFrame

Visualizza obsoleti

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 and includes essential arithmetic operations for working with 3D data on Roblox.

-- Create a CFrame at a certain position and Euler rotation

local cf = CFrame.new(0, 5, 0) * CFrame.fromEulerAngles(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()). For more information on how the Roblox engine performs rotations, see Enum.RotationOrder.

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.

XVector, RightVectorYVector, UpVectorZVector, -LookVector†
R00R01R02
R10R11R12
R20R21R22
† Unlike the others, LookVector represents the negated column components. The LookVector is useful because many Instances such as the Camera and Attachments treat that vector as the direction the instance is pointing.

Sommario

Costruttori

Proprietà

Metodi

Costruttori

new

new

Parametri

pos: Vector3

new

Parametri

pos: Vector3
lookAt: Vector3

new

Parametri

x: number
y: number
z: number

new

Parametri

x: number
y: number
z: number
qX: number
qY: number
qZ: number
qW: number

new

Parametri

x: number
y: number
z: number
R00: number
R01: number
R02: number
R10: number
R11: number
R12: number
R20: number
R21: number
R22: number

lookAt

Parametri

at: Vector3
lookAt: Vector3
up: Vector3
Valore predefinito: Vector3.yAxis

lookAlong

Parametri

at: Vector3
direction: Vector3
up: Vector3
Valore predefinito: Vector3.yAxis

fromEulerAngles

Parametri

rx: number
ry: number
rz: number
order: Enum.RotationOrder
Valore predefinito: Enum.RotationOrder.XYZ

fromEulerAnglesXYZ

Parametri

rx: number
ry: number
rz: number

fromEulerAnglesYXZ

Parametri

rx: number
ry: number
rz: number

Angles

Parametri

rx: number
ry: number
rz: number

fromOrientation

Parametri

rx: number
ry: number
rz: number

fromAxisAngle

Parametri

v: Vector3
r: number

fromMatrix

Parametri

pos: Vector3
vX: Vector3
vY: Vector3
vZ: Vector3

Proprietà

identity

CFrame

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.

Position

Vector3

The 3D position of the CFrame.

Rotation

CFrame

A copy of the CFrame with no translation.

X

number

The X coordinate of the position.

Y

number

The Y coordinate of the position.

Z

number

The Z coordinate of the position.

LookVector

Vector3

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.

RightVector

Vector3

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)

UpVector

Vector3

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)

XVector

Vector3

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)

YVector

Vector3

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)

ZVector

Vector3

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)

Metodi

Inverse

CFrame

Returns the inverse of the CFrame.

Restituzioni

CFrame

Lerp

CFrame

Returns a CFrame interpolated between itself and goal by the fraction alpha.

Parametri

goal: CFrame
alpha: number

Restituzioni

CFrame

Orthonormalize

CFrame

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.

Restituzioni

CFrame

ToWorldSpace

CFrame

Returns one or more CFrame objects transformed from object to world space. Equivalent to:

CFrame * cf

Parametri

cf: CFrame

Restituzioni

CFrame

ToObjectSpace

CFrame

Returns one or more CFrame objects transformed from world to object space. Equivalent to:

CFrame:Inverse() * cf

Parametri

cf: CFrame

Restituzioni

CFrame

PointToWorldSpace

Vector3

Returns one or more Vector3 objects transformed from object to world space. Equivalent to:

CFrame * v3

Parametri

v3: Vector3

Restituzioni

Vector3

PointToObjectSpace

Vector3

Returns one or more Vector3 objects transformed from world to object space. Equivalent to:

CFrame:Inverse() * v3

Parametri

v3: Vector3

Restituzioni

Vector3

VectorToWorldSpace

Vector3

Returns one or more Vector3 objects rotated from object to world space. Equivalent to:

(CFrame - CFrame.Position) * v3

Parametri

v3: Vector3

Restituzioni

Vector3

VectorToObjectSpace

Vector3

Returns one or more Vector3 objects rotated from world to object space. Equivalent to:

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

Parametri

v3: Vector3

Restituzioni

Vector3

GetComponents

Tuple

Returns the values x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, and R22, where x y z represent the position of the CFrame and R00‑R22 represent its 3×3 rotation matrix.

Restituzioni

Tuple

ToEulerAngles

number

Returns approximate angles that could be used to generate the CFrame using the optional Enum.RotationOrder. If you don't provide order, the method uses Enum.RotationOrder.XYZ.

Parametri

order: Enum.RotationOrder
Valore predefinito: Enum.RotationOrder.XYZ

Restituzioni

number
number
number

ToEulerAnglesXYZ

number

Returns approximate angles that could be used to generate the CFrame using Enum.RotationOrder.XYZ.

Restituzioni

number
number
number

ToEulerAnglesYXZ

number

Returns approximate angles that could be used to generate the CFrame using Enum.RotationOrder.YXZ.

Restituzioni

number
number
number

ToOrientation

number

Equivalent to CFrame:ToEulerAnglesYXZ().

Restituzioni

number
number
number

ToAxisAngle

Vector3

Returns a tuple of a Vector3 and a number which represent the rotation of the CFrame in the axis-angle representation.

Restituzioni

Vector3
number

components

Tuple

Equivalent to CFrame:GetComponents().

Restituzioni

Tuple

FuzzyEq

bool

Returns true if the other 'Datatype.CFrame' is sufficiently close to this 'Datatype.CFrame' in both position and rotation. The eps 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, and for rotation uses a fast approximation of the angle difference.

Parametri

other: CFrame
epsilon: number
Valore predefinito: 0.00001 (1e-5)

Restituzioni

bool

Operazioni Matematiche