Skip to content
This repository has been archived by the owner on Nov 2, 2021. It is now read-only.

Developers

Jump to bottom
Pierre-Yves B edited this page Aug 6, 2020 · 31 revisions

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/AdvancedAchievements/mvn-repo/</url>
</repository>
<dependency>
  <groupId>com.hm.achievement</groupId>
  <artifactId>advanced-achievements-api</artifactId>
  <version>1.2.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!

Modifying the plugin

Setting your own working copy of the project

Ensure you have a working version of the JDK (Java Development Kit).

Fork the repository by clicking on the Fork icon on the top right of the page.
You can also simply clone or download it by going to the main page.

Eclipse

  • In Eclipse, go to File -> Import... -> Maven -> Existing Maven Projects.
  • In the Root Directory field, select the location where you downloaded the Advanced Achievements repository.
  • Tick the pom.xml box that appears in the Projects field and click Finish.
  • To compile the plugin, in the Package Explorer window, right click on the imported project, then Run As -> Maven Install.
  • The plugin will be generated in the target folder of the project.

IntelliJ IDEA

  • In IntelliJ IDEA go to Open.. and open the repository root folder (Your download location)
    • IDEA will run Sync on the maven project - if not click the Configure maven project pop-up that appears
  • If not yet installed, install Maven Helper-plugin to run maven goals inside IDEA (For next steps)
  • To compile the plugin, in Project right click AdvancedAchievements > ⚙️ Run Maven > install, this will run mvn install:install
  • The plugin will be generated in the target folder of the project.

For easy PRs:

  • Use tabs: Settings > Editor > Code Style > Java > Tabs and indents > Use tab character
  • You can run mvn formatter:format with ⚙️ Run Maven > Plugins > maven-formatter-plugin > formatter:format

Implementing new categories

Adding simple categories directly in Advanced Achievements is really easy and does not require advanced Java knowledge: it's mostly a matter of following the code that's already written!

  • Define a new category by adding a value to the NormalAchievements.java enum in the com.hm.achievement.category package. For instance: 
    CATEGORYNAME("CategoryNameInConfigs", "lang-key-for-aach-list", "Default display name", "Comment in config.yml"),
  • Add a new listener class to the com.hm.achievement.listener.statistics package. DropsListener.java is a very simple example you can use as a reference.
  • Add a new binding method in ReloadableModule.java, similar to the existing ones.
  • Add a new default permission value in plugin.yml (achievement.count. followed by the category name in lower case). This file is situated in the resources folder.
  • Still in the resources folder, update config.yml, lang.yml and _gui.yml to include your new category. You're done!

If you're happy with what you've done, why not contribute and open a pull request?

Wiki pages

Clone this wiki locally