Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Quaternion
代表 3D 旋转的单位四元数。
描述
内置的 Quaternion（四元数）Variant 类型是一种 4D 数据结构，它以 哈密顿约定四元数 的形式来表示旋转。与可以同时存储旋转和缩放的 Basis（基）类型相比，四元数 只能 存储旋转。
一个 Quaternion 由 4 个浮点数分量组成：w、x、y 和 z。这些分量在内存中非常紧凑，因此某些运算不仅效率更高，而且更不容易产生浮点误差。像 get_angle()（获取角度）、get_axis()（获取轴）和 slerp()（球面线性插值）这类方法，都比它们在 Basis 中对应的方法运行得更快。
如果想深入了解四元数，推荐观看 3Blue1Brown 的这个视频。不过，你并不需要完全搞懂四元数背后的复杂数学原理，因为 Godot 提供了许多辅助方法来帮你处理这些。这些方法包括 slerp() 和 spherical_cubic_interpolate()（球面三次插值），以及 * 运算符。
注意： 四元数在用于旋转之前必须先进行归一化（详见 normalized()）。
注意： 和 Vector2、Vector3 类似，四元数的分量默认使用 32 位精度，这与始终为 64 位的 float 类型不同。如果需要双精度，请使用 precision=double 选项来编译引擎。
注意： 在布尔值（boolean）上下文中，如果一个四元数等于 IDENTITY（单位四元数），它将评估为 false。否则，四元数永远都会评估为 true。
备注
通过 C# 使用该 API 时会有显著不同，详见 C# API 与 GDScript 的差异。
教程
属性
|
||
|
||
|
||
|
构造函数
Quaternion(from: Quaternion) |
|
Quaternion(arc_from: Vector3, arc_to: Vector3) |
|
Quaternion(axis: Vector3, angle: float) |
|
Quaternion(from: Basis) |
|
Quaternion(x: float, y: float, z: float, w: float) |
方法
angle_to(to: Quaternion) const |
|
dot(with: Quaternion) const |
|
exp() const |
|
from_euler(euler: Vector3) static |
|
get_angle() const |
|
get_axis() const |
|
inverse() const |
|
is_equal_approx(to: Quaternion) const |
|
is_finite() const |
|
is_normalized() const |
|
length() const |
|
length_squared() const |
|
log() const |
|
normalized() const |
|
slerp(to: Quaternion, weight: float) const |
|
slerpni(to: Quaternion, weight: float) const |
|
spherical_cubic_interpolate(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float) const |
|
spherical_cubic_interpolate_in_time(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float, b_t: float, pre_a_t: float, post_b_t: float) const |
运算符
operator !=(right: Quaternion) |
|
operator *(right: Quaternion) |
|
operator *(right: Vector3) |
|
operator *(right: float) |
|
operator *(right: int) |
|
operator +(right: Quaternion) |
|
operator -(right: Quaternion) |
|
operator /(right: float) |
|
operator /(right: int) |
|
operator ==(right: Quaternion) |
|
operator [](index: int) |
|
常量
IDENTITY = Quaternion(0, 0, 0, 1) 🔗
单位四元数，代表无旋转。这与 Basis.IDENTITY 具有相同的旋转。
如果一个 Vector3 被该四元数旋转（乘以），则它不会改变。
注意：在 GDScript 中，该常量等价于不带任何参数创建 Quaternion。可以用来让代码更加清晰，并且与 C# 保持一致。
属性说明
四元数的 W 分量。这是“实数”的部分。
注意：四元数分量通常不应被直接操作。
四元数的 X 分量。这是沿“虚数” i 轴的值。
注意：四元数分量通常不应被直接操作。
四元数的 Y 分量。这是沿“虚数” j 轴的值。
注意：四元数分量通常不应被直接操作。
四元数的 Z 分量。这是沿“虚数” k 轴的值。
注意：四元数分量通常不应被直接操作。
构造函数说明
Quaternion Quaternion() 🔗
构造与 IDENTITY 相同的 Quaternion。
注意：在 C# 中构造的 Quaternion 的所有分量都为 0.0。
Quaternion Quaternion(from: Quaternion)
构造给定 Quaternion 的副本。
Quaternion Quaternion(arc_from: Vector3, arc_to: Vector3)
构造一个表示 arc_from 和 arc_to 之间最短弧的 Quaternion。这些可以想象为与球体表面相交的两个点，球面半径为 1.0。
Quaternion Quaternion(axis: Vector3, angle: float)
构造一个 Quaternion，表示围绕 axis 旋转给定的 angle 弧度。该轴必须是一个归一化向量。
Quaternion Quaternion(from: Basis)
根据给定的旋转 Basis 构造一个 Quaternion。
该构造函数比 Basis.get_rotation_quaternion() 更快，但给定的基必须是正交归一化的（请参阅 Basis.orthonormalized()）。否则，构造函数将失败并返回 IDENTITY。
Quaternion Quaternion(x: float, y: float, z: float, w: float)
构造一个由给定值定义的 Quaternion。
注意：只有归一化的四元数才表示旋转；如果这些值没有归一化，则新的 Quaternion 将不是有效的旋转。
方法说明
float angle_to(to: Quaternion) const 🔗
返回这个四元数与 to 之间的角度。这是从一个旋转到另一个旋转所需的角度大小。
注意：该方法的浮点数误差异常地高，因此 is_zero_approx 等方法的结果不可靠。
float dot(with: Quaternion) const 🔗
返回该四元数与 with 的点积。
等价于 (quat.x * with.x) + (quat.y * with.y) + (quat.z * with.z) + (quat.w * with.w)。
Quaternion exp() const 🔗
返回该四元数的指数。该结果的旋转轴是该四元数的归一化旋转轴，该结果的角度是该四元数的向量部分的长度。
Quaternion from_euler(euler: Vector3) static 🔗
根据给定的 Euler angles（以弧度为单位）构造一个新的 Quaternion（四元数）。在 Godot 中，欧拉角始终使用内旋顺序。该方法始终使用内旋 YXZ 约定（即 @GlobalScope.EULER_ORDER_YXZ）。
返回该四元数表示的旋转角度。
注意：该四元数必须被归一化。
返回该四元数表示的旋转的旋转轴。
Vector3 get_euler(order: int = 2) const 🔗
将此四元数的旋转角度以 欧拉角 Vector3 的形式返回，单位为弧度。
可以通过 order 参数来改变每个连续旋转的顺序（详见 EulerOrder 常量）。在 Godot 中，欧拉角始终使用内旋（intrinsic）顺序。默认情况下，使用的是内旋 YXZ 约定（即 @GlobalScope.EULER_ORDER_YXZ）：由于这是一个分解过程，因此会先计算局部 Z 轴（滚转/roll），然后是局部 X 轴（俯仰/pitch），最后是局部 Y 轴（偏航/yaw）。当使用反向方法 from_euler() 来合成旋转时，这个顺序则是相反的。
Quaternion inverse() const 🔗
返回该四元数的逆版本，反转除 w 之外的每个分量的符号。
bool is_equal_approx(to: Quaternion) const 🔗
如果该四元数和 to 近似相等，则返回 true，判断方法是通过对每个分量调用 @GlobalScope.is_equal_approx()。
如果该四元数是有限的，则返回 true，判断方法是在每个分量上调用 @GlobalScope.is_finite()。
如果该四元数已被归一化，则返回 true。另见 normalized()。
返回该四元数的长度，也被称为幅度。
float length_squared() const 🔗
返回该四元数的长度的平方。
注意：该方法比 length() 更快，因此如果你只需要比较四元数的长度，则优先使用它。
Quaternion log() const 🔗
返回该四元数的对数。将该四元数的旋转轴乘以它的旋转角度，并将结果存储在返回的四元数的向量部分（x、y 和 z）中。返回的四元数的实数部分（w）始终为 0.0。
Quaternion normalized() const 🔗
返回该四元数的副本，已归一化，因此其长度为 1.0。另见 is_normalized()。
Quaternion slerp(to: Quaternion, weight: float) const 🔗
使用 to 四元数，在给定 weight 下执行球面线性插值并返回结果。该四元数和 to 都必须已归一化。
Quaternion slerpni(to: Quaternion, weight: float) const 🔗
在给定 weight 的情况下，使用 to 四元数执行球面线性插值并返回结果。与 slerp() 不同，该方法不检查旋转路径是否小于 90 度。该四元数和 to 都必须是归一化的。
Quaternion spherical_cubic_interpolate(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float) const 🔗
在四元数 pre_a、这个向量、b 以及 post_b 之间按照给定的 weight 进行球面三次插值。
Quaternion spherical_cubic_interpolate_in_time(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float, b_t: float, pre_a_t: float, post_b_t: float) const 🔗
在四元数 pre_a、该向量、b 和 post_b 之间，按给定量 weight 执行三次球面插值。
它可以根据时间值执行比 spherical_cubic_interpolate() 更平滑的插值。
运算符说明
bool operator !=(right: Quaternion) 🔗
如果两个四元数的分量不完全相等，则返回 true。
注意：由于浮点精度误差，请考虑改用 is_equal_approx()，这样更可靠。
Quaternion operator *(right: Quaternion) 🔗
组合（相乘）两个四元数。这会由该四元数（父项）旋转 right 四元数（子项）。
Vector3 operator *(right: Vector3) 🔗
由该四元数旋转（乘以） right 向量，返回一个 Vector3。
Quaternion operator *(right: float) 🔗
将该 Quaternion 的每个分量乘以右侧的 float 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator *(right: int) 🔗
将该 Quaternion 的每个分量乘以右侧 int 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator +(right: Quaternion) 🔗
将左侧 Quaternion 的每个分量添加到右侧 Quaternion。
该操作本身没有意义，但可以用作更大表达式的一部分，例如用于近似两个相邻旋转之间的中间旋转。
Quaternion operator -(right: Quaternion) 🔗
将左侧 Quaternion 的每个分量减去右侧 Quaternion。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator /(right: float) 🔗
将该 Quaternion 的每个分量除以右侧 float 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator /(right: int) 🔗
将该 Quaternion 的每个分量除以右侧的 int 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
bool operator ==(right: Quaternion) 🔗
如果两个四元数的分量完全相等，则返回 true。
注意：由于浮点精度误差，请考虑改用 is_equal_approx()，这样更可靠。
float operator [](index: int) 🔗
通过索引访问该四元数的每个分量。
索引 0 与 x 相同，索引 1 与 y 相同，索引 2 与 z 相同，索引 3 与 w 相同。
Quaternion operator unary+() 🔗
返回与 + 不存在时相同的值。单目 + 没有作用，但有时可以使你的代码更具可读性。
Quaternion operator unary-() 🔗
返回该 Quaternion 的负值。这与将所有分量乘以 -1 相同。这个操作得到的是代表相同旋转的四元数。