Package com.palmergames.bukkit.towny
Class TownyAPI
java.lang.Object
com.palmergames.bukkit.towny.TownyAPI
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 Summary
Modifier and TypeMethodDescriptionvoid
abortTeleportRequest
(Resident resident) void
abortTeleportRequest
(Resident resident, CancelledTownyTeleportEvent.CancelledTeleportReason reason) void
See TranslationLoader for an easy-to-use way of creating the Map needed for this method.boolean
areMobsEnabled
(org.bukkit.Location location) Answers whether Towny has mobs enabled at a location.filterByStartOrGetTownyObjectStartingWith
(List<String> filters, String arg, String type) Checks if arg starts with filters, if not returns matches fromgetTownyObjectStartingWith(String, String)
.Gets Towny's saving Databasestatic TownyAPI
@Nullable Nation
Gets the nation from the given name.@Nullable Nation
Gets the nation from the given UUID.@Nullable Nation
getNation
(@NotNull org.bukkit.entity.Player player) Get a List of all the Nations.getNations
(String[] names) Gets a List of Nations using an array of names.getNations
(List<UUID> uuids) Gets a List of Nations using a List of UUIDsgetNations
(UUID[] uuids) @Nullable org.bukkit.Location
getNationSpawnLocation
(org.bukkit.entity.Player player) Gets the nation spawnLocation
of aPlayer
.List
<org.bukkit.entity.Player> getOnlinePlayers
(ResidentList owner) Gets all onlinePlayer
s for a specificResidentList
.List
<org.bukkit.entity.Player> getOnlinePlayersAlliance
(Nation nation) Gets all onlinePlayer
s for a specificNation
s alliance.List
<org.bukkit.entity.Player> getOnlinePlayersInNation
(Nation nation) Gets all onlinePlayer
s for a specificNation
.List
<org.bukkit.entity.Player> getOnlinePlayersInTown
(Town town) Gets all onlinePlayer
s for a specificTown
.getOnlineResidents
(ResidentList owner) Check whichResident
s are online in aResidentList
org.bukkit.entity.Player
Find the the matchingPlayer
of the specifiedResident
.@Nullable UUID
getPlayerUUID
(Resident resident) @Nullable Resident
getResident
(String name) Gets the resident from the given name.@Nullable Resident
getResident
(UUID uuid) Gets the resident from the given UUID.@Nullable Resident
getResident
(org.bukkit.entity.Player player) Gets the resident from the given Player.@Nullable Nation
getResidentNationOrNull
(Resident resident) Gets the resident's nation if they have one.@Nullable Resident
getResidentOrNull
(TownBlock townBlock) @NotNull Resident
getResidentOrThrow
(@Nullable org.bukkit.entity.Player player) Gets the resident from the given Player or throws a TownyException if that isn't possible.Gets a List of all of the Residents on the server.getResidents
(String[] names) Get a List of Resident from an array of names.getResidents
(UUID[] uuids) Get a List of Resident from an array of UUIDs.getResidentsOfTownStartingWith
(String townName, String str) Returns the names a town's residents that start with a string.Gets a List of all the Residents which don't belong to a town.Returns a list of residents which are online and have no town.@Nullable Town
getResidentTownOrNull
(Resident resident) Gets the resident's town if they have one.@Nullable Town
Gets the town from the given name.@Nullable Town
Gets the town from the given UUID.@Nullable Town
getTown
(@NotNull org.bukkit.entity.Player player) @Nullable Town
getTown
(org.bukkit.Location location) Get theTown
at a specificLocation
.@Nullable TownBlock
Get theTownBlock
at a specificWorldCoord
.@Nullable TownBlock
getTownBlock
(@NotNull org.bukkit.entity.Player player) Get theTownBlock
in which aPlayer
is located.@Nullable TownBlock
getTownBlock
(org.bukkit.Location location) Get theTownBlock
at a specificLocation
.Get a Collection of all of the TownBlocks.getTownName
(org.bukkit.entity.Player player) Returns the name of the Player's town, if they have one, or an empty String.@Nullable String
getTownName
(org.bukkit.Location location) Get the name of aTown
at a specificLocation
.@Nullable Nation
getTownNationOrNull
(Town town) Gets the town's nation if they have one.@Nullable Town
getTownOrNull
(TownBlock townBlock) getTownResidentNamesOfPlayerStartingWith
(org.bukkit.entity.Player player, String str) Returns the names a player's town's residents that start with a string.getTowns()
Get a List of all the Towns.Gets a List of Towns using an array of names.Gets a List of Towns using a List of UUIDs@Nullable org.bukkit.Location
getTownSpawnLocation
(org.bukkit.entity.Player player) Gets the town spawnLocation
of aPlayer
.Get a List of all the Towns that aren't a part of a Nation.@Nullable UUID
getTownUUID
(org.bukkit.Location location) getTownyObjectStartingWith
(String arg, String type) Returns a List<String> containing strings of resident, town, and/or nation names that match with arg.@Nullable TownyWorld
getTownyWorld
(String worldName) ReturnsTownyWorld
unless it is null.@Nullable TownyWorld
getTownyWorld
(UUID worldUUID) ReturnsTownyWorld
unless it is null.@Nullable TownyWorld
getTownyWorld
(org.bukkit.World world) ReturnsTownyWorld
unless it is null.hasNationZone
(WorldCoord worldCoord) Method to figure out if a worldcoord in the wilderness is normal wilderness of nation zone.hasNationZone
(org.bukkit.Location location) Method to figure out if a location in the wilderness is normal wilderness of nation zone.boolean
isNationZone
(org.bukkit.Location location) Method to figure out if a location is in a NationZone.boolean
isPVP
(org.bukkit.Location location) Answers whether Towny considers PVP enabled at a location.boolean
isTownyWorld
(org.bukkit.World world) Returns value of usingTowny for the given world.boolean
isWilderness
(WorldCoord worldCoord) Check if the specifiedWorldCoord
is in the wilderness.boolean
isWilderness
(org.bukkit.block.Block block) Check if the specifiedBlock
is in the wilderness.boolean
isWilderness
(org.bukkit.Location location) Check if the specifiedLocation
is in the wilderness.void
registerCustomDataField
(CustomDataField<?> field) void
requestTeleport
(org.bukkit.entity.Player player, org.bukkit.Location spawnLoc) void
requestTeleport
(org.bukkit.entity.Player player, org.bukkit.Location spawnLoc, int cooldown) void
testPlotOwnerOrThrow
(@NotNull Resident resident, @NotNull TownBlock townBlock) 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.void
testTownClaimOrThrow
(Town town, WorldCoord coordToClaim, boolean outpost, boolean newTown) Test a WorldCoord to see if Towny would allow the area to be claimed by the given town.void
testTownUnclaimOrThrow
(Town town, WorldCoord coordToUnclaim) Test a WorldCoord to see if Towny would allow the area to be unclaimed by the given town.
-
Method Details
-
getTownSpawnLocation
@Nullable public @Nullable org.bukkit.Location getTownSpawnLocation(org.bukkit.entity.Player player) Gets the town spawnLocation
of aPlayer
.- 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 spawnLocation
of aPlayer
.- Parameters:
player
-Player
of which you want the nation spawn.- Returns:
Location
of the nation spawn or if it is not obtainable null.
-
getResidentTownOrNull
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
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
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
Gets the nation from the given name.- Parameters:
name
- String name of the nation.- Returns:
- nation or null if it doesn't exist.
-
getNation
Gets the nation from the given UUID.- Parameters:
uuid
- UUID of the nation.- Returns:
- nation or null if it doesn't exist.
-
getNations
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
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
-
getResident
Gets the resident from the given name.- Parameters:
name
- String name of the resident.- Returns:
- resident or null if it doesn't exist.
-
getResident
Gets the resident from the given UUID.- Parameters:
uuid
- UUID name of the resident.- Returns:
- resident or null if it doesn't exist.
-
getResident
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
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
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
Gets a List of all of the Residents on the server.- Returns:
- a List of Residents
-
getResidentsWithoutTown
Gets a List of all the Residents which don't belong to a town.- Returns:
- A List of all townless Residents.
-
getTown
Gets the town from the given name.- Parameters:
name
- String name of the town.- Returns:
- town or null if it doesn't exist.
-
getTown
Gets the town from the given UUID.- Parameters:
uuid
- UUID name of the town.- Returns:
- town or null if it doesn't exist.
-
getTowns
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
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
-
getPlayer
Find the the matchingPlayer
of the specifiedResident
.- Parameters:
resident
-Resident
of which you want the matchingPlayer
.- Returns:
- an online
Player
or if it's not obtainable.
-
getPlayerUUID
-
getOnlinePlayers
Gets all onlinePlayer
s for a specificResidentList
.- Parameters:
owner
-ResidentList
of which you want all the onlinePlayer
s.- Returns:
List
of all onlinePlayer
s in the specifiedResidentList
.
-
getOnlinePlayersInTown
Gets all onlinePlayer
s for a specificTown
. -
getOnlinePlayersInNation
Gets all onlinePlayer
s for a specificNation
. -
getOnlinePlayersAlliance
Gets all onlinePlayer
s for a specificNation
s alliance. -
isWilderness
public boolean isWilderness(org.bukkit.block.Block block) Check if the specifiedBlock
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 specifiedLocation
is in the wilderness.- Parameters:
location
-Location
to test widlerness for.- Returns:
- true if the
Location
is in the wilderness, false otherwise.
-
isWilderness
Check if the specifiedWorldCoord
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
ReturnsTownyWorld
unless it is null.- Parameters:
worldName
- - the name of the world to get.- Returns:
- TownyWorld or
null
.
-
getTownyWorld
ReturnsTownyWorld
unless it is null.- Parameters:
worldUUID
- - the uuid of the world to get.- Returns:
- TownyWorld or
null
.
-
getTownyWorld
ReturnsTownyWorld
unless it is null.- Parameters:
world
- - the world to get.- Returns:
- TownyWorld or
null
.
-
getTown
Get theTown
at a specificLocation
. -
getTownOrNull
-
getResidentOrNull
-
getTownName
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
Get the name of aTown
at a specificLocation
. -
getTownUUID
-
getTowns
Get a List of all the Towns.- Returns:
- a List of all the Towns.
-
getNations
Get a List of all the Nations.- Returns:
- a List of all the Nations.
- Since:
- 0.98.4.1.
-
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
Get theTownBlock
at a specificLocation
. -
getTownBlock
@Nullable public @Nullable TownBlock getTownBlock(@NotNull @NotNull org.bukkit.entity.Player player) Get theTownBlock
in which aPlayer
is located. -
getTownBlock
Get theTownBlock
at a specificWorldCoord
.- Parameters:
wc
-WorldCoord
to get theTownBlock
of (if it claimed by a town.)- Returns:
TownBlock
at thisWorldCoord
, ornull
if this isn't claimed.
-
getTownBlocks
Get a Collection of all of the TownBlocks.- Returns:
- Collection of TownBlocks.
-
getDataSource
Gets Towny's saving Database- Returns:
- the
TownyDataSource
-
getOnlineResidents
Check whichResident
s are online in aResidentList
- Parameters:
owner
-ResidentList
to check for onlineResident
s.- Returns:
List
ofResident
s 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
-
abortTeleportRequest
public void abortTeleportRequest(Resident resident, CancelledTownyTeleportEvent.CancelledTeleportReason reason) -
registerCustomDataField
- 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
Method to figure out if a location in the wilderness is normal wilderness of nation zone. Recommended to useisWilderness(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
Method to figure out if a worldcoord in the wilderness is normal wilderness of nation zone. Recommended to useisWilderness(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
-
getTownyObjectStartingWith
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 typetype
- 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 fromgetTownyObjectStartingWith(String, String)
. Add a "+" to the type to return both cases. Useful for tab completion systems.- Parameters:
filters
- the strings to filter arg witharg
- the string to check with filters and possibly match with Towny objects if no filters are foundtype
- the type of check to use, seegetTownyObjectStartingWith(String, String)
for possible types. Add "+" to check for both filters andgetTownyObjectStartingWith(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 ofstr
- the string to check if the town's residents start with- Returns:
- the resident names that match str
-
getResidentsOfTownStartingWith
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 ofstr
- the string to check if the town's residents start with- Returns:
- the resident names that match str
-
getResidentsWithoutTownStartingWith
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
-
getNation
-
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
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.
-