Premier Toplist Voting Gateway

Getting Started with Motivote

In order to use Motivote, you must download it and include it in your classpath. Click here if you use Eclipse otherwise, click here.

Motivote is designed to work with any server, with as few alterations as possible. We do the hard work, so you don't have to!

What Is This Guide?

This guide will serve as the main point of reference for any server-specific guide. All steps seen here must be covered, in addition to any steps that are specific to the environment you'll be working in.

Required information

In order to utilize the functions of the Motiservice API, you must first figure out a few details, all of which are available to you on the Motivote Management Portal.

Motivote, and other Moti-services, utilize a container system. This container is home to all your Motiservices. The container will have a unique name which will be used as a sub-domain that all your Moti-services can be found under.

Finally, the last piece of information you have to find is your API key. This is similar to a password, and is used by your game server to talk to the Moti-service. You can find it on the management portal.

Important Imports

In order to use Motivote, you'll have to indicate to the compiler what classes you want, so we can do that with a simple import statement at the top of the file you intend on integrating with Motivote.

If you're unsure, just copy it wherever you think you will reference any Motivote-related code.

If you use an IDE, class imports should automatically be suggested to you. Conversely, unused imports that you add will be suggested for removal as well. It is highly recommended you use an IDE, such as Eclipse, because it will speed your development process up greatly.

import com.motiservice.Motivote;

Create a Motivote Instance

In order to utilize the functions of Motivote, we must create the Motivote API object. It takes two parameters, the container name, and the API key.

In this example, you will want to place this line of code inside of your class definition, and not inside any methods.

public static final Motivote MOTIVOTE = new Motivote(CONTAINER_NAME, API_KEY);

Redemption by Username, Auth, and IP Address

This method uses server commands in order to reward users for voting on toplists for you. Below is a simple example, to get you started. Server-specific code will be covered in a different section.

The main(String[]) method is a good place to start, since most servers use an array of strings to store the command, it will serve as a good analog for any server.

public static void main(String[] args) {
	try {
		String command = args[0];
		switch (command) {
			case "redeemauth":
				String auth = args[1];
				Result r1 = MOTIVOTE.redeem(SearchField.AUTH_CODE, auth);
				if (r1.success()) {
					// we only expect 1 result, so skip checking the size of the results
					System.out.println("Successful redemption!");
			case "redeemuser":
				String username = args[1];
				Result r2 = MOTIVOTE.redeem(SearchField.USER_NAME, username);
				if (r2.success()) {
					// since this type of redemption can yield multiple votes being redeemed at once
					// check how many were redeemed.
					int total = r2.votes().size();
					System.out.println("Successful redemption! x" + total);
			case "redeemip":
				String ip = args[1];
				Result r3 = MOTIVOTE.redeem(SearchField.IP_ADDRESS, ip);
				if (r3.success()) {
					// since this type of redemption can yield multiple votes being redeemed at once
					// check how many were redeemed.
					int total = r3.votes().size();
					System.out.println("Successful redemption! x" + total);
				System.err.println("Unknown command: " + command);
	catch (Exception ex) {

Automatic Redemption

The Motivote API also supports automatic redemption of votes. You can use this to automatically deliver rewards based on username or IP address, easily! Let's jump into that.

This is done using the checkUnredeemedPeriodically(Consumer<Result> resultConsumer) method. This block of code would go in your main(String[]) method of your application.

MOTIVOTE.checkUnredeemedPeriodically((result) -> {
	result.votes().forEach((vote) -> {
		boolean online = vote.username() != null && World.isPlayerOnline(vote.username());
		if (online) {
			Player player = World.getPlayer(vote.username());
			if (player != null) {
				MOTIVOTE.redeemFuture(vote).thenAccept((r2) -> {
					if (r2.success()) {
						// reward user
						player.addItem(995, 1000);

Of course, this will have to be modified to work with your server. Upon receival of a Result, the code you specify will be called.

  1. Go through each Vote in the Result
  2. Check if player is online by using their username.
  3. If online, find the user based on the username
  4. Do a null check that skips the reward process if the player is not found.
  5. Attempt to redeem the vote.
  6. Upon the receival of that Result, in reference to the redemption operation, check if the redemption was a success.
  7. Reward the player!