Struct Vector3

#[repr(C)]
pub struct Vector3 {
    pub x: f32,
    pub y: f32,
    pub z: f32,
}

Vector used for 3D math using floating point coordinates.

3-element structure that can be used to represent continuous positions or directions in 3D space, as well as any other triple of numeric values.

It uses floating-point coordinates of 32-bit precision, unlike the engine’s float type which is always 64-bit. The engine can be compiled with the option precision=double to use 64-bit vectors instead; use the gdext library with the double-precision feature in that case.

Conversions are provided via various from_* and to_* functions, not via the From trait. This encourages new() as the main way to construct vectors, is explicit about the conversion taking place, needs no type inference, and works in const contexts.

Navigation to impl blocks within this page

• Constants
• Constructors and general vector functions
• Specialized Vector3 functions
• Float-specific functions
• 3D functions
• 2D and 3D functions
• 3D and 4D functions
• Trait impls + operators

All vector types

Dimension	Floating-point	Integer
2D	Vector2	Vector2i
3D	Vector3	Vector3i
4D	Vector4	Vector4i

You can convert to 2D vectors using to_2d(), and to Vector3i using cast_int().

Godot docs

Vector3 (stable)

Fields

x: f32

The vector’s X component.

y: f32

The vector’s Y component.

z: f32

The vector’s Z component.

Implementations

impl Vector3

Constants

pub const ZERO: Vector3 = _

Zero vector, a vector with all components set to 0.

pub const ONE: Vector3 = _

One vector, a vector with all components set to 1.

pub const INF: Vector3 = _

Infinity vector, a vector with all components set to real::INFINITY.

pub const LEFT: Vector3 = _

Unit vector in -X direction. Can be interpreted as left in an untransformed 3D world.

pub const RIGHT: Vector3 = _

Unit vector in +X direction. Can be interpreted as right in an untransformed 3D world.

pub const UP: Vector3 = _

Unit vector in +Y direction. Typically interpreted as up in a 3D world.

pub const DOWN: Vector3 = _

Unit vector in -Y direction. Typically interpreted as down in a 3D world.

pub const FORWARD: Vector3 = _

Unit vector in -Z direction. Can be interpreted as “into the screen” in an untransformed 3D world.

pub const BACK: Vector3 = _

Unit vector in +Z direction. Can be interpreted as “out of the screen” in an untransformed 3D world.

pub const MODEL_LEFT: Vector3 = _

Unit vector pointing towards the left side of imported 3D assets.

pub const MODEL_RIGHT: Vector3 = _

Unit vector pointing towards the right side of imported 3D assets.

pub const MODEL_TOP: Vector3 = _

Unit vector pointing towards the top side (up) of imported 3D assets.

pub const MODEL_BOTTOM: Vector3 = _

Unit vector pointing towards the bottom side (down) of imported 3D assets.

pub const MODEL_FRONT: Vector3 = _

Unit vector pointing towards the front side (facing forward) of imported 3D assets.

pub const MODEL_REAR: Vector3 = _

Unit vector pointing towards the rear side (back) of imported 3D assets.

impl Vector3

Constructors and general vector functions

The following associated functions and methods are available on all vectors (2D, 3D, 4D; float and int).

pub const fn new(x: f32, y: f32, z: f32) -> Vector3

Creates a vector with the given components.

pub const fn splat(v: f32) -> Vector3

Creates a vector with all components set to v.

pub const fn from_tuple(tuple: (f32, f32, f32)) -> Vector3

Creates a vector from the given tuple.

pub const fn from_array(array: [f32; 3]) -> Vector3

Creates a vector from the given array.

pub const fn to_tuple(&self) -> (f32, f32, f32)

Returns a tuple with the components of the vector.

pub const fn to_array(&self) -> [f32; 3]

Returns an array with the components of the vector.

pub fn abs(self) -> Vector3

Returns a new vector with all components in absolute values (i.e. positive or zero).

pub fn clamp(self, min: Vector3, max: Vector3) -> Vector3

Returns a new vector with all components clamped between the components of min and max.

Panics

If min > max, min is NaN, or max is NaN.

pub fn length(self) -> f32

Returns the length (magnitude) of this vector.

pub fn length_squared(self) -> f32

Squared length (squared magnitude) of this vector.

Runs faster than length(), so prefer it if you need to compare vectors or need the squared distance for some formula.

pub fn coord_min(self, other: Vector3) -> Vector3

Returns a new vector containing the minimum of the two vectors, component-wise.

You may consider using the fully-qualified syntax Vector3::coord_min(a, b) for symmetry.

pub fn coord_max(self, other: Vector3) -> Vector3

Returns a new vector containing the maximum of the two vectors, component-wise.

You may consider using the fully-qualified syntax Vector3::coord_max(a, b) for symmetry.

pub fn sign(self) -> Vector3

Returns a new vector with each component set to 1 if the component is positive, -1 if negative, and 0 if zero.

impl Vector3

Specialized Vector3 functions

pub const fn from_vector3i(v: Vector3i) -> Vector3

👎Deprecated: Moved to Vector3i::cast_float()

pub fn cross(self, with: Vector3) -> Vector3

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.

pub fn octahedron_decode(uv: Vector2) -> Vector3

Returns the Vector3 from an octahedral-compressed form created using Vector3::octahedron_encode (stored as a Vector2).

pub fn octahedron_encode(self) -> Vector2

Returns the octahedral-encoded (oct32) form of this Vector3 as a Vector2.

Since a Vector2 occupies 1/3 less memory compared to Vector3, this form of compression can be used to pass greater amounts of Vector3::normalized Vector3s without increasing storage or memory requirements. See also Vector3::octahedron_decode.

Note: Octahedral compression is lossy, although visual differences are rarely perceptible in real world scenarios.

Panics

If vector is not normalized.

pub fn outer(self, with: Vector3) -> Basis

Returns the outer product with with.

pub fn rotated(self, axis: Vector3, angle: f32) -> Vector3

Returns this vector rotated around axis by angle radians. axis must be normalized.

Panics

If axis is not normalized.

pub fn angle_to(self, to: Vector3) -> f32

Returns the unsigned angle between self and the given vector, as radians in [0, +π].

Note that behavior is different from 2D Vector2::angle_to(), which returns the signed angle.

pub fn signed_angle_to(self, to: Vector3, axis: Vector3) -> f32

Returns the signed angle to the given vector, as radians in [-π, +π].

The sign of the angle is positive in a counter-clockwise direction and negative in a clockwise direction, when viewed from the side specified by the axis.

For unsigned angles, use Vector3::angle_to().

pub fn slerp(self, to: Vector3, weight: f32) -> Vector3

Returns the spherical linear interpolation between the vector and to by the weight amount.

The variable weight is representing the amount of interpolation, which is on the range of 0.0 to 1.0.

Length is also interpolated in the case that the input vectors have different lengths. If both input vectors have zero length or are collinear to each other, the method instead behaves like Vector3::lerp.

impl Vector3

Float-specific functions

The following methods are only available on floating-point vectors.

pub const fn cast_int(self) -> Vector3i

Converts to a vector with integer components, using as casts.

pub fn floor(self) -> Vector3

Returns a new vector with all components rounded down (towards negative infinity).

pub fn ceil(self) -> Vector3

Returns a new vector with all components rounded up (towards positive infinity).

pub fn cubic_interpolate( self, b: Vector3, pre_a: Vector3, post_b: Vector3, weight: f32, ) -> Vector3

Cubic interpolation between self 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.

pub fn cubic_interpolate_in_time( self, b: Vector3, pre_a: Vector3, post_b: Vector3, weight: f32, b_t: f32, pre_a_t: f32, post_b_t: f32, ) -> Vector3

Cubic interpolation between self 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.

pub fn try_direction_to(self, to: Vector3) -> Option<Vector3>

Returns the normalized vector pointing from this vector to to or None, if self and to are equal.

This is equivalent to using (b - a).try_normalized(). See also direction_to().

pub fn direction_to(self, to: Vector3) -> Vector3

⚠️ Returns the normalized vector pointing from this vector to to.

This is equivalent to using (b - a).normalized(). See also try_direction_to().

Panics

If self and to are equal.

pub fn distance_squared_to(self, to: Vector3) -> f32

Returns the squared distance between this vector and to.

This method runs faster than Self::distance_to, so prefer it if you need to compare vectors or need the squared distance for some formula.

pub fn distance_to(self, to: Vector3) -> f32

Returns the distance between this vector and to.

pub fn dot(self, with: Vector3) -> f32

Returns the dot product of this vector and with.

pub fn is_finite(self) -> bool

Returns true if each component of this vector is finite.

pub fn is_normalized(self) -> bool

Returns true if the vector is normalized, i.e. its length is approximately equal to 1.

pub fn is_zero_approx(self) -> bool

Returns true if this vector’s values are approximately zero.

This method is faster than using approx_eq() with one value as a zero vector.

pub fn lerp(self, other: Vector3, weight: f32) -> Vector3

Returns the result of the linear interpolation between this vector and to by amount weight.

weight is on the range of 0.0 to 1.0, representing the amount of interpolation.

pub fn try_normalized(self) -> Option<Vector3>

Returns the vector scaled to unit length or None, if called on a zero vector.

Computes self / self.length(). See also normalized() and is_normalized().

pub fn normalized(self) -> Vector3

⚠️ Returns the vector scaled to unit length.

Computes self / self.length(). See also try_normalized() and is_normalized().

Panics

If called on a zero vector.

pub fn normalized_or_zero(self) -> Vector3

Returns the vector scaled to unit length or Self::ZERO, if called on a zero vector.

Computes self / self.length(). See also try_normalized() and is_normalized().

pub fn posmod(self, pmod: f32) -> Vector3

Returns a vector composed of the FloatExt::fposmod() of this vector’s components and pmod.

pub fn posmodv(self, modv: Vector3) -> Vector3

Returns a vector composed of the FloatExt::fposmod() of this vector’s components and modv’s components.

pub fn round(self) -> Vector3

Returns a new vector with all components rounded to the nearest integer, with halfway cases rounded away from zero.

pub fn snapped(self, step: Vector3) -> Vector3

A new vector with each component snapped to the closest multiple of the corresponding component in step.

impl Vector3

3D functions

The following methods are only available on 3D vectors (for both float and int).

pub fn to_2d(self) -> Vector2

Reduces dimension to 2D, discarding the Z component.

See also swizzle! for a more general way to extract components. self.to_2d() is equivalent to swizzle!(self => x, y).

pub fn max_axis(self) -> Option<Vector3Axis>

Returns the axis of the vector’s highest value. See Vector3Axis enum. If all components are equal, this method returns None.

To mimic Godot’s behavior, unwrap this function’s result with unwrap_or(Vector3Axis::X).

pub fn min_axis(self) -> Option<Vector3Axis>

Returns the axis of the vector’s lowest value. See Vector3Axis enum. If all components are equal, this method returns None.

To mimic Godot’s behavior, unwrap this function’s result with unwrap_or(Vector3Axis::Z).

impl Vector3

2D and 3D functions

The following methods are available on both 2D and 3D float vectors.

pub fn bezier_derivative( self, control_1: Vector3, control_2: Vector3, end: Vector3, t: f32, ) -> Vector3

Returns the derivative at the given t on the Bézier curve defined by this vector and the given control_1, control_2, and end points.

pub fn bezier_interpolate( self, control_1: Vector3, control_2: Vector3, end: Vector3, t: f32, ) -> Vector3

Returns the point at the given t on the Bézier curve defined by this vector and the given control_1, control_2, and end points.

pub fn bounce(self, n: Vector3) -> Vector3

Returns a new vector “bounced off” from a plane defined by the given normal.

Panics

If n is not normalized.

pub fn limit_length(self, length: Option<f32>) -> Vector3

Returns the vector with a maximum length by limiting its length to length.

pub fn move_toward(self, to: Vector3, delta: f32) -> Vector3

Returns a new vector moved toward to by the fixed delta amount. Will not go past the final value.

pub fn project(self, b: Vector3) -> Vector3

Returns the result of projecting the vector onto the given vector b.

pub fn reflect(self, n: Vector3) -> Vector3

Returns the result of reflecting the vector defined by the given direction vector n.

Panics

If n is not normalized.

pub fn slide(self, n: Vector3) -> Vector3

Returns a new vector slid along a plane defined by the given normal.

Panics

If n is not normalized.

impl Vector3

3D and 4D functions

The following methods are available on both 3D and 4D float vectors.

pub fn recip(self) -> Vector3

Returns the reciprocal (inverse) of the vector. This is the same as 1.0/n for each component.

Trait Implementations

impl Add for Vector3

type Output = Vector3

The resulting type after applying the + operator.

fn add(self, rhs: Vector3) -> <Vector3 as Add>::Output

Performs the + operation.

impl AddAssign for Vector3

fn add_assign(&mut self, rhs: Vector3)

Performs the += operation.

impl ApproxEq for Vector3

fn approx_eq(&self, other: &Vector3) -> bool

Returns true if this vector and to are approximately equal.

impl ArrayElement for Vector3

fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError>

impl Clone for Vector3

fn clone(&self) -> Vector3

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Vector3

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Vector3

fn default() -> Vector3

Returns the “default value” for a type.

impl Display for Vector3

Formats the vector like Godot: (x, y, z).

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Div<f32> for Vector3

type Output = Vector3

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> <Vector3 as Div<f32>>::Output

Performs the / operation.

impl Div for Vector3

type Output = Vector3

The resulting type after applying the / operator.

fn div(self, rhs: Vector3) -> <Vector3 as Div>::Output

Performs the / operation.

impl DivAssign<f32> for Vector3

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl DivAssign for Vector3

fn div_assign(&mut self, rhs: Vector3)

Performs the /= operation.

impl Export for Vector3

fn export_hint() -> PropertyHintInfo

The export info to use for an exported field of this type, if no other export info is specified.

fn as_node_class() -> Option<ClassName>

If this is a class inheriting Node, returns the ClassName; otherwise None.

impl Extend<Vector3> for PackedVector3Array

Extends aPackedVector3Array with the contents of an iterator

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = Vector3>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl FromGodot for Vector3

fn try_from_godot( via: <Vector3 as GodotConvert>::Via, ) -> Result<Vector3, ConvertError>

Converts the Godot representation to this type, returning Err on failure.

fn from_godot(via: Self::Via) -> Self

⚠️ Converts the Godot representation to this type.

fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>

Performs the conversion from a Variant, returning Err on failure.

fn from_variant(variant: &Variant) -> Self

⚠️ Performs the conversion from a Variant.

impl FromIterator<Vector3> for PackedVector3Array

Creates a PackedVector3Array from an iterator.

fn from_iter<I>(iter: I) -> PackedVector3Array

where I: IntoIterator<Item = Vector3>,

Creates a value from an iterator.

impl GodotConvert for Vector3

type Via = Vector3

The type through which Self is represented in Godot.

impl Index<Vector3Axis> for Vector3

type Output = f32

The returned type after indexing.

fn index(&self, axis: Vector3Axis) -> &f32

Performs the indexing (container[index]) operation.

impl IndexMut<Vector3Axis> for Vector3

fn index_mut(&mut self, axis: Vector3Axis) -> &mut f32

Performs the mutable indexing (container[index]) operation.

impl Mul<Vector3> for Basis

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> <Basis as Mul<Vector3>>::Output

Performs the * operation.

impl Mul<Vector3> for Quaternion

fn mul(self, rhs: Vector3) -> <Quaternion as Mul<Vector3>>::Output

Applies the quaternion’s rotation to the 3D point represented by the vector.

Panics

If the quaternion is not normalized.

type Output = Vector3

The resulting type after applying the * operator.

impl Mul<Vector3> for Transform3D

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> <Transform3D as Mul<Vector3>>::Output

Performs the * operation.

impl Mul<f32> for Vector3

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> <Vector3 as Mul<f32>>::Output

Performs the * operation.

impl Mul for Vector3

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> <Vector3 as Mul>::Output

Performs the * operation.

impl MulAssign<f32> for Vector3

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation.

impl MulAssign for Vector3

fn mul_assign(&mut self, rhs: Vector3)

Performs the *= operation.

impl Neg for Vector3

type Output = Vector3

The resulting type after applying the - operator.

fn neg(self) -> <Vector3 as Neg>::Output

Performs the unary - operation.

impl PartialEq for Vector3

fn eq(&self, other: &Vector3) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Product<&'a Vector3> for Vector3

fn product<I>(iter: I) -> Vector3

where I: Iterator<Item = &'a Vector3>,

Element-wise product of all vectors in the iterator.

impl Product for Vector3

fn product<I>(iter: I) -> Vector3

where I: Iterator<Item = Vector3>,

Element-wise product of all vectors in the iterator.

impl Sub for Vector3

type Output = Vector3

The resulting type after applying the - operator.

fn sub(self, rhs: Vector3) -> <Vector3 as Sub>::Output

Performs the - operation.

impl SubAssign for Vector3

fn sub_assign(&mut self, rhs: Vector3)

Performs the -= operation.

impl<'a> Sum<&'a Vector3> for Vector3

fn sum<I>(iter: I) -> Vector3

where I: Iterator<Item = &'a Vector3>,

Element-wise sum of all vectors in the iterator.

impl Sum for Vector3

fn sum<I>(iter: I) -> Vector3

where I: Iterator<Item = Vector3>,

Element-wise sum of all vectors in the iterator.

impl ToGodot for Vector3

type ToVia<'v> = <Vector3 as GodotConvert>::Via

Target type of to_godot(), which differs from Via for pass-by-reference types.

fn to_godot(&self) -> <Vector3 as ToGodot>::ToVia<'_>

Converts this type to the Godot type by reference, usually by cloning.

fn to_variant(&self) -> Variant

Converts this type to a Variant.

impl Var for Vector3

fn get_property(&self) -> <Vector3 as GodotConvert>::Via

fn set_property(&mut self, value: <Vector3 as GodotConvert>::Via)

fn var_hint() -> PropertyHintInfo

Specific property hints, only override if they deviate from GodotType::property_info, e.g. for enums/newtypes.

impl Copy for Vector3

impl GodotType for Vector3

impl PackedArrayElement for Vector3

impl StructuralPartialEq for Vector3