Leaderboards

Overview

Everyone is probably familiar with how leaderboards generally work so not much description is really needed in how they will function. The general idea is that a game will be able to have as many leaderboards as they need and all of it will be managed through API's and Libraries that we will provide to developers.

Defining Leaderboards

Leaderboards will be defined through a json structure and the API's will handle automatically creating leaderboards that do not exist. They will be created both locally and in the cloud (if enabled by the developer).

Score Submission

When scores are submitted they will automatically go to both the local and online leaderboards (if an internet connection is available). If the user is not connected to the internet, that score will not ever be submitted online to avoid users manually altering scores when offline. Scores will be attached to the logged in user's account and some meta information like region will be automatically attached.

Leaderboard Schema

{
  title: String
  slug: String
  online_enabled: Boolean
  columns: [ColumnSchema]
  limit: Number
}

Column Schema

The point of providing a separate schema for columns is to make them as flexible as possible for developers. Everything is optional except for the title, but without providing at least a type sorting will not be possible.

{
  title: String
  sortable: Boolean
  type(1): String
  formatter(2): Function
}

1. Types will be predefined and provided in the libraries. The purpose of specifying a type is to make sorting easier on the API. Types will be: String, Number

2. The point of a formatter is to alter output. Some of these could be provided in the Libraries (such as adding comma's to numbers) but these can also be custom functions the developers create for special fields.

Example

For clarification purposes, here is an example leaderboard definition based on Twitter stats.

{
  title: 'Twitter Leaders',
  slug: 'twitter_leaders',
  online_enabled: true,
  limit: 100,
  columns: [
    {
      title: 'Username',
      type: Leaderboards.ColumnTypes.String,
      sortable: true
    },
    {
      title: 'Tweets',
      type: Leaderboards.ColumnTypes.Number,
      sortable: true,
      formatter: Leaderboards.Formatters.NumberFormat
    },
    {
      title: 'Followers',
      type: Leaderboards.ColumnTypes.Number,
      sortable: true,
      formatter: Leaderboards.Formatters.NumberFormat
    },
    {
      title: 'Following',
      type: Leaderboards.ColumnTypes.Number,
      sortable: true,
      formatter: Leaderboards.Formatters.NumberFormat
    },
    {
      title: 'Latest Tweet',
      type: Leaderboards.ColumnTypes.Date,
      sortable: false,
      formatter: function(date){
        var months = custom_months || ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
            ,days = custom_days || ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
        ;

        return days[date.getDay()] + ', ' + months[date.getMonth()] + ' ' + date.getDate() + ', ' + date.getYear();
      }
    }
  ]
}

If a developer didn't want to take advantage of the formatters or smart sorting (for fields like dates) then the columns definition could be simplified down to:

columns: ['Username', 'Tweets', 'Followers', 'Following', 'Latest Tweet'] 

A-Z style sorting could still be automatically applied across all columns with this, but all formatting would need done by the developer when they submit scores.