Tolerate floating-point drift at AABB contacts

[aibengineering]

Summary

Fix AABB collision offsets when two faces that should be touching differ only by floating-point rounding.

The change adds a symmetric 1e-7 metre contact tolerance to computeOffsetX, computeOffsetY, and computeOffsetZ. It does not change the player hitbox or scale.

How we found it

We were reproducing a Mineflayer Pathfinder failure in Minecraft 1.21.4 where a bot repeatedly got stuck while climbing a compact staircase with a U-turn.

Tracing the movement showed that Pathfinder selected a valid route and the controller issued the expected input. The failure occurred later, during the local collision sweep: physics allowed the player to move a tiny distance into the block, the server corrected the position, and the controller retried the same jump.

At the block face where the bot stalled, the player AABB was reconstructed as:

4 + 0.3005 = 4.3004999999999995
4.3004999999999995 - 0.3005 = 3.9999999999999996

The two faces should meet at x = 4, but the negative-X collision check used an exact comparison:

other.minX >= this.maxX

That becomes 3.9999999999999996 >= 4, so contact is missed.

We confirmed that this was a rounding issue by trying several player half-widths. Tiny changes caused the same course to alternate between passing and failing: 0.30025 passed 4/4 runs, while the larger 0.30050 failed 4/4; 0.301 happened to pass. Because the result was non-monotonic, there was no geometrically “correct” replacement width—the width changes were only changing how the face coordinates rounded.

What changed

• Add a named CONTACT_EPSILON of 1e-7 metres.
• Compare signed face gaps on the movement axis.
• Treat epsilon-sized reconstructed overlap as contact, allowing zero movement into the obstacle.
• Apply the same rule on X, Y, and Z.
• Leave perpendicular overlap checks and intersects semantics unchanged.

The player AABB is not expanded. Real gaps retain their exact clearance, overlap beyond the tolerance keeps the existing behavior, and movement away from contact remains unrestricted.

Tests

This PR adds test/aabb.test.js with 19 AABB collision-offset tests. They cover every axis and both movement directions, including:

• exact contact;
• sub-epsilon reconstructed overlap;
• real and sub-epsilon gaps;
• requested motion smaller than a gap;
• overlap beyond the tolerance;
• movement away from contact;
• tangential perpendicular contact; and
• contact reconstructed with sub-epsilon floating-point overlap.

The complete repository test suite passes: 38 tests total (19 new AABB tests and 19 existing tests).

External movement tests

Separately from this repository's unit tests, we installed the patched package into Mineflayer Pathfinder and ran a bot through several movement courses in Minecraft Java 1.21.4.

• A compact curved staircase with a U-turn had completed 0/8 comparison runs before this change; with the patch, it completed 8/8.
• A 15-step spiral staircase completed 6/6 runs: three clockwise and three counterclockwise.
• Ordinary stairs, a tight two-block-high L-shaped tunnel, and climbing out of water each completed 3/3 runs.
• All 23 runs used the standard playerHalfWidth = 0.3 and playerHeight = 1.8, with no Pathfinder stuck resets or damage.

These movement tests are external to this repository and are not part of the prismarine-physics test suite.

Related reports

• Mineflayer 1.21.11 Pathfinding bug mineflayer#3911 reports modern movement failures and a player-scale workaround.
• Fix 1.21.x pathfinder collision bug by slightly expanding client hitbox mineflayer-pathfinder#364 proposes small player-dimension changes to avoid collision-boundary failures.

This change fixes the exact-contact rounding failure without requiring changes to player scale, half-width, or height.

[001ben]

this PR would also address PrismarineJS/mineflayer#3913 :)