Record Class Vec

java.lang.Object
java.lang.Record
net.minestom.server.coordinate.Vec
Record Components:
x - the X coordinate
y - the Y coordinate
z - the Z coordinate
All Implemented Interfaces:
Point
public record Vec(double x, double y, double z) extends Record implements Point
Represents a 3D vector with double-precision coordinates.

This is the fundamental coordinate type for precise spatial calculations. Supports standard vector operations including dot product, cross product, normalization, and rotation.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Vec.Interpolation
    Deprecated, for removal: This API element is subject to removal in a future version.
    use EaseFunction instead with lerp(Point, double)
    static interface 
    Vec.Operator
    A functional interface representing an operation on the components of a Vec.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Vec
    CHUNK
     
    static final Vec
    ONE
     
    static final Vec
    REGION
     
    static final Vec
    SECTION
     
    static final Vec
    ZERO
     

    Fields inherited from interface Point

    EPSILON, REGION_SIZE, SECTION_SIZE

  • 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
    Vec
    abs()
    Represents this point with all coordinates as their absolute values.
    Vec
    add(double value)
    Creates a new point by adding the provided value to this point coordinates for all XYZ.
    Vec
    add(double x, double y, double z)
    Creates a new point by adding the provided values to this point coordinates.
    Vec
    add(Point point)
    Creates a new point by adding another point coordinates to this point coordinates.
    Vec
    apply(Vec.Operator operator)
    Applies the given operator to this vector's coordinates (x/y/z).
    Pos
    asPosition()
    Deprecated, for removal: This API element is subject to removal in a future version.
    use Point.asPos() instead.
    Vec
    asVec()
    Deprecated.
    Vec
    cross(Point point)
    Calculates the cross product of this point with another.
    Vec
    div(double value)
    Creates a new point by dividing the provided value to this point coordinates for all XYZ.
    Vec
    div(double x, double y, double z)
    Creates a new point by dividing the provided values to this point coordinates.
    Vec
    div(Point point)
    Creates a new point by dividing another point coordinates to this point coordinates.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    static Vec
    fromPoint(Point point)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use Point.asVec() instead
    final int
    hashCode()
    Returns a hash code value for this object.
    Vec
    interpolate(Vec target, double alpha, Vec.Interpolation interpolation)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use Point.lerp(Point, double) with a EaseFunction instead
    Vec
    lerp(Point point, double alpha)
    Calculates a linear interpolation between this point with another point (x/y/z).
    Vec
    max(double value)
    Gets a point representing the maximum values between this point and the provided value for all coordinates.
    Vec
    max(double x, double y, double z)
    Gets a point representing the maximum values between this point and the provided coordinates (x/y/z).
    Vec
    max(Point point)
    Gets a point representing the maximum values between this point and the provided one (x/y/z).
    Vec
    min(double value)
    Gets a point representing the minimum values between this point and the provided value for all coordinates.
    Vec
    min(double x, double y, double z)
    Gets a point representing the minimum values between this point and the provided coordinates (x/y/z).
    Vec
    min(Point point)
    Gets a point representing the minimum values between this point and the provided one (x/y/z).
    Vec
    mul(double value)
    Creates a new point by multiplying the provided value to this point coordinates for all XYZ.
    Vec
    mul(double x, double y, double z)
    Creates a new point by multiplying the provided values to this point coordinates.
    Vec
    mul(Point point)
    Creates a new point by multiplying another point coordinates to this point coordinates.
    Vec
    neg()
    Represents this point with all coordinates negated.
    Vec
    normalize()
    Converts this point to a unit point (a point with length of 1).
    Vec
    relative(BlockFace face)
    Creates a new point relative to this point based on the provided block face.
    Vec
    rotate(double angleX, double angleY, double angleZ)
    Rotates the vector around the x, y, and z axes.
    Vec
    rotateAroundAxis(Vec axis, double angle)
    Rotates the vector around a given arbitrary axis in 3 dimensional space.
    Vec
    rotateAroundNonUnitAxis(Vec axis, double angle)
    Rotates the vector around a given arbitrary axis in 3 dimensional space.
    Vec
    rotateAroundX(double angle)
    Rotates the vector around the x-axis.
    Vec
    rotateAroundY(double angle)
    Rotates the vector around the y-axis.
    Vec
    rotateAroundZ(double angle)
    Rotates the vector around the z axis
    Vec
    rotateFromView(float yawDegrees, float pitchDegrees)
    Rotates the vector from a given yaw and pitch.
    Vec
    rotateFromView(Pos pos)
    Rotates the vector from a position's view (yaw/pitch).
    Vec
    sub(double value)
    Creates a new point by subtracting the provided value to this point coordinates for all XYZ.
    Vec
    sub(double x, double y, double z)
    Creates a new point by subtracting the provided values to this point coordinates.
    Vec
    sub(Point point)
    Creates a new point by subtracting another point coordinates to this point coordinates.
    final String
    toString()
    Returns a string representation of this record class.
    Vec
    withX(double x)
    Creates a point with the specified X coordinate.
    Vec
    withX(DoubleUnaryOperator operator)
    Creates a point with a modified X coordinate based on its value.
    Vec
    withY(double y)
    Creates a point with the specified Y coordinate.
    Vec
    withY(DoubleUnaryOperator operator)
    Creates a point with a modified Y coordinate based on its value.
    Vec
    withZ(double z)
    Creates a point with the specified Z coordinate.
    Vec
    withZ(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 Object

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

    Methods inherited from interface Point

    angle, asBlockVec, asPos, blockX, blockY, blockZ, chunkX, chunkZ, distance, distance, distanceSquared, distanceSquared, dot, isNormalized, isZero, length, lengthSquared, regionX, regionZ, sameBlock, sameBlock, sameChunk, samePoint, samePoint, samePoint, samePoint, section, sectionX, sectionY, sectionZ, similarPoint, similarPoint

  • Field Details

    • ZERO

      public static final Vec ZERO

    • ONE

      public static final Vec ONE

    • SECTION

      public static final Vec SECTION

    • CHUNK

      public static final Vec CHUNK

    • REGION

      public static final Vec REGION

  • 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

      @Deprecated(forRemoval=true) public static Vec fromPoint(Point point)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use Point.asVec() instead
      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

      public Vec apply(Vec.Operator operator)
      Applies the given operator to this vector's coordinates (x/y/z).
      Parameters:
      operator - the operator to apply
      Returns:
      the resulting vector

    • withX

      @Contract("_ -> new") public Vec withX(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, value="_ -> new") public 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("_ -> new") public Vec withY(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, value="_ -> new") public 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("_ -> new") public Vec withZ(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, value="_ -> new") public 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

      @Contract(pure=true, value="_, _, _ -> new") public Vec add(double x, double y, double z)
      Description copied from interface: Point
      Creates a new point by adding the provided values to this point coordinates.
      Specified by:
      add in interface Point
      Parameters:
      x - the x to add
      y - the y to add
      z - the z to add
      Returns:
      the new point

    • add

      @Contract(pure=true, value="_ -> new") public Vec add(Point point)
      Description copied from interface: Point
      Creates a new point by adding another point coordinates to this point coordinates.
      Specified by:
      add in interface Point
      Parameters:
      point - the point decomposed by Point.x(), Point.y() and Point.z()
      Returns:
      the new point

    • add

      @Contract(pure=true, value="_ -> new") public Vec add(double value)
      Description copied from interface: Point
      Creates a new point by adding the provided value to this point coordinates for all XYZ.
      Specified by:
      add in interface Point
      Parameters:
      value - the value to add
      Returns:
      the new point

    • sub

      @Contract(pure=true, value="_, _, _ -> new") public Vec sub(double x, double y, double z)
      Description copied from interface: Point
      Creates a new point by subtracting the provided values to this point coordinates.
      Specified by:
      sub in interface Point
      Parameters:
      x - the x to subtract
      y - the y to subtract
      z - the z to subtract
      Returns:
      the new point

    • sub

      @Contract(pure=true, value="_ -> new") public Vec sub(Point point)
      Description copied from interface: Point
      Creates a new point by subtracting another point coordinates to this point coordinates.
      Specified by:
      sub in interface Point
      Parameters:
      point - the point decomposed by Point.x(), Point.y() and Point.z()
      Returns:
      the new point

    • sub

      @Contract(pure=true, value="_ -> new") public Vec sub(double value)
      Description copied from interface: Point
      Creates a new point by subtracting the provided value to this point coordinates for all XYZ.
      Specified by:
      sub in interface Point
      Parameters:
      value - the value to subtract
      Returns:
      the new point

    • mul

      @Contract(pure=true, value="_, _, _ -> new") public Vec mul(double x, double y, double z)
      Description copied from interface: Point
      Creates a new point by multiplying the provided values to this point coordinates.
      Specified by:
      mul in interface Point
      Parameters:
      x - the x to multiply
      y - the y to multiply
      z - the z to multiply
      Returns:
      the new point

    • mul

      @Contract(pure=true, value="_ -> new") public Vec mul(Point point)
      Description copied from interface: Point
      Creates a new point by multiplying another point coordinates to this point coordinates.
      Specified by:
      mul in interface Point
      Parameters:
      point - the point decomposed by Point.x(), Point.y() and Point.z()
      Returns:
      the new point

    • mul

      @Contract(pure=true, value="_ -> new") public Vec mul(double value)
      Description copied from interface: Point
      Creates a new point by multiplying the provided value to this point coordinates for all XYZ.
      Specified by:
      mul in interface Point
      Parameters:
      value - the value to multiply
      Returns:
      the new point

    • div

      @Contract(pure=true, value="_, _, _ -> new") public Vec div(double x, double y, double z)
      Description copied from interface: Point
      Creates a new point by dividing the provided values to this point coordinates.

      Warning: division by zero will not error.

      Specified by:
      div in interface Point
      Parameters:
      x - the x to divide
      y - the y to divide
      z - the z to divide
      Returns:
      the new point

    • div

      @Contract(pure=true, value="_ -> new") public Vec div(Point point)
      Description copied from interface: Point
      Creates a new point by dividing another point coordinates to this point coordinates.

      Warning: division by zero will not error.

      Specified by:
      div in interface Point
      Parameters:
      point - the point decomposed by Point.x(), Point.y() and Point.z()
      Returns:
      the new point

    • div

      @Contract(pure=true, value="_ -> new") public Vec div(double value)
      Description copied from interface: Point
      Creates a new point by dividing the provided value to this point coordinates for all XYZ.

      Warning: division by zero will not error.

      Specified by:
      div in interface Point
      Parameters:
      value - the value to divide
      Returns:
      the new point

    • relative

      @Contract(pure=true, value="_ -> new") public Vec relative(BlockFace face)
      Description copied from interface: Point
      Creates a new point relative to this point based on the provided block face.
      Specified by:
      relative in interface Point
      Parameters:
      face - the face
      Returns:
      the new point

    • neg

      @Contract(pure=true, value="-> new") public Vec neg()
      Description copied from interface: Point
      Represents this point with all coordinates negated. For example, (x, y, z) becomes (-x, -y, -z).
      Specified by:
      neg in interface Point
      Returns:
      the negated point

    • abs

      @Contract(pure=true, value="-> new") public Vec abs()
      Description copied from interface: Point
      Represents this point with all coordinates as their absolute values. For example, (x, y, z) becomes (|x|, |y|, |z|).
      Specified by:
      abs in interface Point
      Returns:
      the absolute point

    • min

      @Contract(pure=true, value="_ -> new") public Vec min(Point point)
      Description copied from interface: Point
      Gets a point representing the minimum values between this point and the provided one (x/y/z).
      Specified by:
      min in interface Point
      Parameters:
      point - the other point
      Returns:
      the minimum point

    • min

      @Contract(pure=true, value="_, _, _ -> new") public Vec min(double x, double y, double z)
      Description copied from interface: Point
      Gets a point representing the minimum values between this point and the provided coordinates (x/y/z).
      Specified by:
      min in interface Point
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      Returns:
      the minimum point

    • min

      @Contract(pure=true, value="_ -> new") public Vec min(double value)
      Description copied from interface: Point
      Gets a point representing the minimum values between this point and the provided value for all coordinates.
      Specified by:
      min in interface Point
      Parameters:
      value - the value
      Returns:
      the minimum point

    • max

      @Contract(pure=true, value="_ -> new") public Vec max(Point point)
      Description copied from interface: Point
      Gets a point representing the maximum values between this point and the provided one (x/y/z).
      Specified by:
      max in interface Point
      Parameters:
      point - the other point
      Returns:
      the maximum point

    • max

      @Contract(pure=true, value="_, _, _ -> new") public Vec max(double x, double y, double z)
      Description copied from interface: Point
      Gets a point representing the maximum values between this point and the provided coordinates (x/y/z).
      Specified by:
      max in interface Point
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      Returns:
      the maximum point

    • max

      @Contract(pure=true, value="_ -> new") public Vec max(double value)
      Description copied from interface: Point
      Gets a point representing the maximum values between this point and the provided value for all coordinates.
      Specified by:
      max in interface Point
      Parameters:
      value - the value
      Returns:
      the maximum point

    • asPosition

      @Deprecated(forRemoval=true) @Contract(pure=true) public Pos asPosition()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use Point.asPos() instead.

    • normalize

      @Contract(pure=true, value="-> new") public Vec normalize()
      Description copied from interface: Point
      Converts this point to a unit point (a point with length of 1).
      Specified by:
      normalize in interface Point
      Returns:
      the same point

    • cross

      @Contract(pure=true, value="_ -> new") public Vec cross(Point point)
      Description copied from interface: Point
      Calculates the cross product of this point with another. The cross product is defined as:
      • x = y1 * z2 - y2 * z1
      • y = z1 * x2 - z2 * x1
      • z = x1 * y2 - x2 * y1
      Specified by:
      cross in interface Point
      Parameters:
      point - the other point
      Returns:
      the cross product point

    • rotateAroundX

      @Contract(pure=true, value="_ -> new") public 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, value="_ -> new") public 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, value="_ -> new") public 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, value="_, _, _ -> new") public Vec rotate(double angleX, double angleY, double angleZ)
      Rotates the vector around the x, y, and z axes.
      Parameters:
      angleX - the angle to rotate around the x-axis in radians
      angleY - the angle to rotate around the y-axis in radians
      angleZ - the angle to rotate around the z-axis in radians
      Returns:
      a new, rotated vector

    • rotateFromView

      @Contract(pure=true, value="_, _ -> new") public Vec rotateFromView(float yawDegrees, float pitchDegrees)
      Rotates the vector from a given yaw and pitch.
      Parameters:
      yawDegrees - the yaw in degrees
      pitchDegrees - the pitch in degrees
      Returns:
      a new, rotated vector

    • rotateFromView

      @Contract(pure=true, value="_ -> new") public Vec rotateFromView(Pos pos)
      Rotates the vector from a position's view (yaw/pitch).
      Parameters:
      pos - the position containing the view
      Returns:
      a new, rotated vector

    • rotateAroundAxis

      @Contract(pure=true, value="_, _ -> new") public Vec rotateAroundAxis(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, value="_, _ -> new") public Vec rotateAroundNonUnitAxis(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, value="_, _ -> new") public Vec lerp(Point point, double alpha)
      Description copied from interface: Point
      Calculates a linear interpolation between this point with another point (x/y/z).
      Specified by:
      lerp in interface Point
      Parameters:
      point - the other point
      alpha - The alpha value, must be between 0.0 and 1.0
      Returns:
      Linear interpolated point

    • interpolate

      @Deprecated(forRemoval=true) @Contract(pure=true) public Vec interpolate(Vec target, double alpha, Vec.Interpolation interpolation)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use Point.lerp(Point, double) with a EaseFunction instead
      Calculates an interpolation between this vector and a target vector.
      Parameters:
      target - the target vector
      alpha - the alpha value, must be between 0.0 and 1.0
      interpolation - the interpolation function to use
      Returns:
      the interpolated vector

    • asVec

      @Deprecated @Contract(pure=true, value="-> this") public Vec asVec()
      Deprecated.
      Does nothing as this is already a Vec.

      Marked as deprecated to warn against redundant usage.

      Specified by:
      asVec in interface Point
      Returns:
      this vector

    • 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 the compare method from their corresponding wrapper classes.
      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