BlueMapAPI

Table of Contents

Preparations
API entry-point
Creating Map-Markers
Persisting Markers

Preparations

With Gradle or Maven you can use our Maven Repository to add BlueMapAPI to your project and lookup the latest version.

Gradle (groovy):

repositories {
    maven { url 'https://repo.bluecolored.de/releases' }
}

dependencies {
    compileOnly 'de.bluecolored.bluemap:BlueMapAPI:2.7.1'
}

Gradle (kotlin):

repositories {
    maven ( "https://repo.bluecolored.de/releases" )
}

dependencies {
    compileOnly ("de.bluecolored.bluemap:BlueMapAPI:2.7.1")
}

Maven:

<repositories>
    <repository>
        <id>bluecolored</id>
        <url>https://repo.bluecolored.de/releases</url>
    </repository>
</repositories>

<dependency>
    <groupId>de.bluecolored.bluemap</groupId>
    <artifactId>BlueMapAPI</artifactId>
    <version>2.7.1</version>
    <scope>provided</scope>
</dependency>

API entry-point

Javadoc: https://repo.bluecolored.de/javadoc/releases/de/bluecolored/bluemap/BlueMapAPI/latest

The BlueMapAPI class has some static methods that will be your entry-point into the API:

// Directly getting the api (wrapped in an Optional)
Optional<BlueMapAPI> optionalApi = BlueMapAPI.getInstance();

// Directly using the API if it is enabled
BlueMapAPI.getInstance().ifPresent(api -> {
   //code executed when the api is enabled (skipped if the api is not enabled)
});

// Using a listener to do something as soon as the API is available
BlueMapAPI.onEnable(api -> {
   //code executed when the api got enabled
});

BlueMapAPI.onDisable(api -> {
   //code executed right before the api gets disabled
});

Creating Map-Markers

You can simply create any type of Marker using its constructor:

POIMarker marker = new POIMarker("My Marker", new Vector3d(20, 65, -23));
marker.setMaxDistance(1000);

or using the Builder-Pattern:

POIMarker marker = POIMarker.builder()
    .label("My Marker")
    .position(20, 65, -23)
    .maxDistance(1000)
    .build();

To add this marker to a map, you also need a MarkerSet which you can create on the same ways as you would create markers. And then you can just add the marker to one or more maps, like this:

POIMarker marker = POIMarker.builder()
        .label("My Marker")
        .position(20, 65, -23)
        .maxDistance(1000)
        .build();

MarkerSet markerSet = MarkerSet.builder()
        .label("Test")
        .build();

markerSet.getMarkers()
        .put("my-marker-id", marker);

api.getWorld(player.getWorld()).ifPresent(world -> {
    for (BlueMapMap map : world.getMaps()) {
        map.getMarkerSets().put("my-marker-set-id", markerSet);
    }
});

As you can see, both: markerSet.getMarkers() and map.getMarkerSets() return a simple Java-Map<> that you can both modify in any way like you want and at any point in time. Modifying those Java-Map<>s or any Marker or MarkerSet inside, will directly modify the markers that are displayed on that map.

Persisting Markers

Markers that you create are not persistent! This means as soon as BlueMap unloads, they are gone. Your plugin is supposed to re-create all Markers each time BlueMap loads. (= each time a BlueMapAPI.onEnable()-Consumer gets invoked) -> Your plugin is responsible for persisting it's own markers.

This sounds complicated, but there is a really easy way to do this:

You can easily save any Marker or entire MarkerSet (including all markers) to a file like this:

try (FileWriter writer = new FileWriter("marker-file.json")) {
    MarkerGson.INSTANCE.toJson(markerSet, writer);
} catch (IOException ex) {
    // handle io-exception
    ex.printStackTrace();
}

And you can as easily load this file and create a Marker or entire MarkerSet again:

try (FileReader reader = new FileReader("marker-file.json")) {
    markerSet = MarkerGson.INSTANCE.fromJson(reader, MarkerSet.class);
} catch (IOException ex) {
    // handle io-exception
    ex.printStackTrace();
}

This uses the Gson Library which is included in BlueMap and BlueMapAPI (and Minecraft). With Gson you can do much more than just loading and saving those markersets. The MarkerGson class just provides you with a Gson-Instance that has all necessary (de)serializers pre-registered. So you can use the full power of the Gson-Library if you want.