Installation & Setup

The first step in installing the HighScoreServer is to unzip the files from the installation file into a directory of your choice. Once all the files have been extracted, open the file called config.cfg into a text editor. This is the configuration file for the server and contains information about the high score tables the server will manage. Each line in the file represents a high score table and contains the table's name, it's size (the maximum number of high scores it can contain), and it's file name (used to save the high score table to disk). To add more high score tables for the server to manage, simply add them in this format.

name#size#filename

Note: It is important that each line in the file follows this format exactly!.

If the file name you supply for a high score table does not exist, it will be created when the server starts and will contain high score entries with the name unknown with a score of 100.

Once configured, the server is fired up from the command line like this ...

java HighScoreServer 1234

... where 1234 is the port number the server will run on. Any port number can be used as long as it is not being used by any other services on your server.



Using the server

Once the server is up and running you do not need to do anything with it, you can just leave it running and it will happily sit there and manage the high scores for all your Java game applets, however for you power users the server does allow some interaction should you need it. When the server finished loading you may have noticed a > prompt in the server console, this means the server is running and ready to take any commands from you. To see a list of commands the server accepts, type help and press enter, a list of commands the server understands will be displayed in the console. I will list and explain each command below.


help Displays a list of all the commands the server understands with a short description for each.
add tableno||name||score Submits a high score entry to the specified table. The position the score entered at (if at all) will be displayed.
load tableno Loads the specified high score table's data from it's file. Useful if you have added a score to the table manually but then change your mind and want to revert back before the auto-save kicks in.
save tableno Saves the specified high score table's data to it's file. This allows you to force a save rather than waiting for the auto-save.
view [tableno] If this command is issued without specifying a table number then a list of all the high score tables the server is currently managing will be listed. If a table number is given, the high scores in that table will be displayed instead.
quit Shuts down the server.


Submitting & Retrieving high scores to/from the server (Applet)

Submitting scores to the server and retrieving them is achieved via a simple protocol described below. You should be able to use the following code easily to get your own applets talking to the high score server.

First we need to set up the variables we will use to communitcate with the server.

Socket socket;
BufferedReader is;
PrintWriter os;

The following code will make a connection to the high score server at my.server.com listening on port 1234. I would recommend that you read these values in as parameters to your applet rather than hard coding them as this will allow you to move your applet/high score server to different hosts without having to recompile the applet each time.

Note: Due to the security restrictions Java places on applets, the applet must be running on the same host as the high score server.

try
{
    socket = new Socket("my.server.com", 1234);
    is = new BufferedReader(new InputStreamReader
    (new BufferedInputStream(socket.getInputStream())));
    os = new PrintWriter(socket.getOutputStream());
}
catch(IOException e)
{
    System.err.println("Failed to connect to server.");
    System.err.println(e);
}


Once we have a connection to the server we can submit high scores with the following code...

os.println("submit||tablename||name||score");
os.flush();

And retrieve a list of high scores in a high score table with...

os.println("retrieve||tablename");
os.flush();


After we have sent a command to the server, we need to read what the server returns to us...

try
{
    String inputLine = is.readLine().trim();
}
catch(Exception ex)
{
    System.err.println("Failed to read response from server.");
    System.err.println(e);
}

If we were submitting a score, the server will return the position the score entered at (or 0 if it didn't qualify), if we are retrieving the high scores from a table, the server will return the scores in the following format...

name#score#name#score#name#score#name#score.....


Finally, when we have finished with the server we disconnect...

//Let server know we are disconnecting
os.println("bye");
os.flush();

//Close streams and socket
try
{
    is.close();
    os.close();
    socket.close();
}
catch(IOException e)
{
    System.err.println("Failed to close socket.");
    System.err.println(e);
}