Using the RuneLocus callback system

This is a tutorial created by Hope, one of our forum members. The tutorial will teach you to integrate the RuneLocus callback system into your own RuneScape private server.

Requirements

  • A MyLocus account. If you do not have one, create one by clicking on MyLocus at the navigation menu.
  • A place to host your voting script. This is usually done on a web-host, eventually a VPS or dedicated server.
  • A submitted RuneScape server on the toplist. If you don’t have a RuneScape private server on the toplist, register for a MyLocus account and then proceed to “Add Server” once logged in.

1. Downloading the callback script

Having completed the pre-requirements listed above, proceed to download the PHP Callback Example located at this link. Once downloaded, un-zip the archive and go to the next step.

2. Uploading and configuring the files on your web-host

Proceed to upload form.html and process.php to your webhost in a directory of your choice. Usually, users put these files in the desired voting directory. Example: http://yourserverwebsite.com/vote.

2.1. File: form.html

You will see the following code inside form.html.

<form action="http://www.runelocus.com/toplist/index.php" method="get">
<input type="hidden" name="action" value="vote" />
<input type="hidden" name="id" value="YOURSERVERID" />
Username: <input type="text" name="id2" placeholder="username" />
<input type="submit" value="Vote for us" /></form>

You may use this form however you want (putting it in another file, on your homepage, ect.) as long as it stays in a similar format and sends the value “vote” and an input with a name of “id2″.
Where it says YOURSERVERID, replace that with your toplist server ID. You can find the ID in the URL of your RuneScape server’s details page.

2.2. Creating a database

This will only work if you have a webhost that uses the cPanel system. Navigate to your cPanel and scroll down until you see the category similar to the picture below.

After you find the “Databases” category, click on MySQL Databases (which is the first option). On this page you’ll see a section called “Create New Database”. In this tutorial we’ve called the database “vote” (shown by the picture below).

Finish by clicking “Create Database”. Staying on the same page as before, locate at the bottom where it says “Create New User”. Fill in your desired username along with a password of your choice (shown below).

Finish by clicking “Create User”. Staying on the same page once again, locate the section “Add User to Database”, which should be right below where you created your user. Select the database you created, and the matching username you created for it (shown below).

Finish by clicking “Add”. It should direct you to a new page and ask for what privileges you’d like to assign. Simply click the “All Privileges” button located at the top and it should check mark everything. After done, click “Make Changes” at the bottom.

Congratulations! You’ve made a database.

2.3. Creating a table for your database to use

In order for you to keep track of your voters, you’ll need to create a table inside your database which organizes and holds voter information. This is a simple step.

Begin by navigating to your cPanel home (just like before) and in the “Databases” category (once again), click on “phpMyAdmin”. You will be redirected to phpMyAdmin, an example is shown below.

Take a look on the left hand side. On the left you’ll see your username to log into cPanel (in this example “world987″. Click on the “+”, which should open a list of your databases. You will now see the new database you have created in the previous steps. It should look something like “yourusername_vote”. Click on it, and you’ll see the following:

For the “name”, enter “players” and for the number of columns, enter the number “2″. After clicking “Ok” at the bottom right, it should take you to a page that you might look confusing. That’s alright! Simply copy what’s in the below image and make your page look the same as the screenshot below.

After you’ve finished, click “Save” in the bottom right. Congratulations once again! You’ve just created a place to store information for your validated voters.

The ‘username’ variable is self-explanatory. It holds the player’s username.
The ‘tokens’ field holds how many validated votes the player has made.

3. File: process.php

Next, open up process.php. You should see the following code:

<?php

    $con = mysql_connect("localhost","DATABASE_USERNAME","DATABASE_PASSWORD");
    if (!$con) {
        die("Could not connect to database: " . mysql_error());
    }

    mysql_select_db("DATABASE_NAME", $con);

    $username = mysql_escape_string($_GET['usr']);

    if (isset($_GET['usr'])) {
        mysql_query("UPDATE players SET tokens = tokens + 10 WHERE username = '$username'");
        // Above is an example, would add 10 vote tokens to the user.
    }

    mysql_close($con);

?>

In order for this code to work, we’re going to have to edit a few things.

Locate the following:

$con = mysql_connect("localhost","DATABASE_USERNAME","DATABASE_PASSWORD");

Place your earlier created username and password in the corresponding places. Next, locate the following:

mysql_select_db("DATABASE_NAME", $con);

Enter your earlier created database name.

We’re almost done! Hang in there.

In the same file, where it says:

if (isset($_GET['usr'])) {
        mysql_query("UPDATE players SET tokens = tokens + 10 WHERE username = '$username'");
        // Above is an example, would add 10 vote tokens to the user.
}

Replace that with:

if (isset($_GET['usr'])) {
      $result = mysql_query("SELECT * FROM players WHERE username = '$username'");
      if(mysql_num_rows($result) == 0) {
          mysql_query("INSERT INTO players (username, tokens) VALUES ('$username', 1);");
      } else {
          mysql_query("UPDATE players SET tokens = tokens + 1 WHERE username = '$username'");
      }
}

What this code does: Whenever RuneLocus sends a validation back to your process.php document, it will search for any entries in your database corresponding with the player name. If there is one in there, it will add +1 to the token count, and if there isn’t any entries in it, it will insert the player’s name along with 1 token into the database table.

You’re done this part, don’t forget to save process.php!

4. Setting the callback url

Navigate to your MyLocus account once again. Click on “Edit” next to your server listing. Scroll down and find the box where it says “Incentive Callback URL”. This is where the URL to your process will be placed. For example, this link would be wherever you uploaded your process.php. An example would be http://yoursite.com/vote/process.php

Once that’s done, click save.

Congratulations! You now have a voting system that authenticates users. Direct the users to the page containing the form.html you edited earlier. They will proceed to enter their username and click the “vote” button which will redirect them to runelocus. After they have voted, RuneLocus will send information to your process.php file and update your database.

5. Claiming the votes on your RuneScape private server

Next, we have to set up our RSPS so that players can claim their votes as a reward. Begin by going into your source and creating a new class called Vote. Copy and paste the below code into it.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class Vote {

    private static Connection con = null;
    private static Statement stmt;

    public static void createConnection() {
        try {
            Class.forName("com.mysql.jdbc.Driver").newInstance();
            String IP="WEB HOST IP";
            String DB="DATABASE NAME";
            String User="DATABASE USERNAME";
            String Pass="DATABASE PASSWORD";
            con = DriverManager.getConnection("jdbc:mysql://"+IP+"/"+DB, User, Pass);
            stmt = con.createStatement();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void claimVote(Player player) {
        createConnection();
        if (checkVote(player.getUsername())) {
            int tokens = getVotes(player.getUsername()); //Number of times this user has voted. Number of unclaimed votes.

            //methods for giving rewards to players goes here.
            //for example, I might give a user 50,000 coins per 1 time they voted, so I would do:
            player.getInventory().add(new Item(995, 50000 * tokens)); // adds 50,000 * token amount of coins to the player's inventory.

            //remove votes after user as claimed.
            removeVotes(player.getUsername());
        } else {
            player.sendMessage("You either have not voted, already claimed your reward, or there was an error.");
            player.sendMessage("Either try again in a few minutes, or contact a staff member.");
        }
    }

    private static ResultSet query(String s) throws SQLException {
        try {
            if (s.toLowerCase().startsWith("select")) {
                ResultSet rs = stmt.executeQuery(s);
                return rs;
            } else {
                stmt.executeUpdate(s);
            }
            return null;
        } catch (Exception e) {
            destroyConnection();
            createConnection();
        }
        return null;
    }

    private static void destroyConnection() {
        try {
            stmt.close();
            con.close();
        } catch (Exception e) {

        }
    }

    private static boolean checkVote(String playerName) {
        try {
            String name2 = playerName.replaceAll("_", " ");
            Statement statement = con.createStatement();
            String query = "SELECT * FROM players WHERE username = '" + name2 + "'";
            ResultSet results = statement.executeQuery(query);
                while(results.next()) {
                    int tokens = results.getInt("tokens");
                    if(tokens >= 0) {
                         return true;
                    }
                }
        } catch(SQLException e) {
            e.printStackTrace();
        }
        return false;
    }

    private static int getVotes(String playerName) {
        try {
            String name2 = playerName.replaceAll("_", " ");
            Statement statement = con.createStatement();
            String query = "SELECT * FROM players WHERE username = '" + name2 + "'";
            ResultSet results = statement.executeQuery(query);
            while(results.next()) {
                int tokens = results.getInt("productid");
                if(tokens >= 1) {
                    return tokens;
                }
            }
            } catch(SQLException e) {
                e.printStackTrace();
            }
            return 0;
    }

    private static boolean removeVotes(String playerName) {
        try {
            String name2 = playerName.replaceAll("_", " ");
            query("DELETE FROM `players` WHERE username = '"+name2+"';");
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
        return true;
    }

}

The above code is an example of a class that connects to your website database, checks to see if the user voted, and if he/she has, then it handles the rewards.

Begin by locating the following piece of code:

String IP="WEB HOST IP";
String DB="DATABASE NAME";
String User="DATABASE USERNAME";
String Pass="DATABASE PASSWORD";

Just as you did in process.php on your webhost, enter the correct details corresponding to your database. For the WEB HOST IP, simply use the IP of your web-host. If you do not know it, it is on the left hand side of the main page of your cPanel.

After that, scroll down and find the method claimVote, which should look like this:

    public static void claimVote(Player player) {
        createConnection();
        if (checkVote(player.getUsername())) {
            int tokens = getVotes(player.getUsername()); //Number of times this user has voted. Number of unclaimed votes.

            //methods for giving rewards to players goes here.
            //for example, I might give a user 50,000 coins per 1 time they voted, so I would do:
            player.getInventory().add(new Item(995, 50000 * tokens)); // adds 50,000 * token amount of coins to the player's inventory.

            //remove votes after user as claimed.
            removeVotes(player.getUsername());
        } else {
            player.sendMessage("You either have not voted, already claimed your reward, or there was an error.");
            player.sendMessage("Either try again in a few minutes, or contact a staff member.");
        }
    }

You’ll need to properly change the syntax of certain things (such as the parameters of the method depending on what your sources uses as the player class, and the function of how to get the player’s username.

Here’s how you add rewards for the player:

Find:

int tokens = getVotes(player.getUsername()); //Number of times this user has voted. Number of unclaimed votes.

            //methods for giving rewards to players goes here.
            //for example, I might give a user 50,000 coins per 1 time they voted, so I would do:
            player.getInventory().add(new Item(995, 50000 * tokens)); // adds 50,000 * token amount of coins to the
player's inventory.

It grabs the player’s tokens from the database (if any), then stores it as an integer. You can use this any way you want to. For example, you’ll see that right after it, I made the system add 50.000 coins times the number of votes in the database. The methods and classes in which your RuneScape private server operates upon will be different, so you’ll need to customize this method a bit. It helps to use an IDE (like Eclipse) if you’re somewhat more advanced in programming.

We’re almost done! There’s only a few steps left to do.

After saving Vote.class, navigate to your webhost and go to the main page of the cPanel. Just as before, scroll down to the “Databases” category and select the “Remote MySQL” button. You’ll see something like this:

In the box, enter the IP upon which your RS private server is hosted. If you have a VPS, it will be the IP address of that, if you’re hosting it on your home computer, you can put the IP address of your network. It whitelists the IP so that connects can be made and your RSPS can access the database files.

That’s it!

Generally users create a command called “claim” or “vote” that calls the Vote.claimVote(player); method, but feel free to do it any way you’d like. Enjoy your callback system!

If you have any questions about this tutorial, please contact Hope or any other RuneLocus member at the RuneLocus forum. We’re here for any RuneScape private server related support!