Developer's 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.

---

Index

• Hooking into Autorank
• Setting up connection
• Start getting data
• Autorank events
• Custom requirements

---

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. Happy coding!

---

Autorank events

Autorank has its own events.

Currently (as of Beta 2.7.2), there are 2 events. PlayerPromoteEvent and RequirementCompleteEvent. The first one is fired when a player is going to be promoted to a new group. It is cancellable. The second one is fired when a player meets the requirements for a certain requirement and the results will be run. This one is also cancellable.

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

@EventHandler
public void onPlayerPromote(PlayerPromoteEvent event) {
// do fancy stuff here.

}

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

---

Custom requirements

Autorank has a lot of requirements you can use in the advanced config. Those are predefined, though. You can also make your own requirements. You'll need to make a class that extends the Requirement class of Autorank. Example of the time requirement class:

import java.util.ArrayList;
import java.util.List;

import me.armar.plugins.autorank.AutorankTools;
import me.armar.plugins.autorank.language.Lang;
import me.armar.plugins.autorank.playerchecker.result.Result;

import org.bukkit.entity.Player;

public class TimeRequirement extends Requirement {

	int time = -1;
	private boolean optional = false;
	private boolean autoComplete = false;
	private int reqId;
	List<Result> results = new ArrayList<Result>();

	@Override
	public boolean setOptions(String[] options, boolean optional,
			List<Result> results, boolean autoComplete, int reqId) {
		this.optional = optional;
		this.results = results;
		this.autoComplete = autoComplete;
		this.reqId = reqId;

		if (options.length > 0)
			this.time = AutorankTools.stringToMinutes(options[0]);
		return (time != -1);
	}

	@Override
	public boolean meetsRequirement(Player player) {
		if (isCompleted(getReqId(), player.getName())) {
			return true;
		}

		double playtime = this.getAutorank().getPlaytimes()
				.getLocalTime(player.getName());
		return time != -1 && time <= playtime;
	}

	@Override
	public String getDescription() {
		return Lang.TIME_REQUIREMENT.getConfigValue(new String[]       {AutorankTools.minutesToString(time)});
	}

	@Override
	public boolean isOptional() {
		return optional;
	}

	@Override
	public List<Result> getResults() {
		return results;
	}

	@Override
	public String getProgress(Player player) {
		String progress = "";
		progress = progress.concat(getAutorank().getPlaytimes().getLocalTime(
				player.getName()) + " min" 
				+ "/" + time + " min");
		return progress;
	}

	@Override
	public boolean useAutoCompletion() {
		return autoComplete;
	}
	
	@Override
	public int getReqId() {
		return reqId;
	}

}

As you can see, there are a few methods that need to be included to make it a valid requirement. The setOptions() method takes a bunch of parameters.

Parameters (as of Beta 2.7.2):

• String[] options
• boolean optional
• List result
• boolean autoComplete
• integer reqId

The options parameter is the value line defined in the config. The optional value shows whether it's a optional requirment The result list will hold a list of results that need to be performed when this requirement is met. The autoComplete value will tell you whether Autorank will auto-complete the requirement when it's met. And last but not least, the reqId is a number that stores what requirement this is. This is a unique number and used to control what requirement a player already has completed.

NOTE: All the parameters will be given by Autorank. You should never call this method by yourself. Autorank will call it when necessary.

The second method is meetsRequirement() . This will hold the logic that checks whether a player meets the requirement. This method has to always have this inside it:

if (isCompleted(getReqId(), player.getName())) {
	return true;
}

That will basically check whether the requirement is already completed. If this is not included Autorank will never detect whether a requirement is already done or not.

That's basically all you need for a requirement.

There's only one thing that you'll need to add 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 Autorank main class and calling the method registerRequirement(). Example:

// Register requirement
Autorank.registerRequirement("time", TimeRequirement.class);

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

You're all set now!