Package org.bukkit.util

Class Vector

java.lang.Object

org.bukkit.util.Vector

All Implemented Interfaces:

Cloneable, ConfigurationSerializable

Direct Known Subclasses:

BlockVector

public class Vector
extends Object
implements Cloneable, ConfigurationSerializable

Represents a mutable vector. Because the components of Vectors are mutable, storing Vectors long term may be dangerous if passing code modifies the Vector later. If you want to keep around a Vector, it may be wise to call clone() in order to get a copy.

Field Summary

Fields

Modifier and Type	Field	Description
protected double	x
protected double	y
protected double	z

Constructor Summary

Constructors

Constructor	Description
Vector()	Construct the vector with all components as 0.
Vector(double x, double y, double z)	Construct the vector with provided double components.
Vector(float x, float y, float z)	Construct the vector with provided float components.
Vector(int x, int y, int z)	Construct the vector with provided integer components.

Method Summary

Modifier and Type	Method	Description
Vector	add(Vector vec)	Adds a vector to this one
float	angle(Vector other)	Gets the angle between this vector and another in radians.
void	checkFinite()	Check if each component of this Vector is finite.
Vector	clone()	Get a new vector.
Vector	copy(Vector vec)	Copies another vector
Vector	crossProduct(Vector o)	Calculates the cross product of this vector with another.
static Vector	deserialize(Map<String,Object> args)
double	distance(Vector o)	Get the distance between this vector and another.
double	distanceSquared(Vector o)	Get the squared distance between this vector and another.
Vector	divide(Vector vec)	Divides the vector by another.
double	dot(Vector other)	Calculates the dot product of this vector with another.
boolean	equals(Object obj)	Checks to see if two objects are equal.
static Vector	fromJOML(org.joml.Vector3d vector)	Gets a vector with components that match the provided JOML Vector3d.
static Vector	fromJOML(org.joml.Vector3dc vector)	Gets a vector with components that match the provided JOML Vector3dc.
static Vector	fromJOML(org.joml.Vector3f vector)	Gets a vector with components that match the provided JOML Vector3f.
static Vector	fromJOML(org.joml.Vector3fc vector)	Gets a vector with components that match the provided JOML Vector3fc.
static Vector	fromJOML(org.joml.Vector3i vector)	Gets a vector with components that match the provided JOML Vector3i.
static Vector	fromJOML(org.joml.Vector3ic vector)	Gets a vector with components that match the provided JOML Vector3ic.
int	getBlockX()	Gets the floored value of the X component, indicating the block that this vector is contained with.
int	getBlockY()	Gets the floored value of the Y component, indicating the block that this vector is contained with.
int	getBlockZ()	Gets the floored value of the Z component, indicating the block that this vector is contained with.
Vector	getCrossProduct(Vector o)	Calculates the cross product of this vector with another without mutating the original.
static double	getEpsilon()	Get the threshold used for equals().
static Vector	getMaximum(Vector v1, Vector v2)	Gets the maximum components of two vectors.
Vector	getMidpoint(Vector other)	Gets a new midpoint vector between this vector and another.
static Vector	getMinimum(Vector v1, Vector v2)	Gets the minimum components of two vectors.
static Vector	getRandom()	Gets a random vector with components having a random value between 0 and 1.
double	getX()	Gets the X component.
double	getY()	Gets the Y component.
double	getZ()	Gets the Z component.
int	hashCode()	Returns a hash code for this vector
boolean	isInAABB(Vector min, Vector max)	Returns whether this vector is in an axis-aligned bounding box.
boolean	isInSphere(Vector origin, double radius)	Returns whether this vector is within a sphere.
boolean	isNormalized()	Returns if a vector is normalized
boolean	isZero()	Check whether or not each component of this vector is equal to 0.
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.
Vector	midpoint(Vector other)	Sets this vector to the midpoint between this vector and another.
Vector	multiply(double m)	Performs scalar multiplication, multiplying all components with a scalar.
Vector	multiply(float m)	Performs scalar multiplication, multiplying all components with a scalar.
Vector	multiply(int m)	Performs scalar multiplication, multiplying all components with a scalar.
Vector	multiply(Vector vec)	Multiplies the vector by another.
Vector	normalize()	Converts this vector to a unit vector (a vector with length of 1).
Vector	rotateAroundAxis(Vector axis, double angle)	Rotates the vector around a given arbitrary axis in 3 dimensional space.
Vector	rotateAroundNonUnitAxis(Vector axis, double angle)	Rotates the vector around a given arbitrary axis in 3 dimensional space.
Vector	rotateAroundX(double angle)	Rotates the vector around the x axis.
Vector	rotateAroundY(double angle)	Rotates the vector around the y axis.
Vector	rotateAroundZ(double angle)	Rotates the vector around the z axis
Map<String,Object>	serialize()	Creates a Map representation of this class.
Vector	setX(double x)	Set the X component.
Vector	setX(float x)	Set the X component.
Vector	setX(int x)	Set the X component.
Vector	setY(double y)	Set the Y component.
Vector	setY(float y)	Set the Y component.
Vector	setY(int y)	Set the Y component.
Vector	setZ(double z)	Set the Z component.
Vector	setZ(float z)	Set the Z component.
Vector	setZ(int z)	Set the Z component.
Vector	subtract(Vector vec)	Subtracts a vector from this one.
BlockVector	toBlockVector()	Get the block vector of this vector.
Location	toLocation(World world)	Gets a Location version of this vector with yaw and pitch being 0.
Location	toLocation(World world, float yaw, float pitch)	Gets a Location version of this vector.
String	toString()	Returns this vector's components as x,y,z.
org.joml.Vector3d	toVector3d()	Get this vector as a JOML Vector3d.
org.joml.Vector3f	toVector3f()	Get this vector as a JOML Vector3f.
org.joml.Vector3i	toVector3i()	Get this vector as a JOML Vector3i with its components floored.
org.joml.Vector3i	toVector3i(int roundingMode)	Get this vector as a JOML Vector3i.
Vector	zero()	Zero this vector's components.

Methods inherited from class java.lang.Object

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

Field Details

x

protected double x

y

protected double y

z

protected double z

Constructor Details

Vector

public Vector()

Construct the vector with all components as 0.

Vector

public Vector(int x,
 int y,
 int z)

Construct the vector with provided integer components.

Parameters:

x - X component

y - Y component

z - Z component

Vector

public Vector(double x,
 double y,
 double z)

Construct the vector with provided double components.

Parameters:

x - X component

y - Y component

z - Z component

Vector

public Vector(float x,
 float y,
 float z)

Construct the vector with provided float components.

Parameters:

x - X component

y - Y component

z - Z component

Method Details

add

@NotNull
public Vector add(@NotNull
 Vector vec)

Adds a vector to this one

Parameters:

vec - The other vector

Returns:

the same vector

subtract

@NotNull
public Vector subtract(@NotNull
 Vector vec)

Subtracts a vector from this one.

Parameters:

vec - The other vector

Returns:

the same vector

multiply

@NotNull
public Vector multiply(@NotNull
 Vector vec)

Multiplies the vector by another.

Parameters:

vec - The other vector

Returns:

the same vector

divide

@NotNull
public Vector divide(@NotNull
 Vector vec)

Divides the vector by another.

Parameters:

vec - The other vector

Returns:

the same vector

copy

@NotNull
public Vector copy(@NotNull
 Vector vec)

Copies another vector

Parameters:

vec - The other vector

Returns:

the same vector

length

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

lengthSquared

public double lengthSquared()

Gets the magnitude of the vector squared.

Returns:

the magnitude

distance

public double distance(@NotNull
 Vector o)

Get the distance between this vector and another. 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 distance is too long.

Parameters:

o - The other vector

Returns:

the distance

distanceSquared

public double distanceSquared(@NotNull
 Vector o)

Get the squared distance between this vector and another.

Parameters:

o - The other vector

Returns:

the distance

angle

public float angle(@NotNull
 Vector other)

Gets the angle between this vector and another in radians.

Parameters:

other - The other vector

Returns:

angle in radians

midpoint

@NotNull
public Vector midpoint(@NotNull
 Vector other)

Sets this vector to the midpoint between this vector and another.

Parameters:

other - The other vector

Returns:

this same vector (now a midpoint)

getMidpoint

@NotNull
public Vector getMidpoint(@NotNull
 Vector other)

Gets a new midpoint vector between this vector and another.

Parameters:

other - The other vector

Returns:

a new midpoint vector

multiply

@NotNull
public Vector multiply(int m)

Performs scalar multiplication, multiplying all components with a scalar.

Parameters:

m - The factor

Returns:

the same vector

multiply

@NotNull
public Vector multiply(double m)

Performs scalar multiplication, multiplying all components with a scalar.

Parameters:

m - The factor

Returns:

the same vector

multiply

@NotNull
public Vector multiply(float m)

Performs scalar multiplication, multiplying all components with a scalar.

Parameters:

m - The factor

Returns:

the same vector

dot

public double dot(@NotNull
 Vector other)

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:

other - The other vector

Returns:

dot product

crossProduct

@NotNull
public Vector crossProduct(@NotNull
 Vector 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

getCrossProduct

@NotNull
public Vector getCrossProduct(@NotNull
 Vector o)

Calculates the cross product of this vector with another without mutating the original. 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:

a new vector

normalize

@NotNull
public Vector normalize()

Converts this vector to a unit vector (a vector with length of 1).

Returns:

the same vector

zero

@NotNull
public Vector zero()

Zero this vector's components.

Returns:

the same vector

isZero

public boolean isZero()

Check whether or not each component of this vector is equal to 0.

Returns:

true if equal to zero, false if at least one component is non-zero

isInAABB

public boolean isInAABB(@NotNull
 Vector min,
 @NotNull
 Vector max)

Returns whether this vector is in an axis-aligned bounding box.

The minimum and maximum vectors given must be truly the minimum and maximum X, Y and Z components.

Parameters:

min - Minimum vector

max - Maximum vector

Returns:

whether this vector is in the AABB

isInSphere

public boolean isInSphere(@NotNull
 Vector origin,
 double radius)

Returns whether this vector is within a sphere.

Parameters:

origin - Sphere origin.

radius - Sphere radius

Returns:

whether this vector is in the sphere

isNormalized

public boolean isNormalized()

Returns if a vector is normalized

Returns:

whether the vector is normalised

rotateAroundX

@NotNull
public Vector 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:

the same vector

rotateAroundY

@NotNull
public Vector 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:

the same vector

rotateAroundZ

@NotNull
public Vector 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:

the same vector

rotateAroundAxis

@NotNull
public Vector rotateAroundAxis(@NotNull
 Vector 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(Vector, 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:

the same vector

Throws:

IllegalArgumentException - if the provided axis vector instance is null

rotateAroundNonUnitAxis

@NotNull
public Vector rotateAroundNonUnitAxis(@NotNull
 Vector 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(Vector, double)

Parameters:

axis - the axis to rotate the vector around.

angle - the angle to rotate the vector around the axis

Returns:

the same vector

Throws:

IllegalArgumentException - if the provided axis vector instance is null

getX

public double getX()

Gets the X component.

Returns:

The X component.

getBlockX

public int getBlockX()

Gets the floored value of the X component, indicating the block that this vector is contained with.

Returns:

block X

getY

public double getY()

Gets the Y component.

Returns:

The Y component.

getBlockY

public int getBlockY()

Gets the floored value of the Y component, indicating the block that this vector is contained with.

Returns:

block y

getZ

public double getZ()

Gets the Z component.

Returns:

The Z component.

getBlockZ

public int getBlockZ()

Gets the floored value of the Z component, indicating the block that this vector is contained with.

Returns:

block z

setX

@NotNull
public Vector setX(int x)

Set the X component.

Parameters:

x - The new X component.

Returns:

This vector.

setX

@NotNull
public Vector setX(double x)

Set the X component.

Parameters:

x - The new X component.

Returns:

This vector.

setX

@NotNull
public Vector setX(float x)

Set the X component.

Parameters:

x - The new X component.

Returns:

This vector.

setY

@NotNull
public Vector setY(int y)

Set the Y component.

Parameters:

y - The new Y component.

Returns:

This vector.

setY

@NotNull
public Vector setY(double y)

Set the Y component.

Parameters:

y - The new Y component.

Returns:

This vector.

setY

@NotNull
public Vector setY(float y)

Set the Y component.

Parameters:

y - The new Y component.

Returns:

This vector.

setZ

@NotNull
public Vector setZ(int z)

Set the Z component.

Parameters:

z - The new Z component.

Returns:

This vector.

setZ

@NotNull
public Vector setZ(double z)

Set the Z component.

Parameters:

z - The new Z component.

Returns:

This vector.

setZ

@NotNull
public Vector setZ(float z)

Set the Z component.

Parameters:

z - The new Z component.

Returns:

This vector.

equals

public boolean equals(Object obj)

Checks to see if two objects are equal.

Only two Vectors can ever return true. This method uses a fuzzy match to account for floating point errors. The epsilon can be retrieved with epsilon.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code for this vector

Overrides:

hashCode in class Object

Returns:

hash code

clone

@NotNull
public Vector clone()

Get a new vector.

Overrides:

clone in class Object

Returns:

vector

toString

public String toString()

Returns this vector's components as x,y,z.

Overrides:

toString in class Object

toLocation

@NotNull
public Location toLocation(@NotNull
 World world)

Gets a Location version of this vector with yaw and pitch being 0.

Parameters:

world - The world to link the location to.

Returns:

the location

toLocation

@NotNull
public Location toLocation(@NotNull
 World world,
 float yaw,
 float pitch)

Gets a Location version of this vector.

Parameters:

world - The world to link the location to.

yaw - The desired yaw.

pitch - The desired pitch.

Returns:

the location

toBlockVector

@NotNull
public BlockVector toBlockVector()

Get the block vector of this vector.

Returns:

A block vector.

toVector3f

@NotNull
public org.joml.Vector3f toVector3f()

Get this vector as a JOML Vector3f.

Returns:

the JOML vector

toVector3d

@NotNull
public org.joml.Vector3d toVector3d()

Get this vector as a JOML Vector3d.

Returns:

the JOML vector

toVector3i

@NotNull
public org.joml.Vector3i toVector3i(int roundingMode)

Get this vector as a JOML Vector3i.

Parameters:

roundingMode - the RoundingMode to use for this vector's components

Returns:

the JOML vector

toVector3i

@NotNull
public org.joml.Vector3i toVector3i()

Get this vector as a JOML Vector3i with its components floored.

Returns:

the JOML vector

See Also:

• toVector3i(int)

checkFinite

public void checkFinite()
                 throws IllegalArgumentException

Check if each component of this Vector is finite.

Throws:

IllegalArgumentException - if any component is not finite

getEpsilon

public static double getEpsilon()

Get the threshold used for equals().

Returns:

The epsilon.

getMinimum

@NotNull
public static Vector getMinimum(@NotNull
 Vector v1,
 @NotNull
 Vector v2)

Gets the minimum components of two vectors.

Parameters:

v1 - The first vector.

v2 - The second vector.

Returns:

minimum

getMaximum

@NotNull
public static Vector getMaximum(@NotNull
 Vector v1,
 @NotNull
 Vector v2)

Gets the maximum components of two vectors.

Parameters:

v1 - The first vector.

v2 - The second vector.

Returns:

maximum

getRandom

@NotNull
public static Vector getRandom()

Gets a random vector with components having a random value between 0 and 1.

Returns:

A random vector.

fromJOML

@NotNull
public static Vector fromJOML(@NotNull
 org.joml.Vector3f vector)

Gets a vector with components that match the provided JOML Vector3f.

Parameters:

vector - the vector to match

Returns:

the new vector

fromJOML

@NotNull
public static Vector fromJOML(@NotNull
 org.joml.Vector3d vector)

Gets a vector with components that match the provided JOML Vector3d.

Parameters:

vector - the vector to match

Returns:

the new vector

fromJOML

@NotNull
public static Vector fromJOML(@NotNull
 org.joml.Vector3i vector)

Gets a vector with components that match the provided JOML Vector3i.

Parameters:

vector - the vector to match

Returns:

the new vector

fromJOML

@NotNull
public static Vector fromJOML(@NotNull
 org.joml.Vector3fc vector)

Gets a vector with components that match the provided JOML Vector3fc.

Parameters:

vector - the vector to match

Returns:

the new vector

fromJOML

@NotNull
public static Vector fromJOML(@NotNull
 org.joml.Vector3dc vector)

Gets a vector with components that match the provided JOML Vector3dc.

Parameters:

vector - the vector to match

Returns:

the new vector

fromJOML

@NotNull
public static Vector fromJOML(@NotNull
 org.joml.Vector3ic vector)

Gets a vector with components that match the provided JOML Vector3ic.

Parameters:

vector - the vector to match

Returns:

the new vector

serialize

@NotNull
public Map<String,Object> serialize()

Description copied from interface: ConfigurationSerializable

Creates a Map representation of this class.

This class must provide a method to restore this class, as defined in the ConfigurationSerializable interface javadocs.

Specified by:

serialize in interface ConfigurationSerializable

Returns:

Map containing the current state of this class

deserialize

@NotNull
public static Vector deserialize(@NotNull
 Map<String,Object> args)