工坊手册

主题

CFrame ​

CFrame 表示三维空间中的位置与旋转，可同时承载平移和朝向信息，常用于描述单位的位姿或两个坐标系之间的相对变换。它提供 Position、Rotation、LookVector、UpVector 等属性读取位置与方向，并支持逆变换、世界...

概览 ​

CFrame 表示三维空间中的位置与旋转，可同时承载平移和朝向信息，常用于描述单位的位姿或两个坐标系之间的相对变换。它提供 Position、Rotation、LookVector、UpVector 等属性读取位置与方向，并支持逆变换、世界空间与对象空间互转、插值、正交化以及多种欧拉角与轴向角的转换。

可通过 CFrame.New() 构造

代码示例 ​

构造坐标帧并读取属性

lua
-- @runtime client
local cf = CFrame.New(10, 20, 30)
local pos = cf.Position
print("位置:", pos.x, pos.y, pos.z)
local inv = cf:Inverse()
print("逆变换位置:", inv.Position.x, inv.Position.y, inv.Position.z)
local look = cf.LookVector
print("朝向分量:", look.x, look.y, look.z)

使用 LookAt 构造朝向并做坐标变换

lua
-- @runtime client
local origin = Vector3.New(0, 0, 0)
local target = Vector3.New(10, 0, 0)
local up = Vector3.New(0, 1, 0)
local lookAt = CFrame.LookAt(origin, target, up)
local localPoint = Vector3.New(0, 0, 5)
local worldPoint = lookAt:PointToWorldSpace(localPoint)
print("世界坐标:", worldPoint.x, worldPoint.y, worldPoint.z)
local right = lookAt.RightVector
print("右向量:", right.x, right.y, right.z)

函数 ​

Inverse ​

签名：Inverse() -> CFrame

返回当前 CFrame 的逆变换，可用于把世界空间中的变换转换到当前 CFrame 的局部空间。

返回值 CFrame

计算 CFrame 的逆变换

lua
-- @runtime client
-- 构造一个非单位 CFrame
local cf = CFrame(Vector3.New(10, 20, 30)) * CFrame.FromEulerAnglesXYZ(0.5, 0.3, 0.1)
-- 求逆变换
local invCf = cf:Inverse()
-- 验证逆变换：原变换再应用逆变换应回到原点
local result = cf * invCf
print("逆变换后的位置:", result.Position)

ToWorldSpace ​

签名：ToWorldSpace(cf: CFrame) -> CFrame

将另一个 CFrame 从当前 CFrame 的局部空间变换到世界空间，等价于 self * cf。

参数类型说明
cfCFrame局部坐标系下的 CFrame

返回值 CFrame

将物体局部空间 CFrame 转换到世界空间

lua
-- @runtime client
-- 定义物体自身的世界变换
local objectCf = CFrame(Vector3.New(5, 0, 0)) * CFrame.FromEulerAnglesXYZ(0, math.pi / 4, 0)
-- 定义物体局部空间中的一个偏移 CFrame
local localOffset = CFrame(Vector3.New(1, 0, 0))
-- 转换到世界空间
local worldCf = objectCf:ToWorldSpace(localOffset)
print("世界空间位置:", worldCf.Position)

ToObjectSpace ​

签名：ToObjectSpace(cf: CFrame) -> CFrame

将另一个 CFrame 从世界空间变换到当前 CFrame 的局部空间，等价于 self:Inverse() * cf。

参数类型说明
cfCFrame世界坐标系下的 CFrame

返回值 CFrame

将世界空间 CFrame 转换到物体局部空间

lua
-- @runtime client
-- 定义物体自身的世界变换
local objectCf = CFrame(Vector3.New(5, 0, 0)) * CFrame.FromEulerAnglesXYZ(0, math.pi / 4, 0)
-- 定义世界空间中的另一个 CFrame
local worldCf = CFrame(Vector3.New(6, 1, 0))
-- 转换到物体局部空间
local localCf = objectCf:ToObjectSpace(worldCf)
print("局部空间位置:", localCf.Position)

Lerp ​

签名：Lerp(goal: CFrame, alpha: Float) -> CFrame

在当前 CFrame 和目标 CFrame 之间进行线性插值，位置使用线性插值，旋转使用球面线性插值。

参数类型说明
goalCFrame插值目标 CFrame
alphaFloat插值系数

返回值 CFrame

在两个 CFrame 之间进行线性插值

lua
-- @runtime client
-- 定义起始和目标 CFrame
local startCf = CFrame(Vector3.New(0, 0, 0))
local goalCf = CFrame(Vector3.New(10, 0, 0)) * CFrame.FromEulerAnglesXYZ(0, math.pi / 2, 0)
-- 在中间位置插值
local alpha = 0.5
local midCf = startCf:Lerp(goalCf, alpha)
print("插值结果位置:", midCf.Position)
print("插值结果旋转:", midCf.Rotation)

Orthonormalize ​

签名：Orthonormalize() -> CFrame

对旋转矩阵进行 Gram-Schmidt 正交化，修正因数值累积导致的非正交漂移。

返回值 CFrame

正交化坐标帧的旋转基

lua
-- @runtime client
local cf = CFrame.New(1, 2, 3) * CFrame.FromEulerAnglesXYZ(0.2, 0.4, 0.1)
local ortho = cf:Orthonormalize()
print("正交化后的位置:", ortho.Position)
print("右向量长度:", ortho.RightVector.Magnitude)

FuzzyEq ​

签名：FuzzyEq(other: CFrame, epsilon: Float) -> Bool

判断两个 CFrame 是否在给定容差内近似相等，同时比较位置和旋转部分。

参数类型说明
otherCFrame用于比较的另一个 CFrame
epsilonFloat允许的最大分量误差，默认 1e-5

返回值 Bool

比较两个 CFrame 是否近似相等

lua
-- @runtime client
-- 构造两个位置和旋转都接近的 CFrame
local cf1 = CFrame(Vector3.New(1, 2, 3)) * CFrame.FromEulerAnglesXYZ(0.1, 0.2, 0.3)
local cf2 = CFrame(Vector3.New(1.0001, 2.0001, 3.0001)) * CFrame.FromEulerAnglesXYZ(0.1001, 0.2001, 0.3001)
-- 使用 FuzzyEq 检查是否在容差范围内相等
local epsilon = 0.001
local isEqual = cf1:FuzzyEq(cf2, epsilon)
print("两个 CFrame 是否近似相等:", isEqual)

LookAt ​

签名：LookAt(target: Vector3, up: Vector3) -> CFrame

保持自身位置不变，调整旋转使坐标帧的 LookVector 指向目标点

参数类型说明
targetVector3希望朝向的世界坐标点
upVector3参考上方向，用于消除滚转自由度，默认 (0,1,0)

返回值 CFrame

PointToWorldSpace ​

签名：PointToWorldSpace(point: Vector3) -> Vector3

将局部坐标点变换到世界坐标系下。

参数类型说明
pointVector3局部坐标系下的点坐标

返回值 Vector3

将物体局部坐标点转换到世界坐标

lua
-- @runtime client
-- 定义物体自身的世界变换
local objectCf = CFrame(Vector3.New(5, 0, 0)) * CFrame.FromEulerAnglesXYZ(0, math.pi / 4, 0)
-- 定义物体局部空间中的一个点
local localPoint = Vector3.New(1, 0, 0)
-- 转换到世界空间
local worldPoint = objectCf:PointToWorldSpace(localPoint)
print("世界坐标:", worldPoint)

PointToObjectSpace ​

签名：PointToObjectSpace(point: Vector3) -> Vector3

将世界坐标点变换到当前 CFrame 的局部坐标系下。

参数类型说明
pointVector3世界坐标系下的点坐标

返回值 Vector3

将世界坐标点转换到物体局部坐标

lua
-- @runtime client
-- 定义物体自身的世界变换
local objectCf = CFrame(Vector3.New(5, 0, 0)) * CFrame.FromEulerAnglesXYZ(0, math.pi / 4, 0)
-- 定义世界空间中的一个点
local worldPoint = Vector3.New(6, 1, 0)
-- 转换到物体局部空间
local localPoint = objectCf:PointToObjectSpace(worldPoint)
print("局部坐标:", localPoint)

VectorToWorldSpace ​

签名：VectorToWorldSpace(vector: Vector3) -> Vector3

将局部方向向量变换到世界坐标系下，忽略位移。

参数类型说明
vectorVector3局部坐标系下的方向向量

返回值 Vector3

将物体局部方向向量转换到世界方向

lua
-- @runtime client
-- 定义物体自身的世界变换
local objectCf = CFrame(Vector3.New(5, 0, 0)) * CFrame.FromEulerAnglesXYZ(0, math.pi / 4, 0)
-- 定义物体局部空间中的一个方向向量
local localDir = Vector3.New(1, 0, 0)
-- 转换到世界空间（忽略位移）
local worldDir = objectCf:VectorToWorldSpace(localDir)
print("世界方向:", worldDir)

VectorToObjectSpace ​

签名：VectorToObjectSpace(vector: Vector3) -> Vector3

将世界方向向量变换到当前 CFrame 的局部坐标系下，忽略位移。

参数类型说明
vectorVector3世界坐标系下的方向向量

返回值 Vector3

将世界方向向量转换到物体局部方向

lua
-- @runtime client
-- 定义物体自身的世界变换
local objectCf = CFrame(Vector3.New(5, 0, 0)) * CFrame.FromEulerAnglesXYZ(0, math.pi / 4, 0)
-- 定义世界空间中的一个方向向量
local worldDir = Vector3.New(1, 0, 0)
-- 转换到物体局部空间（忽略位移）
local localDir = objectCf:VectorToObjectSpace(worldDir)
print("局部方向:", localDir)

ToEulerAnglesXYZ ​

签名：ToEulerAnglesXYZ() -> Float, Float, Float

将旋转部分分解为外部 XYZ 顺序的欧拉角，返回弧度值。

返回值 Float rx — X轴旋转（弧度）；Float ry — Y轴旋转（弧度）；Float rz — Z轴旋转（弧度）

按 XYZ 顺序提取欧拉角

lua
-- @runtime client
local cf = CFrame.FromEulerAnglesXYZ(0.5, 0.3, 0.1)
local x, y, z = cf:ToEulerAnglesXYZ()
print(string.format('XYZ 欧拉角: %.4f, %.4f, %.4f', x, y, z))

ToEulerAnglesYXZ ​

签名：ToEulerAnglesYXZ() -> Float, Float, Float

将旋转部分分解为外部 YXZ 顺序的欧拉角，返回弧度值。

返回值 Float rx — X轴旋转（弧度）；Float ry — Y轴旋转（弧度）；Float rz — Z轴旋转（弧度）

按 YXZ 顺序提取欧拉角

lua
-- @runtime client
local cf = CFrame.FromEulerAnglesYXZ(0.5, 0.3, 0.1)
local x, y, z = cf:ToEulerAnglesYXZ()
print(string.format('YXZ 欧拉角: %.4f, %.4f, %.4f', x, y, z))

ToEulerAngles ​

签名：ToEulerAngles(order: Int) -> Float, Float, Float

CFrame:ToEulerAngles(order) 是 CFrame 的实例方法，用于把该 CFrame 的旋转部分按 order 指定的旋转顺序分解为欧拉角，并按固定次序返回三个 Float 弧度值：X 轴旋转、Y 轴旋转、Z 轴旋转。

参数类型说明
orderIntEnums.RotationOrder（默认 XYZ=0）

返回值 Float rx — X轴旋转（弧度）；Float ry — Y轴旋转（弧度）；Float rz — Z轴旋转（弧度）

ToOrientation ​

签名：ToOrientation() -> Float, Float, Float

将旋转部分分解为朝向角度，等同于 ToEulerAnglesYXZ。

返回值 Float rx — X轴旋转（弧度）；Float ry — Y轴旋转（弧度）；Float rz — Z轴旋转（弧度）

提取朝向角

lua
-- @runtime client
local cf = CFrame.LookAt(Vector3.New(0,0,0), Vector3.New(1,0,0))
local x, y, z = cf:ToOrientation()
print(string.format('朝向角: %.4f, %.4f, %.4f', x, y, z))

ToAxisAngle ​

签名：ToAxisAngle() -> Vector3, Float

将 CFrame 的旋转部分分解为旋转轴和旋转角度。

返回值 Vector3 axis — 旋转轴；Float angle — 旋转角度（弧度）

提取 CFrame 的轴角表示

lua
-- @runtime client
local cf = CFrame.FromEulerAnglesXYZ(0, 1.5708, 0)  -- 绕 Y 轴 90 度
local axis, angle = cf:ToAxisAngle()
print(string.format('旋转轴: %s, 角度(弧度): %.4f', tostring(axis), angle))

AngleBetween ​

签名：AngleBetween(other: CFrame) -> Float

计算两个 CFrame 旋转部分之间的夹角，返回弧度值。

参数类型说明
otherCFrame用于比较的另一个 CFrame

返回值 Float

计算两个 CFrame 旋转部分之间的夹角

lua
-- @runtime client
-- 构造两个朝向不同的 CFrame
local cf1 = CFrame.FromEulerAnglesXYZ(0, 0, 0)
local cf2 = CFrame.FromEulerAnglesXYZ(0, math.pi / 2, 0)
-- 计算夹角（弧度）
local angle = cf1:AngleBetween(cf2)
print("旋转夹角（弧度）:", angle)
print("旋转夹角（度）:", math.deg(angle))

GetComponents ​

签名：GetComponents() -> Float, Float, Float, Float, Float, Float, Float, Float, Float, Float, Float, Float

获取 CFrame 的全部 12 个分量，依次为位置 X, Y, Z 和旋转矩阵的 9 个元素（行优先）。

返回值 Float x — 位置 X；Float y — 位置 Y；Float z — 位置 Z；Float R00 — 旋转矩阵 [0][0]；Float R01 — 旋转矩阵 [0][1]；Float R02 — 旋转矩阵 [0][2]；Float R10 — 旋转矩阵 [1][0]；Float R11 — 旋转矩阵 [1][1]；Float R12 — 旋转矩阵 [1][2]；Float R20 — 旋转矩阵 [2][0]；Float R21 — 旋转矩阵 [2][1]；Float R22 — 旋转矩阵 [2][2]

分解 CFrame 的位置与旋转分量

lua
-- @runtime client
-- 构造一个带平移和旋转的 CFrame
local cf = CFrame.New(10, 5, 0) * CFrame.FromEulerAnglesXYZ(0, 1.57, 0)
-- GetComponents 返回位置 x/y/z 与 3x3 旋转矩阵的 9 个分量
local x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22 = cf:GetComponents()
print(string.format('位置: %.2f, %.2f, %.2f', x, y, z))
print(string.format('第一行旋转矩阵: %.3f, %.3f, %.3f', r00, r01, r02))

Identity ​

签名：Identity() -> CFrame

返回单位 CFrame，位置在原点且无旋转。

返回值 CFrame

创建单位 CFrame（原点无旋转）

lua
-- @runtime client
-- 获取单位 CFrame
local identity = CFrame.Identity()
print("单位 CFrame 位置:", identity.Position)
print("单位 CFrame 旋转:", identity.Rotation)

FromMatrix ​

签名：FromMatrix() -> CFrame

根据位置和旋转矩阵列向量构造 CFrame；可传入 pos、vX、vY、vZ，或省略 vZ 由 vX 与 vY 自动推导。

返回值 CFrame

LookAt ​

签名：LookAt(at: Vector3, target: Vector3, up: Vector3) -> CFrame

返回一个新的 CFrame，其位置与当前 CFrame 相同，但朝向指向目标点。

参数类型说明
atVector3新 CFrame 的位置
targetVector3希望朝向的目标点
upVector3参考上方向，用于消除滚转自由度，默认 (0,1,0)

返回值 CFrame

区分实例 LookAt 与静态 LookAt

lua
-- @runtime client
local up = Vector3.New(0, 1, 0)
local at = Vector3.New(0, 2, 0)
local target = Vector3.New(10, 2, 0)

-- 静态工厂：显式指定起点 at 与朝向目标 target
local staticCf = CFrame.LookAt(at, target, up)

-- 实例方法：保留 base 的当前位置，只调整朝向
local base = CFrame.New(5, 2, 0)
local instanceCf = base:LookAt(target, up)

print(staticCf.Position, instanceCf.Position)

LookAlong ​

签名：LookAlong(at: Vector3, dir: Vector3, up: Vector3) -> CFrame

构造一个位于 at 点、朝向 dir 方向的 CFrame。

参数类型说明
atVector3新 CFrame 的位置
dirVector3希望沿其方向的世界空间向量
upVector3参考上方向，用于消除滚转自由度，默认 (0,1,0)

返回值 CFrame

构造沿指定方向的 CFrame

lua
-- @runtime client
-- 定义位置、方向和上方向
local at = Vector3.New(0, 0, 0)
local dir = Vector3.New(1, 0, 0)
local up = Vector3.New(0, 1, 0)
-- 使用 LookAlong 构造 CFrame
local cf = CFrame.LookAlong(at, dir, up)
print("构造的 CFrame 位置:", cf.Position)
print("构造的 CFrame 朝向:", cf.LookVector)

FromAxisAngle ​

签名：FromAxisAngle(axis: Vector3, angle: Float) -> CFrame

从旋转轴和角度构造一个 CFrame，位置为原点。

参数类型说明
axisVector3旋转轴的单位向量
angleFloat绕轴旋转的角度，单位为弧度

返回值 CFrame

从旋转轴和角度构造 CFrame

lua
-- @runtime client
-- 定义旋转轴（Y轴）和旋转角度（90度）
local axis = Vector3.New(0, 1, 0)
local angle = math.pi / 2
-- 使用 FromAxisAngle 构造 CFrame
local cf = CFrame.FromAxisAngle(axis, angle)
print("构造的 CFrame 旋转:", cf.Rotation)

FromEulerAnglesXYZ ​

签名：FromEulerAnglesXYZ(rx: Float, ry: Float, rz: Float) -> CFrame

从外部 XYZ 顺序的欧拉角构造一个 CFrame，位置为原点。

参数类型说明
rxFloat绕 X 轴旋转的角度，单位为弧度
ryFloat绕 Y 轴旋转的角度，单位为弧度
rzFloat绕 Z 轴旋转的角度，单位为弧度

返回值 CFrame

从 XYZ 欧拉角构造 CFrame

lua
-- @runtime client
-- 定义 XYZ 欧拉角（弧度）
local rx, ry, rz = 0.1, 0.2, 0.3
-- 使用 FromEulerAnglesXYZ 构造 CFrame
local cf = CFrame.FromEulerAnglesXYZ(rx, ry, rz)
print("构造的 CFrame 旋转:", cf.Rotation)

FromEulerAnglesYXZ ​

签名：FromEulerAnglesYXZ(rx: Float, ry: Float, rz: Float) -> CFrame

从外部 YXZ 顺序的欧拉角构造一个 CFrame，位置为原点。

参数类型说明
rxFloat绕 X 轴旋转的角度，单位为弧度
ryFloat绕 Y 轴旋转的角度，单位为弧度
rzFloat绕 Z 轴旋转的角度，单位为弧度

返回值 CFrame

从 YXZ 欧拉角构造 CFrame

lua
-- @runtime client
-- 定义 YXZ 欧拉角（弧度）
local rx, ry, rz = 0.1, 0.2, 0.3
-- 使用 FromEulerAnglesYXZ 构造 CFrame
local cf = CFrame.FromEulerAnglesYXZ(rx, ry, rz)
print("构造的 CFrame 旋转:", cf.Rotation)

FromOrientation ​

签名：FromOrientation(rx: Float, ry: Float, rz: Float) -> CFrame

从朝向角度构造一个 CFrame，位置为原点，等同于 FromEulerAnglesYXZ。

参数类型说明
rxFloat绕 X 轴旋转的角度，单位为弧度
ryFloat绕 Y 轴旋转的角度，单位为弧度
rzFloat绕 Z 轴旋转的角度，单位为弧度

返回值 CFrame

从朝向角度构造 CFrame（YXZ 顺序）

lua
-- @runtime client
-- 定义朝向角度（弧度）
local rx, ry, rz = 0.1, 0.2, 0.3
-- 使用 FromOrientation 构造 CFrame
local cf = CFrame.FromOrientation(rx, ry, rz)
print("构造的 CFrame 旋转:", cf.Rotation)

FromEulerAngles ​

签名：FromEulerAngles(rx: Float, ry: Float, rz: Float, order: Int) -> CFrame

CFrame.FromEulerAngles(rx, ry, rz, order) 是 CFrame 的构造形式之一，接收三个 Float 弧度分量与一个 Int 旋转顺序 order，按该顺序组合出旋转并返回一个新的 CFrame。

参数类型说明
rxFloat绕 X 轴旋转的角度，单位为弧度
ryFloat绕 Y 轴旋转的角度，单位为弧度
rzFloat绕 Z 轴旋转的角度，单位为弧度
orderIntEnums.RotationOrder (XYZ=0, XZY=1, YZX=2, YXZ=3, ZXY=4, ZYX=5)

返回值 CFrame

FromRotationBetweenVectors ​

签名：FromRotationBetweenVectors(from: Vector3, to: Vector3) -> CFrame

构造一个从 from 向量旋转到 to 向量的最短旋转 CFrame，位置为原点。

参数类型说明
fromVector3起始方向向量
toVector3目标方向向量

返回值 CFrame

从两个向量之间的最短旋转构造 CFrame

lua
-- @runtime client
-- 定义起始方向和目标方向
local fromDir = Vector3.New(1, 0, 0)
local toDir = Vector3.New(0, 1, 0)
-- 使用 FromRotationBetweenVectors 构造旋转 CFrame
local cf = CFrame.FromRotationBetweenVectors(fromDir, toDir)
print("构造的 CFrame 旋转:", cf.Rotation)

属性 ​

名称类型默认值说明
XFloat-CFrame 位置的 X 坐标分量。
YFloat-CFrame 位置的 Y 坐标分量。
ZFloat-CFrame 位置的 Z 坐标分量。
PositionVector3-CFrame 的位置部分，表示坐标系原点的世界坐标。
RotationCFrame-仅保留旋转部分的 CFrame，位置被清零。
RightVectorVector3-右方向单位向量，指向 +X 方向。
UpVectorVector3-上方向单位向量，指向 +Y 方向。
LookVectorVector3-获取 CFrame 的前方朝向单位向量；按当前 Meta 契约，它对应旋转矩阵的 column 2，与 ZVector 等同。
LeftVectorVector3-左方向单位向量，等于 -RightVector。
XVectorVector3-旋转矩阵的第一列，等同于 RightVector。
YVectorVector3-旋转矩阵的第二列，等同于 UpVector。
ZVectorVector3-旋转矩阵的第三列，等同于 LookVector。