AGK Tutorial - Online High Score System

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.

Click here for PHP Script #1

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".

Click here for AGK Script #1

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:

Click here for PHP Script #2

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.

Click here for AGK Script #2

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.

The Making of a Word Game

Originally published in the TGC Newsletter March 2014

There are many grid-based word games on the market at present, with other popular titles such as Words With Friends,Word Feud, Wordz Up and many more. Sean Mann of Napland Games gives us an insight on the makings of such an application.

Word lists

All word games need a qualified word list. There are many free lists out there and the best public domain list is ENABLE (Enhanced North American Benchmark LExicon) available from the Google Project site. 

This list contains some 170,000 words and is widely accepted as one of the best. It did need some minor modifications to be ready for use in a game. For example, we removed all single letter words since you have to play at least 2 letters and we removed all words longer than 15 letters since the board is 15x15 tiles. We also removed any words which have a purely vulgar meaning as we felt that they were inappropriate for a game designed for all ages. We also added all of the commonly accepted 2-letter words from other games. 

The list also had to go through some modification so that it could be accessed in an optimal way. A word list of 170,000 words can be a bit cumbersome to search. If the list was stored on the device it would be very slow. We stored the list in our MySQL database on our server which is very fast for searches, but still the list was split into multiple small tables so that search time would never take long (indeed it takes 0.0019 seconds to search our largest list). The way we split up the lists is straight-forward. There is a list for every letter and word length combination (i.e. all words beginning with A and 2 letters long, A and 3 letters, A and 4 letters, etc.). To accomplish this I created a simple program that parsed the big word list and simply saved it into smaller text files. It created quite a few text files (about 26 * 14) but they were easy to mass import to a MySQL database.

Protecting the data One thing to look out for when importing is that text files have characters for new lines and these can get stored in your database, which potentially can cause searching issues. Another major advantage of having the list stored on a server is we can add and remove words on demand. We've already had a number of users request additional words and have added some of them to our dictionary immediately. Leveraging an online database to control elements in your game is very useful. We can also send out news messages to our players from our online database and lock out obsolete versions of the game if we ever need to.

Since our word lists are stored in our protected database online, we didn't have to worry about users potentially modifying the files. If you plan to store your files within the app you should consider your own method of encryption and validation to ensure that users haven't modified the files. One of my favorite methods is simply storing a key in an array for your program and using that key along with XOR to encrypt/decrypt the bytes in a data file.

This method made the basics of verifying a word to our dictionary very quick and simple. The more difficult part was verifying the words on the board since you have to take into consideration the various possible crosswords. The idea behind the algorithm for doing this is quite simple, but implementation was a bit tricky. Simply determine the upper-most, left-most letter that has been placed on the board and look left, right, up, and down for other unplayed letters or played letters. 

I hope this gives a brief insight into Word Games and inspires you to think about making your own in the near future.

Preparing for Game 2 - Learning PHP and MySQL

In order for my next game to be able to save user data and transfer data for turns and chat I'll need to set up a server and learn how to get data on and off it vial simple HTTP commands. I began my adventure today and will chronicle what I've done so others can easily set up a test system. I feel that what I'm trying to do is so basic (send data to be written to a database and retrieve that data)

First thing's first, set up Apache Server. This was pretty easy: download the ZIP for Apache 2.0, extract the files to the directory of your choice (I chose c:/Apache), make a few minor changes to its config file, and then just open up some ports on your router and unblock them from your firewall. That's it! I had this part of the project going before noon today and was pretty happy with the information I was able to find.

There are a ton of guides out there on how to set up Apache server (2.0 Win32) in Windows, so I'm not going into great detail here. One thing I should mention is that you should be careful with security. If you're just testing an app then shut down your server when not testing. Once the server is installed you should see an icon in your taskbar's icon try (tiny up arrow over by the clock). Left clicking on this will allow you to quickly start/stop/restart the server.

After you've downloaded the ZIP for Apache server 2.0 for win32 x86 and extract it to the directory of your choice you can start meddling with the configuration file. It's called httpd.conf and located in the Apache/conf folder. Simply open it up with Notepad and make the following changes:

• Find this: ServerName localhost:80 and replace localhost with whatever name you want. This will be the name you type into your browser on the server computer to check things as you set them up. I left mine alone.
• You also might want to change this ServerAdmin admin@localdomain to whatever email address you might want to use. Again I left this alone as my server won't need email functionality.
• If you don't want to use the default directory for you website's files then change the DocumentRoot "C:/Apache/Apache2/htdocs" to the directory of your choice.
• Change the line DirectoryIndex index.html to also include index.php - we'll use that later after we set up PHP.
• Next we'll want to set up a password. This is done by going to the Apache/bin directory then hold shit and right click in a blank area of the Windows Explorer window and "Open Command Window Here" for a command prompt. Type htpasswd -c "c:/Apache/Apache2/pw.txt" yourName. Replace the directory with your actual directory and replace yourName with whatever name you want for the admin account. You'll then be prompted to create a password and you're done.
• Now we need to create a script to manage the login. Create a file in Notepad and name it .htaccess then enter the following:

AuthType Basic
AuthName "This is a private area, please log in" 

AuthUserFile "c:/Apache/Apache2/pw.txt"
AuthGroupFile /dev/null 

<Limit GET POST PUT>
require valid-user
</Limit>

• Restart Apache server and then open a browser and enter localhost if all went well you should be prompted to enter your username and password. If you didn't create any index.html or index.php yet then you won't see anything else, so go ahead and create that if you want.
• Now you're going to want to set this up so that you can access it via the web so open up your router's settings and port forward port 80 for the IP address of your server. Then set your server's IP to be in the DMZ (usually under WAN setup).  You may also want to make sure the computer you're using as a server has a fixed IP on the network and the address has been reserved on the router. 
• Finally you'll want to open up your firewall and add an exception for two-way traffic on port 80. Now you should be able to go to any computer on the internet and login to see your website.

That's all it takes. Many other guides I see have a bit more detail, but they seem like they expect you don't know much about changing your router settings or how to navigate Windows Explorer to find files. I hope that this guide is a bit more to-the-point and helps the slightly advanced user get up and running quickly. If you're stuck on any point you might want to search Google for a more detailed guide. For many I hope this will get you up and running in a jiffy.

Next up is setting up PHP and then MySQL. Thanks for reading, see you next time!