Originally published in the TGC Newsletter – April, 2014
In concert with the current competition to make an addictive game, we thought it might be a good idea to show how to set up an online scoring system. This tutorial will make use of AGK Tier 1 BASIC, PHP, and MySQL. You will need access to a server with PHP and MySQL capabilities.
To start, if you don’t already have a server set up, you can install XAMPP (www.apachefriends.org) to your local PC. This could be used as your server, but you will need to allow access to outside networks which can be dangerous without the proper knowledge of security. I do suggest that you use XAMPP for testing before going to a live server.
The database
After you have XAMPP set up you’ll need to create a database and table for the highscores to be recorded in. For this tutorial let’s call the database “high_scores” and the table will be “my_game“. You’ll also need to create a user for the database who has access to selecting (searching), and inserting the row. The table will need the following columns as a minimum:
- PID – the primary index for the database and set to auto increment.
- NAME – this is where you’ll store the user’s name. I’d suggest limiting it to 12 characters or less and making this column a VARCHAR(13) type. The 13 is the maximum string length (12) plus 1.
- SCORE – an integer
- DATE – Type is TIMESTAMP and I like to use the “current date on update” feature so that whenever a new score is entered you know the date of entry.
Another thing about the database is that you might want to clean it up every so often to delete scores that are below the top 10 high scores. You can either automate this process or do it manually. The database should be fairly lightweight so it really won’t need to be done often.
The PHP Scripts
Now we’ve got the database all set up let’s take a look at a simple PHP script that will allow your app to send data to the database. We’ll call this script “scores.php“. Because the code inthese examples is substantial, theyhave been extracted into text files for you to view and also to copy to your own implementation.
Note that this script checks that the score is a new high score and inserts it into the database at the same time. For a live application you might want to split this into two scripts: One that will initially check to see if the player’s score is a high score and then report back to the app. The app will then ask for the player’s name. Then finally you’d use the above script to insert the new high score. You’ll also want to put scripts like this into a protected directory on your server so that they cannot be abused. You can also add other mechanisms to the script to check for unreasonable scores.
Sending the Data
For the next part we’ll examine how to send this data from your AGK app to the server. Here I’m assuming that you have placed the PHP script in a protected directory as I’ve suggested. For this example, the protected directory is called “myProtectedDirectory“, the user for that directory is “myUserName” and the password is “myPassword“.
The above function is a very basic framework and will need you to add in user interface elements and what to do when the different events (high score is good, not a high score, and error) occur.
Retrieving the Scores
Next let’s take a look at how to get the high score data back to the application.
Create a PHP script called “getscores.php” with the following contents:
Back in AGK we will be able to fetch this string and output it with the following function. I used Chr(10) to separate each row by a new line which will allow it to be displayed easily in a Message() window. You may want to use something different and implement AGK’s GetStringToken() function to parse the data to your needs.
Notice that the function GetHighScores() is very similar to SendScore(). If you plan to use HTTP connections in your program, you’ll likely want to separate out the first 21 lines of those two functions into their own function. The GetHighScore() function is very basic and needs a bit of polish before it is ready to be used in a game, but it serves its purpose for this tutorial. Another item you may want to consider is what to do when a player might have more than 1 high score in the top ten. On old arcade games this would likely just allow them to have multiple entries on the list which might allow them to dominate the list. Instead you might want to first check the database for that user’s name and then only update their score if they beat their last high score. Another consideration to make is whether you want to censor user name entry. Since the list is public you probably don’t want a bunch of vulgar names showing up on the list. Ban builder is a very simple and easy to set up filter that will allow you to censor name input. It takes less than 5 minutes to set up. Also make sure to look over the word list before making it live because there are words like “hell” in there that might be a part of someone’s name like “shelly“.Although the easiest and safest way to maintain an online high score system is to use your own server, there is at least one free alternative that I know of: Google Docs. With Google Forms you can set up a form that will allow you to pass data to it via a post method which will store the data in a Google Spreadsheet. You can then turn around and query that spreadsheet via a URL. An example of querying by URL is given here. To send data to a Google Form via post you’ll need to create a form and then determine the form’s key and closely examine the source for it to to find the names of the post variables. The response from the query will be a json string which means that you’ll need to do a bit of parsing to get at the data you need. While Google docs is an alternative to having your own server, it is likely a bit more work to get it up and going. It may also be subject to abuse by users if they are able to gain your spreadsheet’s access key.
There are also some cheap servers out there that you can get. Digital Awakening on the forums brought One.com to my attention. Right now it appears that they’re offering one year free which includes a domain registration plus a small setup fee. Quite worth it if you’re just looking for a small server to handle things like scoreboards. Phaelax from the forums has also made a free online high score system available to all here.
