Matrix

概览

字段	值
Kind	Data · 数据 Data
Realm	common

Matrix 是描述平移、旋转与缩放复合变换的数学数据结构，同时以 Translation、Rotation、Scale 三个分量和 Right、Up、Forward 方向向量暴露内部状态，并可通过 Pitch、Yaw、Roll 读取按 ZXY 顺序解释的欧拉角。它既提供 New、Identity、Zero、FromEulerAngles 等构造与工厂入口，也提供 Inverse、GetInverse、Transpose、Apply 等运算，用来求逆、转置以及把向量送入变换后的坐标系。借助 MakeOrient、MakeRotation、MakeRotationBetween 等函数，还可以直接由方向向量或旋转轴生成朝向与旋转分量。

适用场景

当需要在局部坐标与场景坐标之间互相换算，或需要对一个方向向量施加旋转与平移时，可以构造 Matrix（例如 Matrix.New 或 Matrix.FromEulerAngles），再用 Apply 取得变换后的向量；反向换算则使用 Inverse 或 GetInverse。需要处理朝向对齐时，可用 MakeOrient 依据前向与上方向构造朝向，或用 MakeRotationBetween 求两个方向之间的旋转。

使用要点

先通过 Matrix.New(translation, rotation, scale) 或等价简写 Matrix(translation, rotation, scale) 创建实例，三个参数依次为 Vector3 平移、Quaternion 旋转与 Vector3 缩放；只需要单位变换或零矩阵时使用 Matrix.Identity() 与 Matrix.Zero()。构造完成后读取 Translation、Rotation、Scale、Right、Up、Forward 或 Pitch、Yaw、Roll 获取分解结果，再调用 Apply 把 Vector3 送入该变换。需要逆向结果时调用 Inverse 或 GetInverse，需要转置结果时调用 Transpose；也可以先用 MakeOrient、MakeRotation、MakeRotationX、MakeRotationY、MakeRotationZ、MakeRotationBetween 生成旋转分量后再参与组合。

注意事项

Matrix 实例通过 Matrix.New(translation, rotation, scale)、Matrix(translation, rotation, scale) 或 Matrix.Identity() 等公开构造/工厂方法获取；Rotation 属性为 Quaternion 类型，Pitch、Yaw、Roll 按 ZXY 顺序解释。

代码示例

构造平移、旋转与缩放矩阵

-- @runtime client
local translation = Vector3.New(10, 20, 30)
local rotation = Quaternion.FromEulerAngles(0, math.rad(90), 0)  -- 绕 Y 轴 90 度
local scale = Vector3.New(1, 2, 1)
local matrix = Matrix.New(translation, rotation, scale)
print('矩阵:', tostring(matrix))

属性 (9)

Name	类型	默认值	说明
Translation	Vector3	-	可读写属性，类型为 Vector3，表示矩阵中的平移分量。
Rotation	Quaternion	-	可读写属性，类型为 Quaternion，表示矩阵中的旋转分量。
Scale	Vector3	-	可读写属性，类型为 Vector3，表示矩阵中的缩放分量。
Right	Vector3	-	只读属性，类型为 Vector3，表示该矩阵的局部右方向轴。
Up	Vector3	-	只读属性，类型为 Vector3，表示该矩阵的局部上方向轴。
Forward	Vector3	-	只读属性，类型为 Vector3，表示该矩阵的局部前方向轴。
Pitch	Float	-	只读属性，类型为 Float，表示矩阵旋转的俯仰角（ZXY 顺序，弧度）。
Yaw	Float	-	只读属性，类型为 Float，表示矩阵旋转的偏航角（ZXY 顺序，弧度）。
Roll	Float	-	只读属性，类型为 Float，表示矩阵旋转的翻滚角（ZXY 顺序，弧度）。

关联类型

• Quaternion
• Vector3

函数 (14)

New

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

由平移、旋转、缩放三个分量构造一个新的 Matrix（4x4 矩阵）并返回该实例。

参数	类型	说明
translation	Vector3	-
rotation	Quaternion	-
scale	Vector3	-

返回值 Matrix

示例代码

构造平移、旋转与缩放矩阵

-- @runtime client
local translation = Vector3.New(10, 20, 30)
local rotation = Quaternion.FromEulerAngles(0, math.rad(90), 0)  -- 绕 Y 轴 90 度
local scale = Vector3.New(1, 2, 1)
local matrix = Matrix.New(translation, rotation, scale)
print('矩阵:', tostring(matrix))

Identity

签名：Identity() -> Matrix

返回一个单位矩阵，无平移、无旋转、缩放为 1。

返回值 Matrix

示例代码

获取单位矩阵

-- @runtime client
local m = Matrix.Identity()
print('单位矩阵已创建:', tostring(m))

Zero

签名：Zero() -> Matrix

返回一个零矩阵，无平移、无旋转、缩放为 0。

返回值 Matrix

示例代码

调用示例

-- @runtime client
local result = Matrix.Zero()  -- 返回 Matrix
if result ~= nil then
    print(result)
    local resultText = tostring(result)
    print(resultText)
end

FromEulerAngles

签名：FromEulerAngles(x: Float, y: Float, z: Float) -> Matrix

根据欧拉角（弧度，ZXY 顺序）构造仅包含旋转的矩阵，平移为零，缩放为 1。

参数	类型	说明
x	Float	Pitch（弧度）
y	Float	Yaw（弧度）
z	Float	Roll（弧度）

返回值 Matrix

示例代码

从欧拉角构造旋转矩阵

-- @runtime client
-- FromEulerAngles 的参数按 Meta 标注传入弧度：pitch, yaw, roll
local m = Matrix.FromEulerAngles(math.rad(30), math.rad(45), 0)
print('旋转矩阵:', tostring(m))

Inverse

签名：Inverse() -> Matrix

原地求逆，将当前矩阵变为其逆矩阵。

返回值 Matrix

示例代码

原地求矩阵的逆

-- @runtime client
local matrix = Matrix.New(
    Vector3.New(5, 0, 0),
    Quaternion.FromEulerAngles(0, 0, math.rad(60)),
    Vector3.New(2, 2, 2)
)
matrix:Inverse()
print('逆矩阵:', tostring(matrix))

GetInverse

签名：GetInverse() -> Matrix

返回当前矩阵的逆矩阵副本，不修改原矩阵。

返回值 Matrix

示例代码

获取逆矩阵副本

-- @runtime client
local matrix = Matrix.New(
    Vector3.New(10, 0, 0),
    Quaternion.FromEulerAngles(0, math.rad(45), 0),
    Vector3.New(1, 1, 1)
)
local inverse = matrix:GetInverse()
print('逆矩阵副本:', tostring(inverse))

Transpose

签名：Transpose() -> Matrix

返回当前矩阵的转置矩阵。

返回值 Matrix

示例代码

转置矩阵

-- @runtime client
local matrix = Matrix.New(
    Vector3.New(0, 0, 0),
    Quaternion.FromEulerAngles(math.rad(45), 0, 0),
    Vector3.New(1, 1, 1)
)
local transposed = matrix:Transpose()
print('转置矩阵:', tostring(transposed))

Apply

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

对传入的 Vector3 应用当前矩阵的变换，并返回变换后的 Vector3。

参数	类型	说明
v	Vector3	-

返回值 Vector3

示例代码

将矩阵变换应用到向量

-- @runtime client
local matrix = Matrix.New(
    Vector3.New(5, 0, 0),
    Quaternion.FromEulerAngles(0, math.rad(90), 0),
    Vector3.New(1, 1, 1)
)
local transformed = matrix:Apply(Vector3.New(1, 0, 0))
print('变换结果:', tostring(transformed))

MakeOrient

签名：MakeOrient(forward: Vector3, up: Vector3) -> void

原地把矩阵构造为朝向旋转：依据传入的前方向 forward 与上方向 up 生成旋转。

参数	类型	说明
forward	Vector3	-
up	Vector3	-

返回值 void

示例代码

构造朝向矩阵

-- @runtime client
local m = Matrix.Identity()  -- 先取得可修改的矩阵实例
m:MakeOrient(Vector3.New(1,0,0), Vector3.New(0,1,0))  -- 原地修改为朝向旋转
print('朝向矩阵:', tostring(m))

MakeRotationX

签名：MakeRotationX(angle: Float) -> void

将当前矩阵原地构造为绕 X 轴旋转指定角度的旋转矩阵。

参数	类型	说明
angle	Float	-

返回值 void

示例代码

构造绕 X 轴的旋转矩阵

-- @runtime client
local m = Matrix.Identity()  -- 先取得可修改的矩阵实例
m:MakeRotationX(1.5708)  -- 原地修改为绕 X 轴 90 度
print('X 轴旋转矩阵:', tostring(m))

MakeRotationY

签名：MakeRotationY(angle: Float) -> void

将当前矩阵原地构造为绕 Y 轴旋转指定角度的旋转矩阵。

参数	类型	说明
angle	Float	-

返回值 void

示例代码

构造绕 Y 轴的旋转矩阵

-- @runtime client
local m = Matrix.Identity()  -- 先取得可修改的矩阵实例
m:MakeRotationY(1.5708)  -- 原地修改为绕 Y 轴 90 度
print('Y 轴旋转矩阵:', tostring(m))

MakeRotationZ

签名：MakeRotationZ(angle: Float) -> void

将当前矩阵原地构造为绕 Z 轴旋转指定角度的旋转矩阵。

参数	类型	说明
angle	Float	-

返回值 void

示例代码

构造绕 Z 轴的旋转矩阵

-- @runtime client
local m = Matrix.Identity()  -- 先取得可修改的矩阵实例
m:MakeRotationZ(1.5708)  -- 原地修改为绕 Z 轴 90 度
print('Z 轴旋转矩阵:', tostring(m))

MakeRotation

签名：MakeRotation(axis: Vector3, angle: Float) -> void

原地把矩阵构造为绕指定轴旋转指定角度的旋转。

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

返回值 void

示例代码

构造绕指定轴的旋转矩阵

-- @runtime client
local m = Matrix.Identity()  -- 先取得可修改的矩阵实例
m:MakeRotation(Vector3.New(0, 1, 0), 1.5708)  -- 原地修改为绕 Y 轴 90 度
print('旋转矩阵:', tostring(m))

MakeRotationBetween

签名：MakeRotationBetween(from: Vector3, to: Vector3) -> void

原地把矩阵构造为将 from 方向对齐到 to 方向的旋转。

参数	类型	说明
from	Vector3	-
to	Vector3	-

返回值 void

示例代码

构造从一向量旋转到另一向量的矩阵

-- @runtime client
local m = Matrix.Identity()  -- 先取得可修改的矩阵实例
m:MakeRotationBetween(Vector3.New(1,0,0), Vector3.New(0,1,0))  -- 原地修改
print('从 X 轴到 Y 轴的旋转矩阵:', tostring(m))