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...
Vector3
A 3D vector using floating-point coordinates.
說明
包含三個元素的結構體，可用於代表 3D 座標或任何數值的三元組。
使用浮點數座標。預設情況下，這些浮點值為 32 位精度，與始終為 64 位的 float 並不相同。如果需要雙精度，請在編譯引擎時使用 precision=double 選項。
對應的整數版本見 Vector3i。
注意：在布林語境中，如果 Vector3 等於 Vector3(0, 0, 0) 則求值結果為 false。否則 Vector3 的求值結果始終為 true。
教學
屬性
|
||
|
||
|
建構子
Vector3() |
|
方法
abs() const |
|
bezier_derivative(control_1: Vector3, control_2: Vector3, end: Vector3, t: float) const |
|
bezier_interpolate(control_1: Vector3, control_2: Vector3, end: Vector3, t: float) const |
|
ceil() const |
|
cubic_interpolate(b: Vector3, pre_a: Vector3, post_b: Vector3, weight: float) const |
|
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 |
|
direction_to(to: Vector3) const |
|
distance_squared_to(to: Vector3) const |
|
distance_to(to: Vector3) const |
|
floor() const |
|
inverse() const |
|
is_equal_approx(to: Vector3) const |
|
is_finite() const |
|
is_normalized() const |
|
is_zero_approx() const |
|
length() const |
|
length_squared() const |
|
limit_length(length: float = 1.0) const |
|
max_axis_index() const |
|
min_axis_index() const |
|
move_toward(to: Vector3, delta: float) const |
|
normalized() const |
|
octahedron_decode(uv: Vector2) static |
|
octahedron_encode() const |
|
round() const |
|
sign() const |
|
signed_angle_to(to: Vector3, axis: Vector3) const |
|
運算子
operator !=(right: Vector3) |
|
operator *(right: Basis) |
|
operator *(right: Quaternion) |
|
operator *(right: Transform3D) |
|
operator *(right: Vector3) |
|
operator *(right: float) |
|
operator *(right: int) |
|
operator +(right: Vector3) |
|
operator -(right: Vector3) |
|
operator /(right: Vector3) |
|
operator /(right: float) |
|
operator /(right: int) |
|
operator <(right: Vector3) |
|
operator <=(right: Vector3) |
|
operator ==(right: Vector3) |
|
operator >(right: Vector3) |
|
operator >=(right: Vector3) |
|
operator [](index: int) |
|
列舉
enum Axis: 🔗
Axis AXIS_X = 0
X 軸的列舉值。由 max_axis_index() 和 min_axis_index() 返回。
Axis AXIS_Y = 1
Y 軸的列舉值。由 max_axis_index() 和 min_axis_index() 返回。
Axis 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 素材背面（後方）的單位向量。
屬性說明
向量的 X 分量。也可以通過使用索引位置 [0] 存取。
向量的 Y 分量。也可以通過使用索引位置 [1] 存取。
向量的 Z 分量。也可以通過使用索引位置 [2] 存取。
建構子說明
建構預設初始化的 Vector3，所有分量都設定為 0。
Vector3 Vector3(from: Vector3)
建構給定 Vector3 的副本。
Vector3 Vector3(from: Vector3i)
從 Vector3i 建構新的 Vector3。
Vector3 Vector3(x: float, y: float, z: float)
返回具有給定分量的 Vector3。
方法說明
返回一個新向量，其所有分量都是絕對值，即正值。
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 🔗
Returns the vector "bounced off" from a plane defined by the given normal n.
Note: bounce() performs the operation that most engines and frameworks call reflect().
返回一個新向量，所有的分量都是向上四捨五入（正無窮大方向）。
Vector3 clamp(min: Vector3, max: Vector3) const 🔗
返回一個新向量，每個分量都使用 @GlobalScope.clamp() 限制在 min 和 max 之間。
Vector3 clampf(min: float, max: float) const 🔗
Returns a new vector with all components clamped between min and max, by running @GlobalScope.clamp() on each component.
Vector3 cross(with: Vector3) const 🔗
Returns the cross product of this vector and with.
This returns a vector perpendicular to both this and with, which would be the normal vector of the plane defined by the two vectors. As there are two such vectors, in opposite directions, this method returns the vector defined by a right-handed coordinate system. If the two vectors are parallel this returns an empty vector, making it useful for testing if two vectors are parallel.
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 🔗
Performs a cubic interpolation between this vector and b using pre_a and post_b as handles, and returns the result at position weight. weight is on the range of 0.0 to 1.0, representing the amount of interpolation.
It can perform smoother interpolation than cubic_interpolate() by the time values.
Vector3 direction_to(to: Vector3) const 🔗
返回從該向量指向 to 的正規化向量。相當於使用 (b - a).normalized()。
float distance_squared_to(to: Vector3) const 🔗
Returns the squared Euclidean distance between this vector and to.
This method runs faster than distance_to(), so prefer it if you need to compare vectors or need the squared distance for some formula.
float distance_to(to: Vector3) const 🔗
Returns the Euclidean distance between this vector and 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(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()。
如果該向量無窮，則返回 true，判斷方法是對每個分量呼叫 @GlobalScope.is_finite()。
如果該向量是正規化的，即長度約等於 1，則返回 true。
如果該向量的值大約為零，則返回 true，判斷方法是對每個分量運作 @GlobalScope.is_zero_approx()。
該方法比使用 is_equal_approx() 和零向量比較要快。
返回這個向量的長度，即大小。
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 🔗
Returns the vector with a maximum length by limiting its length to length. If the vector is non-finite, the result is undefined.
Vector3 max(with: Vector3) const 🔗
Returns the component-wise maximum of this and with, equivalent to Vector3(maxf(x, with.x), maxf(y, with.y), maxf(z, with.z)).
返回該向量中最大值的軸。見 AXIS_* 常數。如果所有分量相等，則該方法返回 AXIS_X。
Vector3 maxf(with: float) const 🔗
Returns the component-wise maximum of this and with, equivalent to Vector3(maxf(x, with), maxf(y, with), maxf(z, with)).
Vector3 min(with: Vector3) const 🔗
Returns the component-wise minimum of this and with, equivalent to Vector3(minf(x, with.x), minf(y, with.y), minf(z, with.z)).
返回該向量中最小值的軸。見 AXIS_* 常數。如果所有分量相等，則該方法返回 AXIS_Z。
Vector3 minf(with: float) const 🔗
Returns the component-wise minimum of this and with, equivalent to Vector3(minf(x, with), minf(y, with), minf(z, with)).
Vector3 move_toward(to: Vector3, delta: float) const 🔗
返回一個新向量，該向量朝 to 移動了固定的量 delta。不會超過最終值。
Returns the result of scaling the vector to unit length. Equivalent to v / v.length(). Returns (0, 0, 0) if v.length() == 0. See also is_normalized().
Note: This function may return incorrect values if the input vector length is near zero.
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 🔗
Returns a new vector resulting from projecting this vector onto the given vector b. The resulting new vector is parallel to b. See also slide().
Note: If the vector b is a zero vector, the components of the resulting new vector will be @GDScript.NAN.
Vector3 reflect(n: Vector3) const 🔗
Returns the result of reflecting the vector through a plane defined by the given normal vector n.
Note: reflect() differs from what other engines and frameworks call reflect(). In other engines, reflect() returns the result of the vector reflected by the given plane. The reflection thus passes through the given normal. While in Godot the reflection passes through the plane and can be thought of as bouncing off the normal. See also bounce() which does what most engines call reflect().
Vector3 rotated(axis: Vector3, angle: float) const 🔗
返回將這個向量圍繞給定的軸旋轉 angle（單位為弧度）的結果。旋轉軸必須為正規化的向量。另見 @GlobalScope.deg_to_rad()。
返回所有分量都被四捨五入為最接近的整數的向量，中間情況向遠離零的方向四捨五入。
返回新的向量，分量如果為正則設為 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 🔗
Returns a new vector resulting from sliding this vector along a plane with normal n. The resulting new vector is perpendicular to n, and is equivalent to this vector minus its projection on n. See also project().
Note: The vector n must be normalized. See also normalized().
Vector3 snapped(step: Vector3) const 🔗
返回新的向量，每個分量都吸附到了與 step 中對應分量最接近的倍數。也可以用於將分量四捨五入至小數點後的任意位置。
Vector3 snappedf(step: float) const 🔗
Returns a new vector with each component snapped to the nearest multiple of step. This can also be used to round the components to an arbitrary number of decimals.
運算子說明
bool operator !=(right: Vector3) 🔗
如果向量不相等，則返回 true。
注意：由於浮點數精度誤差，請考慮改用 is_equal_approx()，會更可靠。
注意：包含 @GDScript.NAN 元素的向量的行為與其他向量不同。因此，如果包含 NaN，則這個方法的結果可能不準確。
Vector3 operator *(right: Basis) 🔗
Inversely transforms (multiplies) the Vector3 by the given Basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
vector * basis is equivalent to basis.transposed() * vector. See Basis.transposed().
For transforming by inverse of a non-orthonormal basis (e.g. with scaling) basis.inverse() * vector can be used instead. See Basis.inverse().
Vector3 operator *(right: Quaternion) 🔗
Inversely transforms (multiplies) the Vector3 by the given Quaternion.
vector * quaternion is equivalent to quaternion.inverse() * vector. See Quaternion.inverse().
Vector3 operator *(right: Transform3D) 🔗
Inversely transforms (multiplies) the Vector3 by the given Transform3D transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
vector * transform is equivalent to transform.inverse() * vector. See Transform3D.inverse().
For transforming by inverse of an affine transformation (e.g. with scaling) transform.affine_inverse() * vector can be used instead. See Transform3D.affine_inverse().
Vector3 operator *(right: Vector3) 🔗
Multiplies each component of the Vector3 by the components of the given Vector3.
print(Vector3(10, 20, 30) * Vector3(3, 4, 5)) # Prints (30.0, 80.0, 150.0)
Vector3 operator *(right: float) 🔗
將該 Vector3 的每個分量乘以給定的 float。
Vector3 operator *(right: int) 🔗
將該 Vector3 的每個分量乘以給定的 int。
Vector3 operator +(right: Vector3) 🔗
Adds each component of the Vector3 by the components of the given Vector3.
print(Vector3(10, 20, 30) + Vector3(3, 4, 5)) # Prints (13.0, 24.0, 35.0)
Vector3 operator -(right: Vector3) 🔗
Subtracts each component of the Vector3 by the components of the given Vector3.
print(Vector3(10, 20, 30) - Vector3(3, 4, 5)) # Prints (7.0, 16.0, 25.0)
Vector3 operator /(right: Vector3) 🔗
Divides each component of the Vector3 by the components of the given Vector3.
print(Vector3(10, 20, 30) / Vector3(2, 5, 3)) # Prints (5.0, 4.0, 10.0)
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 的負值。和寫 Vector3(-v.x, -v.y, -v.z) 是一樣的。該操作在保持相同幅度的同時，翻轉向量的方向。對於浮點數，零也有正負兩種。