Leaderboard
第 5 章 積分板處理
5-1 認識積分板(Leaderboard)
積分板是用來記錄玩家遊戲分數並產生成績排行榜，SGC 提供的積分排行榜分為日排行、週排行、月排行、總排行。 日排行成績會在 UTC 時間的每日凌晨零時歸零重置，而週排行、月排行則分別在每週日與每月一號的 UTC 時間凌晨零時歸零重置，至於總排行則永不歸零。 除了成績排行外，SGC 也提供玩家個人記錄成績的服務，開發者可依遊戲需要，在遊戲程式中記錄與查閱玩家成績。
5-2 積分板管理
使用 SGC 的積分板服務前，開發者必須在開發者後台建立一個新的積分板，並取得積分板的GUID(稱為 LGUID)，然後在遊戲程式中以 CloudScore 類別中的靜態函式來處理遊戲中的積分板。
以下是建立積分板時所填寫的表單：
欄位說明：
1.名稱
積分板的名稱。
2.說明
積分板的說明，開發者可在此處詳細說明積分板的用途。
3.數據類型
分為「分數」與「計數器」兩種：
「分數」就是一般的數字成績，可自由寫入成績值，「計數器」則是每次寫入將成績值相加。
4.排行期限
可選擇「無限制」、「日排行」、「週排行」、「月排行」。
5.排列類型
「升序」：第一名的分數值最低，依序遞減；「降序」：第一名的分數值最高，依序遞減。
6.覆蓋狀態
每次提交成績時，過去已經存在的成績是否要覆寫過去，共分為三種：
- 不覆蓋(Insert)：直接新增一筆成績記錄，舊記錄仍會保留並參與排行，因此玩家可能會有多筆成績資料。
- 分數佳的覆蓋(Write Better)：提交的成績比原來的成績佳才會寫入，並覆蓋舊成績，因此同一個玩家在排行時只會有一筆記錄。
- 強制覆蓋(Overwrite)：每次提交成績後，舊成績都會刪除，所以同一個玩家在排行時只會有一筆記錄。
7.規則精靈
規則精靈將積分板與物品整合，設定自動發送物品的條件後，系統就會依照條件規則，自動發送物品給達到標準的玩家，詳細的操作請參考下一節。
表單填好後，點選右下方的「建立積分板」，方才新建的積分板資料就會出現在列表中了：
5-3 自動發送物品
積分板管理表單的下方會出現規則設定的欄位：
1.格式設定
分為「分數」和「排名」兩種選擇，意指當分數或排名達到設定的條件時就可以發送物品。
2.排行期限
此處也有「無限制」、「日排行」、「週排行」、「月排行」四種選擇，不過必須是積分板也有選擇的排行期限，這邊才能選取。
3.條件
- 等於：當成績等於指定的數值時。
- 介於：當成績介於指定的兩個數值之間時，又依照有無等於分為四種：
a≦成績≦b a≦成績＜b a＜成績≦b a＜成績＜b - 小於：當成績小於指定的數值時。
- 大於：當成績大於指定的數值時。
- 小於等於：當成績小於等於指定的數值時。
- 大於等於：當成績大於等於指定的數值時。
4.發送物品
下拉選單會出現物品名稱和物品的 IGUID，可用來選擇要發送的物品。
如果要發送更多物品，請點選下方「發送更多物品」，然後就會出現新的下拉選單讓我們再選擇發送的物品。
5-4 積分板處理方式
積分板處理的API 函式都在CloudScore 類別中，此類別是由靜態函式組成，沒有建構子(Constructor)， 也沒有物件屬性(Property)，要進行與物品相關的處理，請直接叫用這些函式。
接下來所介紹的 API 函式，以下一節的 CommitLeaderBoard()為例，程式設計師呼叫時要在前面加上「CloudScore.」，就像這個樣子：
CloudScore.CommitLeaderBoard();
5-5 提交成績到積分板
要將成績提交到積分板，必須在遊戲程式中呼叫 CommitLeaderBoard() 函數，函數定義如下：
public static void CommitLeaderBoard(CloudGame game, string lguid, int score, OnCallCompletion cb, object token)
lguid 是要提交到的積分板之 LGUID。
score 則是要登錄的成績，如果積分板是屬於「計數型」，那麼 score 參數將被忽略。
cb 為完成API 後的callback 函式，其函式定義如下：
void cb(int code, object token)
提交成功，code 為 0，反之，若提交失敗，則 code 為非零。
成績提交到積分板之後，系統會和其它玩家的成績進行排序作業，然後產生日、週、月、總等四個排行榜的資料，程式設計師可以透過讀取積分板的API 將排行資料下載到應用程式中顯示或處理。
5-6 讀取積分板
讀取積分板 API 為 GetLeaderBoard()，為了配合應用程式的需要，GetLeaderBoard 共有八種 Overloading：
第一種，最基本的讀取積分板資料功能，函式定義如下：
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int ex,
OnCallCompletionWithData cb, object token)
參數 lguid 就是要讀取的積分板之LGUID。參數 type 用來指定要讀取的積分板類型：
| type | 0 | 1 | 2 | 3 |
|---|---|---|---|---|
| 類型 | 累積排行 | 日排行 | 週排行 | 月排行 |
參數 ex 可以指定是現在或過去多久的積分板，ex=0 就是讀取目前的積分板。
例如 :
type=2，ex=3， 就是讀取三天前的日排行。
type=3，ex=2 則是兩個月前的月排行。
參數 cb 是GetLeaderBoard 執行完成後的 callback 函式，其定義如下：
void cb(int code, object obj, object token)
函式成功完成，code 傳回 0，反之則傳回非0。
obj 的型別為 List <Hashtable>，List 的每一元素即為一筆分數記錄，以Hashtable 記錄該筆分數計錄，共有五個 Key :
| Key | 說明 |
|---|---|
| userid | 登錄此分數的玩家之帳號名稱 |
| score | 分數 |
| nickname | 錄此分數的玩家暱稱 |
| note | 此分數的備註資料，也就是在CommitLeaderBoard() 時的「Note」參數值 |
| stamp | 登錄此分數的時間，格式為yyyy/MM/dd HH:mm:ss |
第二種，指定要讀取的筆數，如果不指定，積分板上的排行記錄有多少筆，GetLeaderBoard 就會讀到多少筆，例如某個排行榜只排到前 100 名，那麼呼叫 GetLeaderBoard 後，callback 傳回的 List 最多只會有 100 筆。指定讀取筆數的函式定義如下：
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int ex, OnCallCompletionWithData cb, object token, int Num)
最後一個參數 num 即為指定要讀取的排行筆數。
第三種，依照提交成績的時間順序讀取積分板資料，函式定義如下：
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int orderby, int ex, OnCallCompletionWithData cb, object token)
參數 orderby 用來指定讀取積分板資料時的排序方式：
| Orderby | 排序方式 |
|---|---|
| 0 | 依分數擊根據後台設定的方式排序 |
| 1 | 根據寫入時間排序(降序，最近的時間排前面) |
| 2 | 根據寫入時間排序(升序，最久的時間排前面) |
第四種，依照提交成績的時間順序讀取積分板資料，同時也指定讀取的資料筆數：
public static void GetLeaderBoard(CloudGame game, string lguid, int type, int orderby, int ex, OnCallCompletionWithData cb, object token, int Num)
剩餘的種類，可參考上方的Overloading，只是多了參數 poid ，即為使用者的識別碼。
5-7 直接寫入個人成績紀錄
如果只要記錄個人成績而不需要提交到積分板，可以使用RecordPlayerScore，函式定義如下：
public static void RecordPlayerScore(CloudGame game,int tag,
string score, OnCallCompletion cb, object token)
參數tag 是用來區別成績表的標籤，用來區別成績類別。
參數score 則是要寫入的成績資料。
public static void RecordPlayerScore(CloudGame game, uint poid, int tag,
string score, OnCallCompletion cb, object token)
參數poid 使用者的識別碼。
參數tag 是用來區別成績表的標籤，用來區別成績類別。
參數score 則是要寫入的成績資料。
5-8 讀取個人成績紀錄
要讀取個人的成績資料，使用的是 GetPlayerScore，函式定義如下：
public static void GetPlayerScore(CloudGame game, int tag, int orderby, int order, string startDate, string endDate, OnCallCompletionWithData cb, object token)
參數 tag 是用來區別成績表的標籤，開發者可以自行為成績類別指定標籤，舉例來說，我們可以訂定 tag=1 為個人勝場數，tag=2 為個人擊敗魔王的次數，tag=3 為個人的官階等級。
參數 orderby 為讀取資料時的排序方式：
| orderby | 排序方式 |
|---|---|
| 0 | 依照日期排序 |
| 1 | 依照分數排序 |
參數 order 指定排序的升冪或降冪：
| orderby | 排序方式 |
|---|---|
| 0 | 升冪排序 |
| 1 | 降冪排序 |
參數 startDate ，查詢期間之起始日期，格式為 yyyy/MM/dd HH:mm:ss，若為空字串表示無起始日期。參數 endDate，查詢期間之結束日期，格式為 yyyy/MM/dd HH:mm:ss，若為空字串表示無結束日期。
參數 cb 則是完成呼叫後的 callback 函式，定義如下：
cb(code, obj, token)
參數 code 若為 0 表示函式讀取資料成功，反之非零則是讀取失敗。
參數 obj 則是所讀取的成績資料，型別為 List <Hashtable> ，List 的每一元素即為一筆分數記錄，
以Hashtable 記錄該筆分數記錄，共有三個 Key：
| Key | 內容 |
|---|---|
| tag | 該分數的標籤，一定與傳入的tag參數相同 |
| score | 分數 |
| stamp | 登錄此分數的時間，格式為yyyy/MM/dd HH:mm:ss |
GetPlayerScore 還有另外一個 Overloading，可以指定要讀取的資料筆數，函式定義如下：
csharp
public static void GetPlayerScore(CloudGame game, int tag, int orderby, int order, string startDate, string endDate, OnCallCompletionWithData cb, object token,int Num)
參數 num 即為指定要讀取的資料筆數。
另外一個 Overloading 多了一個參數 poid ，代表讀取玩家(poid)分數的資料。
csharp
public static void GetPlayerScore(CloudGame game, uint poid, int tag, int orderby, int order, string startDate, string endDate, OnCallCompletionWithData cb, object token)
參數 poid 即為使用者的識別碼。
最後一個 Overloading 多了二個參數， poid ，代表讀取玩家(poid)分數的資料，Num，代表只要讀取 Num 筆分數的資料。
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)
參數 poid 即為使用者的識別碼。
參數 num 即為指定要讀取的資料筆數。