Package com.palmergames.bukkit.towny

Class TownyAPI

java.lang.Object
com.palmergames.bukkit.towny.TownyAPI
public class TownyAPI extends Object
Towny's class for external API Methods For more dynamic/controlled changing of Towny's behavior, for example Database, War, Permissions The TownyUniverse class should be used. It contains the map of all objects aswell as serving as an internal API, that Towny uses.
Author:
Articdive

  • Method Details

    • getTownSpawnLocation

      @Nullable public @Nullable org.bukkit.Location getTownSpawnLocation(org.bukkit.entity.Player player)
      Gets the town spawn Location of a Player.
      Parameters:
      player - Player of which you want the town spawn.
      Returns:
      Location of the town spawn or if it is not obtainable null.

    • getNationSpawnLocation

      @Nullable public @Nullable org.bukkit.Location getNationSpawnLocation(org.bukkit.entity.Player player)
      Gets the nation spawn Location of a Player.
      Parameters:
      player - Player of which you want the nation spawn.
      Returns:
      Location of the nation spawn or if it is not obtainable null.

    • getResidentTownOrNull

      @Nullable public @Nullable Town getResidentTownOrNull(Resident resident)
      Gets the resident's town if they have one.
      Parameters:
      resident - Resident to get the town from.
      Returns:
      The resident's Town or null if they have none.

    • getResidentNationOrNull

      @Nullable public @Nullable Nation getResidentNationOrNull(Resident resident)
      Gets the resident's nation if they have one.
      Parameters:
      resident - Resident to get the nation from.
      Returns:
      The resident's Nation or null if they have none.

    • getTownNationOrNull

      @Nullable public @Nullable Nation getTownNationOrNull(Town town)
      Gets the town's nation if they have one.
      Parameters:
      town - Town to get the nation from.
      Returns:
      The town's Nation or null if they have none.

    • getNation

      @Nullable public @Nullable Nation getNation(String name)
      Gets the nation from the given name.
      Parameters:
      name - String name of the nation.
      Returns:
      nation or null if it doesn't exist.

    • getNation

      @Nullable public @Nullable Nation getNation(UUID uuid)
      Gets the nation from the given UUID.
      Parameters:
      uuid - UUID of the nation.
      Returns:
      nation or null if it doesn't exist.

    • getNations

      public List<Nation> getNations(String[] names)
      Gets a List of Nations using an array of names.
      Parameters:
      names - Array of Strings representing possible Nation names.
      Returns:
      List of Nations for which a name was matched.

    • getNations

      public List<Nation> getNations(List<UUID> uuids)
      Gets a List of Nations using a List of UUIDs
      Parameters:
      uuids - List of UUIDs representing possible Nations.
      Returns:
      List of Nations for which a UUID was matched.

    • getNations

      public List<Nation> getNations(UUID[] uuids)

    • getResident

      @Nullable public @Nullable Resident getResident(String name)
      Gets the resident from the given name.
      Parameters:
      name - String name of the resident.
      Returns:
      resident or null if it doesn't exist.

    • getResident

      @Nullable public @Nullable Resident getResident(UUID uuid)
      Gets the resident from the given UUID.
      Parameters:
      uuid - UUID name of the resident.
      Returns:
      resident or null if it doesn't exist.

    • getResident

      @Nullable public @Nullable Resident getResident(org.bukkit.entity.Player player)
      Gets the resident from the given Player.
      Parameters:
      player - Player to get the resident from.
      Returns:
      resident or null if it doesn't exist.

    • getResidentOrThrow

      @NotNull @Contract("null -> fail") public @NotNull Resident getResidentOrThrow(@Nullable @Nullable org.bukkit.entity.Player player) throws TownyException
      Gets the resident from the given Player or throws a TownyException if that isn't possible.
      Parameters:
      player - Player to get the resident from.
      Returns:
      resident or null if it doesn't exist.
      Throws:
      TownyException - when the player does not have a Resident.

    • getResidents

      public List<Resident> getResidents(String[] names)
      Get a List of Resident from an array of names.
      Parameters:
      names - Array of Strings representing resident names.
      Returns:
      List of Residents which matched to a name.

    • getResidents

      public List<Resident> getResidents(UUID[] uuids)
      Get a List of Resident from an array of UUIDs.
      Parameters:
      uuids - Array of UUIDs representing resident uuids.
      Returns:
      List of Residents which matched to a UUID.

    • getResidents

      public List<Resident> getResidents()
      Gets a List of all of the Residents on the server.
      Returns:
      a List of Residents

    • getResidentsWithoutTown

      public List<Resident> getResidentsWithoutTown()
      Gets a List of all the Residents which don't belong to a town.
      Returns:
      A List of all townless Residents.

    • getTown

      @Nullable public @Nullable Town getTown(String name)
      Gets the town from the given name.
      Parameters:
      name - String name of the town.
      Returns:
      town or null if it doesn't exist.

    • getTown

      @Nullable public @Nullable Town getTown(UUID uuid)
      Gets the town from the given UUID.
      Parameters:
      uuid - UUID name of the town.
      Returns:
      town or null if it doesn't exist.

    • getTowns

      public List<Town> getTowns(String[] names)
      Gets a List of Towns using an array of names.
      Parameters:
      names - Array of Strings representing possible Town names.
      Returns:
      List of Towns for which a name was matched.

    • getTowns

      public List<Town> getTowns(List<UUID> uuids)
      Gets a List of Towns using a List of UUIDs
      Parameters:
      uuids - List of UUIDs representing possible Towns.
      Returns:
      List of Towns for which a UUID was matched.

    • getTowns

      public List<Town> getTowns(UUID[] uuids)

    • getPlayer

      public org.bukkit.entity.Player getPlayer(Resident resident)
      Find the the matching Player of the specified Resident.
      Parameters:
      resident - Resident of which you want the matching Player.
      Returns:
      an online Player or if it's not obtainable.

    • getPlayerUUID

      @Nullable public @Nullable UUID getPlayerUUID(Resident resident)
      Find the UUID for the matching Player of the specified Resident.
      Parameters:
      resident - Resident of which you want the UUID.
      Returns:
      an online Player's UUID or null if it's not obtainable.

    • getOnlinePlayers

      public List<org.bukkit.entity.Player> getOnlinePlayers(ResidentList owner)
      Gets all online Players for a specific ResidentList.
      Parameters:
      owner - ResidentList of which you want all the online Players.
      Returns:
      List of all online Players in the specified ResidentList.

    • getOnlinePlayersInTown

      public List<org.bukkit.entity.Player> getOnlinePlayersInTown(Town town)
      Gets all online Players for a specific Town.
      Parameters:
      town - Town of which you want all the online Players.
      Returns:
      List of all online Players in the specified Town.

    • getOnlinePlayersInNation

      public List<org.bukkit.entity.Player> getOnlinePlayersInNation(Nation nation)
      Gets all online Players for a specific Nation.
      Parameters:
      nation - Nation of which you want all the online Players.
      Returns:
      List of all online Players in the specified Nation.

    • getOnlinePlayersAlliance

      public List<org.bukkit.entity.Player> getOnlinePlayersAlliance(Nation nation)
      Gets all online Players for a specific Nations alliance.
      Parameters:
      nation - Nation of which you want all the online allied Players.
      Returns:
      List of all online Players in the specified Nations allies.

    • isWilderness

      public boolean isWilderness(org.bukkit.block.Block block)
      Check if the specified Block is in the wilderness.
      Parameters:
      block - Block to test for.
      Returns:
      true if the Block is in the wilderness, false otherwise.

    • isWilderness

      public boolean isWilderness(org.bukkit.Location location)
      Check if the specified Location is in the wilderness.
      Parameters:
      location - Location to test widlerness for.
      Returns:
      true if the Location is in the wilderness, false otherwise.

    • isWilderness

      public boolean isWilderness(WorldCoord worldCoord)
      Check if the specified WorldCoord is in the wilderness.
      Parameters:
      worldCoord - WorldCoord to test widlerness for.
      Returns:
      true if the WorldCoord is in the wilderness, false otherwise.

    • isPVP

      public boolean isPVP(org.bukkit.Location location)
      Answers whether Towny considers PVP enabled at a location.
      Parameters:
      location - Location to check for PVP.
      Returns:
      true if PVP is enabled or this isn't a world with Towny enabled.

    • areMobsEnabled

      public boolean areMobsEnabled(org.bukkit.Location location)
      Answers whether Towny has mobs enabled at a location.
      Parameters:
      location - Location to check for mobs status.
      Returns:
      true if Towny would let mobs spawn/exist at the given Location, or if Towny is disabled in the Location's world.
      Since:
      0.98.2.4.

    • isTownyWorld

      public boolean isTownyWorld(org.bukkit.World world)
      Returns value of usingTowny for the given world.
      Parameters:
      world - - the world to check
      Returns:
      true or false

    • getTownyWorld

      @Nullable public @Nullable TownyWorld getTownyWorld(String worldName)
      Returns TownyWorld unless it is null.
      Parameters:
      worldName - - the name of the world to get.
      Returns:
      TownyWorld or null.

    • getTownyWorld

      @Nullable public @Nullable TownyWorld getTownyWorld(UUID worldUUID)
      Returns TownyWorld unless it is null.
      Parameters:
      worldUUID - - the uuid of the world to get.
      Returns:
      TownyWorld or null.

    • getTownyWorld

      @Nullable public @Nullable TownyWorld getTownyWorld(org.bukkit.World world)
      Returns TownyWorld unless it is null.
      Parameters:
      world - - the world to get.
      Returns:
      TownyWorld or null.

    • getTown

      @Nullable public @Nullable Town getTown(org.bukkit.Location location)
      Get the Town at a specific Location.
      Parameters:
      location - Location to get Town for.
      Returns:
      Town at this location, or null for none.

    • getTownOrNull

      @Nullable public @Nullable Town getTownOrNull(TownBlock townBlock)
      Get the Town of a TownBlock or null. Should be used after testing TownBlock.hasTown().
      Parameters:
      townBlock - TownBlock from which to get a Town.
      Returns:
      Town or null.

    • getResidentOrNull

      @Nullable public @Nullable Resident getResidentOrNull(TownBlock townBlock)
      Get the Resident who owns the TownBlock or null. Resident will be returned if the TownBlock is owned by a player. Should be used after testing TownBlock.hasResident().
      Parameters:
      townBlock - TownBlock from which to get a Resident.
      Returns:
      Resident or null.

    • getTownName

      public String getTownName(org.bukkit.entity.Player player)
      Returns the name of the Player's town, if they have one, or an empty String.
      Parameters:
      player - Player
      Returns:
      Town name or "" if the player has no Town.
      Since:
      0.99.5.14.

    • getTownName

      @Nullable public @Nullable String getTownName(org.bukkit.Location location)
      Get the name of a Town at a specific Location.
      Parameters:
      location - Location to get Town name for.
      Returns:
      String containg the name of the Town at this location, or null for none.

    • getTownUUID

      @Nullable public @Nullable UUID getTownUUID(org.bukkit.Location location)
      Get the UUID of a Town at the specified Location.
      Parameters:
      location - Location to get Town UUID for.
      Returns:
      UUID of any Town at this Location, or null for none.

    • getTowns

      public List<Town> getTowns()
      Get a List of all the Towns.
      Returns:
      a List of all the Towns.

    • getNations

      public List<Nation> getNations()
      Get a List of all the Nations.
      Returns:
      a List of all the Nations.
      Since:
      0.98.4.1.

    • getTownsWithoutNation

      public List<Town> getTownsWithoutNation()
      Get a List of all the Towns that aren't a part of a Nation.
      Returns:
      a List of all the nationless Towns.

    • getTownBlock

      @Nullable public @Nullable TownBlock getTownBlock(org.bukkit.Location location)
      Get the TownBlock at a specific Location.
      Parameters:
      location - Location to get TownBlock of.
      Returns:
      TownBlock at this Location, or null for none.

    • getTownBlock

      @Nullable public @Nullable TownBlock getTownBlock(@NotNull @NotNull org.bukkit.entity.Player player)
      Get the TownBlock in which a Player is located.
      Parameters:
      player - Player to get TownBlock of.
      Returns:
      TownBlock at the location of this Player, or null when the player is in the wilderness.

    • getTownBlock

      @Nullable public @Nullable TownBlock getTownBlock(WorldCoord wc)
      Get the TownBlock at a specific WorldCoord.
      Parameters:
      wc - WorldCoord to get the TownBlock of (if it claimed by a town.)
      Returns:
      TownBlock at this WorldCoord, or null if this isn't claimed.

    • getTownBlocks

      public Collection<TownBlock> getTownBlocks()
      Get a Collection of all of the TownBlocks.
      Returns:
      Collection of TownBlocks.

    • getDataSource

      public TownyDataSource getDataSource()
      Gets Towny's saving Database
      Returns:
      the TownyDataSource

    • getOnlineResidents

      public List<Resident> getOnlineResidents(ResidentList owner)
      Check which Residents are online in a ResidentList
      Parameters:
      owner - ResidentList to check for online Residents.
      Returns:
      List of Residents that are online.

    • requestTeleport

      public void requestTeleport(org.bukkit.entity.Player player, org.bukkit.Location spawnLoc)

    • requestTeleport

      public void requestTeleport(org.bukkit.entity.Player player, org.bukkit.Location spawnLoc, int cooldown)

    • abortTeleportRequest

      public void abortTeleportRequest(Resident resident)

    • abortTeleportRequest

      public void abortTeleportRequest(Resident resident, CancelledTownyTeleportEvent.CancelledTeleportReason reason)

    • registerCustomDataField

      public void registerCustomDataField(CustomDataField<?> field) throws KeyAlreadyRegisteredException
      Throws:
      KeyAlreadyRegisteredException

    • isNationZone

      public boolean isNationZone(org.bukkit.Location location)
      Method to figure out if a location is in a NationZone.
      Parameters:
      location - - Location to test.
      Returns:
      true if the location is in a NationZone.

    • hasNationZone

      public PlayerCache.TownBlockStatus hasNationZone(org.bukkit.Location location)
      Method to figure out if a location in the wilderness is normal wilderness of nation zone. Recommended to use isWilderness(Location) prior to using this, to confirm the location is not in a town.
      Parameters:
      location - - Location to test whether it is a nation zone or normal wilderness.
      Returns:
      returns either UNCLAIMED_ZONE or NATION_ZONE

    • hasNationZone

      public PlayerCache.TownBlockStatus hasNationZone(WorldCoord worldCoord)
      Method to figure out if a worldcoord in the wilderness is normal wilderness of nation zone. Recommended to use isWilderness(WorldCoord) prior to using this, to confirm the location is not in a town.
      Parameters:
      worldCoord - - WorldCoord to test whether it is a nation zone or normal wilderness.
      Returns:
      returns either UNCLAIMED_ZONE or NATION_ZONE

    • addTranslations

      public void addTranslations(org.bukkit.plugin.Plugin plugin, Map<String,Map<String,String>> translations)
      See TranslationLoader for an easy-to-use way of creating the Map needed for this method.
      Parameters:
      plugin - Plugin your plugin.
      translations - Map<String, Map<String, String>> A hashmap keyed by the locale name, with a value of secondary hashmap of the locale's language string keys and their corresponding values.

    • getInstance

      public static TownyAPI getInstance()

    • getTownyObjectStartingWith

      public static List<String> getTownyObjectStartingWith(String arg, String type)
      Returns a List<String> containing strings of resident, town, and/or nation names that match with arg. Can check for multiple types, for example "rt" would check for residents and towns but not nations or worlds. Useful for tab completion systems calling for Towny Objects.
      Parameters:
      arg - the string to match with the chosen type
      type - the type of Towny object to check for, can be r(esident), t(own), n(ation), w(orld), or any combination of those to check.
      Returns:
      Matches for the arg with the chosen type

    • filterByStartOrGetTownyObjectStartingWith

      public static List<String> filterByStartOrGetTownyObjectStartingWith(List<String> filters, String arg, String type)
      Checks if arg starts with filters, if not returns matches from getTownyObjectStartingWith(String, String). Add a "+" to the type to return both cases. Useful for tab completion systems.
      Parameters:
      filters - the strings to filter arg with
      arg - the string to check with filters and possibly match with Towny objects if no filters are found
      type - the type of check to use, see getTownyObjectStartingWith(String, String) for possible types. Add "+" to check for both filters and getTownyObjectStartingWith(String, String)
      Returns:
      Matches for the arg filtered by filters or checked with type

    • getTownResidentNamesOfPlayerStartingWith

      public static List<String> getTownResidentNamesOfPlayerStartingWith(org.bukkit.entity.Player player, String str)
      Returns the names a player's town's residents that start with a string. Useful for tab completion systems.
      Parameters:
      player - the player to get the town's residents of
      str - the string to check if the town's residents start with
      Returns:
      the resident names that match str

    • getResidentsOfTownStartingWith

      public static List<String> getResidentsOfTownStartingWith(String townName, String str)
      Returns the names a town's residents that start with a string. Useful for tab completion systems.
      Parameters:
      townName - the town to get the residents of
      str - the string to check if the town's residents start with
      Returns:
      the resident names that match str

    • getResidentsWithoutTownStartingWith

      public static List<String> getResidentsWithoutTownStartingWith(String str)
      Returns a list of residents which are online and have no town. Useful for tab completion systems.
      Parameters:
      str - the string to check if the resident's name starts with.
      Returns:
      the residents name or an empty list.

    • getTown

      @Nullable public @Nullable Town getTown(@NotNull @NotNull org.bukkit.entity.Player player)

    • getNation

      @Nullable public @Nullable Nation getNation(@NotNull @NotNull org.bukkit.entity.Player player)

    • testPlotOwnerOrThrow

      public void testPlotOwnerOrThrow(@NotNull @NotNull Resident resident, @NotNull @NotNull TownBlock townBlock) throws TownyException
      Test the townBlock to ensure it is owned by the given Resident, or the Resident is considered a Mayor or Town Assistant or a TownyAdmin.
      Parameters:
      resident - Resident Object to test as "owner" of the TownBlock.
      townBlock - TownBlock Object in which to test ownership.
      Throws:
      TownyException - Exception thrown to trigger failures in the methods using this method.

    • testTownClaimOrThrow

      public void testTownClaimOrThrow(Town town, WorldCoord coordToClaim, boolean outpost, boolean newTown) throws TownyException
      Test a WorldCoord to see if Towny would allow the area to be claimed by the given town.
      Parameters:
      town - Town who would become owner of the land.
      coordToClaim - WorldCoord which is to be claimed.
      outpost - whether this would be an outpost, with no connected town land.
      newTown - whether this would be a brand new town claiming their first plot.
      Throws:
      TownyException - thrown when Towny would not allow the claim, with message for the reason why.

    • testTownUnclaimOrThrow

      public void testTownUnclaimOrThrow(Town town, WorldCoord coordToUnclaim) throws TownyException
      Test a WorldCoord to see if Towny would allow the area to be unclaimed by the given town.
      Parameters:
      town - Town that would unclaim the land.
      coordToUnclaim - WorldCoord which is to be unclaimed.
      Throws:
      TownyException - thrown when Towny would not allow the unclaim, with message for the reason why.