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 Link icon

    • getTownSpawnLocation Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      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 Link icon

      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 Link icon

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

    • getResident Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      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 Link icon

      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 Link icon

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

    • getResidentsWithoutTown Link icon

      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 Link icon

      @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 Link icon

      @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 Link icon

      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 Link icon

      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 Link icon

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

    • getPlayer Link icon

      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 Link icon

      @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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      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 Link icon

      @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 Link icon

      @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 Link icon

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

    • getNations Link icon

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

    • getTownsWithoutNation Link icon

      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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

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

    • getDataSource Link icon

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

    • getOnlineResidents Link icon

      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 Link icon

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

    • requestTeleport Link icon

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

    • abortTeleportRequest Link icon

      public void abortTeleportRequest(Resident resident)

    • abortTeleportRequest Link icon

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

    • registerCustomDataField Link icon

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

    • isNationZone Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      public static TownyAPI getInstance()

    • getTownyObjectStartingWith Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

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

    • getNation Link icon

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

    • testPlotOwnerOrThrow Link icon

      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 Link icon

      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 Link icon

      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.