Package de.marcely.bedwars.api.remote

Interface RemoteAPI

public interface RemoteAPI
Generally, this API only gets replaced by the ProxySync addon. If it is not, because it for instance not installed, a general-use implementation will be used. In that case, it will for instance only return all arenas of the local server. This makes adding support for both solutions very easy, as you can just use this API if you plan to add support for remote servers, or just BedwarsAPI.getRemoteAPI() if you don't.

  • Method Details

    • isLocalOnly

      boolean isLocalOnly()
      Returns whether a networking system has been actually implemented.

      Generally, this method returns false, meaning that you might as well just use the generic-use API. Plugins (such as the Enhanced ProxySync) addon may replace the RemoteAPI with their own. In this case, they should return true.

      Returns:
      true when it's only working with the local information

    • isAPIActive

      default boolean isAPIActive()
      Returns whether the current instance is actually the instance that is currently implemented.

      In case this method returns false, the instance returned with BedwarsAPI.getRemoteAPI() differs from this one.

      Returns:
      true when you may continue using this object

    • getImplementingPlugin

      Plugin getImplementingPlugin()
      Returns the plugin that has implemented the current RemoteAPI instance.

      By default, it will output the same as BedwarsAPI.getPlugin().

      Returns:
      The plugin that has implemented the remote system

    • getArenas

      Collection<? extends RemoteArena> getArenas(boolean includeLocal)
      Returns known arenas.
      Parameters:
      includeLocal - true: all arenas, false: only the ones from the other servers
      Returns:
      A collection of arenas

    • getArenas

      default Collection<? extends RemoteArena> getArenas()
      Returns all existing arenas.

      This includes the ones on this servers and the ones on the other servers.

      Returns:
      All (known) arenas

    • getArenaByName

      @Nullable @Nullable RemoteArena getArenaByName(String name)
      Looks for an arena with that name and optionally parses it as an arena picker.
      Parameters:
      name - The name of the arena
      Returns:
      The arena instance. Returns null if it hasn't found it

    • getArenaByExactName

      @Nullable @Nullable RemoteArena getArenaByExactName(String name)
      Looks for an arena with exactly that name.

      Ignores display name, arena pickers etc.

      Parameters:
      name - The name of the arena
      Returns:
      The arena instance. Returns null if it hasn't found it

    • getArenaByPlayingPlayer

      @Nullable @Nullable RemoteArena getArenaByPlayingPlayer(UUID uuid)
      Looks for an arena with that player inside the arena.

      Ignores spectators and the state of the arena, meaning it doesn't care whether the arena is currently in lobby, running or in endlobby.

      Parameters:
      uuid - The uuid of the player who joined the arena
      Returns:
      The arena instance. Returns null when the player isn't inside the arena

    • getArenaByPlayingPlayer

      @Nullable default @Nullable RemoteArena getArenaByPlayingPlayer(RemotePlayer player)
      Looks for an arena with that player inside the arena.

      Ignores spectators and the state of the arena, meaning it doesn't care whether the arena is currently in lobby, running or in endlobby.

      Parameters:
      player - The player who joined the arena
      Returns:
      The arena instance. Returns null when the player isn't inside the arena

    • getArenaByPlayingPlayer

      @Nullable default @Nullable RemoteArena getArenaByPlayingPlayer(OfflinePlayer player)
      Looks for an arena with that player inside the arena.

      Ignores spectators and the state of the arena, meaning it doesn't care whether the arena is currently in lobby, running or in endlobby.

      Parameters:
      player - The player who joined the arena
      Returns:
      The arena instance. Returns null when the player isn't inside the arena

    • getArenaBySpectator

      @Nullable @Nullable RemoteArena getArenaBySpectator(UUID uuid)
      Looks for an arena with that player spectating the arena.

      Ignores normal players and the state of the arena, meaning it doesn't care whether the arena is currently in lobby, running or in endlobby.

      Parameters:
      uuid - The uuid of the player who's spectating the arena
      Returns:
      The arena instance. Returns null when the player isn't spectating any arena

    • getArenaBySpectator

      @Nullable default @Nullable RemoteArena getArenaBySpectator(RemotePlayer player)
      Looks for an arena with that player spectating the arena.

      Ignores normal players and the state of the arena, meaning it doesn't care whether the arena is currently in lobby, running or in endlobby.

      Parameters:
      player - The player who's spectating the arena
      Returns:
      The arena instance. Returns null when the player isn't spectating any arena

    • getArenaBySpectator

      @Nullable default @Nullable RemoteArena getArenaBySpectator(OfflinePlayer player)
      Looks for an arena with that player spectating the arena.

      Ignores normal players and the state of the arena, meaning it doesn't care whether the arena is currently in lobby, running or in endlobby.

      Parameters:
      player - The player who's spectating the arena
      Returns:
      The arena instance. Returns null when the player isn't spectating any arena

    • getOnlinePlayers

      Collection<? extends RemotePlayer> getOnlinePlayers()
      Returns a collection of all known online players on the network.
      Returns:
      All players on the network

    • getOnlinePlayer

      @Nullable @Nullable RemotePlayer getOnlinePlayer(UUID uuid)
      Returns the information of a player that is currently online on the network.
      Parameters:
      uuid - The uuid of the player who's currently on the network
      Returns:
      The info object. May be null when the player isn't online

    • getOnlinePlayer

      @Nullable @Nullable RemotePlayer getOnlinePlayer(OfflinePlayer player)
      Returns the information of a player that is currently online on the network.
      Parameters:
      player - The player who's currently on the network
      Returns:
      The info object. May be null when the player isn't online

    • getOnlinePlayer

      @Nullable @Nullable RemotePlayer getOnlinePlayer(String name)
      Returns the information of a player that is currently online on the network.
      Parameters:
      name - The username of the player
      Returns:
      The info object. May be null when there's no player with the given name

    • getServers

      Collection<? extends RemoteServer> getServers()
      Returns a collection of all known servers (including the local one getLocalServer()).
      Returns:
      All known servers on the network

    • getLocalServer

      RemoteServer getLocalServer()
      Returns the local server.
      Returns:
      The local server

    • teleportPlayerToArena

      void teleportPlayerToArena(RemotePlayer player, RemoteArena arena, boolean sendMessage, @Nullable @Nullable Consumer<Boolean> callback)
      Makes the teleport himself into the arena. He will not actually play in it!

      Note: The reason it is located in RemoteAPI is to add an integration layer for the plugin implementing the network layer.
      Alternative methods:
      - RemoteArena.teleportHere(RemotePlayer)
      - RemoteArena.teleportHere(RemotePlayer, boolean)
      - RemoteArena.teleportHere(RemotePlayer, Consumer)
      - RemoteArena.teleportHere(RemotePlayer, boolean, Consumer)

      Parameters:
      player - The player that shall get teleported
      arena - The arena in which he gets teleported into
      sendMessage - Whether a message shall be sent to the player when it failed or was succesful
      callback - A callback you may use to find out whether it was successful. May be null

    • addSpectatorToArena

      void addSpectatorToArena(RemotePlayer player, RemoteArena arena, SpectateReason reason, boolean ignoreArenaState, @Nullable @Nullable Consumer<RemoteSpectatorAddResult> callback)
      Makes a player enter an arena as a spectator.

      Note: The reason it is located in RemoteAPI is to add an integration layer for the plugin implementing the network layer.
      Alternative methods:
      - RemoteArena.addSpectator(RemotePlayer)
      - RemoteArena.addSpectator(RemotePlayer, boolean)
      - RemoteArena.addSpectator(RemotePlayer, Consumer)
      - RemoteArena.addSpectator(RemotePlayer, boolean, Consumer)
      - RemoteArena.addSpectator(RemotePlayer, SpectateReason)
      - RemoteArena.addSpectator(RemotePlayer, SpectateReason, boolean)
      - RemoteArena.addSpectator(RemotePlayer, SpectateReason, Consumer)
      - RemoteArena.addSpectator(RemotePlayer, SpectateReason, boolean, Consumer)

      Parameters:
      player - The player who shall enter as a spectator
      arena - The arena he shall enter
      reason - The reason he's spectating
      ignoreArenaState - true: Will always join the arena, even when the arena is not running
      callback - The callback you may use to find out whether it was successful. May be null

    • addPlayerToArena

      void addPlayerToArena(AddRemotePlayerInfo info, RemoteArena arena, @Nullable @Nullable Consumer<RemotePlayerAddResult> callback)
      Makes the player enter the arena and play in it.

      Note: The reason it is located in RemoteAPI is to add an integration layer for the plugin implementing the network layer.
      Alternative methods:
      - RemoteArena.addPlayer(RemotePlayer)
      - RemoteArena.addPlayer(RemotePlayer, Team)
      - RemoteArena.addPlayer(RemotePlayer, Consumer)
      - RemoteArena.addPlayer(RemotePlayer, Team, Consumer)
      - RemoteArena.addPlayer(AddRemotePlayerInfo, Consumer)

      Parameters:
      info - Contains all the info, such as the players who is joining the arena
      arena - The arena they/he shall join
      callback - The callback you may use to find out whether it was successful. May be null

    • sendToHub

      void sendToHub(RemotePlayer player)
      Causes a player to get teleported to the hub server.

      It's possible that nothing will happen when he's already on a hub server.

      Parameters:
      player - The player who shall get moved

    • isInstantPlayerDataSyncingActive

      boolean isInstantPlayerDataSyncingActive()
      Returns whether sync-player-data is active in ProxySync's configs.

      Player data refers to its stats, properties and achievements.

      As MBedwars by default doesn't support immediate player data syncing, this method will return false in case the ProxySync addon is not installed.

      Returns:
      Whether the current RemoteAPI implementation supports instant player data syncing

    • broadcastCustomMessage

      void broadcastCustomMessage(String channel, byte[] payload)
      Sends a custom message to any server on the network (apart from the local one).

      This method is useful when you want to communicate between servers. Use RemoteCustomMessageReceiveEvent to listen to the message.

      Note that the message may not be received if the connection to other servers hasn't be established yet. You may use the #size() method of getServers() to identify whether there are other servers on the network.

      The channel parameter is useful as it allows you to be distant from other plugins that make use of the messaging system as well. You may e.g. insert the name of your plugin. Note that encoded as UTF-8. You may later use RemoteCustomMessageReceiveEvent.getChannel() to identify the channel again.

      Parameters:
      channel - The channel in which you want to communicate
      payload - The actual message that you want to send. Use e.g. String.getBytes() to pass a String.
      Throws:
      IllegalArgumentException - When channel name is longer than 255 bytes or when payload is larger than 10MB (not a typo)
      See Also:

    • flushQueuedPlayerData

      void flushQueuedPlayerData()
      Transfers all queued-up player data to the other servers.

      In case isInstantPlayerDataSyncingActive() is active, the ProxySync queues up the player data (properties, stats ...) and transfers it after a certain period. With this method, you may enforce it without the wait period.

    • saveAllPlayerData

      void saveAllPlayerData(boolean stats, boolean properties, boolean achievements, Runnable callback)
      Announce to all servers (including this one) that we would like to save all locally-cached player data.

      This is used for player ranks, as they must be saved before we catch the proper rank.

      The callback is always called on the main-thread.

      Parameters:
      stats - Whether to store stats
      properties - Whether to store properties
      achievements - Whether to store achievements
      callback - Gets called when the data has been saved

    • getImplementedAPIVersion

      int getImplementedAPIVersion()
      Returns the MBedwars API version that is implemented by the current RemoteAPI instance.

      Used internally to avoid compatibility issues.

      Returns:
      The implemented API version

    • get

      static RemoteAPI get()
      Returns the global RemoteAPI instance.
      Returns:
      The global RemoteAPI instance