Bukkit

AreaTools API

This library was created by me, Impelon, in order for other developers to use it in Bukkit-programming. It incluedes multiple classes for an easy management of multiple connected Locations within the same World (aka. Area).

The functionality is as follows:

• You create a new variable to retain the Area and you define two corner-locations inside the constructor of either the SimpleArea or the Area (difference will be explained further down); Also you tell it whenever it should use floored Locations (aka. block-locations)
• An Area of Locations between those two corner-locations will be memorized as illustrated in the following image (blocks are just for demonstration)

• You can now access each individual Location within the Area, by accessing it inside a HashMap, the key being in a format as illustrated above. Do what you want to use the Area now, there are some usefull methods included (see below).

Methods

• getLocations() - Returns a HashMap of all Locations within the Area and a matching identifier-index
• getLocation(String xyz) - Returns a Location inside the Area; xyz referring to the relative coordinates, formatted like this: "x.y.z"
• getWorld() - Returns the World of the Area
• getSize() - Returns the Size of the Area
• getLength(String dir) - Returns the amount of Locations of one side of the Area; dir referres to the side; Valid directions are: "x", "y", "z"
• getOverlap(Location pos) - Determines if a Location is within the Area
• getOverlap(Area area) - Determines if an Area is within the Area
• getOverlap(SimpleArea area) - Determines if an SimpleArea is within the Area
• toString() - Returns a String to describe the Area; "<nameOfClass>{minLocation; maxLocaton}"

SimpleArea vs. Area (and also AreaConfiguration)

AreaTools includes as of now 3 classes: Area, SimpleArea and AreaConfiguration. AreaConfiguration is just a simple class for creating an additional YAML-File you could store data about your Areas inside (it's just for making things confortable, not really much code there, so I will not mention it again). Area is the basic class of AreaTools. It allows all of the functionality, same does SimpleArea. Basically Area remebers every Location in a HashMap<String, Location>, while SimpleArea constructs such a HashMap, if you need it to (by accessing getLocations). That makes Area more resource-(RAM)-intensive then SimpleArea, while SimpleArea relies on calculations. That means that if you need to access all of the Locations within one of these two classes, Area would be able to give you the result instantly, while SimpleArea needs to calculate it first. If you need to access the Locations at a quite frequent rate, I would suggest using Area, if not SimpleArea, as it is very RAM-friendly. Actually in most cases it should be better to use SimpleArea, as even the provided methods work less resource-intensive for it (except the getLocations() - as described above).

NOTE: Both Area and SimpleArea have a restriction of maxsize built-in. You can remove it, but it may cause a OutOfMemoryError, if the two Locations given creates an area too big for the server's RAM to remember.