Vector3

使用浮点数坐标的 3D 向量。

描述

包含三个元素的结构体，可用于代表 3D 坐标或任何数值的三元组。

使用浮点数坐标。默认情况下，这些浮点值为 32 位精度，与始终为 64 位的 float 并不相同。如果需要双精度，请在编译引擎时使用 precision=double 选项。

对应的整数版本见 Vector3i。

注意：在布尔语境中，如果 Vector3 等于 Vector3(0, 0, 0) 则求值结果为 false。否则 Vector3 的求值结果始终为 true。

教程

• 数学文档索引

• 向量数学

• 高等向量数学

• 3Blue1Brown《线性代数的本质》

• 矩阵变换演示

• 所有 3D 演示

属性

构造函数

方法

运算符

常量

AXIS_X = 0 🔗

X 轴的枚举值。由 max_axis_index 和 min_axis_index 返回。

AXIS_Y = 1 🔗

Y 轴的枚举值。由 max_axis_index 和 min_axis_index 返回。

AXIS_Z = 2 🔗

Z 轴的枚举值。由 max_axis_index 和 min_axis_index 返回。

ZERO = Vector3(0, 0, 0) 🔗

零向量，所有分量都设置为 0 的向量。

ONE = Vector3(1, 1, 1) 🔗

一向量，所有分量都设置为 1 的向量。

INF = Vector3(inf, inf, inf) 🔗

无穷大向量，所有分量都设置为 @GDScript.INF 的向量。

LEFT = Vector3(-1, 0, 0) 🔗

左单位向量。代表局部的左方向，全局的西方向。

RIGHT = Vector3(1, 0, 0) 🔗

右单位向量。代表局部的右方向，全局的东方向。

UP = Vector3(0, 1, 0) 🔗

上单位向量。

DOWN = Vector3(0, -1, 0) 🔗

下单位向量。

FORWARD = Vector3(0, 0, -1) 🔗

向前的单位向量。代表局部的前方，全局的北方。请注意，灯光、相机等的前方和角色等 3D 资产的前方是不同的，后者通常朝向相机。处理 3D 资产空间时，请使用 MODEL_FRONT 等常量。

BACK = Vector3(0, 0, 1) 🔗

向后的单位向量。代表局部的后方，全局的南方。

MODEL_LEFT = Vector3(1, 0, 0) 🔗

指向导入后 3D 资产左侧的单位向量。

MODEL_RIGHT = Vector3(-1, 0, 0) 🔗

指向导入后 3D 资产右侧的单位向量。

MODEL_TOP = Vector3(0, 1, 0) 🔗

指向导入后 3D 资产顶部（上方）的单位向量。

MODEL_BOTTOM = Vector3(0, -1, 0) 🔗

指向导入后 3D 资产底部（下方）的单位向量。

MODEL_FRONT = Vector3(0, 0, 1) 🔗

指向导入后 3D 资产正面（前方）的单位向量。

MODEL_REAR = Vector3(0, 0, -1) 🔗

指向导入后 3D 资产背面（后方）的单位向量。

属性说明

float x = 0.0 🔗

向量的 X 分量。也可以通过使用索引位置 [0] 访问。

float y = 0.0 🔗

向量的 Y 分量。也可以通过使用索引位置 [1] 访问。

float z = 0.0 🔗

向量的 Z 分量。也可以通过使用索引位置 [2] 访问。

构造函数说明

Vector3 Vector3() 🔗

构造默认初始化的 Vector3，所有分量都设置为 0。

Vector3 Vector3(from: Vector3)

构造给定 Vector3 的副本。

Vector3 Vector3(from: Vector3i)

从 Vector3i 构造新的 Vector3。

Vector3 Vector3(x: float, y: float, z: float)

返回具有给定分量的 Vector3。

方法说明

Vector3 abs() const 🔗

返回一个新向量，其所有分量都是绝对值，即正值。

float angle_to(to: Vector3) const 🔗

返回与给定向量的无符号最小角度，单位为弧度。

Vector3 bezier_derivative(control_1: Vector3, control_2: Vector3, end: Vector3, t: float) const 🔗

返回贝赛尔曲线上 t 处的导数，该曲线由此向量和控制点 control_1、control_2、终点 end 定义。

Vector3 bezier_interpolate(control_1: Vector3, control_2: Vector3, end: Vector3, t: float) const 🔗

返回贝赛尔曲线上 t 处的点，该曲线由此向量和控制点 control_1、control_2、终点 end 定义。

Vector3 bounce(n: Vector3) const 🔗

返回从给定法线 n 定义的平面“弹起”的向量。

注意：bounce 执行大多数引擎和框架调用 reflect() 的操作。

Vector3 ceil() const 🔗

返回一个新向量，所有的分量都是向上舍入（正无穷大方向）。

Vector3 clamp(min: Vector3, max: Vector3) const 🔗

返回一个新向量，每个分量都使用 @GlobalScope.clamp 限制在 min 和 max 之间。

Vector3 clampf(min: float, max: float) const 🔗

返回一个新向量，每个分量都使用 @GlobalScope.clamp 限制在 min 和 max 之间。

Vector3 cross(with: Vector3) const 🔗

返回该向量与 with 的叉积。

这将返回一个垂直于该向量和 with 的向量，它将是两个向量定义的平面的法向量。由于有两个这样的向量，方向相反，该方法返回由右手坐标系定义的向量。如果这两个向量平行，则返回一个空向量，这使其可用于测试两个向量是否平行。

Vector3 cubic_interpolate(b: Vector3, pre_a: Vector3, post_b: Vector3, weight: float) const 🔗

返回该向量和 b 之间进行三次插值 weight 处的结果，使用 pre_a 和 post_b 作为控制柄。weight 在 0.0 到 1.0 的范围内，代表插值的量。

Vector3 cubic_interpolate_in_time(b: Vector3, pre_a: Vector3, post_b: Vector3, weight: float, b_t: float, pre_a_t: float, post_b_t: float) const 🔗

返回该向量和 b 之间进行三次插值 weight 处的结果，使用 pre_a 和 post_b 作为控制柄。weight 在 0.0 到 1.0 的范围内，代表插值的量。

通过使用时间值，可以比 cubic_interpolate 进行更平滑的插值。

Vector3 direction_to(to: Vector3) const 🔗

返回从该向量指向 to 的归一化向量。相当于使用 (b - a).normalized()。

float distance_squared_to(to: Vector3) const 🔗

返回该向量与 to 之间的距离的平方。

该方法比 distance_to 运行得更快，因此请在需要比较向量或者用于某些公式的平方距离时，优先使用这个方法。

float distance_to(to: Vector3) const 🔗

返回该向量与 to 之间的距离。

float dot(with: Vector3) const 🔗

Returns the dot product of this vector and with. This can be used to compare the angle between two vectors. For example, this can be used to determine whether an enemy is facing the player.

The dot product will be 0 for a right angle (90 degrees), greater than 0 for angles narrower than 90 degrees and lower than 0 for angles wider than 90 degrees.

When using unit (normalized) vectors, the result will always be between -1.0 (180 degree angle) when the vectors are facing opposite directions, and 1.0 (0 degree angle) when the vectors are aligned.

Note: a.dot(b) is equivalent to b.dot(a).

Vector3 floor() const 🔗

返回一个新的向量，所有的向量都被四舍五入，向负无穷大。

Vector3 inverse() const 🔗

返回该向量的逆向量。与 Vector3(1.0 / v.x, 1.0 / v.y, 1.0 / v.z) 相同。

bool is_equal_approx(to: Vector3) const 🔗

如果这个向量与 to 大致相等，则返回 true，判断方法是对每个分量执行 @GlobalScope.is_equal_approx。

bool is_finite() const 🔗

如果该向量无穷，则返回 true，判断方法是对每个分量调用 @GlobalScope.is_finite。

bool is_normalized() const 🔗

如果该向量是归一化的，即长度约等于 1，则返回 true。

bool is_zero_approx() const 🔗

如果该向量的值大约为零，则返回 true，判断方法是对每个分量运行 @GlobalScope.is_zero_approx。

该方法比使用 is_equal_approx 和零向量比较要快。

float length() const 🔗

返回这个向量的长度，即大小。

float length_squared() const 🔗

返回这个向量的平方长度，即平方大小。

这个方法比 length 运行得更快，所以如果你需要比较向量或需要一些公式的平方距离时，更喜欢用它。

Vector3 lerp(to: Vector3, weight: float) const 🔗

返回此向量和 to 之间，按数量 weight 线性插值结果。weight 在 0.0 到 1.0 的范围内，代表插值的量。

Vector3 limit_length(length: float = 1.0) const 🔗

返回应用了最大长度限制的向量，长度被限制到 length。

Vector3 max(with: Vector3) const 🔗

返回自身与 with 各分量的最大值，等价于 Vector3(maxf(x, with.x), maxf(y, with.y), maxf(z, with.z))。

int max_axis_index() const 🔗

返回该向量中最大值的轴。见 AXIS_* 常量。如果所有分量相等，则该方法返回 AXIS_X。

Vector3 maxf(with: float) const 🔗

返回自身与 with 各分量的最大值，等价于 Vector3(maxf(x, with), maxf(y, with), maxf(z, with))。

Vector3 min(with: Vector3) const 🔗

返回自身与 with 各分量的最小值，等价于 Vector3(minf(x, with.x), minf(y, with.y), minf(z, with.z))。

int min_axis_index() const 🔗

返回该向量中最小值的轴。见 AXIS_* 常量。如果所有分量相等，则该方法返回 AXIS_Z。

Vector3 minf(with: float) const 🔗

返回自身与 with 各分量的最小值，等价于 Vector3(minf(x, with), minf(y, with), minf(z, with))。

Vector3 move_toward(to: Vector3, delta: float) const 🔗

返回一个新向量，该向量朝 to 移动了固定的量 delta。不会超过最终值。

Vector3 normalized() const 🔗

返回该向量缩放至单位长度的结果。等价于 v / v.length()。如果 v.length() == 0 则返回 (0, 0, 0)。另见 is_normalized。

注意：如果输入向量的长度接近零，则这个函数可能返回不正确的值。

Vector3 octahedron_decode(uv: Vector2) static 🔗

根据使用 octahedron_encode 进行八面体压缩后的形式（存储为 Vector2）返回 Vector3。

Vector2 octahedron_encode() const 🔗

将该 Vector3 的八面体编码（oct32）形式作为一个 Vector2 返回。由于 Vector2 占用的内存比 Vector3 少 1/3，因此这种压缩形式可用于传递更多的 normalized Vector3，而不会增加存储或内存需求。另见 octahedron_decode。

注意：octahedron_encode 只能用于 normalized 向量。octahedron_encode 不检查这个 Vector3 是否已归一化，如果该 Vector3 没有被归一化，将返回一个不解压缩到原始值的值。

注意：八面体压缩是有损的，尽管视觉差异在现实世界场景中很难被察觉。

Basis outer(with: Vector3) const 🔗

返回与 with 的外积。

Vector3 posmod(mod: float) const 🔗

返回由该向量的分量与 mod 执行 @GlobalScope.fposmod 运算后组成的向量。

Vector3 posmodv(modv: Vector3) const 🔗

返回由该向量的分量与 modv 的分量执行 @GlobalScope.fposmod 运算后组成的向量。

Vector3 project(b: Vector3) const 🔗

返回将该向量投影到给定的 b 向量上所得到的新向量。得到的新向量与 b 平行。另见 slide。

注意：如果 b 向量为零向量，得到的新向量的分量均为 @GDScript.NAN。

Vector3 reflect(n: Vector3) const 🔗

返回通过给定法线向量 n 定义的平面反射向量的结果。

注意：reflect 与其他引擎和框架调用的 reflect() 不同。在其他引擎中，reflect() 返回由给定平面反射的向量的结果。因此反射穿过给定的法线。而在 Godot 中，反射穿过平面，可以被认为是从法线反弹。另请参阅 bounce，它执行大多数引擎调用的 reflect()。

Vector3 rotated(axis: Vector3, angle: float) const 🔗

返回将这个向量围绕给定的轴旋转 angle（单位为弧度）的结果。旋转轴必须为归一化的向量。另见 @GlobalScope.deg_to_rad。

Vector3 round() const 🔗

返回所有分量都被四舍五入为最接近的整数的向量，中间情况向远离零的方向舍入。

Vector3 sign() const 🔗

返回新的向量，分量如果为正则设为 1.0，如果为负则设为 -1.0，如果为零则设为 0.0。结果与对每个分量调用 @GlobalScope.sign 一致。

float signed_angle_to(to: Vector3, axis: Vector3) const 🔗

返回给定向量的带符号角度，单位为弧度。从 axis 指定的一侧看，该角度在逆时针方向时符号为正，在顺时针方向时符号为负。

Vector3 slerp(to: Vector3, weight: float) const 🔗

返回在这个向量和 to 之间进行 weight 的球面线性插值的结果。weight 在 0.0 和 1.0 的范围内，代表插值的量。

如果输入向量的长度不同，这个函数也会对长度进行插值处理。对于输入向量中存在长度为零的向量的特殊情况，这个方法的行为与 lerp 一致。

Vector3 slide(n: Vector3) const 🔗

返回将该向量沿着法线为 n 的平面滑动所得到的新向量。得到的新向量与 n 垂直，等价于将该向量减去在 n 上的投影。另见 project。

注意：向量 n 必须为归一化的向量。另见 normalized。

Vector3 snapped(step: Vector3) const 🔗

返回新的向量，每个分量都吸附到了与 step 中对应分量最接近的倍数。也可以用于将分量四舍五入至小数点后的任意位置。

Vector3 snappedf(step: float) const 🔗

返回一个新向量，其中每个分量都吸附到 step 的最接近的倍数。这也可以用于将分量四舍五入为任意数位的小数。

运算符说明

bool operator !=(right: Vector3) 🔗

如果向量不相等，则返回 true。

注意：由于浮点数精度误差，请考虑改用 is_equal_approx，会更可靠。

注意：包含 @GDScript.NAN 元素的向量的行为与其他向量不同。因此，如果包含 NaN，则这个方法的结果可能不准确。

Vector3 operator *(right: Basis) 🔗

假设该基是正交的（即旋转/反射可以，缩放/倾斜则不然），将 Vector3 逆向变换（乘以）给定的 Basis 矩阵。

vector * basis 性当于 basis.transposed() * vector。请参阅 Basis.transposed。

对于通过非正交的基的逆进行的变换（例如使用缩放），可以使用 basis.inverse() * vector 代替。请参阅 Basis.inverse。

Vector3 operator *(right: Quaternion) 🔗

将 Vector3 与给定的 Quaternion 进行逆向变换（相乘）。

vector * quaternion 相当于 quaternion.inverse() * vector。请参阅 Quaternion.inverse。

Vector3 operator *(right: Transform3D) 🔗

假设该变换的基是正交的（即旋转/反射可以，缩放/倾斜不行），将 Vector3 逆向变换（乘以）给定的 Transform3D 变换矩阵。

vector * transform 相当于 transform.inverse() * vector。请参阅 Transform3D.inverse。

对于通过仿射变换的逆进行的变换（例如缩放），可以使用 transform.affine_inverse() * vector 代替。请参阅 Transform3D.affine_inverse。

Vector3 operator *(right: Vector3) 🔗

将该 Vector3 的每个分量乘以给定 Vector3 的对应分量。

print(Vector3(10, 20, 30) * Vector3(3, 4, 5)) # 输出 "(30, 80, 150)"

Vector3 operator *(right: float) 🔗

将该 Vector3 的每个分量乘以给定的 float。

Vector3 operator *(right: int) 🔗

将该 Vector3 的每个分量乘以给定的 int。

Vector3 operator +(right: Vector3) 🔗

将该 Vector3 的每个分量加上给定 Vector3 的对应分量。

print(Vector3(10, 20, 30) + Vector3(3, 4, 5)) # 输出 "(13, 24, 35)"

Vector3 operator -(right: Vector3) 🔗

将该 Vector3 的每个分量减去给定 Vector3 的对应分量。

print(Vector3(10, 20, 30) - Vector3(3, 4, 5)) # 输出 "(7, 16, 25)"

Vector3 operator /(right: Vector3) 🔗

将该 Vector3 的每个分量除以给定 Vector3 的对应分量。

print(Vector3(10, 20, 30) / Vector3(2, 5, 3)) # 输出 "(5, 4, 10)"

Vector3 operator /(right: float) 🔗

将该 Vector3 的每个分量除以给定的 float。

Vector3 operator /(right: int) 🔗

将该 Vector3 的每个分量除以给定的 int。

bool operator <(right: Vector3) 🔗

比较两个 Vector3 向量，首先检查左向量的 X 值是否小于 right 向量的 X 值。如果 X 值完全相等，则用相同的方法检查两个向量的 Y 值、Z 值。该运算符可用于向量排序。

注意：包含 @GDScript.NAN 元素的向量的行为与其他向量不同。因此，如果包含 NaN，则这个方法的结果可能不准确。

bool operator <=(right: Vector3) 🔗

比较两个 Vector3 向量，首先检查左向量的 X 值是否小于等于 right 向量的 X 值。如果 X 值完全相等，则用相同的方法检查两个向量的 Y 值、Z 值。该运算符可用于向量排序。

注意：包含 @GDScript.NAN 元素的向量的行为与其他向量不同。因此，如果包含 NaN，则这个方法的结果可能不准确。

bool operator ==(right: Vector3) 🔗

如果向量完全相等，则返回 true。

注意：由于浮点数精度误差，请考虑改用 is_equal_approx，会更可靠。

注意：包含 @GDScript.NAN 元素的向量的行为与其他向量不同。因此，如果包含 NaN，则这个方法的结果可能不准确。

bool operator >(right: Vector3) 🔗

比较两个 Vector3 向量，首先检查左向量的 X 值是否大于 right 向量的 X 值。如果 X 值完全相等，则用相同的方法检查两个向量的 Y 值、Z 值。该运算符可用于向量排序。

注意：包含 @GDScript.NAN 元素的向量的行为与其他向量不同。因此，如果包含 NaN，则这个方法的结果可能不准确。

bool operator >=(right: Vector3) 🔗

比较两个 Vector3 向量，首先检查左向量的 X 值是否大于等于 right 向量的 X 值。如果 X 值完全相等，则用相同的方法检查两个向量的 Y 值、Z 值。该运算符可用于向量排序。

注意：包含 @GDScript.NAN 元素的向量的行为与其他向量不同。因此，如果包含 NaN，则这个方法的结果可能不准确。

float operator [](index: int) 🔗

使用向量分量的 index 来访问向量分量。v[0] 等价于 v.x，v[1] 等价于 v.y，v[2] 等价于 v.z。

Vector3 operator unary+() 🔗

返回与 + 不存在时相同的值。单目 + 没有作用，但有时可以使你的代码更具可读性。

Vector3 operator unary-() 🔗

返回该 Vector3 的负值。和写 Vector3(-v.x, -v.y, -v.z) 是一样的。该操作在保持相同幅度的同时，翻转向量的方向。对于浮点数，零也有正负两种。