Interface Point

All Known Implementing Classes:

BlockVec, Pos, Vec

public sealed interface Point
permits Vec, Pos, BlockVec

Represents a 3D point in coordinate space.

This interface has three main implementations:

• Vec - Double-precision coordinates (x, y, z)
• Pos - Double-precision coordinates with view angles (yaw, pitch)
• BlockVec - Integer block-aligned coordinates

Coordinate Scale:

• Block: Individual voxel position (1 block)
• Section: 16 blocks (SECTION_SIZE)
• Chunk: Same as a section in X and Z axis (SECTION_SIZE)
• Region: 512 blocks or 32 sections (REGION_SIZE)

Coordinate Conventions:

• Three double values represent global coordinates
• Three double values following two float values represent global position coordinates
• Three int values represent global block coordinates

Directionality:

• X increases towards East, decreases towards West
• Y increases upwards, decreases downwards
• Z increases towards South, decreases towards North

Avoid relying on Object.equals(Object) for direct Point comparison, as different implementations may represent the same 3D coordinates but be different instances. Use samePoint(Point) or samePoint(Point, double) instead. You can also ensure both points are of the same implementation, but this is fragile.

Usage: Prefer accepting Point in method parameters when only coordinate access (x/y/z) is needed. This avoids forcing callers to convert between specific implementations.

All implementations are immutable and subject to become value types. Type conversions are also explicit to avoid precision loss.

Field Summary

Fields

Modifier and Type	Field	Description
static final double	EPSILON	The smallest difference between two double values to consider them equal if applicable.
static final int	REGION_SIZE	Represents the size of a region (32 sections) or (512 blocks).
static final int	SECTION_SIZE	Represents the size of a section (16 blocks).

Method Summary

Modifier and Type	Method	Description
Point	abs()	Represents this point with all coordinates as their absolute values.
Point	add(double value)	Creates a new point by adding the provided value to this point coordinates for all XYZ.
Point	add(double x, double y, double z)	Creates a new point by adding the provided values to this point coordinates.
Point	add(Point point)	Creates a new point by adding another point coordinates to this point coordinates.
default double	angle(Point point)	Gets the angle between this point and another in radians.
default BlockVec	asBlockVec()	Converts this point to a BlockVec.
default Pos	asPos()	Converts this point to a Pos.
default Vec	asVec()	Converts this point to a Vec.
default int	blockX()	Gets the floored value of the X component
default int	blockY()	Gets the floored value of the Y component
default int	blockZ()	Gets the floored value of the Z component
default int	chunkX()	The chunk X coordinate of blockX(), also known as the section X sectionX()
default int	chunkZ()	The chunk Z coordinate of blockZ(), also known as the section Z sectionZ()
Point	cross(Point point)	Calculates the cross product of this point with another.
default double	distance(double x, double y, double z)	Gets the distance between this point and the provided coordinates.
default double	distance(Point point)	Gets the distance between this point and another.
default double	distanceSquared(double x, double y, double z)	Gets the squared distance between this point and the provided coordinates.
default double	distanceSquared(Point point)	Gets the squared distance between this point and another.
Point	div(double value)	Creates a new point by dividing the provided value to this point coordinates for all XYZ.
Point	div(double x, double y, double z)	Creates a new point by dividing the provided values to this point coordinates.
Point	div(Point point)	Creates a new point by dividing another point coordinates to this point coordinates.
default double	dot(Point point)	Calculates the dot product of this point with another.
default boolean	isNormalized()	Returns if a point is normalized
default boolean	isZero()	Checks if the three coordinates x(), y() and z() are equal to 0.
default double	length()	Gets the magnitude of the point, defined as sqrt(x^2+y^2+z^2).
default double	lengthSquared()	Gets the magnitude of the point squared.
Point	lerp(Point point, double alpha)	Calculates a linear interpolation between this point with another point (x/y/z).
Point	max(double value)	Gets a point representing the maximum values between this point and the provided value for all coordinates.
Point	max(double x, double y, double z)	Gets a point representing the maximum values between this point and the provided coordinates (x/y/z).
Point	max(Point point)	Gets a point representing the maximum values between this point and the provided one (x/y/z).
Point	min(double value)	Gets a point representing the minimum values between this point and the provided value for all coordinates.
Point	min(double x, double y, double z)	Gets a point representing the minimum values between this point and the provided coordinates (x/y/z).
Point	min(Point point)	Gets a point representing the minimum values between this point and the provided one (x/y/z).
Point	mul(double value)	Creates a new point by multiplying the provided value to this point coordinates for all XYZ.
Point	mul(double x, double y, double z)	Creates a new point by multiplying the provided values to this point coordinates.
Point	mul(Point point)	Creates a new point by multiplying another point coordinates to this point coordinates.
Point	neg()	Represents this point with all coordinates negated.
Point	normalize()	Converts this point to a unit point (a point with length of 1).
default int	regionX()	The region x coordinate of blockX(), determined by REGION_SIZE
default int	regionZ()	The region z coordinate of blockZ(), determined by REGION_SIZE
default Point	relative(BlockFace face)	Creates a new point relative to this point based on the provided block face.
default boolean	sameBlock(int blockX, int blockY, int blockZ)	Checks if the three blockX(), blockY(), blockZ(), are equal to the provided ones.
default boolean	sameBlock(Point point)	Checks if two points are in the same block.
default boolean	sameChunk(Point point)	Checks if two points are in the same chunk.
default boolean	samePoint(double x, double y, double z)	Checks if two points have similar (x/y/z).
default boolean	samePoint(double x, double y, double z, double epsilon)	Checks it two points have similar (x/y/z) coordinates within a given epsilon.
default boolean	samePoint(Point point)	Checks if two points have similar (x/y/z).
default boolean	samePoint(Point point, double epsilon)	Checks it two points have similar (x/y/z) coordinates within a given epsilon.
default int	section()	Deprecated. use sectionY() instead.
default int	sectionX()	The section x coordinate of blockX(), determined by SECTION_SIZE
default int	sectionY()	The section y coordinate of blockY(), determined by SECTION_SIZE
default int	sectionZ()	The section z coordinate of blockZ(), determined by SECTION_SIZE
default boolean	similarPoint(double x, double y, double z)	Checks it two points have similar (x/y/z) coordinates within EPSILON.
default boolean	similarPoint(Point point)	Checks it two points have similar (x/y/z) coordinates within EPSILON.
Point	sub(double value)	Creates a new point by subtracting the provided value to this point coordinates for all XYZ.
Point	sub(double x, double y, double z)	Creates a new point by subtracting the provided values to this point coordinates.
Point	sub(Point point)	Creates a new point by subtracting another point coordinates to this point coordinates.
Point	withX(double x)	Creates a point with the specified X coordinate.
Point	withX(DoubleUnaryOperator operator)	Creates a point with a modified X coordinate based on its value.
Point	withY(double y)	Creates a point with the specified Y coordinate.
Point	withY(DoubleUnaryOperator operator)	Creates a point with a modified Y coordinate based on its value.
Point	withZ(double z)	Creates a point with the specified Z coordinate.
Point	withZ(DoubleUnaryOperator operator)	Creates a point with a modified Z coordinate based on its value.
double	x()	Gets the X coordinate.
double	y()	Gets the Y coordinate.
double	z()	Gets the Z coordinate.

Field Details

EPSILON

static final double EPSILON

The smallest difference between two double values to consider them equal if applicable.

See Also:

• Constant Field Values

SECTION_SIZE

static final int SECTION_SIZE

Represents the size of a section (16 blocks).

Also known as chunk in X and Z axis.

See Also:

• Constant Field Values

REGION_SIZE

static final int REGION_SIZE

Represents the size of a region (32 sections) or (512 blocks). Used in Anvil (.mca) region files.

Regions do not normally have a Y component.

See Also:

• Constant Field Values

Method Details

x

@Contract(pure=true)
double x()

Gets the X coordinate.

Returns:

the X coordinate

y

@Contract(pure=true)
double y()

Gets the Y coordinate.

Returns:

the Y coordinate

z

@Contract(pure=true)
double z()

Gets the Z coordinate.

Returns:

the Z coordinate

blockX

@Contract(pure=true)
default int blockX()

Gets the floored value of the X component

Returns:

the block X

blockY

@Contract(pure=true)
default int blockY()

Gets the floored value of the Y component

Returns:

the block Y

blockZ

@Contract(pure=true)
default int blockZ()

Gets the floored value of the Z component

Returns:

the block Z

sectionX

@Contract(pure=true)
default int sectionX()

The section x coordinate of blockX(), determined by SECTION_SIZE

Returns:

the section x coordinate

sectionY

@Contract(pure=true)
default int sectionY()

The section y coordinate of blockY(), determined by SECTION_SIZE

Returns:

the section y coordinate

sectionZ

@Contract(pure=true)
default int sectionZ()

The section z coordinate of blockZ(), determined by SECTION_SIZE

Returns:

the section z coordinate

chunkX

@Contract(pure=true)
default int chunkX()

The chunk X coordinate of blockX(), also known as the section X sectionX()

Returns:

the chunk X coordinate

chunkZ

@Contract(pure=true)
default int chunkZ()

The chunk Z coordinate of blockZ(), also known as the section Z sectionZ()

Returns:

the chunk Z coordinate

regionX

@Contract(pure=true)
default int regionX()

The region x coordinate of blockX(), determined by REGION_SIZE

Returns:

the region x coordinate

regionZ

@Contract(pure=true)
default int regionZ()

The region z coordinate of blockZ(), determined by REGION_SIZE

Returns:

the region z coordinate

section

@Deprecated
@Contract(pure=true)
default int section()

Deprecated.

use sectionY() instead.

withX

@Contract("_ -> new")
Point withX(DoubleUnaryOperator operator)

Creates a point with a modified X coordinate based on its value.

Parameters:

operator - the operator providing the current X coordinate and returning the new

Returns:

a new point

withX

@Contract(pure=true,
          value="_ -> new")
Point withX(double x)

Creates a point with the specified X coordinate.

Parameters:

x - the new X coordinate

Returns:

a new point

withY

@Contract("_ -> new")
Point withY(DoubleUnaryOperator operator)

Creates a point with a modified Y coordinate based on its value.

Parameters:

operator - the operator providing the current Y coordinate and returning the new

Returns:

a new point

withY

@Contract(pure=true,
          value="_ -> new")
Point withY(double y)

Creates a point with the specified Y coordinate.

Parameters:

y - the new Y coordinate

Returns:

a new point

withZ

@Contract("_ -> new")
Point withZ(DoubleUnaryOperator operator)

Creates a point with a modified Z coordinate based on its value.

Parameters:

operator - the operator providing the current Z coordinate and returning the new

Returns:

a new point

withZ

@Contract(pure=true,
          value="_ -> new")
Point withZ(double z)

Creates a point with the specified Z coordinate.

Parameters:

z - the new Z coordinate

Returns:

a new point

add

@Contract(pure=true,
          value="_, _, _ -> new")
Point add(double x,
 double y,
 double z)

Creates a new point by adding the provided values to this point coordinates.

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")
Point add(Point point)

Creates a new point by adding another point coordinates to this point coordinates.

Parameters:

point - the point decomposed by x(), y() and z()

Returns:

the new point

add

@Contract(pure=true,
          value="_ -> new")
Point add(double value)

Creates a new point by adding the provided value to this point coordinates for all XYZ.

Parameters:

value - the value to add

Returns:

the new point

sub

@Contract(pure=true,
          value="_, _, _ -> new")
Point sub(double x,
 double y,
 double z)

Creates a new point by subtracting the provided values to this point coordinates.

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")
Point sub(Point point)

Creates a new point by subtracting another point coordinates to this point coordinates.

Parameters:

point - the point decomposed by x(), y() and z()

Returns:

the new point

sub

@Contract(pure=true,
          value="_ -> new")
Point sub(double value)

Creates a new point by subtracting the provided value to this point coordinates for all XYZ.

Parameters:

value - the value to subtract

Returns:

the new point

mul

@Contract(pure=true,
          value="_, _, _ -> new")
Point mul(double x,
 double y,
 double z)

Creates a new point by multiplying the provided values to this point coordinates.

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")
Point mul(Point point)

Creates a new point by multiplying another point coordinates to this point coordinates.

Parameters:

point - the point decomposed by x(), y() and z()

Returns:

the new point

mul

@Contract(pure=true,
          value="_ -> new")
Point mul(double value)

Creates a new point by multiplying the provided value to this point coordinates for all XYZ.

Parameters:

value - the value to multiply

Returns:

the new point

div

@Contract(pure=true,
          value="_, _, _ -> new")
Point div(double x,
 double y,
 double z)

Creates a new point by dividing the provided values to this point coordinates.

Warning: division by zero will not error.

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")
Point div(Point point)

Creates a new point by dividing another point coordinates to this point coordinates.

Warning: division by zero will not error.

Parameters:

point - the point decomposed by x(), y() and z()

Returns:

the new point

div

@Contract(pure=true,
          value="_ -> new")
Point div(double value)

Creates a new point by dividing the provided value to this point coordinates for all XYZ.

Warning: division by zero will not error.

Parameters:

value - the value to divide

Returns:

the new point

relative

@Contract(pure=true,
          value="_ -> new")
default Point relative(BlockFace face)

Creates a new point relative to this point based on the provided block face.

Parameters:

face - the face

Returns:

the new point

distanceSquared

@Contract(pure=true)
default double distanceSquared(double x,
 double y,
 double z)

Gets the squared distance between this point and the provided coordinates.

Parameters:

x - the x coordinate

y - the y coordinate

z - the z coordinate

Returns:

the squared distance

distanceSquared

@Contract(pure=true)
default double distanceSquared(Point point)

Gets the squared distance between this point and another.

Parameters:

point - the other point, decomposed by x(), y() and z()

Returns:

the squared distance

distance

@Contract(pure=true)
default double distance(double x,
 double y,
 double z)

Gets the distance between this point and the provided coordinates.

Parameters:

x - the x coordinate

y - the y coordinate

z - the z coordinate

Returns:

the distance

distance

@Contract(pure=true)
default double distance(Point point)

Gets the distance between this point 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 point'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:

point - the other point

Returns:

the distance

samePoint

@Contract(pure=true)
default boolean samePoint(double x,
 double y,
 double z)

Checks if two points have similar (x/y/z).

Parameters:

x - the x coordinate

y - the y coordinate

z - the z coordinate

Returns:

true if the two positions are similar

samePoint

@Contract(pure=true)
default boolean samePoint(Point point)

Checks if two points have similar (x/y/z).

Parameters:

point - the point to compare, decomposed by x(), y() and z()

Returns:

true if the two positions are similar

samePoint

@Contract(pure=true)
default boolean samePoint(double x,
 double y,
 double z,
 double epsilon)

Checks it two points have similar (x/y/z) coordinates within a given epsilon.

Parameters:

x - the x coordinate to compare

y - the y coordinate to compare

z - the z coordinate to compare

epsilon - the maximum difference allowed between the two points (exclusive)

Returns:

true if the two positions are similar within the epsilon

Throws:

IllegalArgumentException - if epsilon is less than or equal to 0

samePoint

@Contract(pure=true)
default boolean samePoint(Point point,
 double epsilon)

Checks it two points have similar (x/y/z) coordinates within a given epsilon.

Parameters:

point - the point to compare

epsilon - the maximum difference allowed between the two points (exclusive)

Returns:

true if the two positions are similar within the epsilon

Throws:

IllegalArgumentException - if epsilon is less than or equal to 0

similarPoint

@Contract(pure=true)
default boolean similarPoint(double x,
 double y,
 double z)

Checks it two points have similar (x/y/z) coordinates within EPSILON.

Parameters:

x - the x coordinate

y - the y coordinate

z - the z coordinate

Returns:

true if the two positions are similar within EPSILON

similarPoint

@Contract(pure=true)
default boolean similarPoint(Point point)

Checks it two points have similar (x/y/z) coordinates within EPSILON.

Parameters:

point - the point to compare

Returns:

true if the two positions are similar within EPSILON

isZero

@Contract(pure=true)
default boolean isZero()

Checks if the three coordinates x(), y() and z() are equal to 0.

Returns:

true if the three coordinates are zero

sameChunk

@Contract(pure=true)
default boolean sameChunk(Point point)

Checks if two points are in the same chunk.

Parameters:

point - the point to compare to

Returns:

true if 'this' is in the same chunk as point

sameBlock

@Contract(pure=true)
default boolean sameBlock(int blockX,
 int blockY,
 int blockZ)

Checks if the three blockX(), blockY(), blockZ(), are equal to the provided ones.

Parameters:

blockX - the block x

blockY - the block y

blockZ - the block z

Returns:

true if 'this' is in the same block as the provided coordinates

sameBlock

@Contract(pure=true)
default boolean sameBlock(Point point)

Checks if two points are in the same block.

Parameters:

point - the point to compare to

Returns:

true if 'this' is in the same block as point

lengthSquared

@Contract(pure=true)
default double lengthSquared()

Gets the magnitude of the point squared.

Returns:

the magnitude

length

@Contract(pure=true)
default double length()

Gets the magnitude of the point, 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 point'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

isNormalized

@Contract(pure=true)
default boolean isNormalized()

Returns if a point is normalized

Returns:

whether the point is normalized

angle

@Contract(pure=true)
default double angle(Point point)

Gets the angle between this point and another in radians.

Parameters:

point - the other point

Returns:

angle in radians

dot

@Contract(pure=true)
default double dot(Point point)

Calculates the dot product of this point with another. The dot product is defined as x1*x2+y1*y2+z1*z2. The returned value is a scalar.

Parameters:

point - the other point

Returns:

dot product

neg

@Contract(pure=true,
          value="-> new")
Point neg()

Represents this point with all coordinates negated. For example, (x, y, z) becomes (-x, -y, -z).

Returns:

the negated point

abs

@Contract(pure=true,
          value="-> new")
Point abs()

Represents this point with all coordinates as their absolute values. For example, (x, y, z) becomes (|x|, |y|, |z|).

Returns:

the absolute point

min

@Contract(pure=true,
          value="_ -> new")
Point min(Point point)

Gets a point representing the minimum values between this point and the provided one (x/y/z).

Parameters:

point - the other point

Returns:

the minimum point

min

@Contract(pure=true,
          value="_, _, _ -> new")
Point min(double x,
 double y,
 double z)

Gets a point representing the minimum values between this point and the provided coordinates (x/y/z).

Parameters:

x - the x coordinate

y - the y coordinate

z - the z coordinate

Returns:

the minimum point

min

@Contract(pure=true,
          value="_ -> new")
Point min(double value)

Gets a point representing the minimum values between this point and the provided value for all coordinates.

Parameters:

value - the value

Returns:

the minimum point

max

@Contract(pure=true,
          value="_ -> new")
Point max(Point point)

Gets a point representing the maximum values between this point and the provided one (x/y/z).

Parameters:

point - the other point

Returns:

the maximum point

max

@Contract(pure=true,
          value="_, _, _ -> new")
Point max(double x,
 double y,
 double z)

Gets a point representing the maximum values between this point and the provided coordinates (x/y/z).

Parameters:

x - the x coordinate

y - the y coordinate

z - the z coordinate

Returns:

the maximum point

max

@Contract(pure=true,
          value="_ -> new")
Point max(double value)

Gets a point representing the maximum values between this point and the provided value for all coordinates.

Parameters:

value - the value

Returns:

the maximum point

normalize

@Contract(pure=true,
          value="-> new")
Point normalize()

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

Returns:

the same point

cross

@Contract(pure=true,
          value="_ -> new")
Point cross(Point 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

Parameters:

point - the other point

Returns:

the cross product point

lerp

@Contract(pure=true,
          value="_, _ -> new")
Point lerp(Point point,
 double alpha)

Calculates a linear interpolation between this point with another point (x/y/z).

Parameters:

point - the other point

alpha - The alpha value, must be between 0.0 and 1.0

Returns:

Linear interpolated point

asPos

@Contract(pure=true,
          value="-> new")
default Pos asPos()

Converts this point to a Pos.

Returns:

the converted position or this if already a Pos

asVec

@Contract(pure=true,
          value="-> new")
default Vec asVec()

Converts this point to a Vec.

Returns:

the converted point or this if already a Vec

asBlockVec

@Contract(pure=true,
          value="-> new")
default BlockVec asBlockVec()

Converts this point to a BlockVec. Likely flooring as needed.

Returns:

the converted block point or this if already a BlockVec