Developer API

Hello developer.

You probably came here because you wanted to implement support for your own plugin with Autorank. Or perhaps you wanted to know how Autorank works? You're at the right place. You'll get to know how Autorank exactly works and what kind of data Autorank can provide you. Below you will find some general information about how to hook into Autorank and some examples. If you need more information beyond that, you are able to view the Javadocs here.

Using Maven

To be able to use Autorank in your project (if you're running Maven), you can use the following settings:

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

	<dependency>
	    <groupId>com.github.Staartvin</groupId>
	    <artifactId>Autorank-2</artifactId>
	    <version>VersionHere</version>
	</dependency>

If you're not using Maven, you can download the latest release from here and include it in your project.

Making sure your plugin loads before Autorank

To make sure that Autorank recognizes your requirements, your plugin should load before Autorank does. You can do this by adding a depend or soft depend option in your plugin.yml, see this page. You can use soft depend whenever Autorank is not necessary to run your plugin. If you need Autorank to always be there when you run your plugin, you should use depend.

Hooking into Autorank

If you want to access data of Autorank, you'll need to check if the server is running Autorank and if Autorank is enabled. You can do this as so:

public Autorank getAutorank() {
	Plugin plugin = getServer().getPluginManager().getPlugin("Autorank");
		
	// Plugin is not loaded or enabled
	if (plugin == null || !(plugin instanceof Autorank)) {
		return null; // You could also throw an exception if you want to.
	}
		
	return (Autorank) plugin;
}

This method will get check if Autorank is installed on the server and if it's enabled. It will return null if Autorank wasn't present; otherwise it will return the Autorank class.

Setting up connection

To make a reference to the Autorank class, you'll have to define an Autorank object in your class and call the getAutorank() (from above) method. An example snippet:

private Autorank autorank;

// Your onEnable method in your main class
public void onEnable() {

    autorank = getAutorank();

    if (autorank == null) {
        this.getLogger().warning("Autorank has not been found! Warning!");
    } else {
        this.getLogger().info("Autorank has been found and has been hooked into!");
    }

// rest of your code
}

This is your basic setup for hooking into Autorank. After you have verified that Autorank is installed on the server (and enabled), you can get the API class and start getting data!

Start getting data

Before we can get data off of Autorank, we need to find its API class. Fortunately, that's really easy. See this snippet below:

private API autorankAPI;
private Autorank autorank;

public API getAutorankAPI() {
    
    // Check whether Autorank has been found earlier on
    if (autorank == null || !autorank.isEnabled()) {
        // Warning: Autorank is not enabled!
        return null;
    }

    API autorankAPI = autorank.getAPI();
    return autorankAPI;
}

We check whether Autorank is found and if it's found, we get the API class of Autorank. This is the basic setup for your plugin. You are now ready to start working with Autorank.

Autorank events

Autorank has its own events.

There is 1 event: RequirementCompleteEvent. The event is fired when a player meets the requirements for a certain path and the results will be run. This one is cancellable.

You would listen to it as any other Bukkit event. An example:

@EventHandler
public void onReqCompletion(RequirementCompleteEvent event) {

    plugin.getServer().broadcast(event.getPlayer().getName() + " just completed a requirement!");

    // do more fancy stuff here.
}

It's really easy!

Building your own requirement

Autorank has a lot of requirements that are built into the plugin. However, you're also able to register your own requirements. Requirements are based on the AbstractRequirement class. You'll need to extend this class.

AbstractRequirement

An AbstractRequirementclass is the template class to be able to create a new requirement. It consists of many methods, but I'll show you the most important ones.

Type of requirement

There are two types of requirements:

1. Requirements that need a player to be online to be able to check whether it's been completed

2. Requirements that do not need a player to be online to be able to check whether it's been completed

If your requirement is of the first type, you'll need to override the method needsOnlinePlayer() to return true, like so:

@Override
public boolean needsOnlinePlayer() {
    return true;
}

Initializing your requirement

Whenever a requirement is registered and is detected in a path, it is initialized using the initRequirement(String[] options) method. This argument is a String array. It represents the string provided in the Paths file, divided by the semicolon (;). The method should return true when the requirement is set up correctly or false if it did not.

Whenever something went wrong during setup, it's good practice to use registerWarningMessage(String message) to tell the user something went wrong. These messages are automatically delivered to the user.

Checking progress of a requirement

Once a requirement is initialized, players can check their progress on the requirement. If your requirement needs a player to be online to check their status, it will callgetProgressString(Player player). You should return a string that shows the progress of that player. If your requirement does not need a player to be online, Autorank will call getProgressString(UUID uuid).

Whenever Autorank wants to show the percentage towards completion of the requirement, it will call the getProgressPercentage(UUID uuid) method. Note that this method will only be called with a UUID parameter. If your requirement needs a player to be online, you should not override this method. It will then always return zero when the player is not online.

Providing a description

Whenever a player wants to view the description of your requirement, Autorank will call the getDescription() method. This description should not state any information about the current progress. It should just show what the player should do.

Checking whether a requirement is completed

Finally, when Autorank wants to check whether a player has completed a requirement, it will call either the meetsRequirement(UUID uuid) or the meetsRequirement(Player player) method (based on whether the requirement needs players to be online or not). Regardless of which method you override, you'll need to return true whenever the requirement is met or false if it is not.

That's basically all you need for a requirement.

Last step

There's only one thing that you'll need to do before Autorank detects the requirement.

You'll need to register the requirement so Autorank knows what words can be used to define such requirement in the config files. You can do this by grabbing the RequirementBuilder class and calling the method registerRequirement(). Example:

// Register requirement
RequirementBuilder.registerRequirement("gamemode", GamemodeRequirement.class);

This will register your requirement. Whenever an admin uses the word gamemode in the config, it will redirect to your requirement.

You're all set now. Happy coding!