API

Using the API

In your own plugin project, you might want to retrieve data from Advanced Achievements. To integrate with the API, follow these steps:

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

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

<dependency>
  <groupId>com.github.pyvesb</groupId>
  <artifactId>advanced-achievements</artifactId>
  <version>VERSION</version>
  <scope>provided</scope>
</dependency>

Replace VERSION with the latest release number visible here, (e.g. 6.4.0). Note that unless there is a major version bump, newer versions of the plugin are expected to maintain compatibility with older API versions, so don't get worried if that number gets outdated when new releases happen.

• 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!