1. Chris Byerley
  2. Coronium Leaderboard Module

Wiki

Clone wiki

Coronium Leaderboard Module / Home

Coronium Leaderboard

The Coronium Leaderboard requires at least Beta 1.6 of the Coronium Cloud Server.

Click here to install a free Coronium Cloud Server, or visit this page to learn how to update your server.

Installing the Leaderboard Server Module

Log into your Coronium Cloud Server (1.6+) via SSH and enter the following command, or copy and paste:

sudo ./coronium install coronium_leaderboard

The server-side leaderboard module will be installed and ready to use.

Download the Leaderboard Client Package

Click here to download the Leaderboard demo and module files. Once you have the folder, uncompress the archive. Inside will be a client-side module and a simple Corona SDK demo project showing the leaderboard usage.

Running the Leaderboard Demo Project

Before you can run the Corona SDK project you must add the Coronium Cloud client module. Then pass the Coronium client instance to the Leaderboard Module, like so:

local coronium = require( "mod_coronium" )
local leaderboard = require( "mod_leaderboard" )

coronium:init( { appId = "app-id", apiKey = "api-key" } )

leaderboard.init( coronium )

Run the project. After either logging in or registering a user, click the "Score!" button to add random scores for the user. View the scores by clicking the "leaderboard" button. Register and login with different users to add more scores.


Leaderboard Client Module Methods and Usage

addUser( username, password [, callback ] )

Adds a User to the leaderboard. If the username exists, an error is returned.

username - The preferred username. (string, required)

password - The preferred password. (string, required)

callback - Optional callback function. Will return an event object with result or error key (function).

Example:

local function onAddUser( event )
  if not event.error then
    userId = event.result.objectId
  else
    --username is taken
  end
end
leaderboard.addUser( "Charles", "coronageek", onAddUser )

getUser( username, password [, callback ] )

Will get the User based on the username and password. If the user does not exists, an error will be returned.

username - The Users stored username. (string, required)

password - The Users stored password. (string, required)

callback - Optional callback function. Will return an event object with result or error key (function).

Example:

local function onGetUser( event )
  if not event.error then
    userId = event.result.objectId
    username = event.result.username
  else
    --User not found
  end
end
leaderboard.addUser( "Charles", "coronageek", onGetUser )

addScore( userId, score [, callback ] )

Adds the Users score to the leaderboard.

userId - The Users ID from getUser, addUser, or previously stored. (string, required)

score - The score value to save to the leaderboard. (integer, required)

callback - Optional callback function. Will return an event object with result or error key (function).

Example:

local function onAddScore( event )
  if not event.error then
    --User score added
  else
    --Error occurred
  end
end
leaderboard.addScore( "UserId", 2123456, onAddScore )

getScoresBy*() Methods

The following methods are shortcuts for the getScore() method (see below) and can take an additional options table with the keys: count, sort_order, sort_field, and limit_fields

Defaults are 10 scores, sorted from high to low with username, score, platform, and country field returned.

getScoresByUserId( userId, [ options ] [, callback ] )

--Get top 10 scores by userId, sorted lowest to highest
local function onGetScores( event )
  if not event.error then
    for _, entry in ipairs( event.result )
      print( entry.username, entry.score, entry.country, entry.platform )
    end
  end
end
leaderboard.getScoresByUserId( userId, { sort_order = "ASC" }, onGetScores )

getScoresByUsername( username, [ options ] [, callback ] )

--Get top 3 scores by username
local function onGetScores( event )
  if not event.error then
    for _, entry in ipairs( event.result )
      print( entry.username, entry.score, entry.country, entry.platform )
    end
  end
end
leaderboard.getScoresByUsername( username, { count = 3 }, onGetScores )

getScoresByPlatform( platform, [ options ] [, callback ] )

--Get top 10 scores by platform
local function onGetScores( event )
  if not event.error then
    for _, entry in ipairs( event.result )
      print( entry.username, entry.score, entry.country, entry.platform )
    end
  end
end
leaderboard.getScoresByPlatform( "ios", onGetScores )

getScoresByCountry( countryCode, [ options ] [, callback ] )

--Get top 10 scores by country code
local function onGetScores( event )
  if not event.error then
    for _, entry in ipairs( event.result )
      print( entry.username, entry.score, entry.country, entry.platform )
    end
  end
end
leaderboard.getScoresByCountry( "US", onGetScores )

getScoresGreater( scoreThreshold, [ options ] [, callback ] )

--Get top 10 scores greater than 1000
local function onGetScores( event )
  if not event.error then
    for _, entry in ipairs( event.result )
      print( entry.username, entry.score, entry.country, entry.platform )
    end
  end
end
leaderboard.getScoresGreater( 1000, onGetScores )

getScoresLess( scoreThreshold, [ options ] [, callback ] )

--Get top 10 scores less than 25000, username and country only
local function onGetScores( event )
  if not event.error then
    for _, entry in ipairs( event.result )
      print( entry.username )
    end
  end
end
leaderboard.getScoresLess( 2500, { limit_fields = { score = 0, platform = 0 }, onGetScores )

getScoresEqual( scoreThreshold, [ options ] [, callback ] )

--Get 1 score equal to 100000
local function onGetScores( event )
  if not event.error then
    for _, entry in ipairs( event.result )
      print( entry.username, entry.score, entry.country, entry.platform )
    end
  end
end
leaderboard.getScoresEqual( 100000, { count = 1 }, onGetScores )

getScores( [ options ] [, callback ] )

The getScores() method will retrieve the saved scores from the server. There are default settings which you are able to adjust. A call to getScores with no options performs as follows: Returns 10 scores from the user base with score and username keys, is sorted by score value, and sort order is "DESC" (highest to lowest).

You can pass an options table to the method with the following optional keys:

query - A table with search parameters. (table, optional)

Query supported keys include: score, userId, username, platform, country

count - The amount of scores to be returned. (integer, optional)

sort_field - The field to sort the return by. (string, optional)

sort_order - Sort order of the results: "ASC" or "DESC" (string, optional)

limit_fields - Choose fields to be included or not. (table, optional)

Example:

--Get top 10 scores, from highest to lowest
local function onGetScores( event )
  if not event.error then
    scores = event.result
    for _, entry in ipairs( scores )
      print( entry.username, entry.score )
    end
  else
    --Error occurred
  end
end
leaderboard.getScores( {}, onGetScores )

Other Examples:

--Get top 25 scores, from lowest to highest
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { count = 25, sort_order = "ASC" }, onGetScores )

--Get top 10 scores by country code
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { query = { country = "US" }, onGetScores )

--Get top 10 scores by platform
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { query = { platform = "ios" }, onGetScores )

--Get 10 scores, sort by username
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { sort_field = "username", sort_order = "ASC" }, onGetScores )

--Get top 3 scores for userId, highest to lowest
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { query = { userId = userId }, count = 3 }, onGetScores )

--Get 10 scores by username, from lowest to highest
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { query = { username = "Charles", sort_order = "ASC" }, onGetScores )

--Get top 10 scores, from highest to lowest, no username field
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { limit_field = { username = 0 } }, onGetScores )

--Get scores higher than 1000
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { query = { score = { ["$gt"] = 1000 } } }, onGetScores )

--Get 5 scores lower than or equal to 1000, lowest to highest
--onGetScores(event) callback is shown in first example.
leaderboard.getScores( { query = { score = { ["$lte"] = 1000 } }, count = 5 }, onGetScores )

Updated