Interface GameAPI

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(int)
  • getVisibleLobbyItem(int, Player, Arena)

• 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(int, Player, Arena)

• 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:

  • getLobbyItems(int)

• 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:

  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(Player, boolean)

• 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:

  • sendToHub(Player)

• 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(Entity, UUID)
  • setCompanionOwner(Entity, OfflinePlayer)

• 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:

  • getCompanionOwner(Entity)
  • setCompanionOwner(Entity, OfflinePlayer)

• 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:

  • getCompanionOwner(Entity)

• 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