CFrame

概览

字段	值
Kind	Data · 数据 Data
Realm	common

CFrame 用来描述三维空间中的位置与朝向，既可以表示物体在世界中的摆放，也可以表示相对某个坐标系的局部变换。它对外暴露位置分量、位置向量以及右向量、上向量、前方向量等三根基向量，并支持求逆、父子空间互转、插值、点与向量的坐标换算、欧拉角与轴角互转等运算，是摆放单位、计算朝向和做空间换算的基础载体。

适用场景

用于描述和组合空间位置与朝向。把 CFrame.New(3, 4, 5) 赋给单位的 CFrame 属性可设置整体变换；只修改 Position 时应使用 Vector3.New(3, 4, 5)。LookAt 用于朝向目标，ToObjectSpace 与 PointToWorldSpace 用于坐标空间换算。

使用要点

先用 CFrame.New(x, y, z) 或简写 CFrame(x, y, z) 构造带位置的坐标帧，需要朝向时改用 CFrame.LookAt(at, target, up) 或 CFrame.LookAlong(at, dir, up)，也可以由 CFrame.FromAxisAngle、CFrame.FromEulerAnglesXYZ 等构造纯旋转。拿到坐标帧后，可用 cf.Position 与 cf.LookVector 读取位置和朝向，用 cf:ToObjectSpace(other) 与 cf:PointToWorldSpace(point) 在世界空间与局部空间之间换算，用 cf:Lerp(goal, alpha) 做平滑过渡，必要时用 cf:Inverse() 取得逆变换。

注意事项

CFrame 的静态构造方法（New/LookAt/LookAlong/FromEulerAnglesXYZ 等）必须用点语法 CFrame.Method(...) 调用，禁止冒号语法 CFrame:Method(...)。注意 LookAt 有实例方法和静态方法两种形态：cf:LookAt(target, up) 保持 cf 自身位置不变，只改变朝向；CFrame.LookAt(at, target, up) 才表示在 at 位置构造一个朝向 target 的新 CFrame。写示例时必须按这两个签名区分参数。注意：CFrame 不存在 Angles 方法，请使用 FromEulerAnglesXYZ/FromEulerAnglesYXZ（弧度）。当前运行包调用 FromMatrix(pos, vX, vY, vZ) 会触发 userdata 到 Matrix3x3 的隐式转换错误，在修复前请使用 LookAlong/LookAt 或 New 的公开重载表达位置与朝向。

代码示例

构造坐标帧并读取属性

-- @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 构造朝向并做坐标变换

-- @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)

属性 (12)

Name	类型	默认值	说明
X	Float	-	CFrame 位置分量的 X 轴坐标，类型为 Float，与 Y、Z 共同描述该坐标帧的位置。
Y	Float	-	CFrame 位置分量的 Y 轴坐标，类型为 Float，与 X、Z 共同描述该坐标帧的位置。
Z	Float	-	CFrame 位置分量的 Z 轴坐标，类型为 Float，与 X、Y 共同描述该坐标帧的位置。
Position	Vector3	-	CFrame 的位置向量，类型为 Vector3，表示该坐标帧的平移部分。
Rotation	CFrame	-	仅保留旋转部分、位置清零的 CFrame，类型为 CFrame。
RightVector	Vector3	-	CFrame 的右方向单位向量，类型为 Vector3，描述该坐标帧右轴所指的方向。
UpVector	Vector3	-	CFrame 的上方向单位向量，类型为 Vector3，对应旋转矩阵的 column 1。
LookVector	Vector3	-	获取 CFrame 的前方朝向单位向量；按当前 Meta 契约，它对应旋转矩阵的 column 2，与 ZVector 等同。
LeftVector	Vector3	-	CFrame 的左方向单位向量，类型为 Vector3，等于 RightVector 的反向。
XVector	Vector3	-	旋转矩阵 column 0 对应的方向向量，类型为 Vector3，与 RightVector 含义相同。
YVector	Vector3	-	旋转矩阵 column 1 对应的方向向量，类型为 Vector3，与 UpVector 含义相同。
ZVector	Vector3	-	旋转矩阵 column 2 对应的方向向量，类型为 Vector3，与前方朝向相关。

关联类型

• Vector3

函数 (28)

Inverse

签名：Inverse() -> CFrame

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

返回值 CFrame

示例代码

求 CFrame 的逆变换

-- @runtime client
-- 构造带位置和旋转的坐标帧
local cf = CFrame.New(10, 5, 3) * CFrame.FromEulerAnglesXYZ(0, math.rad(90), 0)
local inv = cf:Inverse()
print("逆变换位置:", inv.Position)
-- 逆变换与原变换组合后位置回到原点
local combined = cf * inv
print("组合后位置:", combined.Position)

ToWorldSpace

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

把物体空间的变换 cf 转换到世界空间，等同 self * cf，返回 CFrame。

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

返回值 CFrame

示例代码

把局部 CFrame 变换到世界空间

-- @runtime client
local base = CFrame.New(10, 0, 0)
local offset = CFrame.New(0, 0, -5)
local worldCf = base:ToWorldSpace(offset)
print("世界空间位置:", worldCf.Position)
local back = base:ToObjectSpace(worldCf)
print("回到局部:", back.Position)

ToObjectSpace

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

把世界空间的变换 cf 转换到当前 CFrame 的物体空间，等同 self:Inverse() * cf，返回 CFrame。

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

返回值 CFrame

示例代码

把 CFrame 从世界空间变换到局部空间

-- @runtime client
local base = CFrame.New(0, 0, 0)
local target = CFrame.New(3, 0, 0)
local localCf = base:ToObjectSpace(target)
print("局部空间位置:", localCf.Position)
local restored = base:ToWorldSpace(localCf)
print("还原世界位置:", restored.Position)

Lerp

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

在当前 CFrame 与 goal 之间进行插值，alpha 为插值系数（Float），返回新的 CFrame；位置采用线性插值，旋转采用球面插值。

参数	类型	说明
goal	CFrame	插值目标 CFrame
alpha	Float	插值系数

返回值 CFrame

示例代码

在两个 CFrame 之间插值

-- @runtime client
local start = CFrame.New(0, 0, 0)
local goal = CFrame.New(10, 0, 0)
local mid = start:Lerp(goal, 0.5)
print("中点位置:", mid.Position)
local quarter = start:Lerp(goal, 0.25)
print("四分之一位置:", quarter.Position)

Orthonormalize

签名：Orthonormalize() -> CFrame

对 CFrame 的旋转部分执行 Gram-Schmidt 正交化，修正数值漂移，无参数，返回 CFrame。

返回值 CFrame

示例代码

正交化坐标帧的旋转基

-- @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（other）和一个容差（epsilon，Float），返回 Bool 表示两者是否在该容差内一致。

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

返回值 Bool

示例代码

按误差阈值比较两个 CFrame

-- @runtime client
-- 构造两个仅位置有极小差异的 CFrame
local a = CFrame.New(0, 0, 0)
local b = CFrame.New(0, 0, 0.0001)
-- epsilon 控制允许误差，返回 Bool
local similar = a:FuzzyEq(b, 0.01)
print("近似相等:", similar)
local c = CFrame.New(10, 0, 0)
print("远距离比较:", a:FuzzyEq(c, 0.01))

LookAt

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

创建朝向目标位置的 CFrame；实例重载使用当前实例的位置，静态重载使用 at 参数指定的位置。

⚙ LookAt 同时存在实例方法与静态工厂方法：cf:LookAt(target, up) 使用 cf 当前的位置；CFrame.LookAt(at, target, up) 使用显式 at 位置。两者参数数量不同，不要把静态示例写进实例签名。

完整重载签名

重载 1：LookAt(target: Vector3（希望朝向的世界坐标点）, up: Vector3（参考上方向，用于消除滚转自由度，默认 (0,1,0)）) -> CFrame (local)

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

重载 2：LookAt(at: Vector3（新 CFrame 的位置）, target: Vector3（希望朝向的目标点）, up: Vector3（参考上方向，用于消除滚转自由度，默认 (0,1,0)）) -> CFrame (global)

构造一个位于 at 点、LookVector 指向 target 点的 CFrame

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

返回值 CFrame

示例代码

区分实例 LookAt 与静态 LookAt

-- @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)

PointToWorldSpace

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

把局部坐标点变换到世界坐标，参数 point 为 Vector3，返回 Vector3。

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

返回值 Vector3

示例代码

局部坐标点转世界坐标

-- @runtime client
local cf = CFrame.New(10, 0, 0)
local localPoint = Vector3.New(1, 2, 3)
local worldPoint = cf:PointToWorldSpace(localPoint)
print("世界坐标:", worldPoint)
print("世界 Y 分量:", worldPoint.y)

PointToObjectSpace

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

把世界坐标点变换到当前 CFrame 的局部坐标，参数 point 为 Vector3，返回 Vector3。

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

返回值 Vector3

示例代码

世界坐标点转局部坐标

-- @runtime client
local cf = CFrame.New(10, 0, 0)
local worldPoint = Vector3.New(13, 2, 0)
local localPoint = cf:PointToObjectSpace(worldPoint)
print("局部坐标:", localPoint)
print("局部 X 分量:", localPoint.x)

VectorToWorldSpace

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

把局部方向向量变换到世界方向，参数 vector 为 Vector3，返回 Vector3，忽略位移。

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

返回值 Vector3

示例代码

局部方向向量转世界方向

-- @runtime client
local cf = CFrame.New(10, 0, 0)
local localDir = Vector3.New(1, 0, 0)
local worldDir = cf:VectorToWorldSpace(localDir)
print("世界方向:", worldDir)
print("世界方向 Y 分量:", worldDir.y)

VectorToObjectSpace

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

把世界方向向量变换到当前 CFrame 的局部方向，参数 vector 为 Vector3，返回 Vector3，忽略位移。

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

返回值 Vector3

示例代码

世界方向向量转局部方向

-- @runtime client
local cf = CFrame.New(10, 0, 0)
local worldDir = Vector3.New(1, 0, 0)
local localDir = cf:VectorToObjectSpace(worldDir)
print("局部方向:", localDir)
print("局部方向 Z 分量:", localDir.z)

ToEulerAnglesXYZ

签名：ToEulerAnglesXYZ() -> Float (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

把 CFrame 的旋转部分分解为外部 XYZ 顺序的欧拉角，返回 X、Y、Z 三个 Float（弧度）。

返回值 Float (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

示例代码

按 XYZ 顺序提取欧拉角

-- @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 (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

把 CFrame 的旋转部分分解为外部 YXZ 顺序的欧拉角，返回 X、Y、Z 三个 Float（弧度）。

返回值 Float (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

示例代码

按 YXZ 顺序提取欧拉角

-- @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 (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

按 order（Int）指定的旋转顺序，把 CFrame 的旋转部分分解为三个欧拉角（Float，弧度）。

⚙ 当前 Meta 将 order 声明为 Int，但没有公开对应的命名枚举。契约补齐前请使用 ToEulerAnglesXYZ() 或 ToEulerAnglesYXZ()，不要用数字或虚构的枚举成员绕过。

参数	类型	说明
order	Int	旋转顺序；当前 Meta 未公开对应的命名枚举，契约补齐前请改用固定顺序方法。

返回值 Float (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

ToOrientation

签名：ToOrientation() -> Float (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

把 CFrame 的旋转部分按 YXZ 顺序分解为三个朝向角度（Float，弧度），效果等同 ToEulerAnglesYXZ。

返回值 Float (X轴旋转（弧度）), Float (Y轴旋转（弧度）), Float (Z轴旋转（弧度）)

示例代码

提取朝向角

-- @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）和旋转角度（Float，弧度），返回两个值。

返回值 Vector3 (旋转轴), Float (旋转角度（弧度）)

示例代码

提取 CFrame 的轴角表示

-- @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 与 other 两个 CFrame 的旋转部分之间的夹角，参数 other 为 CFrame，返回 Float（弧度）。

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

返回值 Float

示例代码

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

-- @runtime client
local a = CFrame.New(0, 0, 0)
local b = CFrame.FromAxisAngle(Vector3.New(0, 1, 0), math.rad(90))
local angle = a:AngleBetween(b)
print("夹角(弧度):", angle)
print("夹角(角度):", math.deg(angle))

GetComponents

签名：GetComponents() -> Float (位置 X), Float (位置 Y), Float (位置 Z), Float (旋转矩阵 [0][0]), Float (旋转矩阵 [0][1]), Float (旋转矩阵 [0][2]), Float (旋转矩阵 [1][0]), Float (旋转矩阵 [1][1]), Float (旋转矩阵 [1][2]), Float (旋转矩阵 [2][0]), Float (旋转矩阵 [2][1]), Float (旋转矩阵 [2][2])

一次性获取 CFrame 的全部 12 个分量：位置 x、y、z，以及 3×3 旋转矩阵的 9 个元素（行优先），返回 12 个 Float。

返回值 Float (位置 X), Float (位置 Y), Float (位置 Z), Float (旋转矩阵 [0][0]), Float (旋转矩阵 [0][1]), Float (旋转矩阵 [0][2]), Float (旋转矩阵 [1][0]), Float (旋转矩阵 [1][1]), Float (旋转矩阵 [1][2]), Float (旋转矩阵 [2][0]), Float (旋转矩阵 [2][1]), Float (旋转矩阵 [2][2])

示例代码

分解 CFrame 的位置与旋转分量

-- @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))

New

签名：New() -> CFrame (构造得到的 CFrame。)

构造 CFrame，支持多个重载：无参（单位 CFrame）、仅位置向量、位置 + 朝向目标点、x/y/z 三个数值、x/y/z + 四元数、x/y/z + 行优先旋转矩阵。

完整重载签名

重载 1：New(无参数) -> CFrame (构造得到的 CFrame。) (global)

Identity CFrame

重载 2：New(pos: Vector3) -> CFrame (构造得到的 CFrame。) (global)

仅位置

重载 3：New(pos: Vector3, lookAt: Vector3) -> CFrame (构造得到的 CFrame。) (global)

位置+朝向

重载 4：New(x: Float, y: Float, z: Float) -> CFrame (构造得到的 CFrame。) (global)

仅位置（xyz）

重载 5：New(x: Float, y: Float, z: Float, qX: Float, qY: Float, qZ: Float, qW: Float) -> CFrame (构造得到的 CFrame。) (global)

位置+四元数

重载 6：New(x: Float, y: Float, z: Float, R00: Float, R01: Float, R02: Float, R10: Float, R11: Float, R12: Float, R20: Float, R21: Float, R22: Float) -> CFrame (构造得到的 CFrame。) (global)

位置+旋转矩阵（行优先）

返回值 CFrame (构造得到的 CFrame。)

示例代码

使用多种重载构造 CFrame

-- @runtime client
local cf = CFrame.New(1, 2, 3)
print("xyz 重载位置:", cf.Position)
local fromVec = CFrame.New(Vector3.New(4, 5, 6))
print("Vector3 重载位置:", fromVec.Position)
local shorthand = CFrame(7, 8, 9)
print("简写构造位置:", shorthand.Position)

Identity

签名：Identity() -> CFrame

表示单位 CFrame，即位于原点且不带旋转的坐标帧。

返回值 CFrame

示例代码

获取单位 CFrame

-- @runtime client
local cf = CFrame.Identity()
print("位置 X:", cf.X)
print("位置 Y:", cf.Y)
print("位置 Z:", cf.Z)
print("朝向:", cf.LookVector)

FromMatrix

签名：FromMatrix(pos: Vector3, vX: Vector3, vY: Vector3, vZ: Vector3) -> CFrame (由位置和基向量构造得到的 CFrame。)

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

⚙ FromMatrix 当前公开形态是 CFrame.FromMatrix(pos, vX, vY[, vZ])，不是 Matrix 单参构造；已有 Matrix 实例不能直接传给 CFrame.FromMatrix。当前运行包实测会触发 userdata 到 Matrix3x3 的隐式转换错误，属于 SDK 实现问题，不是参数数量问题。

完整重载签名

重载 1：FromMatrix(pos: Vector3（新 CFrame 的位置。）, vX: Vector3（旋转矩阵的 X 列向量。）, vY: Vector3（旋转矩阵的 Y 列向量。）, vZ: Vector3（旋转矩阵的 Z 列向量；可省略，由 vX 与 vY 推导。）) -> CFrame (由位置和基向量构造得到的 CFrame。) (global)

位置+三列向量

重载 2：FromMatrix(pos: Vector3（新 CFrame 的位置。）, vX: Vector3（旋转矩阵的 X 列向量。）, vY: Vector3（旋转矩阵的 Y 列向量。）) -> CFrame (由位置和基向量构造得到的 CFrame。) (global)

位置+两列向量（vZ 由 vX:Cross(vY) 推导）

参数	类型	说明
pos	Vector3	新 CFrame 的位置。
vX	Vector3	旋转矩阵的 X 列向量。
vY	Vector3	旋转矩阵的 Y 列向量。
vZ	Vector3	旋转矩阵的 Z 列向量；可省略，由 vX 与 vY 推导。

返回值 CFrame (由位置和基向量构造得到的 CFrame。)

示例代码

当前版本使用 LookAlong 替代 FromMatrix

-- @runtime client
local pos = Vector3.New(0, 3, 0)
local direction = Vector3.New(0, 0, -1)
local up = Vector3.New(0, 1, 0)

-- 当前运行包的 FromMatrix 存在类型转换错误，先用公开的 LookAlong 替代
local cf = CFrame.LookAlong(pos, direction, up)
print("CFrame 位置:", cf.Position)

LookAlong

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

CFrame.LookAlong 是 CFrame 类型上的构造接口，接收位置 at、前向方向 dir 与上方向 up 三个 Vector3 参数，返回一个新的 CFrame。返回结果的位置为 at，朝向沿 dir 方向，上方向由 up 决定。

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

返回值 CFrame

示例代码

按指定方向构造 CFrame

-- @runtime client
local at = Vector3.New(0, 5, 0)
local dir = Vector3.New(0, 0, 1)
local up = Vector3.New(0, 1, 0)
local cf = CFrame.LookAlong(at, dir, up)
print("位置:", cf.Position)
print("朝向:", cf.LookVector)

FromAxisAngle

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

根据旋转轴 axis（Vector3）与旋转角度 angle（Float，弧度）构造 CFrame，返回 CFrame。

参数	类型	说明
axis	Vector3	旋转轴的单位向量
angle	Float	绕轴旋转的角度，单位为弧度

返回值 CFrame

示例代码

按旋转轴和角度构造 CFrame

-- @runtime client
local axis = Vector3.New(0, 1, 0)
local angle = math.rad(90)
local cf = CFrame.FromAxisAngle(axis, angle)
print("位置:", cf.Position)
print("朝向:", cf.LookVector)

FromEulerAnglesXYZ

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

从外部 XYZ 顺序的三个欧拉角分量（rx、ry、rz，Float，弧度）构造 CFrame，返回 CFrame。

参数	类型	说明
rx	Float	绕 X 轴旋转的角度，单位为弧度
ry	Float	绕 Y 轴旋转的角度，单位为弧度
rz	Float	绕 Z 轴旋转的角度，单位为弧度

返回值 CFrame

示例代码

按 XYZ 顺序构造欧拉角旋转

-- @runtime client
local cf = CFrame.FromEulerAnglesXYZ(0, math.rad(90), 0)
print("位置:", cf.Position)
print("朝向:", cf.LookVector)
local rx, ry, rz = cf:ToEulerAnglesXYZ()
print("回读欧拉角:", rx, ry, rz)

FromEulerAnglesYXZ

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

从外部 YXZ 顺序的三个欧拉角分量（rx、ry、rz，Float，弧度）构造 CFrame。

参数	类型	说明
rx	Float	绕 X 轴旋转的角度，单位为弧度
ry	Float	绕 Y 轴旋转的角度，单位为弧度
rz	Float	绕 Z 轴旋转的角度，单位为弧度

返回值 CFrame

示例代码

按 YXZ 顺序构造欧拉角旋转

-- @runtime client
local cf = CFrame.FromEulerAnglesYXZ(math.rad(30), math.rad(45), 0)
print("位置:", cf.Position)
local rx, ry, rz = cf:ToEulerAnglesYXZ()
print("回读 X 轴旋转:", rx)
print("回读 Y 轴旋转:", ry)
print("回读 Z 轴旋转:", rz)

FromOrientation

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

从朝向角度（rx、ry、rz，Float，弧度）构造 CFrame，是 FromEulerAnglesYXZ 的别名，使用 YXZ 顺序。

参数	类型	说明
rx	Float	绕 X 轴旋转的角度，单位为弧度
ry	Float	绕 Y 轴旋转的角度，单位为弧度
rz	Float	绕 Z 轴旋转的角度，单位为弧度

返回值 CFrame

示例代码

按朝向角度构造 CFrame

-- @runtime client
local cf = CFrame.FromOrientation(0, math.rad(90), 0)
print("位置:", cf.Position)
print("朝向:", cf.LookVector)
local rx, ry, rz = cf:ToOrientation()
print("回读欧拉角:", rx, ry, rz)

FromEulerAngles

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

按 order（Int）指定的旋转顺序，从三个欧拉角分量（rx、ry、rz，Float，弧度）构造 CFrame。

⚙ 当前 Meta 将 order 声明为 Int，但没有公开对应的命名枚举。契约补齐前请使用 FromEulerAnglesXYZ(...) 或 FromEulerAnglesYXZ(...)，不要用数字或虚构的枚举成员绕过。

参数	类型	说明
rx	Float	绕 X 轴旋转的角度，单位为弧度
ry	Float	绕 Y 轴旋转的角度，单位为弧度
rz	Float	绕 Z 轴旋转的角度，单位为弧度
order	Int	旋转顺序；当前 Meta 未公开对应的命名枚举，契约补齐前请改用固定顺序方法。

返回值 CFrame

FromRotationBetweenVectors

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

根据起始向量 from 与目标向量 to（均为 Vector3），构造表示两者之间最短旋转的 CFrame。

参数	类型	说明
from	Vector3	起始方向向量
to	Vector3	目标方向向量

返回值 CFrame

示例代码

构造从一个向量转向另一个向量的旋转

-- @runtime client
local from = Vector3.New(0, 0, 1)
local to = Vector3.New(1, 0, 0)
local rotation = CFrame.FromRotationBetweenVectors(from, to)
print("位置:", rotation.Position)
print("朝向:", rotation.LookVector)