GS2-Ranking SDK for Game Engine API リファレンス

ゲームエンジン向け GS2-Ranking SDK のモデルの仕様と API のリファレンス

モデル

EzScore

スコア

ゲームプレイヤーごと・カテゴリーごとに登録されたスコアを保持するエンティティです。
各スコアエントリはユニークIDで識別され、カテゴリーとスコア登録ユーザーに関連付けられます。
合算モードでは、新しいスコアは個別のエントリを作成するのではなく、AddScore 操作で既存の合計に加算されます。
カテゴリーの最小値・最大値の範囲外のスコアは登録時に拒否されます。

	型	必須	デフォルト	値の制限	説明
categoryName	string	✓		~ 128文字	カテゴリー名
userId	string	✓		~ 128文字	ユーザーID
uniqueId	string	✓	UUID	~ 36文字	ユニークID このスコアエントリを一意に識別する UUID。作成時に自動生成されます。uniqueByUserId が無効の場合、同一ユーザーの同一カテゴリー内の複数スコアエントリを区別するために使用されます。
scorerUserId	string	✓		~ 128文字	ユーザーID
score	long	✓		0 ~ 9223372036854775805	スコアプレイヤーが登録したスコア値。カテゴリーに設定された最小値・最大値の範囲内である必要があります。合算モードでは、AddScore 操作でこの値をインクリメントできます。
metadata	string			~ 512文字	メタデータメタデータには任意の値を設定できます。これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。

EzRanking

ランキング

ランキングリーダーボードの1エントリを表し、ユーザーの順位、スコア、および関連メタデータを含みます。
グローバルランキング（全プレイヤーが共有ボードでバッチ集計により競争）とスコープランキング（購読したプレイヤーに基づくユーザーごとのボードでリアルタイム反映）の2種類があります。
ランキングはカテゴリーに設定されたソート方向で並び替えられ、同スコアのエントリは同順位を共有しつつ異なるインデックスを保持します。

	型	必須	値の制限	説明
rank	long	✓	1 ~ 9223372036854775805	順位このエントリのランキング順位（1始まり）。同スコアのエントリは同じ順位を共有します。例えば、2ユーザーが1位タイの場合、両方とも順位1となり次のエントリは順位3になります。
index	long	✓	0 ~ 9223372036854775805	インデックスランキングリスト内のゼロベースの連番インデックス。 rank と異なり、複数のエントリが同スコアを共有していてもインデックスは常にユニークで連続します。ページネーションや範囲ベースのクエリに使用されます。
userId	string	✓	~ 128文字	ユーザーID
score	long	✓	0 ~ 9223372036854775805	スコアこのランキングエントリのスコア値。合算モードの場合、登録された全スコアの累積合計です。ランキングのソート順に使用される値はカテゴリーの orderDirection 設定に依存します。
metadata	string		~ 512文字	メタデータこのランキングエントリに関連付けられた任意のメタデータ。スコア登録時に設定され、ランキング結果と共に返されます。最大512文字。
createdAt	long	✓		作成日時 UNIX 時間・ミリ秒 ※ サーバー側で自動的に設定

EzSubscribeUser

購読ユーザー

スコープランキングカテゴリー内の個別の購読関係を表します。
各エントリは、親ユーザーが指定カテゴリーでターゲットユーザーのスコアを購読（フォロー）していることを示します。

	型	有効化条件	必須	デフォルト	値の制限	説明
userId	string		✓		~ 128文字	ユーザーID
targetUserId	string		✓		~ 128文字	購読対象ユーザーID 購読先のプレイヤーのユーザーID。このユーザーのスコアが、購読元ユーザーの指定カテゴリーにおけるスコープランキングに表示されます。

EzCategoryModel

カテゴリーモデル

カテゴリー毎に異なるランキングを作成できます。

カテゴリーには登録できるスコアの最小値・最大値を設定でき、その範囲外のスコアは破棄されます。
ランキングを集計する際にスコアを小さいものを上位（昇順）にするか、大きいものを上位（降順）にするかを設定できます。

ランキングの種類として グローバル と スコープ を選択できます。
グローバルは全プレイヤーが同じ結果を参照するもので、スコープはフレンド内ランキングや、ギルド内ランキングのようなゲームプレイヤー毎に結果の異なるランキングです。

グローバルランキングはカテゴリーごとにランキングの集計間隔を15分～24時間で設定できます。
スコープランキングはリアルタイムで集計結果が反映されます。

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

型

有効化条件

必須

デフォルト

値の制限

説明

name

string

✓

~ 128文字

カテゴリーモデル名

カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

metadata

string

~ 1024文字

メタデータ

メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。

scope

文字列列挙型
enum {
“global”,
“scoped”
}

✓

ランキングの種類

このカテゴリーのランキングタイプ。
“global” は全プレイヤーが共有する単一のリーダーボードを作成し、設定された間隔でバッチ集計されます。
“scoped” は購読したプレイヤー（フレンドやギルドメンバー等）に基づくユーザーごとのリーダーボードを作成し、スコアがリアルタイムで反映されます。

定義	説明
“global”	グローバル
“scoped”	スコープ

globalRankingSetting

EzGlobalRankingSetting

{scope} == “global”

✓※

グローバルランキング設定

グローバルランキングモード固有の設定。集計間隔、固定時刻、スコアのユニーク性、世代管理、および追加の期間限定スコープを含みます。
scope が “global” に設定されている場合のみ適用されます。

※ scope が “global” であれば必須

entryPeriodEventId

string

~ 1024文字

スコア登録期間イベントID

スコア登録を受け付ける期間を定義する GS2-Schedule イベントの GRN。
この期間外のスコア登録リクエストは拒否されます。未設定の場合、スコアはいつでも登録できます。

accessPeriodEventId

string

~ 1024文字

アクセス期間イベントID

ランキングデータを閲覧できる期間を定義する GS2-Schedule イベントの GRN。
この期間外のランキング取得リクエストは拒否されます。未設定の場合、ランキングはいつでもアクセスできます。

EzGlobalRankingSetting

グローバルランキング設定

グローバルは全プレイヤーが同じ結果を参照するものです。
ランキングの集計間隔を15分～24時間で設定できます。

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

	型	有効化条件	必須	デフォルト	値の制限	説明
calculateIntervalMinutes	int		✓		15 ~ 1440	集計間隔（分）連続するランキング再集計の間隔（分）。システムはこの間隔で、登録された全スコアに基づいてグローバルランキングを定期的に再集計します。範囲: 15～1440分（15分～24時間）。
additionalScopes	List<EzScope>				0 ~ 10 items	追加スコープリスト追加の期間限定集計スコープのリスト。各スコープは指定した日数以内に登録されたスコアのみを対象とする別ランキングを定義します。全期間のグローバルランキングと併せて、デイリー・ウィークリー・マンスリーなどのリーダーボードを作成できます。最大10件。

EzScope

集計スコープ

グローバルランキングモードにおける追加の期間限定集計スコープを定義します。
通常、グローバルランキングは登録されたスコア全てを対象に集計が行われます。
スコープを追加することで、指定した日数以内に登録されたスコアのみを対象とする別ランキングを作成でき、全期間ランキングと併せてデイリー・ウィークリー・マンスリーなどのリーダーボードを実現できます。

	型	有効化条件	必須	デフォルト	値の制限	説明
name	string		✓		~ 128文字	スコープ名カテゴリー内でこの集計スコープを一意に識別する名前。複数の期間限定ランキングボードを区別するために使用されます（例: “daily”, “weekly”）。最大128文字。
targetDays	long		✓		1 ~ 365	集計対象日数集計ウィンドウに含める日数。現在時刻からこの日数以内に登録されたスコアのみがスコープランキングの対象となります。範囲: 1～365日。

メソッド

getCategory

特定のランキングカテゴリの詳細を取得する

ランキングカテゴリ名を指定して、スコアリングルールと設定を含む詳細を取得します。

レスポンスには以下が含まれます:

スコア範囲: 登録可能なスコアの最小値と最大値
ソート順: スコアが高いほど上位（降順）か、スコアが低いほど上位（昇順、タイムアタックランキングなどに便利）か
スコープタイプ: グローバルランキングかスコープ付き（フレンド）ランキングか
グローバルランキングの場合: 計算間隔とタイミング設定
エントリー/アクセス期間: GS2-Schedule のイベントと連携している場合、スコア登録やランキング閲覧が可能な期間

詳細画面でランキングのルールや設定を表示する際に使います。

Request

	型	有効化条件	必須	デフォルト	値の制限	説明
namespaceName	string		✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string		✓		~ 128文字	カテゴリーモデル名カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

	型	説明
item	EzCategoryModel	カテゴリモデル

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->CategoryModel(
        "category-0001" // categoryName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

値の変更イベントハンドリング

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->CategoryModel(
        "category-0001" // categoryName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Ranking::Model::FCategoryModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

ランキングカテゴリの一覧を取得する

ネームスペースに定義されているすべてのランキングカテゴリを取得します。
各カテゴリは独立したリーダーボードを表します。たとえば「ハイスコア」「ボスタイムアタック」「週間バトル勝利数」などです。

ランキングには2つのタイプがあります:

グローバルランキング: すべてのプレイヤーが1つのリーダーボードで順位付けされます。ランキングは定期的に再計算される（リアルタイムではない）ため、スコア登録からランキングへの反映には遅延があります。
スコープ付きランキング: プレイヤーごとに、自分と購読（フォロー）しているプレイヤーだけが表示されるパーソナライズされたリーダーボードです（「フレンドランキング」のようなもの）。こちらはリアルタイムで計算されます。

ランキング画面で利用可能なリーダーボードの一覧を表示する際に使います。たとえば「世界ランキング」「フレンドランキング」「週間ランキング」などのタブを表示するような画面です。

Request

	型	有効化条件	必須	デフォルト	値の制限	説明
namespaceName	string		✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

	型	説明
items	List<EzCategoryModel>	カテゴリモデルのリスト

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.CategoryModelsAsync(
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.CategoryModels(
    );
    List<EzCategoryModel> items = new List<EzCategoryModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->CategoryModels(
    );
    TArray<Gs2::UE5::Ranking::Model::FEzCategoryModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

値の変更イベントハンドリング

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeCategoryModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeCategoryModels(callbackId);

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeCategoryModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeCategoryModels(callbackId);

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeCategoryModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeCategoryModels(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

listSubscribes

フレンドランキング用にフォローしているプレイヤーの一覧を取得する

指定されたランキングカテゴリで、現在のプレイヤーが購読（フォロー）しているプレイヤーの一覧を取得します。
スコープ付き（フレンド）ランキングで使用します。他のプレイヤーを購読すると、そのプレイヤーのスコアがパーソナライズされたフレンドランキングに表示されるようになります。

ランキング画面で「フォロー中」リストを表示する際に使います。フレンドリーダーボードにどのプレイヤーのスコアが含まれているかを確認できます。

たとえば PlayerA、PlayerB、PlayerC を購読している場合、フレンドランキングにはこの3人と自分自身のスコアが表示されます。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓	~ 128文字	カテゴリーモデル名
gameSession	GameSession	✓		GameSession

Result

	型	説明
items	List<EzSubscribeUser>	購読対象ユーザー情報のリスト

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var items = await domain.SubscribeUsersAsync(
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var it = domain.SubscribeUsers(
    );
    List<EzSubscribeUser> items = new List<EzSubscribeUser>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto It = Domain->SubscribeUsers(
    );
    TArray<Gs2::UE5::Ranking::Model::FEzSubscribeUserPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

値の変更イベントハンドリング

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeSubscribeUsers(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeSubscribeUsers(callbackId);

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeSubscribeUsers(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeSubscribeUsers(callbackId);

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeSubscribeUsers(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeSubscribeUsers(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

プレイヤーをフォローしてフレンドランキングに含める

指定されたカテゴリで他のプレイヤーを購読し、そのプレイヤーのスコアが自分のスコープ付き（フレンド）ランキングに表示されるようにします。
「フォロー」機能のようなものです。購読後、対象プレイヤーのスコアがパーソナライズされたフレンドリーダーボードに表示されるようになります。

主な使い方:

プレイヤーがフレンド追加した際に、すべてのランキングカテゴリで自動的に購読する
プレイヤーのプロフィール画面に「リーダーボードでフォロー」ボタンを設置する
対戦後、対戦した相手をフォローできるようにする

自分自身を購読することはできません（自分のスコアはフレンドランキングに自動的に含まれます）。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓	~ 128文字	カテゴリー名
gameSession	GameSession	✓		GameSession
targetUserId	string	✓	~ 128文字	購読するユーザーID

Result

	型	説明
item	EzSubscribeUser	購読対象ユーザー情報

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var result = await domain.SubscribeAsync(
        targetUserId: "user-0002"
    );
    var item = await result.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var future = domain.SubscribeFuture(
        targetUserId: "user-0002"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto Future = Domain->Subscribe(
        "user-0002" // targetUserId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

unsubscribe

プレイヤーのフォローを解除してフレンドランキングから除外する

指定されたランキングカテゴリで、指定されたプレイヤーの購読を解除します。
購読解除後、対象プレイヤーのスコアはスコープ付き（フレンド）ランキングに表示されなくなります。

プレイヤーがフレンドリーダーボードで誰かのスコアを表示しないようにしたいときに使います。たとえばフレンド解除時やフォロー解除時です。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓	~ 128文字	カテゴリー名
gameSession	GameSession	✓		GameSession
targetUserId	string	✓	~ 128文字	購読解除するユーザーID

Result

	型	説明
item	EzSubscribeUser	解除した購読対象ユーザー情報

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).SubscribeUser(
        targetUserId: "user-0002"
    );
    var result = await domain.UnsubscribeAsync(
    );

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).SubscribeUser(
        targetUserId: "user-0002"
    );
    var future = domain.UnsubscribeFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    )->SubscribeUser(
        "user-0002" // targetUserId
    );
    const auto Future = Domain->Unsubscribe(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

getNearRanking

特定のスコア付近のランキングを取得する

指定されたスコア値を中心としたランキングの一部を取得します。
プレイヤーが「自分がどのあたりの順位か」を確認するのに便利です。たとえばリーダーボード上で、プレイヤーのスコアの前後数人を表示できます。

一般的な使い方: プレイヤーがゲームを終えた後、自分のスコアとその付近のランキングを表示:
「98位: PlayerX (5,200 pt) → あなた: 5,150 pt → 99位: PlayerY (5,100 pt)」

このAPIはグローバルランキングでのみ使用できます。スコープ付き（フレンド）ランキングの場合はリストが十分小さいため、代わりに GetRanking を使ってください。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓	~ 128文字	カテゴリーモデル名カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
additionalScopeName	string		~ 128文字	スコープ名カテゴリー内でこの集計スコープを一意に識別する名前。複数の期間限定ランキングボードを区別するために使用されます（例: “daily”, “weekly”）。最大128文字。
score	long	✓	0 ~ 9223372036854775805	スコアこのランキングエントリのスコア値。合算モードの場合、登録された全スコアの累積合計です。ランキングのソート順に使用される値はカテゴリーの orderDirection 設定に依存します。

Result

	型	説明
items	List<EzRanking>	ランキングのリスト

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var items = await domain.NearRankingsAsync(
        score: 1000L
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var it = domain.NearRankings(
        score: 1000L
    );
    List<EzRanking> items = new List<EzRanking>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto It = Domain->NearRankings(
        1000L // score
    );
    TArray<Gs2::UE5::Ranking::Model::FEzRankingPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

getRank

特定プレイヤーの順位とスコアを取得する

特定プレイヤーのランキング情報を、順位とスコアを含めて取得します。
結果画面やプロフィールページで「あなたの順位: 42位 (8,500 pt)」のように表示する際に使います。

scorerUserId（順位を調べたいプレイヤー）を指定する必要があります。uniqueId はカテゴリがプレイヤーごとにスコアを1つしか許可しない場合は省略できます（デフォルト “0”）。カテゴリがプレイヤーごとに複数スコアを許可する場合は、uniqueId を指定してどのスコアを調べるか特定します。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓		~ 128文字	カテゴリーモデル名カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
additionalScopeName	string			~ 128文字	スコープ名カテゴリー内でこの集計スコープを一意に識別する名前。複数の期間限定ランキングボードを区別するために使用されます（例: “daily”, “weekly”）。最大128文字。
scorerUserId	string	✓		~ 128文字	スコアを獲得したユーザーのユーザーID
gameSession	GameSession	✓			GameSession
uniqueId	string		“0”	~ 36文字	スコアのユニークID

Result

	型	説明
item	EzRanking	ランキング

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).Ranking(
        scorerUserId: "user-0001",
        index: null
    );
    var item = await domain.ModelAsync(
        scorerUserId : "user-0001"
    );

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).Ranking(
        scorerUserId: "user-0001",
        index: null
    );
    var future = domain.Model(
        scorerUserId : "user-0001"
    );
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    )->Ranking(
        "user-0001", // scorerUserId
        nullptr // index
    );
    const auto Future = Domain->Model(
        "user-0001" // scorerUserId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

値の変更イベントハンドリング

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).Ranking(
        scorerUserId: "user-0001",
        index: null
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).Ranking(
        scorerUserId: "user-0001",
        index: null
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    )->Ranking(
        "user-0001", // scorerUserId
        nullptr // index
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Ranking::Model::FRanking> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

getRanking

ランキングのリーダーボードを取得する

指定されたカテゴリのランキング一覧を取得します。プレイヤーがスコア順に並んで表示されます。
リーダーボード画面を表示するためのメインAPIです。たとえば「1位: PlayerA (10,500 pt)、2位: PlayerB (9,800 pt)、…」のような表示です。

startIndex を指定して特定の順位から取得を開始できます（例: startIndex=0 でトップから、startIndex=99 で100位付近から）。

グローバルランキングの場合、データは最後の計算結果に基づくため、スコア登録からランキング更新まで遅延がある場合があります。
スコープ付き（フレンド）ランキングの場合、データはリアルタイムで計算されます。

カテゴリが追加スコープに対応している場合、additionalScopeName を指定してランキングをさらに絞り込めます。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓		~ 128文字	カテゴリーモデル名カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
additionalScopeName	string			~ 128文字	スコープ名カテゴリー内でこの集計スコープを一意に識別する名前。複数の期間限定ランキングボードを区別するために使用されます（例: “daily”, “weekly”）。最大128文字。
gameSession	GameSession				GameSession
limit	int		30	1 ~ 1000	データの取得件数
pageToken	string			~ 4096文字	データの取得を開始する位置を指定するトークン
startIndex	long			0 ~ 9223372036854775805	ランキングの取得を開始するインデックス

Result

	型	説明
items	List<EzRanking>	ランキングのリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var items = await domain.RankingsAsync(
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var it = domain.Rankings(
    );
    List<EzRanking> items = new List<EzRanking>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto It = Domain->Rankings(
    );
    TArray<Gs2::UE5::Ranking::Model::FEzRankingPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

値の変更イベントハンドリング

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeRankings(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeRankings(callbackId);

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeRankings(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeRankings(callbackId);

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeRankings(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeRankings(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

putScore

ランキングにスコアを登録する

指定されたランキングカテゴリにプレイヤーのスコアを登録します。
プレイヤーが記録したいスコアを達成したときに呼び出します。たとえばステージクリア後、タイムアタック終了時、対戦終了時などです。

スコアにはメタデータ（文字列）をオプションで添付できます。リーダーボード上でスコアと一緒に表示したい追加情報を保存するのに便利です。たとえばプレイヤーのキャラクター名、チーム構成、リプレイデータなどです。

スコアの扱いはカテゴリのタイプによって異なります:

グローバルランキング: スコアが収集され、次のスケジュールされた間隔でランキングが再計算されます。ランキングが更新されるまで遅延があります。
スコープ付きランキング: スコアは即座に反映され、このプレイヤーを購読（フォロー）しているプレイヤーのフレンドランキングに表示されます。

注意: カテゴリの設定によって、プレイヤーごとに最高スコア（昇順ランキングの場合は最低スコア）のみが保持される場合と、複数のスコアが許可される場合があります。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓	~ 128文字	カテゴリーモデル名カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSession	GameSession	✓		GameSession
score	long	✓	0 ~ 9223372036854775805	スコアこのランキングエントリのスコア値。合算モードの場合、登録された全スコアの累積合計です。ランキングのソート順に使用される値はカテゴリーの orderDirection 設定に依存します。
metadata	string		~ 512文字	メタデータこのランキングエントリに関連付けられた任意のメタデータ。スコア登録時に設定され、ランキング結果と共に返されます。最大512文字。

Result

	型	説明
item	EzScore	登録したスコア

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var result = await domain.PutScoreAsync(
        score: 1000L,
        metadata: null
    );
    var item = await result.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var future = domain.PutScoreFuture(
        score: 1000L,
        metadata: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto Future = Domain->PutScore(
        1000L // score
        // metadata
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

getScore

プレイヤーが登録した特定のスコアを取得する

指定されたランキングカテゴリで、指定されたプレイヤーの1つのスコアレコードを取得します。
特定スコアの詳細を表示する際に使います。たとえばスコアの値、登録日時、添付されたメタデータ（キャラクター名やリプレイデータなど）を表示できます。

uniqueId はプレイヤーが複数スコアを持つ場合にどのスコアを取得するかを指定します。カテゴリがプレイヤーごとにスコアを1つしか許可しない場合（最も一般的なケース）は、uniqueId を省略するか “0” に設定できます。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓		~ 128文字	カテゴリー名
gameSession	GameSession	✓			GameSession
scorerUserId	string	✓		~ 128文字	ユーザーID
uniqueId	string		“0”	~ 36文字	スコアのユニークID

Result

	型	説明
item	EzScore	スコア

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Score(
        "category-0001", // categoryName
        "user-0002", // scorerUserId
        "unique-0001" // uniqueId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

値の変更イベントハンドリング

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Score(
        "category-0001", // categoryName
        "user-0002", // scorerUserId
        "unique-0001" // uniqueId
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Ranking::Model::FScore> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

listScores

特定プレイヤーが登録したスコアの一覧を取得する

指定されたランキングカテゴリで、特定のプレイヤーが登録したすべてのスコアを取得します。
プレイヤーのスコア履歴を表示する際に使います。たとえば、タイムアタックステージの全挑戦記録を一覧表示するような場合です。

ランキングの表示（すべてのプレイヤーをスコア順に表示）とは異なり、このAPIは1人の特定プレイヤーの登録スコアに焦点を当てています。

カテゴリがプレイヤーごとにスコアを1つしか許可しない場合は1件だけ返されます。複数スコアが許可されている場合（例: 複数回の挑戦）は、すべてのスコアが返されます。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
categoryName	string	✓		~ 128文字	カテゴリーモデル名
scorerUserId	string	✓		~ 128文字	ユーザーID
gameSession	GameSession	✓			GameSession
limit	int		30	1 ~ 1000	データの取得件数
pageToken	string			~ 1024文字	データの取得を開始する位置を指定するトークン

Result

	型	説明
items	List<EzScore>	スコアのリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.ScoresAsync(
        categoryName: "category-0001",
        scorerUserId: "user-0002"
    ).ToListAsync();

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Scores(
        categoryName: "category-0001",
        scorerUserId: "user-0002"
    );
    List<EzScore> items = new List<EzScore>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Scores(
        "category-0001", // categoryName
        "user-0002" // scorerUserId
    );
    TArray<Gs2::UE5::Ranking::Model::FEzScorePtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

値の変更イベントハンドリング

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeScores(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeScores(callbackId);

    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeScores(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeScores(callbackId);

    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeScores(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeScores(CallbackId);

Warning

このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。

GS2-Ranking SDK for Game Engine API リファレンス

モデル

EzScore

EzRanking

EzSubscribeUser

EzCategoryModel

EzGlobalRankingSetting

EzScope

メソッド

getCategory

Request

Result

実装例

値の変更イベントハンドリング

Warning

listCategories

Request

Result

実装例

値の変更イベントハンドリング

Warning

listSubscribes

Request

Result

実装例

値の変更イベントハンドリング

Warning

subscribe

Request

Result

実装例

unsubscribe

Request

Result

実装例

getNearRanking

Request

Result

実装例

getRank

Request

Result

実装例

値の変更イベントハンドリング

Warning

getRanking

Request

Result

実装例

値の変更イベントハンドリング

Warning

putScore

Request

Result

実装例

getScore

Request

Result

実装例

値の変更イベントハンドリング

Warning

listScores

Request

Result

実装例

値の変更イベントハンドリング

Warning