Package com.jtprince.coordinateoffset

Interface Offset

All Known Implementing Classes:
FixedOffset, ScalableOffset
@NullMarked public sealed interface Offset permits FixedOffset, ScalableOffset
An offset is the amount by which a player's clientside X and Z coordinates will appear shifted compared to their real position in a world.

Offsets are subtracted from real coordinates. An offset of (16, 16) would result in a player seeing themselves at (0, 0) when they are standing at (16, 16) in the Overworld, and seeing themselves standing at (-16, -16) when they are standing at the real origin.

There are two types of offsets: FixedOffset and ScalableOffset. The difference relates to how they handle coordinate rounding and scaling for some worlds (such as the nether). To apply a specific offset that will not be rounded or scaled, use a FixedOffset. To apply an offset that automatically scales to match the coordinate scale of the world and rounds the components as needed, use a ScalableOffset. If unsure, ScalableOffset is generally preferred so that you don't have to worry about world alignment or rounding.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    ALIGN_DEFAULT_OVERWORLD
    Deprecated, for removal: This API element is subject to removal in a future version.
    Alignment is now a server configuration, offsetsAreMultiplesOfBlocks.
    static final FixedOffset
    ZERO
    The "zero" or identity offset.

  • Method Summary

    Modifier and Type
    Method
    Description
    static ScalableOffset
    align(int x, int z)
    Align offset components to the nearest N chunks and create a new ScalableOffset.
    static ScalableOffset
    align(int x, int z, int toChunksPower)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Alignment is now a server configuration, offsetsAreMultiplesOfBlocks.
    static int
    alignComponent(int component, int alignToChunksPower)
    Align a single component (X- or Z-value) to the nearest multiple of 16*2^N chunks.
    static int
    alignComponentToConfiguredMultiple(int component)
    Align a single component (X- or Z-value) to the nearest multiple of the offsetsAreMultiplesOfBlocks value that has been configured globally for the server.
    <T> T
    apply(T location)
    Apply this offset to a location.
    static FixedOffset
    fixed(int x, int z)
    Create a new fixed offset with the given components.
    boolean
    isZero()
    Check if both components of this offset are zero, resulting in no coordinate offset.
    Offset
    negate()
    Get a new Offset with the inverse components as this one (x -> -x, z -> -z).
    static ScalableOffset
    random(int bound)
    Create a new random ScalableOffset with components between negative and positive values of the given bound.
    static ScalableOffset
    random(int bound, int alignToChunksPower)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Configuration now allows the user to specify the desired chunk alignment with offsetsAreMultiplesOfBlocks.
    static ScalableOffset
    scalable(int x, int z)
    Create a new scalable offset with the given components.
    <T> T
    unapply(T location)
    Unapply this offset from a location.

  • Field Details

    • ZERO

      static final FixedOffset ZERO
      The "zero" or identity offset. This offset results in no transformation from real-world coordinates.

    • ALIGN_DEFAULT_OVERWORLD

      @Deprecated(forRemoval=true) static final int ALIGN_DEFAULT_OVERWORLD
      Deprecated, for removal: This API element is subject to removal in a future version.
      Alignment is now a server configuration, offsetsAreMultiplesOfBlocks. Check the configured value with CoordinateOffset.api().getConfig().getOffsetsAreMultiplesOf(); instead of using this hardcoded constant.
      Align offset components to the nearest 8 chunks. This number is selected because the default nether has a coordinate scale of 1/8th of the overworld, so aligning an overworld offset to the nearest 8 chunks guarantees that it will divide evenly to create an offset in the nether.
      See Also:

  • Method Details

    • fixed

      static FixedOffset fixed(int x, int z)
      Create a new fixed offset with the given components.

      Fixed offsets are absolute in any coordinate space. For example, a fixed offset of (800, 800) will always subtract 800 from the player's coordinates. This may break coordinate-based alignment between nether portals and make it possible to reverse-engineer offsets through clever use of nether portals.

      Fixed offsets also do not verify that they are multiples of the offsetsAreMultiplesOfBlocks configuration option. This may result in unexpected behavior, especially if a plugin like Distant Horizons is installed (DHSupport relies on all offsets being a multiple of a larger value like 64).

      ScalableOffset is recommended for most use cases. FixedOffset is only recommended if vanilla nether portal travel is disabled, or if the offset provider is manually performing coordinate scaling.

      Parameters:
      x - X offset value in blocks. Must be a multiple of 16. Will be subtracted from the player's real X coordinate.
      z - Z offset value in blocks. Must be a multiple of 16. Will be subtracted from the player's real Z coordinate.
      Returns:
      A new FixedOffset.

    • scalable

      static ScalableOffset scalable(int x, int z)
      Create a new scalable offset with the given components.

      A scalable offset is scaled based on the coordinate system of the world the offset is applied in. For example, a scalable offset of (800, 800) may subtract 800 blocks from the player's coordinates in the overworld and subtract 100 blocks in the nether.

      After scaling to a world, scalable offsets are rounded to the nearest configured offsetsAreMultiplesOfBlocks value, which defaults to 16 but may be higher if a plugin like Distant Horizons is installed.

      This is the preferred method of applying offsets because it ensures that coordinates still align across worlds. Players expect that entering a nether portal they see at (-4000, 4000) will bring them to (-500, 500) in the nether.

      Parameters:
      x - X offset value in blocks. Will be scaled based on world, rounded to the nearest offsetsAreMultiplesOfBlocks (likely 16) blocks, then subtracted from the player's real X coordinate.
      z - Z offset value in blocks. Will be scaled based on world, rounded to the nearest offsetsAreMultiplesOfBlocks (likely 16) blocks, then subtracted from the player's real Z coordinate.
      Returns:
      A new ScalableOffset.

    • align

      static ScalableOffset align(int x, int z)
      Align offset components to the nearest N chunks and create a new ScalableOffset.

      N is derived from the server configuration offsetsAreMultiplesOfBlocks. In most cases, this method rounds offset components to the nearest 1 chunk; however, higher values of N may be used for compatibility with plugins like Distant Horizons.

      Parameters:
      x - X offset value in blocks. Will be scaled based on world, rounded to the nearest offsetsAreMultiplesOfBlocks (likely 16) blocks, then subtracted from the player's real X coordinate.
      z - Z offset value in blocks. Will be scaled based on world, rounded to the nearest offsetsAreMultiplesOfBlocks (likely 16) blocks, then subtracted from the player's real Z coordinate.
      Returns:
      A new ScalableOffset with provided X and Z components rounded to the nearest multiple of 8*16.

    • align

      @Deprecated(forRemoval=true) static ScalableOffset align(int x, int z, int toChunksPower)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Alignment is now a server configuration, offsetsAreMultiplesOfBlocks. Use align(int, int) instead for automatic alignment based on the configured value.
      Align offset components to the nearest 2^N chunks and create a new ScalableOffset.

      Offset components must be multiples of 16 to align to 1 chunk. For minimal rounding, use toChunksPower=0. For ideal behavior, round to a number of chunks such that the resulting offset in each world will evenly divide into offsets in other worlds. For a default set of vanilla Minecraft worlds, ALIGN_DEFAULT_OVERWORLD aligns offsets to 8 chunks since the nether's coordinate scale is 1/8th of the overworld.

      Parameters:
      x - X offset value in blocks. Will be scaled based on world, then subtracted from the player's real X coordinate.
      z - Z offset value in blocks. Will be scaled based on world, then subtracted from the player's real Z coordinate.
      toChunksPower - Power of 2 to round each component to. For example, toChunksPower=3 will round each component to the nearest (2^3)=8 chunks (128 blocks).
      Returns:
      A new ScalableOffset with provided X and Z components rounded to the nearest multiple of 16*(2^p).

    • random

      static ScalableOffset random(int bound)
      Create a new random ScalableOffset with components between negative and positive values of the given bound.

      Results are guaranteed to be multiples of the globally configured offsetsAreMultiplesOfBlocks value.

      Parameters:
      bound - Maximum absolute value of the generated offset's X and Z components.
      Returns:
      A new ScalableOffset with components divisible by offsetsAreMultiplesOfBlocks.

    • random

      @Deprecated(forRemoval=true) static ScalableOffset random(int bound, int alignToChunksPower)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Configuration now allows the user to specify the desired chunk alignment with offsetsAreMultiplesOfBlocks. Use random(int) instead for automatic alignment based on the configured value.
      Create a new random ScalableOffset with components between negative and positive values of the given bound.

      Components are rounded to the nearest multiple of 2^N chunks. For minimal rounding, use toChunksPower=0. For ideal behavior, round to a number of chunks such that the resulting offset in each world will evenly divide into offsets in other worlds. For a default set of vanilla Minecraft worlds, ALIGN_DEFAULT_OVERWORLD aligns offsets to 8 chunks since the nether's coordinate scale is 1/8th of the overworld.

      Parameters:
      bound - Maximum absolute value of the generated offset's X and Z components.
      alignToChunksPower - Power of 2 to round each component to. For example, toChunksPower=3 will round each component to the nearest (2^3)=8 chunks (128 blocks).
      Returns:
      A new ScalableOffset with components divisible by 128 blocks (to ensure vanilla overworld/nether alignment; see ALIGN_DEFAULT_OVERWORLD)

    • alignComponent

      static int alignComponent(int component, int alignToChunksPower)
      Align a single component (X- or Z-value) to the nearest multiple of 16*2^N chunks.
      Parameters:
      component - X- or Z-value to align.
      alignToChunksPower - Power of 2 to round the component to. For example, toChunksPower=3 will round each component to the nearest (2^3)=8 chunks (128 blocks).
      Returns:
      The aligned component.

    • alignComponentToConfiguredMultiple

      static int alignComponentToConfiguredMultiple(int component)
      Align a single component (X- or Z-value) to the nearest multiple of the offsetsAreMultiplesOfBlocks value that has been configured globally for the server.
      Parameters:
      component - X- or Z-value to align.
      Returns:
      The aligned component.

    • apply

      @Pure <T> T apply(T location) throws ClassCastException
      Apply this offset to a location.
      Type Parameters:
      T - Either OffsetLocation or a platform-specific location object.
      Parameters:
      location - Location to apply the offset to. This may either be a OffsetLocation or a platform-specific location object, such as a Bukkit Location.
      Returns:
      A new Location object with the offset applied and all other data (including type) matching the original.
      Throws:
      ClassCastException - if the provided object is not of an acceptable type for the running platform.

    • unapply

      @Pure <T> T unapply(T location) throws ClassCastException
      Unapply this offset from a location.
      Type Parameters:
      T - Either OffsetLocation or a platform-specific location object.
      Parameters:
      location - Location to unapply the offset from. This may either be a OffsetLocation or a platform-specific location object, such as a Bukkit Location.
      Returns:
      A new Location object with the offset unapplied and all other data (including type) matching the original.
      Throws:
      ClassCastException - if the provided object is not of an acceptable type for the running platform.

    • negate

      @Pure Offset negate()
      Get a new Offset with the inverse components as this one (x -> -x, z -> -z).
      Returns:
      A new Offset.

    • isZero

      boolean isZero()
      Check if both components of this offset are zero, resulting in no coordinate offset.