API

Using the API

In your own plugin project, you might want to retrieve data from Advanced Achievements. Here is a table showing which versions of the API are compatible with which versions of the plugin:

API version	Plugin version
1.5.0	>= 6.2.0
1.4.0 - 14.4.1	5.15.0 - 6.1.3
1.3.0	5.13.0 - 5.14.1
1.2.0	5.12.0 - 5.12.5
1.1.0	5.10.0 - 5.11.2
1.0.0	5.8.0 - 5.9.3

To integrate with the API, follow these steps:

• Add the following repository and dependency to your pom.xml:

<repository>
  <id>advanced-achievements-repo</id>
  <url>https://raw.github.com/PyvesB/advanced-achievements/mvn-repo/</url>
</repository>
<dependency>
  <groupId>com.hm.achievement</groupId>
  <artifactId>advanced-achievements-api</artifactId>
  <version>1.6.0</version>
  <scope>provided</scope>
</dependency>

You can alternatively simply include the full plugin file to the build path of your project, but that approach is not recommended.

• Add a piece of code similar to the following in your project:

import com.hm.achievement.api.AdvancedAchievementsAPI;
import com.hm.achievement.api.AdvancedAchievementsAPIFetcher;
...

Optional<AdvancedAchievementsAPI> advancedAchievementsAPI = AdvancedAchievementsAPIFetcher.fetchInstance();
if (advancedAchievementsAPI.isPresent()) {
  advancedAchievementsAPI.get(). ...
}

To check beforehand that Advanced Achievements is enabled, use Bukkit.getPluginManager().isPluginEnabled("AdvancedAchievements"). If you are unsure whether users will have a recent enough version of Advanced Achievements available, you can retrieve the version with Bukkit.getPluginManager().getPlugin("AdvancedAchievements").getDescription().getVersion().

• Use your AdvancedAchievementsAPI object as you wish! The interface with commented method signatures is available here. Feel free to open an issue if you need any help!
• Add Advanced Achievements as a dependency or soft-dependency in your plugin.yml:

# Make Advanced Achievements compulsory:
depend: [AdvancedAchievements]
# Or make Advanced Achievements optional:
softdepend: [AdvancedAchievements]

---

Listening to achievement events

In your own plugin project, you might want to be notified when a player receives an achievement. That's simple and possible since version 5.0 of the plugin!

• Include the API as a Maven dependency as explained in the previous paragraph.
• Add a new class similar to the following in your project:

import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import com.hm.achievement.utils.PlayerAdvancedAchievementEvent;
...

public class PlayerAdvancedAchievementListener implements Listener {

	...

	@EventHandler(priority = EventPriority.NORMAL, ignoreCancelled = true)
	public void onPlayerAdvancedAchievementReception(PlayerAdvancedAchievementEvent event) {
		...
	}
}

• Make sure you add some code to verify that Advanced Achievements is running with an appropriate version and register the listener to your plugin. For instance in your main plugin class:

...
if (Bukkit.getPluginManager().isPluginEnabled("AdvancedAchievements")) {
    Plugin pluginInstance = Bukkit.getPluginManager().getPlugin("AdvancedAchievements");
    // Check whether the running version contains the PlayerAdvancedAchievementEvent class.
    if (Integer.parseInt(Character.toString(pluginInstance.getDescription().getVersion().charAt(0))) >= 5) {
        getServer().getPluginManager().registerEvents(new PlayerAdvancedAchievementListener(), this);
    }
}
...

• Add Advanced Achievements as a dependency or soft-dependency in your plugin.yml:

# Make Advanced Achievements compulsory:
depend: [AdvancedAchievements]
# Or make Advanced Achievements optional:
softdepend: [AdvancedAchievements]

• Congratulations, your listener code will be run each time a player receives an achievement!