Package de.bsommerfeld.pathetic.engine.util

Class RegionKey

java.lang.Object
de.bsommerfeld.pathetic.engine.util.RegionKey
public final class RegionKey extends Object
Utility class to pack 3D grid coordinates into a single primitive long.

Layout: [X: 22 bit] [Z: 22 bit] [Y: 20 bit]
Range X/Z: [-2,097,152, 2,097,151] (signed 22-bit)
Range Y: [-524,288, 524,287] (signed 20-bit)

Keys are search-relative, not absolute. The engine packs coordinates as offsets from the search origin (the floored start position, see AStarSearchState), so the ranges above bound the exploration radius of a single search, not world coordinates. Absolute positions may use the full int range. A search cannot expand positions farther from its start than the per-axis range; the pathfinder treats such positions as non-navigable. The radius is far beyond what a search can reach in practice: spanning it requires at least 2 million expansions in a straight line with unit offsets (bounded by maxIterations and, before that, by search-state memory), or a custom INeighborStrategy with very large offset vectors.

Each field is two's-complement and only injective within its range. Coordinates outside the supported range are rejected with IllegalArgumentException rather than silently aliasing through the bit mask (which would map distinct positions onto the same key and corrupt the closed set and heap lookups). Callers iterating positions that may leave the range must check isInRange(int, int, int) first.

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    isInRange(int x, int y, int z)
    Checks whether the given (search-relative) coordinates fit into the packed layout, i.e.
    static long
    pack(int x, int y, int z)
    Packs raw integer coordinates into a primitive long key.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • isInRange

      public static boolean isInRange(int x, int y, int z)
      Checks whether the given (search-relative) coordinates fit into the packed layout, i.e. whether pack(int, int, int) would accept them. Callers iterating positions that may leave the supported range (e.g. neighbor expansion at the edge of the exploration radius) should use this to skip such positions instead of letting pack throw.

    • pack

      public static long pack(int x, int y, int z)
      Packs raw integer coordinates into a primitive long key.
      Throws:
      IllegalArgumentException - if any coordinate is outside the supported range (X/Z in [-2097152, 2097151], Y in [-524288, 524287])