GKLeaderboard でどのようなスコアデータの絞り込みができるか

Game Center の Leaderboard のスコアデータは、GKLeaderboard クラスを使用して直接とってくることができます。

アプリケーションでスコアデータを調べたり、独自の Leaderboard ビューを作成したい場合は、GameCenterから直接スコアデータをロードできます。それには、GKLeaderboard クラスを使用します。GKLeaderboard オブジェクトは、Game Center に保存されているアプリケーションのデータへのクエリを表します。スコアデータをロードするには、アプリケーションは GKLeaderboard オブジェクトを作成して、特定のスコアセットをフィルタリングするようにそのプロパティを設定します。（Game Kitプログラミングガイドより）

で、どんなプロパティをセットすることでどのような絞り込みが可能なのか、リファレンスを見たりサンプル作ってみたりして調べてみました。

絞り込み条件用プロパティは次の4つ。

@property(nonatomic, assign)            GKLeaderboardTimeScope      timeScope;
@property(nonatomic, assign)            GKLeaderboardPlayerScope    playerScope;        // Filter on friends. Does not apply to leaderboard initialized with players.
@property(nonatomic, retain)            NSString                    *category;          // leaderboard category.  If nil, then it will fetch the aggregate leaderboard
@property(nonatomic, assign)            NSRange                     range;              // Leaderboards start at index 1 and the length should be less than 100. Does not apply to leaderboards initialized with players.  Exception will be thrown if developer tries to set an invalid range

また、loadScores:が成功すると値がセットされるプロパティ（つまり取得できる情報）は次の4つ。

@property(nonatomic, readonly, retain)  NSString                    *title;             // Localized category title. Defalts to nil until loaded.
@property(nonatomic, readonly, retain)  NSArray                     *scores;            // Scores are not valid until loadScores: has completed.
@property(nonatomic, readonly, assign)  NSUInteger                  maxRange;           // The maxRange which represents the size of the leaderboard is not valid until loadScores: has completed.
@property(nonatomic, readonly, retain)  GKScore                     *localPlayerScore;  // The local player's score

以下、４つの絞り込み条件用プロパティについてどのような指定ができるのか調べた結果です。

timeScope

timeScope プロパティは GKLeaderboardTimeScope 型となっています。
GKLeaderboardTimeScope の定義を見てみると、

enum {
    GKLeaderboardTimeScopeToday = 0,
    GKLeaderboardTimeScopeWeek,
    GKLeaderboardTimeScopeAllTime
};
typedef NSInteger GKLeaderboardTimeScope;

当日、週、全期間の指定ができるようです。

playerScope

playerScope プロパティは GKLeaderboardPlayerScope 型となっています。
GKLeaderboardPlayerScope の定義を見てみると

enum {
    GKLeaderboardPlayerScopeGlobal = 0,
    GKLeaderboardPlayerScopeFriendsOnly
};
typedef NSInteger GKLeaderboardPlayerScope;

となっており、このプロパティを指定することで全体／友達のスコープ指定ができるようです。

range

型は NSRange.
リファレンスによると

取得する順位の範囲を指定できる。たとえば [1,10] と指定すると、トップ10のスコアを取得することになる
デフォルトは [1,25]
指定できるindexの最小値は1、lengthの最大値は100

とのこと。

まとめ

Leaderboard で使用できる絞り込み条件

当日、週、全期間
全体、友達のみ
Leaderboard ID
順位の範囲

そもそもこれを調べようと思った経緯として、複数ユーザーのスコアを合算してひとつのスコアにして、「チーム対抗ランキング」みたいなことをやりたかったからなのですが、残念ながらそれはできなそうです。。

その後のその後

iOSエンジニア堤修一のブログ github.com/shu223

GKLeaderboard でどのようなスコアデータの絞り込みができるか

timeScope

playerScope

category

range

まとめ