Path Position

It’s X, Y, Z. Stored as double. It represents a precise location in the world.

However, because this library is built for Voxel/Grid worlds, this class behaves differently than a standard Vector3D you might know from Unity or Unreal.

---

Immutability (Don't Touch)

PathPosition is immutable. Once created, it cannot be changed. This makes it thread-safe by default.

• Mistake: pos.add(1, 0, 0); (Does nothing to pos)

• Correct: pos = pos.add(1, 0, 0); (Replaces pos with the new result)

If you are wondering why your entity isn't moving, check if you ignored the return value.

---

The Equality Trap (Read This!) ⚠️

This is the most important part of this page.

To optimize for grid-based pathfinding, equals() and hashCode() rely on Integer (Floored) Coordinates. The library considers any point inside the same 1x1x1 block to be the "same" position.

PathPosition a = new PathPosition(10.1, 20.5, 30.9);
PathPosition b = new PathPosition(10.9, 20.1, 30.1);

// THIS RETURNS TRUE
if (a.equals(b)) {
    System.out.println("They are in the same block!");
}

Warning

If you put a and b into a HashSet or HashMap, they will collide. This is intentional. If you need exact equality, compare the double values manually.

The Toolbelt

We included the math so you don't have to import another library.

• distance(other): True Euclidean distance. Slow (Square root).

• distanceSquared(other): Fast distance. Use this for comparisons (if distSq < 25 is faster than if dist < 5).

• manhattanDistance(other): Grid distance (Taxicab geometry).

• floor() / mid(): Snaps the double coordinates to the corner or center of the block. Essential for centering entities after a path is found.

• interpolate(other, fraction): Returns a point X% of the way to the target.