The Javadoc for the API is available here.

MapTowny uses Glare's repository and Jitpack to host the JAR package.

If you're building a plugin that utilizes the MapTowny API, it is highly recommended you use a build tool such as Maven or Gradle. The MapTowny dependency is ONLY the API portion of MapTowny.

The example below shows how to add the MapTowny dependency using Glare's repository. If you are using maven, add the following to your pom.xml:

  <repositories>
    <repository>
      <id>glaremasters repo</id>
      <url>https://repo.glaremasters.me/repository/towny/</url>
    </repository>
  </repositories>
...
<dependency>
    <groupId>me.silverwolfg11</groupId>
    <artifactId>maptowny-api</artifactId>
    <version>2.2.0</version>
</dependency>

For gradle, add the following to your build.gradle:

// ...
repositories {
    maven { url 'https://repo.glaremasters.me/repository/towny/' }
}
// ...
dependencies {
    implementation 'me.silverwolfg11:maptowny-api:2.1.0'
}

Click here if you want to see how to use Jitpack instead.

You will also need to add Towny as a dependency in order to use the MapTowny dependency.

The plugin has two events available to use: MapReloadEvent and WorldRenderTownEvent.

This event is called when the plugin is reloaded. The event is purely informative to notify other plugins when this plugin is reloaded. One thing this event can be used for is re-adding custom tooltip replacements. Tooltip replacements reset every time the MapTowny plugin reloads, so your plugin should listen to this event and re-register custom replacements if they exist.

This event is called whenever the plugin renders a town on the map per world. This event is called asynchronously. Two primary uses of this event are either cancelling this event to prevent the town from being rendered in a specific world or modifying the marker options for the town claim. Cancelling the event means that the town claim will not be rendered, the town outpost icons for that world will not be rendered, and the town homeblock icon will not be rendered (if the homeblock is in that world). The marker options for the specific event will apply to the claim areas and the icons.

To register custom tooltip replacements, you will need to use LayerManager#registerReplacement(String key, Function<Town, String> function). To get the current LayerManager, simply call the getLayerManager() method on the MapTowny plugin object (after casting it to the MapTownyPlugin interface). The registerReplacement() method takes in a key which is essentially the text that you want to replace (e.g. "%mayor%"), and a function that is for replacing the text based on the current town being rendered. The replacements are registered for both the click tooltip, and the hover tooltip text.

Some things to keep in mind:

• Custom replacements are removed every time the plugin reloads. To persist them, listen to the MapReloadEvent and re-register the replacements.
• Registering replacements do perform logic initial logic, so it is recommended to register replacements on plugin load
• Replacements are ran synchronously, so all Bukkit API is safe to access.

Rendering objects on the web-map is a bit of a process.

The easiest way to render a multi-polygon shape is to use Towny Coords. These Towny coords will usually represent a chunk (or whatever the townblock size), but can be used to represent any scale. Make sure the Coords are all part of the same world, because when forming the polygon, the world won't be looked at.

Once you have your collection of Coords, you can use TownyUtil#coordsToPolys to convert them to polygon outlines. The method also takes in two other parameters: findNegativeSpace, and coordScale. findNegativeSpace is a boolean that you can use to indicate whether the algorithm should find holes within the polygon outline. coordScale is an integer to indicate the Coord-to-block scale of each Coord. For example if a Coord represents a chunk, the value would be 16 to indicate the scale is 16 blocks inside of 1 Coord.

In order to render the polygons obtained, you first need to get the MapLayer. The MapLayer can be accessed via MapLayer LayerManager#getTownyWorldLayerProvider(String worldName). With the map layer, you can call MapLayer#addMultiPolyMarker(String markerKey, List<Polygon> polygons, MarkerOptions markerOptions). The markerKey must be unique for each layer. The markerOptions are properties like the fill color, fill size, stroke color, stroke size, tooltip, etc for each polygon rendered on the web-map.

• MapLayer LayerManager#getTownyWorldLayerProvider(String worldName): Gets the layer provider that the MapTowny plugin uses for the certain world.
• LayerManager#unregisterReplacement(String key): Unregister a tooltip replacement.