Kongregate Integration

Monkey Archive Forums/Monkey Tutorials/Kongregate Integration

Foppy

(Posted 2011) [#1]

This is a tutorial about adding Kongregate high scores or other statistics to a Monkey game published on Kongregate. Kongregate (www.kongregate.com) is a site that lets developers upload Flash games. The developers then receive a percentage of advertising earnings. Another interesting aspect of the site is the possibility to create high score lists that appear next to your game. For this to work the game has to communicate with the Kongregate API, sending statistics to the server that have been defined previously on their website, so they know what to expect from your game.

Based on advise from Adam Redwood and slenkar and on the information and code on the Kongregate website itself, I have taken these steps:

Step 1. Create a text file called "kongregate.as" in your project folder. This will be the Actionscript code used to talk to the Kongregate API. Put this in the file:

(Most of this is from this page on the Kongregate website: http://developers.kongregate.com/docs/api-overview/as3-api )

// kongregate.as

// Kongregate API reference
var kongregate:*;

function kongregateInit():void
{
	// Pull the API path from the FlashVars
	var paramObj:Object = LoaderInfo(game.root.loaderInfo).parameters;

	// The API path. The "shadow" API will load if testing locally. 
	var apiPath:String = paramObj.kongregate_api_path || "http://www.kongregate.com/flash/API_AS3_Local.swf";

	// Allow the API access to this SWF
	Security.allowDomain(apiPath);

	// Load the API
	var request:URLRequest = new URLRequest(apiPath);
	var loader:Loader = new Loader();
	loader.contentLoaderInfo.addEventListener(Event.COMPLETE, kongregateLoadComplete);
	loader.load(request);
	game.addChild(loader);
}

// This function is called when loading is complete
function kongregateLoadComplete(event:Event):void
{
    // Save Kongregate API reference
    kongregate = event.target.content;

    // Connect to the back-end
    kongregate.services.connect();
}

function kongregateSubmitScore(pScore:int):void
{
	if (kongregate)
	{
		kongregate.stats.submit("score",pScore);
	}
}

This contains a function kongregateInit() for making contact with the Kongregate server. It makes reference to the "game" variable that is actually created by Monkey when it creates the Actionscript code for your game. The above code will be imported into your game so it has access to the game object.

It also contains a function kongregateSubmitScore(). This I have added myself and it is used to send a statistic to the server. You could add more functions like this for sending other information. You can also use functions in the Kongregate API to request information such as the player's name (the username with which they are logged in to the Kongregate website) but I have so far only used the kongregate.stats.submit function, in this case for submitting high scores.

Sending statistics using the submit function is explained here:

http://developers.kongregate.com/docs/client/submit

On the right you can find a list of other available functions (Client Function List).

Step 2. Create a file "kongregate.monkey". This will be the Monkey "front end" to the Actionscript code. It will enable Monkey to make use of the Actionscript code we created above. Put this in the file:

// kongregate.monkey

Import "kongregate.as"

Extern
	
Function kongregateInit:Void()
Function kongregateSubmitScore:Void(pScore:Int)

As you can see, it only contains references to function that have been defined externally in the imported Actionscript code. Now these functions can be used in your Monkey game if you import kongregate.monkey into the game.

Step 3. Import kongregate.monkey into your game where it is used.

I did this by adding the following code at the top of my game's main Monkey file, because both initializing the connection and sending the scores is done from my main file. If you use the functions elsewhere, of course the Import command should be at those other locations too.

' added at top of main game file:

#if TARGET="flash"
Import includes.kongregate
#end

This will only be incorporated into the game by Monkey if the selected target is Flash. Now I can still create HTML5 versions without having to comment out this code every time. The next step is to actually use the available functions in your game: first by connecting to the Kongregate server, then by using that connection to send scores.

Step 4. Connect to the Kongregate server. This is done in function kongregateInit(). Add this code to your game's OnCreate method:

' added to game's OnCreate method:

#if TARGET="flash"
kongregateInit()
#end

You could in principle connect at the moment you want to send scores, but it is advisable to connect once and at the start of the game. This way, if the connection is not working for some reason, you know right away.

Step 5. Send scores (or other data), for example at the end of your game. In my game Monkey Pixels I send the score when the player gets hit, or when the player ends the game by pressing Escape. At those spots in the code I have added these calls to the score submitting function:

' added where I want to send scores:
 
#if TARGET="flash"
kongregateSubmitScore(myScore)
#end

Step 6. Place your game on Kongregate. It can still remain in preview mode while you continue getting the statistics to work (because they will already work even if the game is not published yet).

Step 7. In order for the scores to appear on the Kongregate website, the statistics you are sending have to be defined there. In function kongregateSubmitScore() I am sending a statistic called "score", so I had to define that first. How to do that is explained here:

http://developers.kongregate.com/docs/single-player/stats (Creating your statistics)

Now you can try to play the game and see if it works. It can take some time (seconds, minutes) for the statistics to appear. They should replace the "More games" tab on the right. I noticed that a browser refresh may be necessary to make (new) statistics appear, for instance if you set a better score it will not be updated automatically, I had to reload the page.

Step 8. Debugging, if necessary. In the Actionscript code I have imported ExternalInterface. This can be used to log debug messages to FireBug, an add-on for Firefox. This is for example explained here:

http://www.nickbloor.co.uk/2011/02/writing-to-the-firebug-console-from-flash-and-php/

I suppose you can leave out the ExternalInterface import if it is not used.

Kongregate also gives you the option to approach your game in debug mode. The Kongregate code will then create debug messages, also written to the FireBug console. This can be done by adding the parameter ?debug_level=4 after the url to your game (while having the FireBug console open).

slenkar

(Posted 2011) [#2]

thanks!