Package com.jtprince.coordinateoffset.api

Interface CoordinateOffsetAPI

@NullMarked public interface CoordinateOffsetAPI
API for the CoordinateOffset plugin.

External plugins may get a singleton instance of this API via CoordinateOffset.api().

  • Method Details

    • getOffset

      FixedOffset getOffset(OffsetPlayer player)
      Get the currently active coordinate Offset for a player.

      Offsets are subtracted from a player's real coordinates to determine the coordinates they see. As an example, a player might have a coordinate offset of (128, 128). This would mean that the player standing at (128, 128) sees that they are standing at (0, 0) in the "F3" menu.

      Similarly, if the player moves to the world's origin (0, 0), they would see in "F3" that they are standing at (-128, -128).

      This Offset is subject to change, for example if the Player changes worlds.

      This method is safe to call from any thread.

      Parameters:
      player - A player currently logged in to the server. Use adaptPlayer(Object) to convert a platform-specific instance (such as a Bukkit Player) to an OffsetPlayer, or getPlayer(UUID) to get a player by their UUID.
      Returns:
      The coordinate offset this player sees, or Offset.ZERO if the player has no offset.
      See Also:

    • getOffsetData

      OffsetData getOffsetData(OffsetPlayer player)
      Get information about a player's current offset, including the source from where the offset came and the context from which the offset was generated.

      This method is safe to call from any thread.

      Parameters:
      player - A player currently logged in to the server. Use adaptPlayer(Object) to convert a platform-specific instance (such as a Bukkit Player) to an OffsetPlayer, or getPlayer(UUID) to get a player by their UUID.
      Returns:
      A container for all known data about the player's current offset.

    • regenerateOffset

      OffsetChange regenerateOffset(OffsetPlayer player)
      Immediately regenerate the player's current offset by selecting a new offset from the applicably configured offset provider. This forces a teleport effect on the player if their offset is changed, but it does not move them in real coordinate space.

      This method must only be called on the main server thread.

      Parameters:
      player - A player currently logged in to the server. Use adaptPlayer(Object) to convert a platform-specific instance (such as a Bukkit Player) to an OffsetPlayer, or getPlayer(UUID) to get a player by their UUID.
      Returns:
      A container with the player's previous and new offset, which can be inspected to determine if the offset was changed.

    • setOffset

      OffsetChange setOffset(OffsetPlayer player, Offset offset)
      Immediately set the player's current offset. This forces a teleport effect on the player if their offset is changed, but it does not move them in real coordinate space.

      Use of this function is discouraged because any applied offset will be lost as soon as the player's offset has a chance to change. This means any teleport, world change, or relog will undo the offset applied here. This is the case even if regenerateOn* options in the configuration are set to false.

      To apply an offset that persists, instead register an OffsetProvider with registerOffsetProviderClass(java.lang.String, java.util.function.Function<com.jtprince.coordinateoffset.provider.OffsetProviderConfig, com.jtprince.coordinateoffset.provider.OffsetProvider>), apply the offset provider in the plugin's configuration, and call regenerateOffset(com.jtprince.coordinateoffset.adapter.OffsetPlayer). Return the desired offset in your offset provider, and that offset will continue to be applied every time the player's offset might change.

      This method must only be called on the main server thread.

      Parameters:
      player - A player currently logged in to the server. Use adaptPlayer(Object) to convert a platform-specific instance (such as a Bukkit Player) to an OffsetPlayer, or getPlayer(UUID) to get a player by their UUID.
      offset - The new offset to apply.
      Returns:
      A container with the player's previous and new offset, which can be inspected to determine if the offset was changed.

    • getPlayer

      @Nullable OffsetPlayer getPlayer(UUID playerUuid)
      Get an OffsetPlayer instance for a player currently connected to the server by their UUID.
      Parameters:
      playerUuid - The UUID of a player currently connected to the server.
      Returns:
      An OffsetPlayer instance for the player, or null if no matching player is connected.

    • adaptPlayer

      OffsetPlayer adaptPlayer(Object platformPlayerObject) throws ClassCastException
      Adapt a platform-specific player object (such as a Bukkit Player) into an OffsetPlayer.

      This method is safe to call from any thread.

      Parameters:
      platformPlayerObject - A platform-specific player object. The exact type depends on the platform adapter in use. For example, on a Paper server, this would be an instance of org.bukkit.entity.Player.
      Returns:
      An OffsetPlayer instance for the player.
      Throws:
      ClassCastException - if the provided object is not of the expected type for the running platform.

    • adaptLocation

      OffsetLocation adaptLocation(Object platformLocationObject) throws ClassCastException
      Adapt a platform-specific location object (such as a Bukkit Location) into an OffsetLocation.

      This method is safe to call from any thread.

      Parameters:
      platformLocationObject - A platform-specific location object. The exact type depends on the platform adapter in use. For example, on a Paper server, this would be an instance of org.bukkit.Location.
      Returns:
      An OffsetLocation instance for the location.
      Throws:
      ClassCastException - if the provided object is not of the expected type for the running platform.

    • getConfig

      CoordinateOffsetConfig getConfig()
      Get running configuration of the CoordinateOffset plugin.

      Configured Offset Providers are not accessible here because they load after the main CoordinateOffset config. See getProviderConfig() for provider-specific configuration access.

      Returns:
      The current configuration.

    • getProviderConfig

      CoordinateOffsetProviderConfig getProviderConfig()
      Get Offset Providers configured in the CoordinateOffset configuration.

      Offset Providers load after external plugins have a chance to register new OffsetProvider classes, so this function must only be called after the server has finished starting up.

      See getConfig() for general configuration access.

      Returns:
      The current configuration.
      Throws:
      IllegalStateException - if Offset Provider configuration has not yet been loaded.

    • registerOffsetProviderClass

      void registerOffsetProviderClass(String className, Function<OffsetProviderConfig,OffsetProvider> deserializeFunction)
      Register a new OffsetProvider class that can be used in the CoordinateOffset configuration.
      Parameters:
      className - A class name to identify the provider in the configuration. Users may activate this provider by creating a provider in the CoordinateOffset config.yml with a class: parameter matching this name. This should be a simple string matching the class name of the provider, for example "MyOffsetProvider".
      deserializeFunction - A function that can create instances of the provider from configuration data. For examples, see the built-in providers.