CFrame

顯示已棄用項目

*此內容是使用 AI（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 一樣使用。

旋轉元件

商店 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 代表否定的柱子組件。數據類型。CFrame.LookVector|LookVector有用，因為許多Instances，例如Camera和附件，將這個向量視為指向實例的方向。

概要

建構子

new()
返回空白身份 CFrame 。
new(pos : Vector3)
返回一個 CFrame 沒有旋轉提供的 Vector3 位置的旋轉。
new(pos : Vector3,lookAt : Vector3)
返回具有第一個 Vector3 位置和指向第二個的方向的 CFrame 。
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)
返回具有第一個 Vector3 位置和指向第二個的方向的 CFrame 。
lookAlong(at : Vector3,direction : Vector3,up : Vector3)
返回具有第一個 Vector3 位置和第二個方向的 CFrame 的值。
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)
從單位 Vector3 返回旋轉的 CFrame 以及旋轉角度。
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
返回一個 CFrame 在自身和 goal 之間被分數 alpha 插入的值。
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
返回值 x , y , z , R00 , R01 , R02 , R10 , R11 , R12 , R20 , R21 , 和 R22 , 其中 x y z 代表了 CFrame 和 R00 ‑ R22 代表了它的 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
如果另一個 CFrame 足夠接近這個 CFrame 在位置和旋轉上，返回 true 。

數學算式

CFrame * CFrame
產生一個新的 CFrame 代表兩個 CFrames 的組成。
CFrame * Vector3
產生一個 Vector3 從對象轉換為世界坐標的變形。
CFrame + Vector3
在世界空間由 Vector3 翻譯的 CFrame 。
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

從單位 Vector3 返回旋轉的 CFrame 以及旋轉角度。

參數

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 對物件的方向的 X 部分。等於 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)