Package net.minestom.server.coordinate

Record Class Vec

java.lang.Object
java.lang.Record
net.minestom.server.coordinate.Vec
All Implemented Interfaces:
Point
public record Vec(double x, double y, double z) extends Record implements Point
Represents an immutable 3D vector.

To become a value then primitive type.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Vec.Interpolation
     
    static interface 
    Vec.Operator
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    EPSILON
     
    static final Vec
    ONE
     
    static final Vec
    SECTION
     
    static final Vec
    ZERO
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Vec(double value)
    Creates a vec with all 3 coordinates sharing the same value.
    Vec(double x, double z)
    Creates a new vec with the [x;z] coordinates set.
    Vec(double x, double y, double z)
    Creates an instance of a Vec record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull Vec
    abs()
     
    @NotNull Vec
    add(double value)
     
    @NotNull Vec
    add(double x, double y, double z)
     
    @NotNull Vec
    add(@NotNull Point point)
     
    double
    angle(@NotNull Vec vec)
    Gets the angle between this vector and another in radians.
    @NotNull Vec
    apply(@NotNull Vec.Operator operator)
    Creates a new point with coordinated depending on this.
    @NotNull Pos
    asPosition()
     
    @NotNull Vec
    cross(@NotNull Vec o)
    Calculates the cross product of this vector with another.
    @NotNull Vec
    div(double value)
     
    @NotNull Vec
    div(double x, double y, double z)
     
    @NotNull Vec
    div(@NotNull Point point)
     
    double
    dot(@NotNull Vec vec)
    Calculates the dot product of this vector with another.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    static @NotNull Vec
    fromPoint(@NotNull Point point)
    Converts a Point into a Vec.
    final int
    hashCode()
    Returns a hash code value for this object.
    @NotNull Vec
    interpolate(@NotNull Vec target, double alpha, @NotNull Vec.Interpolation interpolation)
     
    boolean
    isNormalized()
    Returns if a vector is normalized
    double
    length()
    Gets the magnitude of the vector, defined as sqrt(x^2+y^2+z^2).
    double
    lengthSquared()
    Gets the magnitude of the vector squared.
    @NotNull Vec
    lerp(@NotNull Vec vec, double alpha)
    Calculates a linear interpolation between this vector with another vector.
    @NotNull Vec
    max(double value)
     
    @NotNull Vec
    max(double x, double y, double z)
     
    @NotNull Vec
    max(@NotNull Point point)
     
    @NotNull Vec
    min(double value)
     
    @NotNull Vec
    min(double x, double y, double z)
     
    @NotNull Vec
    min(@NotNull Point point)
     
    @NotNull Vec
    mul(double value)
     
    @NotNull Vec
    mul(double x, double y, double z)
     
    @NotNull Vec
    mul(@NotNull Point point)
     
    @NotNull Vec
    neg()
     
    @NotNull Vec
    normalize()
    Converts this vector to a unit vector (a vector with length of 1).
    @NotNull Vec
    relative(@NotNull BlockFace face)
     
    @NotNull Vec
    rotate(double angleX, double angleY, double angleZ)
     
    @NotNull Vec
    rotateAroundAxis(@NotNull Vec axis, double angle)
    Rotates the vector around a given arbitrary axis in 3 dimensional space.
    @NotNull Vec
    rotateAroundNonUnitAxis(@NotNull Vec axis, double angle)
    Rotates the vector around a given arbitrary axis in 3 dimensional space.
    @NotNull Vec
    rotateAroundX(double angle)
    Rotates the vector around the x-axis.
    @NotNull Vec
    rotateAroundY(double angle)
    Rotates the vector around the y-axis.
    @NotNull Vec
    rotateAroundZ(double angle)
    Rotates the vector around the z axis
    @NotNull Vec
    rotateFromView(float yawDegrees, float pitchDegrees)
     
    @NotNull Vec
    rotateFromView(@NotNull Pos pos)
     
    @NotNull Vec
    sub(double value)
     
    @NotNull Vec
    sub(double x, double y, double z)
     
    @NotNull Vec
    sub(@NotNull Point point)
     
    final String
    toString()
    Returns a string representation of this record class.
    @NotNull Vec
    withX(double x)
    Creates a point with the specified X coordinate.
    @NotNull Vec
    withX(@NotNull DoubleUnaryOperator operator)
    Creates a point with a modified X coordinate based on its value.
    @NotNull Vec
    withY(double y)
    Creates a point with the specified Y coordinate.
    @NotNull Vec
    withY(@NotNull DoubleUnaryOperator operator)
    Creates a point with a modified Y coordinate based on its value.
    @NotNull Vec
    withZ(double z)
    Creates a point with the specified Z coordinate.
    @NotNull Vec
    withZ(@NotNull DoubleUnaryOperator operator)
    Creates a point with a modified Z coordinate based on its value.
    double
    x()
    Returns the value of the x record component.
    double
    y()
    Returns the value of the y record component.
    double
    z()
    Returns the value of the z record component.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface net.minestom.server.coordinate.Point

    blockX, blockY, blockZ, chunkX, chunkZ, distance, distance, distanceSquared, distanceSquared, isZero, sameBlock, sameBlock, sameChunk, samePoint, samePoint, section

  • Field Details

    • ZERO

      public static final Vec ZERO

    • ONE

      public static final Vec ONE

    • SECTION

      public static final Vec SECTION

    • EPSILON

      public static final double EPSILON
      See Also:

  • Constructor Details

    • Vec

      public Vec(double x, double z)
      Creates a new vec with the [x;z] coordinates set. Y is set to 0.
      Parameters:
      x - the X coordinate
      z - the Z coordinate

    • Vec

      public Vec(double value)
      Creates a vec with all 3 coordinates sharing the same value.
      Parameters:
      value - the coordinates

    • Vec

      public Vec(double x, double y, double z)
      Creates an instance of a Vec record class.
      Parameters:
      x - the value for the x record component
      y - the value for the y record component
      z - the value for the z record component

  • Method Details

    • fromPoint

      @NotNull public static @NotNull Vec fromPoint(@NotNull @NotNull Point point)
      Converts a Point into a Vec. Will cast if possible, or instantiate a new object.
      Parameters:
      point - the point to convert
      Returns:
      the converted vector

    • apply

      @Contract(pure=true) @NotNull public @NotNull Vec apply(@NotNull @NotNull Vec.Operator operator)
      Creates a new point with coordinated depending on this.
      Parameters:
      operator - the operator
      Returns:
      the created point

    • withX

      @Contract(pure=true) @NotNull public @NotNull Vec withX(@NotNull @NotNull DoubleUnaryOperator operator)
      Description copied from interface: Point
      Creates a point with a modified X coordinate based on its value.
      Specified by:
      withX in interface Point
      Parameters:
      operator - the operator providing the current X coordinate and returning the new
      Returns:
      a new point

    • withX

      @Contract(pure=true) @NotNull public @NotNull Vec withX(double x)
      Description copied from interface: Point
      Creates a point with the specified X coordinate.
      Specified by:
      withX in interface Point
      Parameters:
      x - the new X coordinate
      Returns:
      a new point

    • withY

      @Contract(pure=true) @NotNull public @NotNull Vec withY(@NotNull @NotNull DoubleUnaryOperator operator)
      Description copied from interface: Point
      Creates a point with a modified Y coordinate based on its value.
      Specified by:
      withY in interface Point
      Parameters:
      operator - the operator providing the current Y coordinate and returning the new
      Returns:
      a new point

    • withY

      @Contract(pure=true) @NotNull public @NotNull Vec withY(double y)
      Description copied from interface: Point
      Creates a point with the specified Y coordinate.
      Specified by:
      withY in interface Point
      Parameters:
      y - the new Y coordinate
      Returns:
      a new point

    • withZ

      @Contract(pure=true) @NotNull public @NotNull Vec withZ(@NotNull @NotNull DoubleUnaryOperator operator)
      Description copied from interface: Point
      Creates a point with a modified Z coordinate based on its value.
      Specified by:
      withZ in interface Point
      Parameters:
      operator - the operator providing the current Z coordinate and returning the new
      Returns:
      a new point

    • withZ

      @Contract(pure=true) @NotNull public @NotNull Vec withZ(double z)
      Description copied from interface: Point
      Creates a point with the specified Z coordinate.
      Specified by:
      withZ in interface Point
      Parameters:
      z - the new Z coordinate
      Returns:
      a new point

    • add

      @NotNull public @NotNull Vec add(double x, double y, double z)
      Specified by:
      add in interface Point

    • add

      @NotNull public @NotNull Vec add(@NotNull @NotNull Point point)
      Specified by:
      add in interface Point

    • add

      @NotNull public @NotNull Vec add(double value)
      Specified by:
      add in interface Point

    • sub

      @NotNull public @NotNull Vec sub(double x, double y, double z)
      Specified by:
      sub in interface Point

    • sub

      @NotNull public @NotNull Vec sub(@NotNull @NotNull Point point)
      Specified by:
      sub in interface Point

    • sub

      @NotNull public @NotNull Vec sub(double value)
      Specified by:
      sub in interface Point

    • mul

      @NotNull public @NotNull Vec mul(double x, double y, double z)
      Specified by:
      mul in interface Point

    • mul

      @NotNull public @NotNull Vec mul(@NotNull @NotNull Point point)
      Specified by:
      mul in interface Point

    • mul

      @NotNull public @NotNull Vec mul(double value)
      Specified by:
      mul in interface Point

    • div

      @NotNull public @NotNull Vec div(double x, double y, double z)
      Specified by:
      div in interface Point

    • div

      @NotNull public @NotNull Vec div(@NotNull @NotNull Point point)
      Specified by:
      div in interface Point

    • div

      @NotNull public @NotNull Vec div(double value)
      Specified by:
      div in interface Point

    • relative

      @NotNull public @NotNull Vec relative(@NotNull @NotNull BlockFace face)
      Specified by:
      relative in interface Point

    • neg

      @Contract(pure=true) @NotNull public @NotNull Vec neg()

    • abs

      @Contract(pure=true) @NotNull public @NotNull Vec abs()

    • min

      @Contract(pure=true) @NotNull public @NotNull Vec min(@NotNull @NotNull Point point)

    • min

      @Contract(pure=true) @NotNull public @NotNull Vec min(double x, double y, double z)

    • min

      @Contract(pure=true) @NotNull public @NotNull Vec min(double value)

    • max

      @Contract(pure=true) @NotNull public @NotNull Vec max(@NotNull @NotNull Point point)

    • max

      @Contract(pure=true) @NotNull public @NotNull Vec max(double x, double y, double z)

    • max

      @Contract(pure=true) @NotNull public @NotNull Vec max(double value)

    • asPosition

      @Contract(pure=true) @NotNull public @NotNull Pos asPosition()

    • lengthSquared

      @Contract(pure=true) public double lengthSquared()
      Gets the magnitude of the vector squared.
      Returns:
      the magnitude

    • length

      @Contract(pure=true) public double length()
      Gets the magnitude of the vector, defined as sqrt(x^2+y^2+z^2). The value of this method is not cached and uses a costly square-root function, so do not repeatedly call this method to get the vector's magnitude. NaN will be returned if the inner result of the sqrt() function overflows, which will be caused if the length is too long.
      Returns:
      the magnitude

    • normalize

      @Contract(pure=true) @NotNull public @NotNull Vec normalize()
      Converts this vector to a unit vector (a vector with length of 1).
      Returns:
      the same vector

    • isNormalized

      public boolean isNormalized()
      Returns if a vector is normalized
      Returns:
      whether the vector is normalised

    • angle

      @Contract(pure=true) public double angle(@NotNull @NotNull Vec vec)
      Gets the angle between this vector and another in radians.
      Parameters:
      vec - the other vector
      Returns:
      angle in radians

    • dot

      @Contract(pure=true) public double dot(@NotNull @NotNull Vec vec)
      Calculates the dot product of this vector with another. The dot product is defined as x1*x2+y1*y2+z1*z2. The returned value is a scalar.
      Parameters:
      vec - the other vector
      Returns:
      dot product

    • cross

      @Contract(pure=true) @NotNull public @NotNull Vec cross(@NotNull @NotNull Vec o)
      Calculates the cross product of this vector with another. The cross product is defined as:
      • x = y1 * z2 - y2 * z1
      • y = z1 * x2 - z2 * x1
      • z = x1 * y2 - x2 * y1
      Parameters:
      o - the other vector
      Returns:
      the same vector

    • rotateAroundX

      @Contract(pure=true) @NotNull public @NotNull Vec rotateAroundX(double angle)
      Rotates the vector around the x-axis.

      This piece of math is based on the standard rotation matrix for vectors in three-dimensional space. This matrix can be found here: Rotation Matrix.

      Parameters:
      angle - the angle to rotate the vector about. This angle is passed in radians
      Returns:
      a new, rotated vector

    • rotateAroundY

      @Contract(pure=true) @NotNull public @NotNull Vec rotateAroundY(double angle)
      Rotates the vector around the y-axis.

      This piece of math is based on the standard rotation matrix for vectors in three-dimensional space. This matrix can be found here: Rotation Matrix.

      Parameters:
      angle - the angle to rotate the vector about. This angle is passed in radians
      Returns:
      a new, rotated vector

    • rotateAroundZ

      @Contract(pure=true) @NotNull public @NotNull Vec rotateAroundZ(double angle)
      Rotates the vector around the z axis

      This piece of math is based on the standard rotation matrix for vectors in three-dimensional space. This matrix can be found here: Rotation Matrix.

      Parameters:
      angle - the angle to rotate the vector about. This angle is passed in radians
      Returns:
      a new, rotated vector

    • rotate

      @Contract(pure=true) @NotNull public @NotNull Vec rotate(double angleX, double angleY, double angleZ)

    • rotateFromView

      @Contract(pure=true) @NotNull public @NotNull Vec rotateFromView(float yawDegrees, float pitchDegrees)

    • rotateFromView

      @Contract(pure=true) @NotNull public @NotNull Vec rotateFromView(@NotNull @NotNull Pos pos)

    • rotateAroundAxis

      @Contract(pure=true) @NotNull public @NotNull Vec rotateAroundAxis(@NotNull @NotNull Vec axis, double angle) throws IllegalArgumentException
      Rotates the vector around a given arbitrary axis in 3 dimensional space.

      Rotation will follow the general Right-Hand-Rule, which means rotation will be counterclockwise when the axis is pointing towards the observer.

      This method will always make sure the provided axis is a unit vector, to not modify the length of the vector when rotating. If you are experienced with the scaling of a non-unit axis vector, you can use rotateAroundNonUnitAxis(Vec, double).

      Parameters:
      axis - the axis to rotate the vector around. If the passed vector is not of length 1, it gets copied and normalized before using it for the rotation. Please use normalize() on the instance before passing it to this method
      angle - the angle to rotate the vector around the axis
      Returns:
      a new vector
      Throws:
      IllegalArgumentException

    • rotateAroundNonUnitAxis

      @Contract(pure=true) @NotNull public @NotNull Vec rotateAroundNonUnitAxis(@NotNull @NotNull Vec axis, double angle) throws IllegalArgumentException
      Rotates the vector around a given arbitrary axis in 3 dimensional space.

      Rotation will follow the general Right-Hand-Rule, which means rotation will be counterclockwise when the axis is pointing towards the observer.

      Note that the vector length will change accordingly to the axis vector length. If the provided axis is not a unit vector, the rotated vector will not have its previous length. The scaled length of the resulting vector will be related to the axis vector. If you are not perfectly sure about the scaling of the vector, use rotateAroundAxis(Vec, double)

      Parameters:
      axis - the axis to rotate the vector around.
      angle - the angle to rotate the vector around the axis
      Returns:
      a new vector
      Throws:
      IllegalArgumentException

    • lerp

      @Contract(pure=true) @NotNull public @NotNull Vec lerp(@NotNull @NotNull Vec vec, double alpha)
      Calculates a linear interpolation between this vector with another vector.
      Parameters:
      vec - the other vector
      alpha - The alpha value, must be between 0.0 and 1.0
      Returns:
      Linear interpolated vector

    • interpolate

      @Contract(pure=true) @NotNull public @NotNull Vec interpolate(@NotNull @NotNull Vec target, double alpha, @NotNull @NotNull Vec.Interpolation interpolation)

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • x

      public double x()
      Returns the value of the x record component.
      Specified by:
      x in interface Point
      Returns:
      the value of the x record component

    • y

      public double y()
      Returns the value of the y record component.
      Specified by:
      y in interface Point
      Returns:
      the value of the y record component

    • z

      public double z()
      Returns the value of the z record component.
      Specified by:
      z in interface Point
      Returns:
      the value of the z record component