Quarter Spiral Flash SDK

The easy way to integrate your game with the Quarter Spiral universe.

Setup

Add the Quarter Spiral SDK.swc file to the build path of your app

First steps

To start using our SDK you first need to obtain an instance of the SDK. You can get one easily like this:

	import com.quarterspiral.sdk.*;
	…
	var qsSdk:Sdk = SdkFactory.getInstance(Starling.current.nativeStage.root.loaderInfo);

In the code above we are using the Starling game framework as an example. It doesn't matter if you use a framework at all or which one you use. Just make sure to pass in the LoaderInfo object to the getInstance method of the SdkFactory which comes with the flash params of your project. Using your main stage has proven to be a good start.

Information about a player

To get information about the current player the SDK provides you with the playerInformation property that returns a PlayerInformation object that gives you insight on the player's name, email address and internal id within the Quarter Spiral universe.

	trace(qsSdk.playerInformation.name);
	trace(qsSdk.playerInformation.email);
	trace(qsSdk.playerInformation.uuid);

As this information is going to be retrieved asynchronously, the playerInformation can return null as long as the retrieval process hat not yet been completed. You can either check if the retrieval is done already like this:

	if (qsSdk.playerInformationReady) {
		trace(qsSdk.playerInformation.name);
	}

or you can even be notified whenever the information becomes available

	qsSdk.onPlayerInformationReady(function(playerInformation:PlayerInformation):void {
		trace(playerInformation.name);
	});

Please note, that qsSdk.playerInformationReady will not trigger the retrieval process. Make sure that you call qsSdk.playerInformation once before to trigger the process.

Manage data for players

Reading data

Quarter Spiral allows you to store arbitrary data for any of your players. That data comes in form of an ordinary Dictionary and can be read like this:

	trace(qsSdk.playerData['highScore']);

As this information is going to be retrieved asynchronously, the playerData can return null as long as the retrieval process hat not yet been completed. You can either check if the retrieval is done already like this:

	if (qsSdk.playerDataReady) {
		trace(qsSdk.playerData['highScore']);
	}

or you can even be notified whenever the data becomes available

	qsSdk.onPlayerDataReady(function(playerData:Dictionary):void {
		trace(playerData['highScore']);
	});

Please note, that qsSdk.playerDataReady will not trigger the retrieval process. Make sure that you call qsSdk.playerData once before to trigger the process.

Writing data

Writing data back to Quarter Spiral can be done like this:

	var data:Dictionary = new Dictionary();
	data['highScore'] = 12345;
	data['lastLevel'] = "Tower of Happiness";
	qsSdk.setPlayerData(data);

If you only want to write a single attribute of the data without touching the rest you can do that like this:

	qsSdk.setPlayerData("highScore", 67890);

Please note, that all writing operations will be queued up until the SDK becomes ready. When you try to carry out writing operations while an older one is still in progress, that leads to queuing as well.

For more fine grained control over the result of all writing operations a SetPlayerDataResponse is returned from the setPlayerData method. This response can be used to determine if an operation has already been completed and if it was successful or not.

Testing

To test your game with the Quarter Spiral SDK you can activate a test mode on the SdkFactory. As a result of that you will get an instance of DomSdk as your SDK which uses a MockDomSdkDriver internally. Use it like this:

	SdkFactory.testing = true;
	var sdk:DomSdk = DomSdk(SdkFactory.getInstance("http://canvas.example.com"));
	sdk.driver.playerInformation = new PlayerInformation("1111-2222-3333", "Peter", "[email protected]");
	//sdk.playerInformation will now return the information we set above

You have to set SdkFactory.testing before any call to SdkFactory.getinstance. Also please note that the MockDomSdkDriver is as dumb as possible. You have to manage all the state yourself.