Interface GameAPI


public interface GameAPI
Contains API for managing game-related stuff, such as arenas, lobbies, spawners...
  • Method Details

    • createArena

      ArenaBuilder createArena()
      Returns a builder to create and add an arena.

      Invoke ArenaBuilder.finish() to add the arena.

      Returns:
      The ArenaBuilder you can use to pass needed information to the arena
    • getArenas

      Collection<Arena> getArenas()
      Returns all existing arenas.
      Returns:
      Returns all added arenas
    • getArenaByName

      @Nullable @Nullable Arena 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 Arena 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
    • getArenaByPlayer

      @Nullable @Nullable Arena getArenaByPlayer(Player 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 Arena getArenaBySpectator(Player 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
    • getArenaByLocation

      @Nullable @Nullable Collection<Arena> getArenaByLocation(Location location)
      Looks for all arenas where the location is inside the arena.

      There's most of the time and when the user has created the arenas correctly, only one entry in the collection.
      Ignores lobby locations etc. and ignores non-normal types (RegenerationType.isNormal())

      Parameters:
      location - The location inside the arena
      Returns:
      Returns the arena in which the location is inside. Returns null if there isn't any
    • isArenaNameValid

      boolean isArenaNameValid(String name)
      Returns weather or not the given String can be used as the name for an arena

      Does not check whether or not the arena already exists. It's only checking if the characters are valid.

      Parameters:
      name - The name we want to check
      Returns:
      If the given name is valid
    • getLobbyItems

      Collection<? extends LobbyItem> getLobbyItems()
      Returns all existing LobbyItems.
      Returns:
      All existing LobbyItems
      See Also:
    • getLobbyItems

      @Nullable @Nullable Collection<? extends LobbyItem> getLobbyItems(int slot)
      Returns all LobbyItems that were added to a specific slot. Might be null if there's no item at the given slot.

      While it does not make any sense at the first glance keep in mind that LobbyItems are only visible at specific conditions. If you want to know which one is currently visible you might want to use getVisibleLobbyItem(int, Player, Arena).

      Parameters:
      slot - The slot at which it's located at (0-8)
      Returns:
      All items that were added to that slot, null if there's none
      Throws:
      IndexOutOfBoundsException - When slot is less than 0 or greater than 8
      See Also:
    • getVisibleLobbyItem

      @Nullable @Nullable LobbyItem getVisibleLobbyItem(int slot, Player player, Arena arena)
      Returns the currently visible item at a specific slot. Might be null if there's none.
      Parameters:
      slot - The slot at which it's located at (0-8)
      player - The player who'd see the item
      arena - The arena in which the player is located in
      Returns:
      The item that's visible for the player, null if there's none
      See Also:
    • getLobbyItemHandlers

      Collection<LobbyItemHandler> getLobbyItemHandlers()
      Returns all registered handlers. Also includes the default ones.

      They are being used for LobbyItems (items that are being placed in the hotbar).

      Returns:
      All registered item handlers
    • getLobbyItemHandler

      @Nullable @Nullable LobbyItemHandler getLobbyItemHandler(String id)
      Returns a registered item handler whos id is equal to the passed one. When there's none the method return null.
      Parameters:
      id - The id that shall match
      Returns:
      The handler whos id is equal. null when there's none
    • registerLobbyItemHandler

      boolean registerLobbyItemHandler(LobbyItemHandler handler)
      Registers a handler for LobbyItems.

      The items are will automatically use it if their set handler id is equal to the given one, so it's not needed to use LobbyItem.setHandler(LobbyItemHandler).

      Might fail (returns false) if the id is already taken

      Parameters:
      handler - The handler that shall be registered
      Returns:
      true if it was successful
      Throws:
      IllegalStateException - when there's something wrong with the properties of the handler
    • unregisterLobbyItemHandler

      boolean unregisterLobbyItemHandler(LobbyItemHandler handler)
      Unregisters a previously registered handler for LobbyItems.

      Might fail when it's not registered.

      Parameters:
      handler - The handler that shall be unregistered
      Returns:
      true when it was successful
    • forceLobbyHotbarRefresh

      boolean forceLobbyHotbarRefresh(Player player)
      Forcefully refresh the hotbar of a player during lobby phase.

      This may be useful if e.g. the icon changes. Note that there is no need to call this to update visibilities, as these get checked frequently. Refreshes only occur periodically and not immediately. May fail if the player isn't in a lobby.

      Parameters:
      player - The player for whom we want to do the refresh
      Returns:
      true if the player has been enqueued for a refresh
    • getDropTypes

      Collection<DropType> getDropTypes()
      Returns all currently existing drop type.
      Returns:
      All currently existing drop types
    • getDropTypeByDrop

      @Nullable @Nullable DropType getDropTypeByDrop(ItemStack is)
      Tries to find a DropType who could've dropped the item is
      Parameters:
      is - The item that could've been dropped by a spawner
      Returns:
      The DropType that fits to the is. null when there's none
    • getDropTypeById

      @Nullable @Nullable DropType getDropTypeById(String id)
      Tries to find a DropType given by its id.
      Parameters:
      id - The id of the drop type
      Returns:
      The DropType that fits to the id. null when there's none
    • registerCustomSpawnerHandler

      boolean registerCustomSpawnerHandler(CustomSpawnerHandler handler)
      Registers the custom spawner handler. Spawners will automatically adapt to it.
      Parameters:
      handler - The spawner handler
      Returns:
      false if it failed because there's already a handler with the same id. Otherwise true
      Throws:
      IllegalStateException - When there's something wrong with the properties of the handler
    • unregisterCustomSpawnerHandler

      boolean unregisterCustomSpawnerHandler(CustomSpawnerHandler handler)
      Unregisters the custom spawner handler. Spawners will automatically detach from it.
      Parameters:
      handler - The spawner handler
      Returns:
      true if its existence has been proved
    • getCustomSpawnerHandlers

      Collection<CustomSpawnerHandler> getCustomSpawnerHandlers()
      Returns all registered custom spawner handlers.
      Returns:
      All currently registered custom spawner handlers
    • getSpectatingPlayers

      Collection<Player> getSpectatingPlayers()
      Returns all players who are currently spectating.
      Returns:
      Every spectating player
    • getSpectators

      Collection<Spectator> getSpectators()
      Returns the spectator data of every player who is currently spectating.
      Returns:
      Spectator instances of any player who's currently spectating
    • getSpectatorByPlayer

      @Nullable @Nullable Spectator getSpectatorByPlayer(Player player)
      Tries to find the corresponding Spectator instance given by its player. May return null when the player isn't actually spectating anything.
      Parameters:
      player - The player who might be spectating
      Returns:
      His Spectator instance
    • getSpectatorItem

      @Nullable @Nullable SpectatorItem getSpectatorItem(int slot)
      Returns a hotbar slot given by its slot. Might be null if there's no item at the given slot.
      Parameters:
      slot - The slot at which it's located at (0-8)
      Returns:
      The item located at the slot, null if there's none
      Throws:
      IndexOutOfBoundsException - When slot is less than 0 or greater than 8
    • getSpectatorItemHandlers

      Collection<SpectatorItemHandler> getSpectatorItemHandlers()
      Returns all registered handlers. Also includes the default ones.

      They are being used for SpectatorItems (items that are being placed in the hotbar).

      Returns:
      All registered item handlers
    • getSpectatorItemHandler

      @Nullable @Nullable SpectatorItemHandler getSpectatorItemHandler(String id)
      Returns a registered item handler whos id is equal to the passed one. When there's none the method return null.
      Parameters:
      id - The id that shall match
      Returns:
      The handler whos id is equal. null when there's none
    • registerSpectatorItemHandler

      boolean registerSpectatorItemHandler(SpectatorItemHandler handler)
      Registers a handler for SpectatorItems.

      The items are will automatically use it if their set handler id is equal to the given one, so it's not needed to use SpectatorItem.setHandler(SpectatorItemHandler).

      Might fail (returns false) if the id is already taken

      Parameters:
      handler - The handler that shall be registered
      Returns:
      true if it was successful
      Throws:
      IllegalStateException - when there's something wrong with the properties of the handler
    • unregisterSpectatorItemHandler

      boolean unregisterSpectatorItemHandler(SpectatorItemHandler handler)
      Unregisters a previously registered handler for SpectatorItems.

      Might fail when it's not registered.

      Parameters:
      handler - The handler that shall be unregistered
      Returns:
      true when it was successful
    • getShopPages

      Collection<ShopPage> getShopPages()
      Returns all existing pages inside the shop
      Returns:
      All ShopPages
    • getBuyGroups

      Collection<BuyGroup> getBuyGroups()
      Returns all existing buy groups
      Returns:
      All BuyGroups
    • getBuyGroup

      @Nullable @Nullable BuyGroup getBuyGroup(String name)
      Tries to locate and return a BuyGroup by its name
      Parameters:
      name - The name of the BuyGroup
      Returns:
      The BuyGroup whose name is equal. null if there's none
    • getShopLayouts

      Collection<ShopLayout> getShopLayouts()
      Returns all existing layouts for the shop
      Returns:
      All existing ShopLayouts
    • getShopLayout

      @Nullable @Nullable ShopLayout getShopLayout(String layoutName)
      Tries to look up for a registered layout that has the given name.
      Parameters:
      layoutName - The name of the layout
      Returns:
      null if none has been found or the layout that has been found
    • registerShopLayout

      boolean registerShopLayout(ShopLayout layout)
      Create and register your own custom ShopLayout using this method. Have a class that inherits from ShopLayout and pass it to this method. Users are able to use it by setting the name of your custom layout in their shop config.
      Parameters:
      layout - The new shop config
      Returns:
      Returns false if there's already a layout under the given name. Otherwise true
    • unregisterShopLayout

      boolean unregisterShopLayout(ShopLayout layout)
      Unregister an already existing ShopLayout using this method. It's not possible to unregister default types.
      Parameters:
      layout - The layout that shall be removed
      Returns:
      Returns ture if it got successfully removed
    • getDefaultShopLayout

      ShopLayout getDefaultShopLayout()
      Returns the default ShopLayout that's being used whenever the player clicks on the dealer
      Returns:
      The default ShopLayout
    • getUpgradeShopLayouts

      Collection<UpgradeShopLayout> getUpgradeShopLayouts()
      Returns all existing layouts for the upgrade shop
      Returns:
      All existing UpgradeShopLayouts
    • getUpgradeShopLayout

      @Nullable @Nullable UpgradeShopLayout getUpgradeShopLayout(String layoutName)
      Tries to look up for a registered layout that has the given name.
      Parameters:
      layoutName - The name of the layout
      Returns:
      null if none has been found or the layout that has been found
    • registerUpgradeShopLayout

      boolean registerUpgradeShopLayout(UpgradeShopLayout layout)
      Create and register your own custom UpgradeShopLayout using this method. Have a class that inherits from UpgradeShopLayout and pass it to this method. Users are able to use it by setting the name of your custom layout in their upgrade shop config.
      Parameters:
      layout - The new upgrade shop config
      Returns:
      Returns false if there's already a layout under the given name. Otherwise true
    • unregisterUpgradeShopLayout

      boolean unregisterUpgradeShopLayout(UpgradeShopLayout layout)
      Unregister an already existing UpgradeShopLayout using this method. It's not possible to unregister default types.
      Parameters:
      layout - The layout that shall be removed
      Returns:
      Returns ture if it got successfully removed
    • getDefaultUpgradeShopLayout

      UpgradeShopLayout getDefaultUpgradeShopLayout()
      Returns the default UpgradeShopLayout that's being used whenever the player clicks on the upgrade dealer
      Returns:
      The default ShopLayout
    • openAchievementsGUI

      void openAchievementsGUI(Player player)
      Opens the AchievementsGUI for a player

      The player doesn't have to be in an arena

      Parameters:
      player - The player for whom the AchievementsGUI shall open
    • openShop

      void openShop(Player player, ShopLayout layout, ShopOpenCause cause, @Nullable @Nullable ShopPage shopPage)
      Opens the shop for a player.

      The player doesn't have to be in an arena for debug purposes. It's not recommended to misuse this as it's likely that errors will occur.

      Parameters:
      player - The player for whom the shop shall open
      layout - The layout that shall be shown to the player
      cause - The cause for this event. Recommended to use ShopOpenCause.PLUGIN
      shopPage - The page the shop will open on (If null, the default first page will be used)
    • openShop

      default void openShop(Player player, ShopLayout layout, ShopOpenCause cause)
      Opens the shop for a player.

      The player doesn't have to be in an arena for debug purposes. It's not recommended to misuse this as it's likely that errors will occur.

      Parameters:
      player - The player for whom the shop shall open
      layout - The layout that shall be shown to the player
      cause - The cause for this event. Recommended to use ShopOpenCause.PLUGIN
    • openShop

      default void openShop(Player player, ShopLayout layout)
      Opens the shop for a player.

      The player doesn't have to be in an arena for debug purposes. It's not recommended to misuse this as it's likely that errors will occur.

      Parameters:
      player - The player for whom the shop shall open
      layout - The layout that shall be shown to the player
    • openShop

      default void openShop(Player player, ShopOpenCause cause)
      Opens the shop for a player.

      The player doesn't have to be in an arena for debug purposes. It's not recommended to misuse this as it's likely that errors will occur.

      Parameters:
      player - The player for whom the shop shall open
      cause - The cause for this event. Recommended to use ShopOpenCause.PLUGIN
    • openShop

      default void openShop(Player player)
      Opens the shop for a player.

      The player doesn't have to be in an arena for debug purposes. It's not recommended to misuse this as it's likely that errors will occur.

      Parameters:
      player - The player for whom the shop shall open
    • openUpgradeShop

      boolean openUpgradeShop(Player player)
      Opens the upgrade shop for a player.

      The upgrade shop will fail to open if the player is not inside an arena, or the arena is not running, or if the player does not have a team

      Parameters:
      player - The player for whom the upgrade shop shall open
      Returns:
      whether or not the upgrade shop could be opened successfully
    • openUpgradeShop

      boolean openUpgradeShop(Player player, Arena arena, Team team, UpgradeShopOpenCause cause)
      Opens the upgrade shop for a player.

      The upgrade shop will fail to open if the arena is not running

      Parameters:
      player - The player for whom the upgrade shop shall open
      arena - What arena the upgrade shop is being open for
      team - The team the player is trying to buy an upgrade for
      cause - Why the upgrade shop is being opened
      Returns:
      whether or not the upgrade shop could be opened successfully
    • getSpecialItems

      Collection<SpecialItem> getSpecialItems()
      Returns all registered (including the default ones) SpecialItems.

      It's not safe to modify the resulting Collection. You may want to use registerSpecialItem(String, Plugin, String, ItemStack) or unregisterSpecialItem(SpecialItem) instead

      Returns:
      All existing SpecialItems
    • getSpecialItem

      @Nullable @Nullable SpecialItem getSpecialItem(String id)
      Tries to locate and return a SpecialItem given by its id.
      Parameters:
      id - The id that shall match to the one of the item
      Returns:
      The item whose id is equal. null when there's none
    • getSpecialItem

      @Nullable @Nullable SpecialItem getSpecialItem(ItemStack itemStack)
      Tries to locate and return a SpecialItem given by its usable item.
      Parameters:
      itemStack - The item that we want to check
      Returns:
      The SpecialItem that'll be executed on use
    • registerSpecialItem

      @Nullable @Nullable SpecialItem registerSpecialItem(String id, Plugin plugin, String name, ItemStack item)
      Registers a custom SpecialItem for the later ingame use.

      Might fail when the id is already taken.

      Parameters:
      id - The id that the item shall receive
      plugin - The plugin that's creating the SpecialItem
      name - The name of the SpecialItem (that also will be displayed ingame, supports message codes)
      item - The ItemStack which players will use to execute the item
      Returns:
      The newly initiated SpecialItem instance. null when it failed because the id is already taken
      Throws:
      IllegalStateException - when there's something wrong with the properties of the handler
    • registerSpecialItem

      boolean registerSpecialItem(SpecialItem specialItem)
      Reregisters a SpecialItem that previously has been unregistered.

      Might fail when it's already registered or the id is already taken.

      Parameters:
      specialItem - The item that shall be reregistered
      Returns:
      true if it was successful
      Throws:
      IllegalStateException - when there's something wrong with the properties of the handler
    • unregisterSpecialItem

      boolean unregisterSpecialItem(SpecialItem specialItem)
      Tries to unregister an existing SpecialItem. This causes the item not to be useable and configurable anymore.
      Parameters:
      specialItem - The item that shall get removed
      Returns:
      false when the SpecialItem already has been unregistered
    • useSpecialItem

      void useSpecialItem(SpecialItem item, Player player, Arena arena, ItemStack is)
      Simulates the player using the special item.

      May fail if it has been cancelled using Cancellable.setCancelled(boolean).

      Parameters:
      item - The item that's being used
      player - The player that uses the item
      arena - The arena in which the player is using the item
      is - The item that's being used (the one that he is holding in his hand)
      Throws:
      IllegalStateException - If the item isn't registered
    • getUpgradeTriggerHandlers

      Collection<UpgradeTriggerHandler> getUpgradeTriggerHandlers()
      Returns all registered (including the default ones) UpgradeTriggerHandlers.

      It's not safe to modify the resulting Collection. You may want to use registerUpgradeTriggerHandler(UpgradeTriggerHandler)

      Returns:
      All existing UpgradeTriggerHandlers
    • getUpgradeTriggerHandler

      @Nullable @Nullable UpgradeTriggerHandler getUpgradeTriggerHandler(String id)
      Tries to locate and return a UpgradeTriggerHandler given by its id.
      Parameters:
      id - The id that shall match to the one of the handler
      Returns:
      The handler whose id is equal. null when there's none
    • getUpgrades

      Collection<Upgrade> getUpgrades()
      Returns all the upgrades that are currently loaded.
      Returns:
      all loaded upgrades
    • registerUpgradeTriggerHandler

      boolean registerUpgradeTriggerHandler(UpgradeTriggerHandler handler)
      Registers a custom UpgradeTriggerHandler for use in the upgradeshop.

      Might fail when the handlers id is already taken.

      Parameters:
      handler - the handler that is being registered
      Returns:
      The newly initiated SpecialItem instance. null when it failed because the id is already taken
    • unregisterUpgradeTriggerHandler

      boolean unregisterUpgradeTriggerHandler(UpgradeTriggerHandler handler)
      Tries to unregister an existing Upgrade. This causes the item not to be useable and configurable anymore.
      Parameters:
      handler - item that shall get removed
      Returns:
      false when the Upgrade already has been unregistered
    • isPlayerBlockMarkingSupported

      boolean isPlayerBlockMarkingSupported()
      Plugin might mark blocks as player placed depending on their configuration. This allows to e.g. make players only to be able to break blocks they've placed during the match.

      This method Arena.setBlockPlayerPlaced(org.bukkit.block.Block, boolean) and Arena.isBlockPlayerPlaced(org.bukkit.block.Block) to check whether or not this is even possible.

      Returns:
      true if the plugin supports player marking. false if it has been disabled by the user
    • getDefaultScoreboardHandler

      ScoreboardHandler getDefaultScoreboardHandler()
      Returns the default handler for scoreboards that's being provided by the plugin.
      It's not a must that this handler is actually being used. It's possible that an other plugin might overwrite it using setScoreboardHandler(ScoreboardHandler). Use getScoreboardHandler() to obtain the currently used handler.
      Returns:
      The default handler for scoreboards
    • getScoreboardHandler

      ScoreboardHandler getScoreboardHandler()
      Returns the current handler for scoreboards.

      It's possible for plugins to set a new handler using setScoreboardHandler(ScoreboardHandler).

      Returns:
      The currently used handler for scoreboards
    • setScoreboardHandler

      void setScoreboardHandler(ScoreboardHandler handler)
      Set the new handler for scoreboards.

      The plugin will automatically replace it with the default one when the plugin unloads. Additionally it'll automatically add the existing players from the previous one to the new one.

      Use getDefaultScoreboardHandler() to change it back to default.

      Parameters:
      handler - The new handler for scoreboards
    • rejoinPlayer

      void rejoinPlayer(Player player, @Nullable @Nullable Consumer<Optional<RejoinPlayerIssue>> callback)
      Tries to make the player rejoin the arena he previously was playing in.

      The task is being processed async, hence the callback.

      Parameters:
      player - The player who shall rejoin a match
      callback - The result of all of this
    • sendToHub

      default void sendToHub(Player player)
      Sends the player to the hub.

      Where exactly the player is being teleported to depends on the configuration of the server. It could include one of these options:
      - To the hub-position that has been specified using /bw sethubpos
      - Being kicked out of the server
      - Being sent to the hub server

      Parameters:
      player - The player that shall be moved
      See Also:
    • sendToHub

      void sendToHub(Player player, boolean permitKicking)
      Sends the player to the hub.

      Where exactly the player is being teleported to depends on the configuration of the server. It could include one of these options:
      - To the hub-position that has been specified using /bw sethubpos
      - Being kicked out of the server (only when permitKicking is set to true)
      - Being sent to the hub server (only when permitKicking is set to true)

      Parameters:
      player - The player that shall be moved
      permitKicking - Whether the player may only get teleported on the same server. When set to false, the player may never leave the server
      See Also:
    • getCompanionOwner

      @Nullable @Nullable UUID getCompanionOwner(Entity entity)
      Get the UUID of the player who owns the given companion.

      A companion may e.g. be an iron golem, a guard dog, a fireball etc.

      Parameters:
      entity - The companion
      Returns:
      The UUID of the player Entity.getUniqueId() who spawned the companion. May be null for none
      Throws:
      IllegalArgumentException - If entity is an invalid entity type (e.g. if it's a player)
      See Also:
    • setCompanionOwner

      void setCompanionOwner(Entity entity, @Nullable @Nullable UUID owner)
      Set the owner of a companion.

      A companion may e.g. be an iron golem, a guard dog, a fireball etc.

      Parameters:
      entity - The companion
      owner - The UUID of the player Entity.getUniqueId() who spawned the companion. May be null for none
      Throws:
      IllegalArgumentException - If entity is an invalid entity type (e.g. if it's a player)
      See Also:
    • setCompanionOwner

      default void setCompanionOwner(Entity entity, @Nullable @Nullable OfflinePlayer owner)
      Set the owner of a companion.

      A companion may e.g. be an iron golem, a guard dog, a fireball etc.

      Parameters:
      entity - The companion
      owner - The player who spawned the companion. May be null for none
      Throws:
      IllegalArgumentException - If entity is an invalid entity type (e.g. if it's a player)
      See Also:
    • getCloningManager

      ArenaCloningManager getCloningManager()
      Returns the ArenaCloningManager whose purpose it is to automatically clone new arenas.
      Returns:
      The global ArenaCloningManager instance
    • drawBorder

      void drawBorder(XYZ min, XYZ max, Player player)
      Draw a cube border once.

      This method uses the exact same logic as for the region arena border. It may be expensive to process, thus it's recommended to call it async.

      Parameters:
      min - Coordinates that are less than the max parameter
      max - Coordinates that are greater than the min parameter
      player - For whom the border shall be drawn for
    • getLastPlayerCausedDamage

      @Nullable @Nullable PlayerDamageInfo getLastPlayerCausedDamage(Player damaged)
      Get the info of the last directly/indirectly player-caused damage during a match.

      This info is used to obtain the killer when the damaged player dies.

      Parameters:
      damaged - The player who got damaged
      Returns:
      The related info object. May be null if nobody damaged him yet
    • get

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