Transform

概览

字段	值
Kind	Data · 数据 Data
Realm	common

Transform 表示由位移、旋转与缩放组合而成的三维变换，可通过 Translation（或 Position）、Rotation、Scale 属性读写各分量，并借助 LookVector、UpVector、RightVector 获取变换后的坐标轴方向。它提供 Apply、ApplyDirection、PointToWorldSpace、VectorToWorldSpace 等函数在局部空间与世界空间之间转换点与方向，也支持 Inverse 与 GetInverse 求逆、Lerp 与 InterpolateTransforms 插值、ToMatrix 输出矩阵表示。构造上还提供 Identity、FromMatrix、FromEulerAngles、FromAxisAngle、LookAt 等辅助入口。

适用场景

当需要把局部坐标下的点或方向换算到世界空间、或把世界空间的目标位置换算回局部空间时使用；在需要把位移、旋转与缩放作为一个整体参与复合、求逆与插值运算的场合也很常见。

使用要点

先通过 Transform.New(translation, rotation, scale) 或等价简写 Transform(...) 创建实例，缩放参数可省略；也可用 Transform.Identity()、Transform.FromMatrix(matrix)、Transform.FromEulerAngles(rx, ry, rz)、Transform.FromAxisAngle(axis, angle) 或 Transform.LookAt(at, lookAt, up) 构造特定变换。随后用 GetPosition 与 SetPosition、GetOrientation 与 SetOrientation 读写位移和旋转分量，用 transform:PointToWorldSpace(v) 与 transform:VectorToWorldSpace(v) 分别变换点和方向（前者应用位移，后者忽略位移），反向操作对应 PointToObjectSpace 与 VectorToObjectSpace。需要复合、求逆、插值或矩阵表示时，分别调用 transform:Transform(other)、transform:Inverse() 或 transform:GetInverse()、transform:Lerp(goal, alpha) 或 Transform.InterpolateTransforms(a, b, t)、以及 transform:ToMatrix()。

注意事项

Transform 实例通过 Transform.New(...) 或 Transform(...) 构造，用于组合位移、旋转与缩放。PointToWorldSpace 用于点变换，会应用位移；VectorToWorldSpace 用于方向变换，会忽略位移。Quaternion.FromEulerAngles 的参数按弧度传入；按角度思考时可使用 math.rad(...) 转换。

代码示例

构造非退化 Transform 并变换点

-- @runtime client
local transform = Transform.New(
    Vector3.New(10, 5, 0),
    Quaternion.FromEulerAngles(0, math.rad(45), 0),
    Vector3.New(1, 1, 1)
)
local worldPoint = transform:PointToWorldSpace(Vector3.New(1, 0, 0))
print('世界坐标:', worldPoint)

属性 (7)

Name	类型	默认值	说明
Translation	Vector3	-	Translation 是可读写的 Vector3 属性，表示 Transform 的位移部分。
Position	Vector3	-	Position 是可读写的 Vector3 属性，表示 Transform 的位移，作为 Translation 的别名存在。
Rotation	Quaternion	-	Rotation 是可读写的 Quaternion 属性，表示 Transform 的旋转部分。
Scale	Vector3	-	Scale 是可读写的 Vector3 属性，表示 Transform 的缩放。
LookVector	Vector3	-	LookVector 是只读的 Vector3 属性，表示 Transform 的前向向量。
UpVector	Vector3	-	UpVector 是只读的 Vector3 属性，表示 Transform 的上方向向量。
RightVector	Vector3	-	RightVector 是只读的 Vector3 属性，表示 Transform 的右方向向量。

关联类型

• Quaternion
• Vector3

函数 (27)

New

签名：New(translation: Vector3, rotation: Quaternion, scale?: Vector3) -> Transform

New 是 Transform 的构造方法，接收位移（Vector3）与旋转（Quaternion），并可选接收缩放（Vector3），返回一个新的 Transform 实例。

参数	类型	说明
translation	Vector3	-
rotation	Quaternion	-
scale?	Vector3	缩放（默认 (1,1,1)）

返回值 Transform

示例代码

构造 Transform（位置+旋转+缩放）

-- @runtime client
local t = Transform.New(
    Vector3.New(10, 5, 0),       -- 位置
    Quaternion.FromAxisAngle(Vector3.New(0,1,0), 1.5708),  -- 旋转
    Vector3.New(1, 1, 1)         -- 缩放
)
print('Transform 已创建:', tostring(t))

Identity

签名：Identity() -> Transform

返回一个单位 Transform，即无平移、无旋转、缩放为 (1,1,1) 的变换。

返回值 Transform

示例代码

获取单位 Transform

-- @runtime client
local t = Transform.Identity()
print('单位 Transform:', tostring(t))

FromMatrix

签名：FromMatrix(matrix: Matrix) -> Transform

FromMatrix 从 4x4 矩阵创建一个 Transform，返回新的 Transform 实例。

参数	类型	说明
matrix	Matrix	-

返回值 Transform

示例代码

从矩阵构造 Transform

-- @runtime client
local m = Matrix.Identity()
local t = Transform.FromMatrix(m)
print('从矩阵构造的 Transform:', tostring(t))

InterpolateTransforms

签名：InterpolateTransforms(a: Transform, b: Transform, t: Float) -> Transform

在两个 Transform 之间进行插值，根据参数 t 返回中间变换。

参数	类型	说明
a	Transform	-
b	Transform	-
t	Float	插值因子 [0, 1]

返回值 Transform

示例代码

在两个 Transform 之间插值

-- @runtime client
local startTransform = Transform.Identity()
local endTransform = Transform.New(
    Vector3.New(10, 0, 0),
    Quaternion.FromEulerAngles(0, math.rad(90), 0),
    Vector3.New(2, 2, 2)
)
local halfway = Transform.InterpolateTransforms(startTransform, endTransform, 0.5)
print('中间位置:', halfway.Position)

GetPosition

签名：GetPosition() -> Vector3

GetPosition 返回当前 Transform 的位置，结果类型为 Vector3。

返回值 Vector3

示例代码

读取 Transform 的位置

-- @runtime client
local transform = Transform.New(Vector3.New(10, 5, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
print('位置:', transform:GetPosition())

SetPosition

签名：SetPosition(pos: Vector3) -> void

SetPosition 设置当前 Transform 的位置，参数为 Vector3。

参数	类型	说明
pos	Vector3	-

返回值 void

示例代码

设置 Transform 的位置

-- @runtime client
local transform = Transform.Identity()
transform:SetPosition(Vector3.New(10, 5, 0))
print('新位置:', transform:GetPosition())

GetOrientation

签名：GetOrientation() -> Quaternion

GetOrientation 返回当前 Transform 的旋转，结果类型为 Quaternion。

返回值 Quaternion

示例代码

读取 Transform 的旋转

-- @runtime client
local rot = Quaternion.FromEulerAngles(math.rad(45), 0, 0)
local t = Transform(Vector3(0, 0, 0), rot, Vector3(1, 1, 1))
local q = t:GetOrientation()
print("旋转四元数:", q.x, q.y, q.z, q.w)

SetOrientation

签名：SetOrientation(quat: Quaternion) -> void

SetOrientation 设置当前 Transform 的旋转，参数为 Quaternion。

参数	类型	说明
quat	Quaternion	-

返回值 void

示例代码

设置 Transform 的旋转

-- @runtime client
local t = Transform(Vector3(0, 0, 0), Quaternion.Identity(), Vector3(1, 1, 1))
local rot = Quaternion.FromEulerAngles(0, math.rad(90), 0)
t:SetOrientation(rot)
print("旋转已更新")

SetToIdentity

签名：SetToIdentity() -> void

将当前 Transform 重置为单位 Transform。

返回值 void

示例代码

重置为单位 Transform

-- @runtime client
local t = Transform(
    Vector3.New(10, 5, 0),
    Quaternion.FromEulerAngles(0, math.rad(45), 0),
    Vector3.New(2, 2, 2)
)
t:SetToIdentity()
print('重置后位置和缩放:', t.Position, t.Scale)

GetInverse

签名：GetInverse() -> Transform

返回当前 Transform 的逆变换。

返回值 Transform

示例代码

获取逆 Transform 副本

-- @runtime client
local transform = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local inverse = transform:GetInverse()
print('逆变换位置:', inverse.Position)

Inverse

签名：Inverse() -> Transform

返回当前 Transform 的逆变换，与 GetInverse 功能相同。

返回值 Transform

示例代码

返回当前 Transform 的逆变换

-- @runtime client
local t = Transform(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local inverse = t:Inverse()
local origin = inverse:Apply(t.Position)
print('逆变换后的原位置:', origin)

IsValid

签名：IsValid() -> Bool

检查 Transform 的位移、旋转和缩放分量是否构成有效变换，例如不包含 NaN 或无穷值且旋转有效。

返回值 Bool

示例代码

检查 Transform 是否有效

-- @runtime client
local transform = Transform.Identity()
print('单位 Transform 是否有效:', transform:IsValid())

Transform

签名：Transform(other: Transform) -> Transform

将当前 Transform 与另一个 Transform 组合，返回 self * other（先应用 other，再应用 self）。

参数	类型	说明
other	Transform	-

返回值 Transform

示例代码

组合两个 Transform

-- @runtime client
local base = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local offset = Transform.New(Vector3.New(0, 2, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local combined = base:Transform(offset)
print('组合后位置:', combined.Position)

Apply

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

Apply 对一个点应用当前 Transform，返回变换后的 Vector3 点。

参数	类型	说明
point	Vector3	-

返回值 Vector3

示例代码

将 Transform 应用到点

-- @runtime client
local transform = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local worldPoint = transform:Apply(Vector3.New(1, 2, 3))
print('世界坐标:', worldPoint)

ApplyDirection

签名：ApplyDirection(dir: Vector3) -> Vector3

ApplyDirection 对一个方向向量应用当前 Transform 并忽略平移，返回变换后的 Vector3。

参数	类型	说明
dir	Vector3	-

返回值 Vector3

示例代码

对方向应用 Transform

-- @runtime client
local rot = Quaternion.FromEulerAngles(0, math.rad(90), 0)
local t = Transform(Vector3(5, 0, 0), rot, Vector3(1, 1, 1))
local localDir = Vector3(1, 0, 0)
local worldDir = t:ApplyDirection(localDir)
print("世界方向:", worldDir.x, worldDir.y, worldDir.z)

ToMatrix

签名：ToMatrix() -> Matrix

ToMatrix 将当前 Transform 转换为 4x4 矩阵，返回 Matrix。

返回值 Matrix

示例代码

转换为 Matrix

-- @runtime client
local transform = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local matrix = transform:ToMatrix()
print('矩阵平移:', matrix.Translation)

Lerp

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

对当前 Transform 和目标 Transform 进行线性插值，返回中间变换。

参数	类型	说明
goal	Transform	-
alpha	Float	-

返回值 Transform

示例代码

插值到目标 Transform

-- @runtime client
local startTransform = Transform.Identity()
local goal = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local halfway = startTransform:Lerp(goal, 0.5)
print('中间位置:', halfway.Position)

ToWorldSpace

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

将本地空间中的 Transform 转换到世界空间。

参数	类型	说明
cf	Transform	-

返回值 Transform

示例代码

将局部 Transform 转到世界空间

-- @runtime client
local parent = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local localTransform = Transform.New(Vector3.New(0, 2, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local worldTransform = parent:ToWorldSpace(localTransform)
print('世界位置:', worldTransform.Position)

ToObjectSpace

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

将世界空间中的 Transform 转换到当前 Transform 的本地空间。

参数	类型	说明
cf	Transform	-

返回值 Transform

示例代码

将世界 Transform 转到局部空间

-- @runtime client
local parent = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local worldTransform = Transform.New(Vector3.New(10, 2, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
local localTransform = parent:ToObjectSpace(worldTransform)
print('局部位置:', localTransform.Position)

PointToWorldSpace

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

PointToWorldSpace 将一个点从当前 Transform 的本地空间转换到世界空间，返回 Vector3。

参数	类型	说明
v	Vector3	-

返回值 Vector3

示例代码

将局部点转到世界空间

-- @runtime client
local transform = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
print('世界坐标:', transform:PointToWorldSpace(Vector3.New(1, 2, 3)))

PointToObjectSpace

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

PointToObjectSpace 将一个点从世界空间转换到当前 Transform 的本地空间，返回 Vector3。

参数	类型	说明
v	Vector3	-

返回值 Vector3

示例代码

将世界点转到局部空间

-- @runtime client
local transform = Transform.New(Vector3.New(10, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
print('局部坐标:', transform:PointToObjectSpace(Vector3.New(11, 2, 3)))

VectorToWorldSpace

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

VectorToWorldSpace 将一个方向向量从本地空间转换到世界空间，返回 Vector3。

参数	类型	说明
v	Vector3	-

返回值 Vector3

示例代码

本地方向转世界方向

-- @runtime client
local rot = Quaternion.FromEulerAngles(0, math.rad(90), 0)
local t = Transform(Vector3(0, 0, 0), rot, Vector3(1, 1, 1))
local localDir = Vector3(1, 0, 0)
local worldDir = t:VectorToWorldSpace(localDir)
print("世界方向:", worldDir.x, worldDir.y, worldDir.z)

VectorToObjectSpace

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

VectorToObjectSpace 将一个方向向量从世界空间转换到当前 Transform 的本地空间，返回 Vector3。

参数	类型	说明
v	Vector3	-

返回值 Vector3

示例代码

世界方向转本地方向

-- @runtime client
local rot = Quaternion.FromEulerAngles(0, math.rad(90), 0)
local t = Transform(Vector3(0, 0, 0), rot, Vector3(1, 1, 1))
local worldDir = Vector3(0, 0, -1)
local localDir = t:VectorToObjectSpace(worldDir)
print("本地方向:", localDir.x, localDir.y, localDir.z)

FuzzyEq

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

判断当前 Transform 与另一个 Transform 是否在给定误差范围内近似相等。

参数	类型	说明
other	Transform	-
epsilon	Float	-

返回值 Bool

示例代码

用容差比较 Transform

-- @runtime client
local first = Transform.Identity()
local second = Transform.New(Vector3.New(0.0001, 0, 0), Quaternion.Identity(), Vector3.New(1, 1, 1))
print('近似相等:', first:FuzzyEq(second, 0.001))

FromEulerAngles

签名：FromEulerAngles(rx: Float, ry: Float, rz: Float) -> Transform

根据欧拉角（ZXY 旋转顺序）创建一个纯旋转的 Transform，平移为 (0,0,0)，缩放为 (1,1,1)。

参数	类型	说明
rx	Float	-
ry	Float	-
rz	Float	-

返回值 Transform

示例代码

从欧拉角构造旋转部分

-- @runtime client
local t = Transform.FromEulerAngles(0.5, 0.3, 0.1)
print('欧拉角 Transform:', tostring(t))

FromAxisAngle

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

FromAxisAngle 从轴与角度创建一个 Transform，返回新的 Transform 实例。

参数	类型	说明
axis	Vector3	-
angle	Float	-

返回值 Transform

示例代码

从轴角构造旋转部分

-- @runtime client
local t = Transform.FromAxisAngle(Vector3.New(0,1,0), 1.5708)
print('轴角 Transform:', tostring(t))

LookAt

签名：LookAt(at: Vector3, lookAt: Vector3, up: Vector3) -> Transform

LookAt 构造一个朝向目标点的 Transform，返回新的 Transform 实例。

参数	类型	说明
at	Vector3	-
lookAt	Vector3	-
up	Vector3	-

返回值 Transform

示例代码

构造朝向目标点的 Transform

-- @runtime client
local at = Vector3.New(0, 2, 0)
local target = Vector3.New(10, 2, 0)
local up = Vector3.New(0, 1, 0)
local transform = Transform.LookAt(at, target, up)
print('位置:', transform.Position, '前向:', transform.LookVector)