| github_url: | hide |
|---|
A 3D vector using integer coordinates.
.. rst-class:: classref-introduction-group
A 3-element structure that can be used to represent 3D grid coordinates or any other triplet of integers.
It uses integer coordinates and is therefore preferable to :ref:`Vector3<class_Vector3>` when exact precision is required. Note that the values are limited to 32 bits, and unlike :ref:`Vector3<class_Vector3>` this cannot be configured with an engine build option. Use :ref:`int<class_int>` or :ref:`PackedInt64Array<class_PackedInt64Array>` if 64-bit values are needed.
Note: In a boolean context, a Vector3i will evaluate to false if it's equal to Vector3i(0, 0, 0). Otherwise, a Vector3i will always evaluate to true.
.. rst-class:: classref-introduction-group
- :doc:`Math documentation index <../tutorials/math/index>`
- :doc:`Vector math <../tutorials/math/vector_math>`
- 3Blue1Brown Essence of Linear Algebra
.. rst-class:: classref-reftable-group
| :ref:`int<class_int>` | :ref:`x<class_Vector3i_property_x>` | 0 |
| :ref:`int<class_int>` | :ref:`y<class_Vector3i_property_y>` | 0 |
| :ref:`int<class_int>` | :ref:`z<class_Vector3i_property_z>` | 0 |
.. rst-class:: classref-reftable-group
.. rst-class:: classref-reftable-group
.. rst-class:: classref-reftable-group
.. rst-class:: classref-section-separator
.. rst-class:: classref-descriptions-group
.. rst-class:: classref-constant
AXIS_X = 0
Enumerated value for the X axis. Returned by :ref:`max_axis_index<class_Vector3i_method_max_axis_index>` and :ref:`min_axis_index<class_Vector3i_method_min_axis_index>`.
.. rst-class:: classref-constant
AXIS_Y = 1
Enumerated value for the Y axis. Returned by :ref:`max_axis_index<class_Vector3i_method_max_axis_index>` and :ref:`min_axis_index<class_Vector3i_method_min_axis_index>`.
.. rst-class:: classref-constant
AXIS_Z = 2
Enumerated value for the Z axis. Returned by :ref:`max_axis_index<class_Vector3i_method_max_axis_index>` and :ref:`min_axis_index<class_Vector3i_method_min_axis_index>`.
.. rst-class:: classref-constant
ZERO = Vector3i(0, 0, 0)
Zero vector, a vector with all components set to 0.
.. rst-class:: classref-constant
ONE = Vector3i(1, 1, 1)
One vector, a vector with all components set to 1.
.. rst-class:: classref-constant
LEFT = Vector3i(-1, 0, 0)
Left unit vector. Represents the local direction of left, and the global direction of west.
.. rst-class:: classref-constant
RIGHT = Vector3i(1, 0, 0)
Right unit vector. Represents the local direction of right, and the global direction of east.
.. rst-class:: classref-constant
UP = Vector3i(0, 1, 0)
Up unit vector.
.. rst-class:: classref-constant
DOWN = Vector3i(0, -1, 0)
Down unit vector.
.. rst-class:: classref-constant
FORWARD = Vector3i(0, 0, -1)
Forward unit vector. Represents the local direction of forward, and the global direction of north.
.. rst-class:: classref-constant
BACK = Vector3i(0, 0, 1)
Back unit vector. Represents the local direction of back, and the global direction of south.
.. rst-class:: classref-section-separator
.. rst-class:: classref-descriptions-group
.. rst-class:: classref-property
:ref:`int<class_int>` x = 0
The vector's X component. Also accessible by using the index position [0].
.. rst-class:: classref-item-separator
.. rst-class:: classref-property
:ref:`int<class_int>` y = 0
The vector's Y component. Also accessible by using the index position [1].
.. rst-class:: classref-item-separator
.. rst-class:: classref-property
:ref:`int<class_int>` z = 0
The vector's Z component. Also accessible by using the index position [2].
.. rst-class:: classref-section-separator
.. rst-class:: classref-descriptions-group
.. rst-class:: classref-constructor
:ref:`Vector3i<class_Vector3i>` Vector3i ( )
Constructs a default-initialized Vector3i with all components set to 0.
.. rst-class:: classref-item-separator
.. rst-class:: classref-constructor
:ref:`Vector3i<class_Vector3i>` Vector3i ( :ref:`Vector3i<class_Vector3i>` from )
Constructs a Vector3i as a copy of the given Vector3i.
.. rst-class:: classref-item-separator
.. rst-class:: classref-constructor
:ref:`Vector3i<class_Vector3i>` Vector3i ( :ref:`Vector3<class_Vector3>` from )
Constructs a new Vector3i from the given :ref:`Vector3<class_Vector3>` by truncating components' fractional parts (rounding towards zero). For a different behavior consider passing the result of :ref:`Vector3.ceil<class_Vector3_method_ceil>`, :ref:`Vector3.floor<class_Vector3_method_floor>` or :ref:`Vector3.round<class_Vector3_method_round>` to this constructor instead.
.. rst-class:: classref-item-separator
.. rst-class:: classref-constructor
:ref:`Vector3i<class_Vector3i>` Vector3i ( :ref:`int<class_int>` x, :ref:`int<class_int>` y, :ref:`int<class_int>` z )
Returns a Vector3i with the given components.
.. rst-class:: classref-section-separator
.. rst-class:: classref-descriptions-group
.. rst-class:: classref-method
:ref:`Vector3i<class_Vector3i>` abs ( ) |const|
Returns a new vector with all components in absolute values (i.e. positive).
.. rst-class:: classref-item-separator
.. rst-class:: classref-method
:ref:`Vector3i<class_Vector3i>` clamp ( :ref:`Vector3i<class_Vector3i>` min, :ref:`Vector3i<class_Vector3i>` max ) |const|
Returns a new vector with all components clamped between the components of min and max, by running :ref:`@GlobalScope.clamp<class_@GlobalScope_method_clamp>` on each component.
.. rst-class:: classref-item-separator
.. rst-class:: classref-method
:ref:`float<class_float>` length ( ) |const|
Returns the length (magnitude) of this vector.
.. rst-class:: classref-item-separator
.. rst-class:: classref-method
:ref:`int<class_int>` length_squared ( ) |const|
Returns the squared length (squared magnitude) of this vector.
This method runs faster than :ref:`length<class_Vector3i_method_length>`, so prefer it if you need to compare vectors or need the squared distance for some formula.
.. rst-class:: classref-item-separator
.. rst-class:: classref-method
:ref:`int<class_int>` max_axis_index ( ) |const|
Returns the axis of the vector's highest value. See AXIS_* constants. If all components are equal, this method returns :ref:`AXIS_X<class_Vector3i_constant_AXIS_X>`.
.. rst-class:: classref-item-separator
.. rst-class:: classref-method
:ref:`int<class_int>` min_axis_index ( ) |const|
Returns the axis of the vector's lowest value. See AXIS_* constants. If all components are equal, this method returns :ref:`AXIS_Z<class_Vector3i_constant_AXIS_Z>`.
.. rst-class:: classref-item-separator
.. rst-class:: classref-method
:ref:`Vector3i<class_Vector3i>` sign ( ) |const|
Returns a new vector with each component set to 1 if it's positive, -1 if it's negative, and 0 if it's zero. The result is identical to calling :ref:`@GlobalScope.sign<class_@GlobalScope_method_sign>` on each component.
.. rst-class:: classref-item-separator
.. rst-class:: classref-method
:ref:`Vector3i<class_Vector3i>` snapped ( :ref:`Vector3i<class_Vector3i>` step ) |const|
Returns a new vector with each component snapped to the closest multiple of the corresponding component in step.
.. rst-class:: classref-section-separator
.. rst-class:: classref-descriptions-group
.. rst-class:: classref-operator
:ref:`bool<class_bool>` operator != ( :ref:`Vector3i<class_Vector3i>` right )
Returns true if the vectors are not equal.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator % ( :ref:`Vector3i<class_Vector3i>` right )
Gets the remainder of each component of the Vector3i with the components of the given Vector3i. This operation uses truncated division, which is often not desired as it does not work well with negative numbers. Consider using :ref:`@GlobalScope.posmod<class_@GlobalScope_method_posmod>` instead if you want to handle negative numbers.
print(Vector3i(10, -20, 30) % Vector3i(7, 8, 9)) # Prints "(3, -4, 3)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator % ( :ref:`int<class_int>` right )
Gets the remainder of each component of the Vector3i with the given :ref:`int<class_int>`. This operation uses truncated division, which is often not desired as it does not work well with negative numbers. Consider using :ref:`@GlobalScope.posmod<class_@GlobalScope_method_posmod>` instead if you want to handle negative numbers.
print(Vector3i(10, -20, 30) % 7) # Prints "(3, -6, 2)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator * ( :ref:`Vector3i<class_Vector3i>` right )
Multiplies each component of the Vector3i by the components of the given Vector3i.
print(Vector3i(10, 20, 30) * Vector3i(3, 4, 5)) # Prints "(30, 80, 150)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3<class_Vector3>` operator * ( :ref:`float<class_float>` right )
Multiplies each component of the Vector3i by the given :ref:`float<class_float>`. Returns a :ref:`Vector3<class_Vector3>`.
print(Vector3i(10, 15, 20) * 0.9) # Prints "(9, 13.5, 18)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator * ( :ref:`int<class_int>` right )
Multiplies each component of the Vector3i by the given :ref:`int<class_int>`.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator + ( :ref:`Vector3i<class_Vector3i>` right )
Adds each component of the Vector3i by the components of the given Vector3i.
print(Vector3i(10, 20, 30) + Vector3i(3, 4, 5)) # Prints "(13, 24, 35)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator - ( :ref:`Vector3i<class_Vector3i>` right )
Subtracts each component of the Vector3i by the components of the given Vector3i.
print(Vector3i(10, 20, 30) - Vector3i(3, 4, 5)) # Prints "(7, 16, 25)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator / ( :ref:`Vector3i<class_Vector3i>` right )
Divides each component of the Vector3i by the components of the given Vector3i.
print(Vector3i(10, 20, 30) / Vector3i(2, 5, 3)) # Prints "(5, 4, 10)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3<class_Vector3>` operator / ( :ref:`float<class_float>` right )
Divides each component of the Vector3i by the given :ref:`float<class_float>`. Returns a :ref:`Vector3<class_Vector3>`.
print(Vector3i(10, 20, 30) / 2.9) # Prints "(5, 10, 15)"
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator / ( :ref:`int<class_int>` right )
Divides each component of the Vector3i by the given :ref:`int<class_int>`.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`bool<class_bool>` operator < ( :ref:`Vector3i<class_Vector3i>` right )
Compares two Vector3i vectors by first checking if the X value of the left vector is less than the X value of the right vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`bool<class_bool>` operator <= ( :ref:`Vector3i<class_Vector3i>` right )
Compares two Vector3i vectors by first checking if the X value of the left vector is less than or equal to the X value of the right vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`bool<class_bool>` operator == ( :ref:`Vector3i<class_Vector3i>` right )
Returns true if the vectors are equal.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`bool<class_bool>` operator > ( :ref:`Vector3i<class_Vector3i>` right )
Compares two Vector3i vectors by first checking if the X value of the left vector is greater than the X value of the right vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`bool<class_bool>` operator >= ( :ref:`Vector3i<class_Vector3i>` right )
Compares two Vector3i vectors by first checking if the X value of the left vector is greater than or equal to the X value of the right vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`int<class_int>` operator [] ( :ref:`int<class_int>` index )
Access vector components using their index. v[0] is equivalent to v.x, v[1] is equivalent to v.y, and v[2] is equivalent to v.z.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator unary+ ( )
Returns the same value as if the + was not there. Unary + does nothing, but sometimes it can make your code more readable.
.. rst-class:: classref-item-separator
.. rst-class:: classref-operator
:ref:`Vector3i<class_Vector3i>` operator unary- ( )
Returns the negative value of the Vector3i. This is the same as writing Vector3i(-v.x, -v.y, -v.z). This operation flips the direction of the vector while keeping the same magnitude.