If you are using the GameMaker: Studio HTML5 module, you know that you will need to find a host server for your games so that people can then play them online. This can be done by simply using a public Dropbox folder or by uploading to your own server and hosting your game on your own web pages, but another option is to upload the game to a games portal. In the case of this example, we are going to show you how to upload to Kongregate, as well as show you how to set up their API so that you can communicate with the site (sending hi-scores for example) which gets you a better revenue share from their advertising.
First Thing's First
Before going any further you will need to have done a few things... Obviously you will need to have a game that you want to upload (this is the hardest part!), but you will also need to have the following resources:
- The Kongregate_shell
- The KongregateAPI GMEZ (A Javascript extension for HTML5)
Once you have set up your account, take a moment to look at the options available and make sure that all the details are correct. If you want to receive any payments from advertising etc... then you should pay particular attention to the Accounts section, as Kongregate will withhold payments until you have properly filled out the necessary tax forms.
NOTE: The GMEZ linked above was created by Giga970, a member of the GameMaker Community. You can find his original topic here: http://gmc.yoyogames.com/index.php?showtopic=573816
With your account created and ready, let's move on now to the API itself and see how to install it and get it working in your game...
The Kongregate API
The Kongregate API extension will need to be added to your game now, so open GameMaker: Studio and load it up. From the resource tree you need to right-click on the "Extensions" folder, and select the option to "Import Extension", then browse to the location where you stored the GMEZ for the Kongregate API. This will install the extension in your game and give you access to the following functions:
kongInit() - Start the API
kongGetAPI() - Check if the API is working and connected to the Kongregate servers
kongIsGuest() - Returns true if it's a Guest user playing the game, false if it's a registered user, and -1 if you aren't on Kongregate
kongShowRegistrationBox() - If the user is a guest, then you can show the registration window to request that they register to benefit from the API services
kongGetUserID() - Get the unique User ID of a registered user
kongGetUsername() - Get the User Name (display name) of the current player
kongSubmitStat() - Submit a statistic (more on this later)
kongChatDisplayMessage(message, username) - Show a message in the user chat
kongChatClearMessages(name, description, size [between 0 and 1]) - Clear the chat of messages
kongChatShowTab() - Enable/disable the chat tab
kongChatCloseTab() - Close the chat tab
You can get additional information on these functions from the Kongregate pages that deal with the Client Functions, although in your game you probably won't actually need to use more than a handful of them, and if you want some further information on how the API in general works, you can check out the Help pages on Kongregate that deal with the JavaScript Client.
It is important to note that these functions will not work without it being connected to the Kongregate server, therefore you should always use the kongGetAPI() function as a wrapper for all other function calls (as you will see in the examples below). Also note that the kongInit() function DOES NOT NEED TO BE CALLED EVER as the extension will take care fo that part automatically.
Using Statistics
The Kongregate API sends "Statistics" to the server (a statistic is simply a time or a score or some other numeric value), and these statistics are then shown in a separate tab of the chat-box that all games have on the site. There are a number of different statistic types, but the actual code for using them in your game is the same for all, as Kongregate will interpret and display the values according to the rules that you set when you added your game to the site (more on this later).
So, with your game finished and the extension installed into it, we need to have it connect to the Kongregate servers before we can actually post anything. This requires the following code, which should be placed at the very start of your game, before anything else is run, and it should also be in an event or instance where it will only ever be run once (the Game Start event of the first instance in the first room of your game, for example):
if kongGetAPI() != -1
{
if kongIsGuest()
{
kongShowRegistrationBox();
}
}
This code checks the API to see if the user is connected to the Kongregate servers, and if it is it then checks the player status. If the user is a Guest (ie: they haven't signed in to a Kongregate account) the code then shows the user a registration box and invites them to sign in.
NOTE: Because we are wrapping the function to check the API, you can distribute your games to other sites without worrying about compatibility.
You can now add some code to send your statistic to the Kongregate servers. The code is very similar to that shown above and requires almost nothing from you to actually use, as the Kongregate API takes care of everything for you. Where you add this code is up to you, but obviously it should be in an object where it will only be run once (as you don't want to send the same statistic multiple times), like a Game Over screen:
if kongGetAPI() != -1
{
kongSubmitStat("Stat_Name", VALUE);
}
Again, we wrap the function being used with a server check, and then if all is okay we send our statistic. The arguments for the function are:
"stat_name" - This is a string and is the name of your statistics table as defined when you added your game (more on this later)
VALUE - A real number that represents the data being sent (a score or a time, for example)
The statistic name can be anything you want, but make it memorable and descriptive and note it down somewhere as you will need it later when you upload your game to the Kongregate server.
Believe it or not, that's all you need to do in your game! With those two short code blocks, your game is integrated with the Kongregate API and will now send a statistic which will be displayed to the user in the Chat Box of the website.
NOTE: You can find out more about Statistics and what is acceptable from the Kongrgate Developer pages here.
Uploading To Kongregate
To actually upload your final game to Kongregate for testing (and publishing), you will need two things:
- The Kongregate shell HTML
- A *.zip of all your game files
So open the Kongregate shell zip that you downloaded (the link is at the top of this tutorial) and extract the kongregate_shell.html file to a safe location, noting where it is saved as we then need to export our GameMaker: Studio files there too.
Next, open your game in GameMaker: Studio and click the Create Executable button (or go to File >> Create Executable), making sure that you have picked the HTML5 export option. In the file explorer, point to where you previously saved the Kongregate shell file, and save the final version of your game there. This will create a folder with all your game files, a favicon image and an index.html file. You now need to zip those three files together, as it's the zip that will be uploaded as a whole, and not the individual files.
NOTE: Make sure that you don't zip the kongregateshell.html file along with the game! You should only have a zip file with your game and the Kongregate shell file, as those aare the only two files that you will upload.
You are not quite ready to upload your game though, as you will have to modify the kongregate_shell.html file to suit your game. This is a simple process however, and requires no prior knowledge of HTML.
Editing The Kongregate Shell File
Open the kongregate_shell.html file in a text editor and find the following line:
<div id="contentdiv" style="top:0px; left:0px; width:700px; height:500px; borders:none;">
This sets the width and height of the window for your game on the Kongregate website, and you should set it to about 20 pixels more than your designed game size. So, if you have a 640x480 game, you would set width:660px and height:500px. We add these "buffer" pixels to the size to prevent Kongregate adding scroll bars to the game window, which usually happens when you use the exact width and height of your game canvas.
If your game file was created using the default GameMaker: Studio values then you need do nothing else, however if you have changed the Global Game Settings to name your "index.html" file as something else (or done it in an external editor) then you also need to change the following line:
kongregateAPI.embedFrame("<GameName>.html");
There you simply change <GameName> to the name of your "index" html for running the game.
You are now ready to upload and test your game with it's new "statistics" feature!
Uploading Your Game
Uploading your game couldn't be simpler. You need to be signed in to Kongregate and then go to the Upload Game page. There you will be requested to give details about your game, such as a description, its controls, etc... so, fill that out and click the "Continue" button. You can always come back and change it later, so don't worry too much about what you write as the game won't be published until you say so.
NOTE: You can leave the "API Callback URL" blank.
The next page is where you supply the game files themselves, as well as any promotional graphics like the icon and screenshots. Here you should be uploading the edited kongregate_shell.html file as the Game File (which is the first option on the form), and then check "Use additional files". You can now supply Kongregate with the ZIP file that we made earlier. The site will automatically extract it's contents to where they store the shell file.
You should continue to fill out the rest of the form details, adding images and checking the licence agreements boxes that are appropriate. However, don't click the Upload button just yet! We have one final task to do and that's add our statistic...
Adding A Statistic
At the bottom of the upload page there is a section for statistics and we need to prepare that to accept the scores or times that our game is going to send, so click "Add a statistic" and fill out the information. It's very important that the section "Statistic's Name" matches that which you added into your game code otherwise the API won't work!
You can give the statistic a description if you want, but this is optional and won't be public (it's more a reminder for you than for the users), and then set the type of statistic that is to be displayed before checking the "Display In Leaderboards" option and clicking "Save".
Summary
If you have followed this tutorial correctly, you can now click the "Upload" button and get the Preview screen for your game. You should play it now and make sure that the shell is correctly positioned and that everything works, although it's worth noting that it can take a few minutes for the system to actually start to show high scores, and it will require a refresh of your browser to actually be able to see them.
It is worth noting that since all your sending is a real number to the Kongregate servers, and that they provide multiple ways in which you can display this, then you are not limited to just high scores, but can send times, or create achievements and other things. The system is fairly flexible and you are not limited to just one statistic for your game... so you can get creative and use them for many things!