CFrame

显示已弃用

*此内容使用人工智能（Beta）翻译，可能包含错误。若要查看英文页面，请点按此处。

CFrame数据类型，简称坐标框架，描述3D位置和方向。它由一个位置组件和一个旋转组件组成，包含 Roblox 上处理 3D 数据所必需的算术操作。


-- 在特定位置创建一个 CFrame 并进行欧几里旋转
local cf = CFrame.new(0, 5, 0) * CFrame.fromEulerAngles(math.rad(45), 0, 0)

有关介绍 CFrame 数据类型的信息，请参阅 CFrames 。

位置组件

位置组件可用作 Vector3 。此外，一个 CFrame 对象的组件位置也可用于 X 、 Y 和 Z 属性，如 Vector3 。

旋转组件

CFrame 存储 3D 旋转数据在 3×3 旋转矩阵中。这些值由 CFrame:GetComponents() 函数在 x、y 和 z 位置值之后返回。当进行旋转计算时，内部使用此矩阵，使用 ради安作为单位 (从一个到另一个转换时，使用 math.rad() 或 math.deg() )。了解 Roblox 引擎如何执行旋转的更多信息，请参阅 Enum.RotationOrder 。

下表代表了 CFrame 对象的旋转矩阵组成和与可用向量属性，例如 LookVector 和 RightVector 的关系。虽然旋转矩阵的单个组件很少单独有用，但由它们派生的向量属性更有用得多。


<th>YVector、UpVector</th>

    <th>ZVector, -LookVector <sup>†</sup></th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>R00</td>

    <td>R01</td>

    <td>R02</td>
  </tr>

  <tr>
    <td>R10</td>

    <td>R11</td>

    <td>R12</td>
  </tr>

  <tr>
    <td>R20</td>

    <td>R21</td>

    <td>R22</td>
  </tr>
</tbody>

XVector、RightVector

^† 与其他不同, LookVector 代表否定的列组件。LookVector 有用，因为许多类.Instance|实例例如类.Camera|Camera 和类.Attachment|附件将该向量视为指向实例的方向。

概要

构造工具

new()
返回空白身份 CFrame .
new(pos : Vector3)
返回一个 CFrame 没有旋转位置的提供的 Vector3 。
new(pos : Vector3,lookAt : Vector3)
返回一个 CFrame 与第一个 Vector3 的位置和一个指向第二个的方向。
new(x : number,y : number,z : number)
返回一个包含提供的 CFrame 、 x 和 y 组成部分的位置的 z 组件。
new(x : number,y : number,z : number,qX : number,qY : number,qZ : number,qW : number)
返回位置( 、、、、、、 )和四元数( 、、、 )。
new(x : number,y : number,z : number,R00 : number,R01 : number,R02 : number,R10 : number,R11 : number,R12 : number,R20 : number,R21 : number,R22 : number)
返回位置 ( x , y , z ) 的 CFrame ，其方向由旋转矩阵指定。
lookAt(at : Vector3,lookAt : Vector3,up : Vector3)
返回一个 CFrame 与第一个 Vector3 的位置和一个指向第二个的方向。
lookAlong(at : Vector3,direction : Vector3,up : Vector3)
返回一个 CFrame 与第一个 Vector3 的位置和一个向第二个方向定向的方向。
fromRotationBetweenVectors(from : Vector3,to : Vector3)
返回一个 CFrame 代表从第一个 Vector3 旋转到第二个所需的方向，位置设置为零。
fromEulerAngles(rx : number,ry : number,rz : number,order : Enum.RotationOrder)
返回旋转的 CFrame 从角度 rx , ry 和 rz 在 ради度上。旋转在可选的 Enum.RotationOrder 中应用，默认值为 XYZ 。
fromEulerAnglesXYZ(rx : number,ry : number,rz : number)
返回旋转的 CFrame 从角度 rx , ry , 和 rz 在 ради度上使用 Enum.RotationOrder.XYZ 。
fromEulerAnglesYXZ(rx : number,ry : number,rz : number)
返回旋转的 CFrame 从角度 rx , ry , 和 rz 在 ради度上使用 Enum.RotationOrder.YXZ 。
Angles(rx : number,ry : number,rz : number)
等于 fromEulerAnglesXYZ() .
fromOrientation(rx : number,ry : number,rz : number)
等于 fromEulerAnglesYXZ() .
fromAxisAngle(v : Vector3,r : number)
返回单位 CFrame 的旋转 Vector3 以及旋转角度。
fromMatrix(pos : Vector3,vX : Vector3,vY : Vector3,vZ : Vector3)
从翻译和旋转矩阵的列中返回 CFrame 以及一个旋转矩阵的列。

属性

identity:CFrame
一个没有翻译或旋转的身份 CFrame 。
Position:Vector3
CFrame 的 3D 位置。
Rotation:CFrame
一份没有翻译的 CFrame 副本。
X:number
位置的 X 坐标。
Y:number
位置的 Y 坐标。
Z:number
位置的 Z 坐标。
LookVector:Vector3
CFrame 对象的前向方向组件，相当于 ZVector 的否定形式。
RightVector:Vector3
CFrame 对象的右向组件的方向。
UpVector:Vector3
CFrame 对象的上向组件的方向。
XVector:Vector3
等于 RightVector .
YVector:Vector3
等于 UpVector .
ZVector:Vector3
CFrame 对象的 Z 组件的方向。等于旋转矩阵的第三个栏。

方法

Inverse():CFrame
返回 CFrame 的反向。
Lerp(goal : CFrame,alpha : number):CFrame
返回一个由与由分数之间交叉的。
Orthonormalize():CFrame
返回一个正常化的 CFrame 副本。
ToWorldSpace(... : Tuple<CFrame>):Tuple<CFrame>
接收一个或多个 CFrame 对象，并将它们转换为对象到世界空间。
ToObjectSpace(... : Tuple<CFrame>):Tuple<CFrame>
接收一个或多个 CFrame 对象，并将它们转换为从世界到对象空间的形式返回。
PointToWorldSpace(... : Tuple<Vector3>):Tuple<Vector3>
接收一个或多个 Vector3 对象，并将它们转换为对象到世界空间。
PointToObjectSpace(... : Tuple<Vector3>):Tuple<Vector3>
接收一个或多个 Vector3 对象，并将它们转换为从世界到对象空间的形式返回。
VectorToWorldSpace(... : Tuple<Vector3>):Tuple<Vector3>
接收一个或多个 Vector3 对象，并将它们旋转到对象到世界空间。
VectorToObjectSpace(... : Tuple<Vector3>):Tuple<Vector3>
接收一个或多个 Vector3 对象，并将它们旋转从世界到对象空间返回。
GetComponents():Tuple
返回值 , , , , , , , , , , , , , , ‑ ‑ 代表了和 ‑ 的 3×3旋转矩阵位置。
ToEulerAngles(order : Enum.RotationOrder):number,number,number
返回可用于生成 CFrame 的大约角度，使用可选的 Enum.RotationOrder 。
ToEulerAnglesXYZ():number,number,number
返回可用于生成 CFrame 的大约角度，使用 Enum.RotationOrder.XYZ 。
ToEulerAnglesYXZ():number,number,number
返回可用于生成 CFrame 的大约角度，使用 Enum.RotationOrder.YXZ 。
ToOrientation():number,number,number
等于 CFrame:ToEulerAnglesYXZ() .
ToAxisAngle():Vector3,number
返回一个 tuple 的 Vector3 和一个数字，它代表在轴角表示中旋转的 CFrame 。
components():Tuple
等于 CFrame:GetComponents() .
FuzzyEq(other : CFrame,epsilon : number):boolean
返回 true 如果另一个 CFrame 足够接近这个 CFrame 在位置和旋转上。
AngleBetween(other : CFrame):number
返回一个 CFrame 和另一个的方向之间的角度，以辐射为单位。

数学算式

CFrame * CFrame
生成一个新的 CFrame 代表了两个 CFrames 的组成。
CFrame * Vector3
生成一个 Vector3 从对象转换为世界坐标的变形。
CFrame + Vector3
生成由 CFrame 在世界空间中翻译的 Vector3 .
CFrame - Vector3
在世界空间中产生一个 CFrame 由负 Vector3 翻译的。

构造工具

new

创建一个空白身份 CFrame .

new

返回一个 CFrame 没有旋转位置的提供的 Vector3 。

参数

pos: Vector3

new

返回一个新的 CFrame 位于 pos 并面向 lookAt ，假设 (0, 1, 0) 在世界空间中被视为“上升”。

这个过载者已被 CFrame.lookAt() 替换，实现了相似的目标。它仍然是为了兼容性而存在。

在高倾斜角度（约 82 度）下，您可能会遇到数值不稳定。如果这是一个问题，或者如果你需要不同的"上"向量，使用 CFrame.fromMatrix() 更准确地构建 CFrame。此外，如果 lookAt 直接上面是 pos (斜角为 90 度)，“上”向量切换到 X 轴。

参数

pos: Vector3

lookAt: Vector3

new

返回一个包含提供的 CFrame 、 x 和 y 组成部分的位置的 z 组件。

参数

x: number

y: number

z: number

new

返回位置( 、、、、、、 )和四元数( 、、、 )。四次方预期为单位长度来表示有效的旋转。如果这不是情况，四次方将被正常化。

参数

x: number

y: number

z: number

qX: number

qY: number

qZ: number

qW: number

new

创建一个从位置 ( x , y , z ) 的 CFrame ，其方向由旋转矩阵指定。

[[R00 R01 R02] [R10 R11 R12] [R20 R21 R22]]

参数

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

返回一个新的 CFrame 与位置为 at 并面向 lookAt ，可选地指定向上方向 ( up ) 默认为 (0, 1, 0) 。

参数

at: Vector3

lookAt: Vector3

up: Vector3

默认值：Vector3.yAxis

lookAlong

返回一个新的 CFrame 与位置 at 并面向 direction , 可选地指定向上方向 ( up ) 默认值为 (0, 1, 0) 。

这个生成器与 CFrame.lookAt(at, at + direction) 相等。

参数

at: Vector3

direction: Vector3

up: Vector3

默认值：Vector3.yAxis

fromRotationBetweenVectors

返回一个 CFrame 代表从第一个 Vector3 旋转到第二个所需的方向，位置设置为零。

参数

from: Vector3

向量代表“从”方向。

to: Vector3

向量代表“到”方向。

fromEulerAngles

返回旋转的 CFrame 从角度 rx , ry 和 rz 在 ради度上。旋转在可选的 Enum.RotationOrder 中应用，默认值为 XYZ , 相当于：


CFrame.fromEulerAngles(rx, 0, 0) *  -- X
CFrame.fromEulerAngles(0, ry, 0) *  -- Y
CFrame.fromEulerAngles(0, 0, rz)    -- Z

参数

rx: number

ry: number

rz: number

order: Enum.RotationOrder

默认值：Enum.RotationOrder.XYZ

fromEulerAnglesXYZ

返回旋转的 CFrame 从角度 rx , ry , 和 rz 在 ради度上使用 Enum.RotationOrder.XYZ , 相当于：


CFrame.fromEulerAngles(rx, 0, 0) *  -- X
CFrame.fromEulerAngles(0, ry, 0) *  -- Y
CFrame.fromEulerAngles(0, 0, rz)    -- Z

参数

rx: number

ry: number

rz: number

fromEulerAnglesYXZ

返回旋转的 CFrame 从角度 rx , ry , 和 rz 在 ради度上使用 Enum.RotationOrder.YXZ , 相当于：


CFrame.fromEulerAngles(0, ry, 0) *  -- Y
CFrame.fromEulerAngles(rx, 0, 0) *  -- X
CFrame.fromEulerAngles(0, 0, rz)    -- Z

fromAxisAngle

返回单位 CFrame 的旋转 Vector3 以及旋转角度。

参数

v: Vector3

r: number

fromMatrix

从翻译和旋转矩阵的列中返回 CFrame 以及一个旋转矩阵的列。如果 vZ 被排除，第三列将计算为 vX:Cross(vY).Unit 。

参数

pos: Vector3

CFrame 的 3D 位置。

vX: Vector3

等于 RightVector .

vY: Vector3

等于 UpVector .

vZ: Vector3

等于 - LookVector .

属性

identity

CFrame

一个没有翻译或旋转的身份 CFrame 。此属性是一个常量，必须通过全球访问而不是通过单个 CFrame 对象访问。

Position

Vector3

CFrame 的 3D 位置。

Rotation

CFrame

一份没有翻译的 CFrame 副本。

X

number

位置的 X 坐标。

Y

number

位置的 Y 坐标。

Z

number

位置的 Z 坐标。

LookVector

Vector3

CFrame 对象的前向方向组件，相当于否定的 ZVector 或旋转矩阵的第三列。


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)

将 CFrame 对象的 LookVector 添加到自己产生了一个向任何方向移动 1 单位的 CFrame 前进的对象。

RightVector

Vector3

CFrame 对象的右向组件的方向。等于 XVector 或旋转矩阵的第一行。


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

CFrame 对象的上向组件的方向。等于 YVector 或旋转矩阵的第二列。


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

X 组件是 CFrame 对象的方向。等于 RightVector 或旋转矩阵的第一行。


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

CFrame 对象的 Y 组件的方向。等于 UpVector 或旋转矩阵的第二列。


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

CFrame 对象的 Z 组件的方向。等于否定的 LookVector 或旋转矩阵的第三列。


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)