---
title: "Leaderboard"
disqus: hackmd
tags: 'ctrl'
---
## Chapter 5 Leaderboard Processions
### 5-1 Knowing the Leaderboard
A leaderboard records players’ game scores and produces score rankings, and the score rankings Cloud provides are daily ranking, weekly ranking, monthly ranking, and total ranking.
The scores on the daily ranking are reset as zero every midnight, in UTC time. The weekly and monthly rankings are respectively reset as zero every Sunday and 1st midnight, while the total ranking is never reset.
Except for the score rankings, Cloud also provides a service that lets players record their personal scores. Developers can record or look up for players’ scores in the game program according to the game’s needs.
### 5-2 Leaderboard Management
Before using Cloud’s leaderboard services, developers have to create a new leaderboard in the developers’ backstage and obtain its GUID (called LGUID). Then, deal with the leaderboards in the game with the static functions in the CloudScore class.
Here is the form for creating a leaderboard:
Descriptions on the columns:
1. name
Leaderboard’s name.
2. note
Notes for the leaderboard, where developers can explain the use of the leaderboard in detail.
3. types of data
There are two types, which are “score” and “counter”:
“Score” is a normal score number, which the score can be written in freely, and “counter” is added with one every time a score is written in.
4. deadline for the ranking
The options are “no limit,” “daily ranking,” “weekly ranking,” and “monthly ranking.”
5. ranking’s type
“ascending order”: The first one has the lowest score and the others are in ascending order. “descending order”: The first one has the highest score and the others are in descending order.
6. overwrite status
Every time a score is handed in, there are three options for whether to overwrite the existing scores:
* Not to overwrite (Insert): Add a new score record directly and the old one is kept and ranked, so the player may have more than one score data.
* Overwrite the better one (Write Better): Write the handed score in and overwrite the old one only when the new one is higher, so the same player has only one score in the ranking.
* Overwrite mandatorily (Overwrite): Every time a score is handed in, the old one gets deleted, so the player only has one score in the ranking.
7. rule elf
A rule elf integrates the leaderboards and the items. After setting conditions for giving out items automatically, the systems will give out items automatically to the players who meet the standard according to the conditions. For detailed operation, please go to the next session.
After filling the form, click “create a leaderboard” in the lower right and the data of the created leaderboard will appear in the list:
### 5-3 Giving out Items Automatically
Below the leaderboard management form, there are the columns about rule setting.
1. format setting
The two options are “score” and “ranking,” which means items are given out to those who meet the condition of score or ranking.
2. deadline for ranking
There are four options, which are also “no limit,” “daily ranking,” “weekly ranking,” and “monthly ranking.” However, the deadline for ranking has to be selected in the leaderboard to be selected here
3. conditions
* equal: When the score equals the designated value.
* between: When the score is in between the two designated values, and there are four types according to whether there is an equal:
a≦score≦b a≦score＜b a＜score≦b a＜score＜b
* smaller than: When the score is smaller than the designated value.
* larger than: When the score is larger than the designated value.
* smaller than or equal to: When the score is smaller than or is equal to the designated value.
* larger than or equal to: When the score is larger than or is equal to the designated value.
4. giving out items
There are items’ names and IGUIDs for selecting the given-out items in the drop-down menu.
If one wants to give out more items, please choose “give out more items” below and then there will be a new menu for one to select the items to give out.
### 5-4 Leaderboard Procession Methods
The API functions for leaderboard management are in the CloudScore class, which is made up of static functions with no constructor and property. To deal with the procession of items, please call these functions directly.
For the next API function we are going to introduce, take `CommitLeaderBoard()` from the next session for example, program designers have to add “CloudScore.” when calling it. It will look like this:
`CloudScore.CommitLeaderBoard();`
### 5-5 Submitting Scores to the Leaderboard
To submit scores to the leaderboard, one has to call the CommitLeaderBoard() function in the game, and here is its definition:
public static void CommitLeaderBoard(CloudGame game, string lguid, int score, OnCallCompletion cb, object token)
`lguid` is the LGUID that one wants to submit to the leaderboard.
`score` is the score one wants to submit, if the leaderboard is a “counter,” the score parameter will be ignored.
cb is the callback function after completing API, and its definition is:
`void cb(int code, object token)`
When the submission is successful, `code` is 0. Instead, when the submission fails, `code` is not zero.
After submitting the score to the leaderboard, the system will rank it with other players’ scores and produce data on the daily, weekly, monthly, and total ranking. Program designers can download the ranking data to the app to show or process them by reading the leaderboard’s API.
### 5-6 Reading Leaderboard
The API that reads the leaderboard is `GetLeaderBoard()`. To meet the app’s needs, `GetLeaderBoard()` has eight kinds of overloadings:
The first kind, which is the most basic function of reading the leaderboard’s data, has the below definition:
```
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int ex,
OnCallCompletionWithData cb, object token)
```
Parameter `lguid` is the LGUID of the leaderboard one wants to read. The type parameter is used for designating the type of leaderboards one wants to read.
| type | 0 | 1 | 2 | 3 |
|:----:|:--------:| ------ |:------:|:------:|
| type | total ranking | daily ranking | weekly ranking | monthly ranking |
The ex parameter can designate the leaderboards of now or how long ago, and `ex=0` means to read the current leaderboard.
Example:
`type=2`，`ex=3` means to read the daily ranking of three days ago.
`type=3`，`ex=2` means to read the monthly ranking of two months ago.
The cb parameter is the callback function after executing GetLeaderBoard, and its definition is:
void cb(int code, object obj, object token)
After the function sussceeds, the code sends back 0. If it does not, the code sends back a number that is not 0.
`obj` is saved as `List <Hashtable>` and every element on the list is a scoring record. The scoring record is recorded with Hashtable, and there are five keys:
| Key | note |
|:------:|:---------------------------------------------:|
| userid | the name of the account of the player who submit this score |
| score | score |
|nickname| the nickname of the player who submit this score |
| note | the note for this score, which is the value of parameter “Note” in CommitLeaderBoard() |
| stamp | the time the score is submitted, and the format is `yyyy/mm/dd hh:mm:ss`. |
The second type, which is about designating the number of records one wants to read. If one chooses to not designate this, GetLeaderBoard reads all the ranking records that are on the leaderboard. For example, if a leaderboard only has 100 places, the list callback sends back after calling GetLeaderBoard has 100 records at most. Here is the definition of the function that designates the number of records one wants to read：
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int ex, OnCallCompletionWithData cb, object token, int Num)
The last parameter, `num`, is the number of records one designates to read.
The third type, which ranks the leaderboard data according to the order of the time the scores are submitted, and its definition is:
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int orderby, int ex, OnCallCompletionWithData cb, object token)
Parameter `orderby` designates the way of ordering the data when reading leaderboard data:
| Orderby | way of ranking |
|:------:|:---------------------------------------------:|
| 0 | according to the scores and the way it is set backstage |
| 1 | according to the time it is written in (in descending order, with the latest time listed first)|
| 2 | according to the time it is written in (in ascending order, with the earlier time listed first)|
The fourth type, which reads the leaderboard data according to the time the score is submitted and designates the number of records read:
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int orderby, int ex, OnCallCompletionWithData cb, object token, int Num)
As for the rest types, one can refer to the overloadings above. Their only difference is an additional parameter `poid`, which is the user’s identification code.
### 5-7 Write in Personal Score Record Directly
If one only wants to record his personal score without submitting it to the leaderboard, he can use RecordPlayerScore, and the definition is:
```
public static void RecordPlayerScore(CloudGame game,int tag,
string score, OnCallCompletion cb, object token)
```
Parameter `tag` is a tag used for distinguishing the leaderboard to distinguish the types of scores.
Parameter `score` is the score data one wants to write in.
```
public static void RecordPlayerScore(CloudGame game, uint poid, int tag,
string score, OnCallCompletion cb, object token)
```
Parameter `poid` is the user’s identification code.
Parameter `tag` is a tag used for distinguishing the leaderboard to distinguish the types of scores.
Parameter `score` is the score data one wants to write in.
### 5-8 Reading Personal Scoring Record
The previous function, CommitLeaderBoard, writes the score in both the designated leaderboard and the personal scoring record. To read the personal scoring record, one uses GetPlayerScore, and its definition is:
public static void GetPlayerScore(CloudGame game, int tag, int orderby, int order, string startDate, string endDate, OnCallCompletionWithData cb, object token)
Parameter `tag` is a tag used for distinguishing leaderboards, and developers can designate the tags for the types of scores. For example, we can set `tag=1` as the number of personal winning rounds, `tag=2` as the number of the times a player defeats the boss, `tag=3` as the player’s level, and so on.
Parameter `orderby` is the way of ranking the data when reading them:
| orderby | way of ranking |
|:-------:|:------------:|
| 0 | according to dates |
| 1 | according to scores |
Parameter oder designates whether the ranking is in ascending and descending order:
| orderby | way of ranking |
|:-------:|:------------:|
| 0 |in ascending order |
| 1 | in descending order |
Parameter startDate searches for the starting date, and the format is yyyy/mm/dd hh:mm:ss. If there is an empty string, there is no starting date. Parameter endDate searches for the starting date, and the format is yyyy/mm/dd hh:mm:ss. If there is an empty string, there is no starting date.
Parameter cb is the callback function after the calling is complete, and here is its definition:
cb(code, obj, token)
Parameter cb is the callback function after the calling is complete, and here is its definition:
Parameter `obj` is the type of the read data, which is saved as `List <Hashtable>` and every element in the List is a scoring record.
The scoring record is recorded with Hashtable, and there are three Keys:
| Key |contents |
|:-----:|:-------------------------------------------:|
| tag | the score’s tag, which has to be the same as the tag parameter that sends in |
| score | score |
| stamp | the time this score is submitted, and the format is yyyy/mm/dd hh:mm:ss |
If the player’s scores are recorded with CommitLeaderBoard and the leaderboard’s type is a “counter,” the Hashtable gets different contents, and there will be six keys:
| Key | contents |
|:-------:|:------------------------------------------------------------:|
| tag | the score’s tag, which has to be the same as the tag parameter that sends in |
| daily | the current count for “daily” (only appears when this value is checked in the leaderboard project ) |
| weekly | the current count for “weekly” (only appears when this value is checked in the leaderboard project ) |
| monthly | the current count for “monthly” (only appears when this value is checked in the leaderboard project ) |
| all | the current count for “all” (only appears when this value is checked in the leaderboard project ) |
| stamp | the time this score is submitted, and the format is yyyy/mm/dd hh:mm:ss
GetPlayerScore has another overloading, which designates the number of record one to read, and here is its definition:
```
csharp
public static void GetPlayerScore(CloudGame game, int tag, int orderby, int order, string startDate, string endDate, OnCallCompletionWithData cb, object token,int Num)
```
Parameter `num` is the number of records one designates to read.
Another overloading has another parameter poid, representing the data of the read player’s(poid) score.
```
csharp
public static void GetPlayerScore(CloudGame game, uint poid, int tag, int orderby, int order, string startDate, string endDate, OnCallCompletionWithData cb, object token)
```
Parameter `poid` is the user’s identification code.
The last overloading has two additional parameters. Poid represents the data of the read player’s(poid) score and Num means to read Num number of data of scores.
```
csharp
public static void GetPlayerScore(CloudGame game, uint poid, int tag, int orderby, int order, string startDate, string endDate, OnCallCompletionWithData cb, object token, int num)
```
Parameter `poid` is the user’s identification code.
Parameter `num` is the number of data one wants to read.
Sign in with Wallet
Connect another wallet