Package com.jtprince.coordinateoffset.provider

Class OffsetProvider

java.lang.Object
com.jtprince.coordinateoffset.provider.OffsetProvider
@NullMarked public abstract class OffsetProvider extends Object
An OffsetProvider is responsible for generating Offsets for players in worlds.

External API consumers may register their own OffsetProvider classes (see CoordinateOffsetAPI.registerOffsetProviderClass(java.lang.String, java.util.function.Function<com.jtprince.coordinateoffset.provider.OffsetProviderConfig, com.jtprince.coordinateoffset.provider.OffsetProvider>)). Users may then configure the registered provider class in an OffsetProvider in the CoordinateOffset config.yml. A registered provider class does nothing until a user creates an OffsetProvider in config.yml AND applies the provider.

OffsetProviders may maintain state about players, either transiently (in memory) or persistently (on disk). If persistent state is maintained, it is the responsibility of the OffsetProvider to save that state when appropriate, and to load that state when appropriate.

  • Field Details

    • OFFSET_MAX

      public static int OFFSET_MAX

    • name

      public final String name

  • Constructor Details

    • OffsetProvider

      public OffsetProvider(String userDefinedProviderName)

  • Method Details

    • provideOffset

      public abstract Offset provideOffset(OffsetProviderContext context)
      Generate a coordinate Offset for a specific player in a world.

      This function is called whenever the player's Offset has an opportunity to change. The reasons that an Offset might be changing are enumerated in OffsetProviderContext.ProvideReason.

      Parameters:
      context - Container for all context associated with this Offset change, such as the OffsetPlayer this Offset will be for, and the name of the World the Offset will be applied in.
      Returns:
      The desired offset for this player.

    • onPlayerQuit

      public void onPlayerQuit(OffsetPlayer player)
      Called on this provider whenever a player leaves. The provider may override this function to write to disk any persistent saved state related to that player.

      This is usually called before onPlayerDisconnect(UUID).

      The implementor should NOT assume that provideOffset(com.jtprince.coordinateoffset.provider.OffsetProviderContext) has been called with this Player at any point before this.

      Parameters:
      player - The player that's leaving.
      See Also:

    • onPlayerDisconnect

      public void onPlayerDisconnect(UUID playerUuid)
      Called on this provider when a player's connection is closed. The provider may override this function to clean up any cached and/or transient state related to that player.

      This is usually called after onPlayerQuit(OffsetPlayer) and may be called after the player has already left the server.

      The implementor should NOT assume that provideOffset(com.jtprince.coordinateoffset.provider.OffsetProviderContext) has been called with this Player at any point before this.

      Parameters:
      playerUuid - The UUID of the player that has disconnected. This is NOT guaranteed to correspond to an online Player at the time this function is called.
      See Also:

    • onOffsetSetByCommand

      public void onOffsetSetByCommand(OffsetSetCommand command, OffsetPlayer target)
      Callback for a player's offset being set by a command.

      This may be useful for making persistent offset stores aware of when a player's offset is set by a command so that they can update their persistent storage accordingly.

      Note that this method is only called if the target player's previous offset was generated by this offset provider. A single command may target multiple players, in which case this callback will be executed once for each targeted player. Avoid using OffsetSetCommand.getTargets() in this callback because some targeted players may have an active offset that was created by another provider.

      Parameters:
      command - Container for information about this offset change. Also contains methods which can be used to respond to the command.
      target - A player whose current offset was created by this provider and who was targeted by the command.

    • serialize

      public abstract SequencedMap<String,?> serialize()
      Serialize this offset provider.

      This method must reverse the logic provided in the provider's deserialize method.

      Returns:
      A map containing the serialized state of this offset provider. Values may be of any type that can be serialized to YAML, including nested maps.