Flash / ActionScript 3 API

Issues with this document? Submit a pull request to the website repository please.

Downloading the API

You can either download the zip or if you're a git user clone the repository.

Initializing the API

Before using the API you must initialize it with your public and private keys. Your keys need to be created in your database.

Playtomic.initialize(publickey:String, privatekey:String, apiurl:String);

Your apiurl will be in the format http://your-application-name.herokuapp.com/ or similar.

To import the packages in your game copy the 'com' folder to your project and in your class:

import com.playtomic.as3.*;

Examples

Each API has an extensive test library in the source code that demonstrates how to use every part in a variety of ways.

Newsletter subscription

Please note this requires additional setup you can read about here.

You can subscribe players to your newsletter mailinglist. By default this uses double-opt in so when a player registers for it they are sent an email and then confirm their intention.

You can collect additional data with your subscriptions but you must set it up first at MailChimp.

Playtomic.Newsletter.subscribe(options, callback);

Subscription options

Subscribing a player

var subscription:Object = {
	email: "[email protected]",
	firstname: "fred",
	lastname: "bloggs",
	fields: {
		FIRSTPLAYED: "2013-05-20",
		PLATFORM: "as3-web",
		GAMEVERSION: 1.08,
		RESOLUTION: "800x400"
	}
};

// note that these example MERGE fields must be created in your MailChimp
// dashboard, they do not exist by default.

Playtomic.Newsletters.subscribe(subscription, function(response:Response):void {

    if(response.success) {
    }
    else {
      // response failed because of response.errormessage
    }
});

Achievements

The Achievements API gives you two powerful ways to add social, cross-platform achievements to your game.

Achievements have to be configured in your database first in the 'achievements' collection with the structure:

{ achievement: "the name", achievementkey: "secret key used when awarding" }

You can include any additional properties you want and have them returned in your game such as image urls, descriptions etc.

Achievement structure

Saving achievements

To save an achievement you must know the achievement name and key and they must match what you configure in your database. This means if you want you can provide separate keys for each achievement so players can't easily cheat.

Playtomic.Achievements.save(achievement, callback);

A full example:

var achievement:Object = {
  achievement: "Punched Tass",
  achievementkey: "abcdefgh",
  playerid: "1",
  playername: "ben",
  fields: {
    difficulty: "easy"
  }
}

Playtomic.Achievements.save(achievement, function(response:Response):void {

  if(response.success) {
    // note that we could still have a failure errorcode here when the player
    // already has an achievement
  }
  else {
    // response failed because of response.errormessage
  }

})

Listing achievements

Achievement lists can be requested that include just the achievement information or also incorporate the player and friends.

Playtomic.Achievements.list(options, callback);

Listing options

Some examples:

// just the achievements
Playtomic.Achievements.list({}, function(achievements:Array, response:Response):void {
  if(response.success) {
    for(var i:int=0; i<achievements.length; i++) {
      trace(JSON.stringify(achievements[i]));
      // will output something { achievement: "Punched Tass" }
    }
  }
});

// my friends and i
var options:Object = {
  playerid: "1",
  friendslist: ["2", "3", "4"]
};

Playtomic.Achievements.list(options, function(achievements:Array, response:Response):void {
  if(response.success) {
    for(var i:int=0; i<achievements.length; i++) {
      trace(JSON.stringify(achievements[i]));
      //{
      //  achievement: "Punched Tass",
      //  player: {
      //    playerid: "1",
      //    playername: "ben",
      //    date: Date(),
      //    rdate: "Just now",
      //    fields: {
      //      difficulty: "easy"
      //    }
      //  },
      //  friends: [
      //    {
      //      // same as player object but for any friends with the achievement
      //    }
      //  ]
      //}
    }
  }
});

Activity stream

You can also get achievements represented as an activity stream of each award.

Playtomic.Achievements.stream(options, callback);

Streaming options

Award data

When you 'stream' the messages are returned in this format. This is the same format used when you include player or friend information in 'list'.

Example streams

// show all the hard achievements by my friends and i as a stream
var options:Object = {
  playerid: "1",
  friendslist: ["2", "3", "4", "5"],
  group: true,
  filters: {
    difficulty: "hard"
  }
}

Playtomic.Achievements.stream(options, function(achievements:Array, numachievements:int, response:Response):void {

  if(response.success) {

        trace(achievements.length + " achievements returned out of " + numachievements);

        for(var i=0; i<achievements.length; i++) {
            console.log(JSON.stringify(achievements[i]));
            // {
            //  playerid: "1",
            //  playername: "ben",
            //  date: Date(),
            //  rdate: "Just now",
            //  fields: {
            //     difficulty: "hard" }
            //  },
            //  awarded: {
            //    achievement: "Punched tass"
            //  }
            // }
        }
  } else {
    // request failed because of response.errormessage
  }
});

Leaderboards

The Leaderboards API gives you very flexible high and low score leaderboards. They can be created in your game dynamically or set up in the edit leaderboards page.

Score structure

Submitting scores

Score submission is handled by:

Leaderboards.save(score:Object, callback:Function=null);

function submitScore(e:MouseEvent):void
{
	// basic score
    var score:Object = {
		playername: "ben",
		points: 173000,
		table: "highscores",
		allowduplicates: true
	};

    Leaderboards.save(score, submitComplete);

    // another score
    var score2:Object = {
		playername: "ben",
		points: 173000,
		table: "highscores",
		allowduplicates: true,
		source: root.loaderInfo.loaderURL,
		fields: {
			character: "barbarian",
			level: 7,
			kills: 18
		}
	};

    Leaderboards.save(score2, submitComplete);
}

function submitComplete(response:Object):void
{
    if(response.success)
    {
        trace("Score saved!");
    }
    else
    {
        // submission failed because of response.errorMessage with response.errorcode
    }
}

Showing scores

Scores are loaded via a simple method that returns an array of scores to your function where you can display the data in your leaderboard.

Leaderboards.list(options:Object, callback:Function);

function showScores(e:MouseEvent):void
{
	// table options
	var table:Object = {
		table: "highscores",
		page: 1,
		perpage: 10,
		highest: true
	};

    Leaderboards.list(table, listComplete);
}

function listComplete(scores:Array, numscores:int, response:Object):void
{
    if(response.success)
    {
        trace(scores.length + " scores returned out of " + numscores);

        for(var i:int=0; i<scores.length; i++)
        {
            var score:Object = scores[i];
            trace(" - " + score.name + " got " + score.points + " on " + score.sdate);

            // including custom data?  score.fields.property
        }
    }
    else
    {
        // score listing failed because of response.errorMessage with response.errorcode
    }
}

Save and list

You can submit scores and at the same time return the leaderboard page that that score is on. This combines the Save and List approaches from above:

Leaderboards.saveAndList(score:Object, callback:Function)

Note: If you pass a 'playerid' to be saved you can exclude it from filtering the returned scores via the additional option, excludeplayerid = true

You don't specify a 'page', you specify the 'perpage' (default 20) and it will automatically decide which page to return based on the submitted score's rank. If you submit the 1187th best score at 30 per page then it will show you page 39, scores #1170 - #1200.

Ranks are returned so you are not viewing the top N scores you are viewing the top N scores from rank X onwards.

Level sharing

The level sharing API provides a way to store and retrieve user-generated content for your game. It can operate anonymously or authenticated via any 3rd party service you're already using.

Level structure

Saving and listing levels uses this class to represent a level.

Saving levels

PlayerLevels.save(level:Object, callback:Function=null);

Example saving level:

function saveLevel(e:MouseEvent):void
{
    var level:Object = {
		name: "My level",
		data: "obj1=cannon&obj1x=120&obj1y=180",
		playername: "Ben"
	}

    PlayerLevels.save(level, saveComplete);
}

function saveComplete(level:Object, response:Object):void
{
    if(response.success)
    {
        trace("Level saved successfully, the level id is " + level.levelid);
    }
    else
    {
        // failed because of response.errorMessage with response.errorcode
    }
}

Rating levels

Levels can be rated 1 - 10 by players. Rating can be done anonymously with some protection against repeat voting, or bound to playerids if you specify them.

PlayerLevels.rate(levelid:String, rating:int, callback:Function=null);

Example rating level:

function rate(e:MouseEvent):void
{
    PlayerLevels.rate(level.levelid, 8, rateComplete);
}

function rateComplete(response:Object):void
{
    if(response.success)
    {
        trace("Rating complete"");
    }
    else
    {
        // Rating failed because of response.errorMessage with response.errorcode
    }
}

Listing levels

Listing levels can be done by popular or newest, with optional filtering by date ranges and/or custom fields.

PlayerLevels.list(options:Object, callback:Function);

Listing options

An example listing levels:

function list(e:MouseEvent):void
{
	var listoptions:Object = {
		mode: "newest",
		data: false,
		perpage: 30,
		filters: {
			difficulty: "hard"
		}
	};

    PlayerLevels.list(listoptions, listLoaded);
}

function listLoaded(levels:Array, numlevels:int, response:Object):void
{
    if(response.success)
    {
        for(var i:int=0; i<levels.length; i++)
        {
            trace(" - " + levels[i].levelid + ": " + levels[i].name);
        }
    }
    else
    {
        // Level list failed to load because of response.errorMessage with response.errorcode
    }
}

Loading levels

If you do not include the data when you load lists of levels then you can request it seperately.

PlayerLevels.load(levelid:String, callback:Function)

An example loading a single level:

function load(e:MouseEvent):void
{
    PlayerLevels.load(level.levelid, loadComplete);
}

function loadComplete(level:Object, response:Object):void
{
    if(response.success)
    {
        trace("Level has been loaded, now you can begin playing it");
    }
    else
    {
        // level failed to load because of response.errorMessage with response.errorcode
    }
}

GameVars

GameVars let you change the value of key variables in your game any time you want.

Setting them up in your database

In your MongoHQ dashboard add a new entry to the "gamevars" collection.

{
	name: "basehitpoints",
	value: 800
}

Loading

They are loaded via:

GameVars.load(callback:Function);

You can load variables individually, for instance if you are caching the GameVars you can check a 'version' GameVar to decide whether to reload the full collection.

GameVars.loadSingle("name", callback);

The callback parameter is your function that receives an object that has properties matching the variables you have configured in your database. The callback is the same for all or single GameVars.

// our variables with default, original values
var basehitpoints:int = 100;
var basegold:int = 50;

function InitialiseGame():void
{
    // load GameVars
    GameVars.load(gameVarsLoaded);
    // or GameVars.loadSingle("basehitpoints", gameVarsLoaded);

    // carry on initializing your game
}

function gameVarsLoaded(vars:Object, response:Object):void
{
    if(response.success)
    {
        // sync the in-game variables
        basehitpoints = vars.basehitpoints;
        basegold = vars.basegold;
    }
    else
    {
        // request failed because of response.errorMessage with response.errorcode
    }
}