Coordinates

Minestom provides a robust coordinate system with three main types: Point, Pos, and Vec. These classes handle 3D positions, entity positions with rotation, and vector mathematics.

Point Interface

The Point interface is the base for all coordinate types in Minestom. It represents a 3D point in space.

Basic Coordinates

x()

double

Gets the X coordinate

y()

double

Gets the Y coordinate

z()

double

Gets the Z coordinate

Block Coordinates

blockX()

int

Gets the floored value of the X coordinate (block position)

blockY()

int

Gets the floored value of the Y coordinate (block position)

blockZ()

int

Gets the floored value of the Z coordinate (block position)

Chunk and Section Coordinates

chunkX()

int

Gets the chunk X coordinate (16-block sections)

chunkZ()

int

Gets the chunk Z coordinate (16-block sections)

sectionX()

int

Gets the section X coordinate

sectionY()

int

Gets the section Y coordinate

sectionZ()

int

Gets the section Z coordinate

Arithmetic Operations

add(x, y, z)

Point

Adds the specified coordinates to this point

Point newPoint = point.add(1.0, 2.0, 3.0);

add(Point)

Point

Adds another point to this point

Point result = point1.add(point2);

sub(x, y, z)

Point

Subtracts the specified coordinates from this point

mul(x, y, z)

Point

Multiplies this point by the specified coordinates

div(x, y, z)

Point

Divides this point by the specified coordinates

Distance Calculations

distance(Point)

double

Calculates the Euclidean distance between this point and another

double dist = point1.distance(point2);

distanceSquared(Point)

double

Calculates the squared distance (more efficient, avoids sqrt)

double distSq = point1.distanceSquared(point2);
if (distSq < 100) { // Within 10 blocks
    // Do something
}

Comparison Methods

samePoint(Point)

boolean

Checks if two points have identical coordinates

sameBlock(Point)

boolean

Checks if two points are in the same block

sameChunk(Point)

boolean

Checks if two points are in the same chunk

Pos (Position with View)

The Pos record represents a position with yaw and pitch rotation, typically used for entities.

public record Pos(double x, double y, double z, float yaw, float pitch)

Creating Positions

// Create position at coordinates
Pos pos = new Pos(10.5, 64.0, 20.5);

// Create position with rotation
Pos pos = new Pos(10.5, 64.0, 20.5, 90.0f, 0.0f);

// Create from Point with rotation
Pos pos = new Pos(point, 180.0f, 45.0f);

View Methods

yaw()

float

Gets the yaw rotation (-180 to 180 degrees)

pitch()

float

Gets the pitch rotation (-90 to 90 degrees)

withView(yaw, pitch)

Pos

Creates a new position with the specified view angles

Pos newPos = pos.withView(90.0f, 0.0f);

withDirection(Point)

Pos

Sets yaw and pitch to point toward a target

Pos lookingAt = pos.withDirection(targetPoint);

withLookAt(Point)

Pos

Creates a position looking at a specific point

Pos lookingAtPlayer = entity.getPosition().withLookAt(player.getPosition());

direction()

Vec

Gets a unit vector pointing in the direction of yaw and pitch

Vec dir = pos.direction();
Point target = pos.add(dir.mul(10)); // 10 blocks ahead

facing()

Direction

Gets the closest cardinal direction this position is facing

Direction dir = pos.facing(); // UP, DOWN, NORTH, SOUTH, EAST, or WEST

Coordinate Methods

withCoord(x, y, z)

Pos

Creates a new position with different coordinates but same view

Pos moved = pos.withCoord(20.0, 70.0, 30.0);

withX(x) / withY(y) / withZ(z)

Pos

Creates a new position with one coordinate changed

Pos higher = pos.withY(pos.y() + 10);

Vec (Vector)

The Vec record represents an immutable 3D vector, ideal for directions, velocities, and vector math.

public record Vec(double x, double y, double z)

Predefined Vectors

Vec.ZERO

Vec

Vector with all components at 0

Vec.ONE

Vec

Vector with all components at 1

Vec.SECTION

Vec

Vector with all components at 16 (section size)

Creating Vectors

// 3D vector
Vec vec = new Vec(1.0, 0.0, 0.0);

// 2D vector (y=0)
Vec vec = new Vec(1.0, 0.0);

// Uniform vector
Vec vec = new Vec(5.0); // (5, 5, 5)

Vector Operations

normalize()

Vec

Converts to a unit vector (length of 1)

Vec direction = vec.normalize();

length()

double

Gets the magnitude (length) of the vector

double speed = velocity.length();

lengthSquared()

double

Gets the squared magnitude (more efficient)

dot(Vec)

double

Calculates the dot product with another vector

double similarity = vec1.normalize().dot(vec2.normalize());
// 1.0 = same direction, 0.0 = perpendicular, -1.0 = opposite

cross(Vec)

Vec

Calculates the cross product (perpendicular vector)

Vec perpendicular = vec1.cross(vec2);

angle(Vec)

double

Gets the angle between two vectors in radians

double angleRad = vec1.angle(vec2);
double angleDeg = Math.toDegrees(angleRad);

Utility Operations

neg()

Vec

Negates all components

Vec opposite = vec.neg(); // (-x, -y, -z)

abs()

Vec

Gets absolute value of all components

Vec positive = vec.abs();

min(Vec)

Vec

Creates vector with minimum of each component

Vec mins = vec1.min(vec2);

max(Vec)

Vec

Creates vector with maximum of each component

Rotation Methods

rotateAroundX(angle)

Vec

Rotates vector around X-axis (angle in radians)

Vec rotated = vec.rotateAroundX(Math.PI / 2); // 90 degrees

rotateAroundY(angle)

Vec

Rotates vector around Y-axis (angle in radians)

rotateAroundZ(angle)

Vec

Rotates vector around Z-axis (angle in radians)

rotateFromView(yaw, pitch)

Vec

Rotates vector based on view angles

Vec rotated = Vec.ONE.rotateFromView(player.getPosition());

lerp(Vec, alpha)

Vec

Linear interpolation between two vectors

Vec midpoint = start.lerp(end, 0.5);
Vec quarterWay = start.lerp(end, 0.25);

BlockFace and Directions

The BlockFace enum represents the six faces of a block.

BlockFace Values

BlockFace

enum

BOTTOM - Down face (Direction.DOWN)
TOP - Up face (Direction.UP)
NORTH - North face
SOUTH - South face
WEST - West face
EAST - East face

Methods

toDirection()

Direction

Converts BlockFace to Direction

getOppositeFace()

BlockFace

Gets the opposite face

BlockFace opposite = BlockFace.TOP.getOppositeFace(); // BOTTOM

fromYaw(yaw)

BlockFace

Gets horizontal BlockFace from yaw angle

BlockFace face = BlockFace.fromYaw(player.getPosition().yaw());

relative(BlockFace)

Point

Gets adjacent point in the specified direction

Point above = point.relative(BlockFace.TOP);
Point north = point.relative(BlockFace.NORTH);

CoordConversion Utilities

The CoordConversion class provides utilities for converting between coordinate systems.

Constants

SECTION_SIZE

int

default:"16"

The size of a section (chunk width/depth)

REGION_SIZE

int

default:"512"

The size of a region in blocks

Conversion Methods

globalToBlock(xyz)

int

Converts global coordinate to block coordinate (floor)

int blockX = CoordConversion.globalToBlock(10.7); // 10

globalToChunk(xz)

int

Converts global coordinate to chunk coordinate

int chunkX = CoordConversion.globalToChunk(100.0); // 6

globalToSection(xyz)

int

Converts global coordinate to section coordinate

globalToSectionRelative(xyz)

int

Gets position within a section (0-15)

int localX = CoordConversion.globalToSectionRelative(27); // 11

Index Methods

chunkIndex(chunkX, chunkZ)

long

Encodes chunk coordinates into a single long

long index = CoordConversion.chunkIndex(10, 20);
int x = CoordConversion.chunkIndexGetX(index);
int z = CoordConversion.chunkIndexGetZ(index);

sectionBlockIndex(x, y, z)

int

Encodes section-relative coordinates (0-15) into an index

Hashing Methods

hashBlockCoord(x, y, z)

long

Generates a hash for block coordinates

long hash = CoordConversion.hashBlockCoord(point);

hashGlobalCoord(x, y, z)

long

Generates a hash for global (double) coordinates

Practical Examples

// Move entity forward
Pos currentPos = entity.getPosition();
Vec direction = currentPos.direction();
Pos newPos = currentPos.add(direction.mul(5)); // Move 5 blocks forward
entity.teleport(newPos);

All coordinate classes are immutable. Methods like add(), mul(), and withX() return new instances rather than modifying the original.

For performance-critical distance checks, use distanceSquared() instead of distance() to avoid the expensive square root calculation.

Core

Systems

Utilities

Point Interface

Basic Coordinates

Block Coordinates

Chunk and Section Coordinates

Arithmetic Operations

Distance Calculations

Comparison Methods

Pos (Position with View)

Creating Positions

View Methods

Coordinate Methods

Vec (Vector)

Predefined Vectors

Creating Vectors

Vector Operations

Utility Operations

Rotation Methods

BlockFace and Directions

BlockFace Values

Methods

CoordConversion Utilities

Constants

Conversion Methods

Index Methods

Hashing Methods

Practical Examples

Build docs developers (and LLMs) love

Core

Systems

Utilities

​Point Interface

​Basic Coordinates

​Block Coordinates

​Chunk and Section Coordinates

​Arithmetic Operations

​Distance Calculations

​Comparison Methods

​Pos (Position with View)

​Creating Positions

​View Methods

​Coordinate Methods

​Vec (Vector)

​Predefined Vectors

​Creating Vectors

​Vector Operations

​Utility Operations

​Rotation Methods

​BlockFace and Directions

​BlockFace Values

​Methods

​CoordConversion Utilities

​Constants

​Conversion Methods

​Index Methods

​Hashing Methods

​Practical Examples

Build docs developers (and LLMs) love

Point Interface

Basic Coordinates

Block Coordinates

Chunk and Section Coordinates

Arithmetic Operations

Distance Calculations

Comparison Methods

Pos (Position with View)

Creating Positions

View Methods

Coordinate Methods

Vec (Vector)

Predefined Vectors

Creating Vectors

Vector Operations

Utility Operations

Rotation Methods

BlockFace and Directions

BlockFace Values

Methods

CoordConversion Utilities

Constants

Conversion Methods

Index Methods

Hashing Methods

Practical Examples