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

モデル

EzCategoryModel

カテゴリーモデル

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

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

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

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

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

	型	必須	値の制限	説明
name	string	✓	~ 128文字	カテゴリ名
metadata	string		~ 1024文字	メタデータ
scope	enum { “global”, “scoped” }	✓	~ 128文字	ランキングの種類
globalRankingSetting	EzGlobalRankingSetting	{scope} == “global”		グローバルランキング設定
entryPeriodEventId	string		~ 1024文字	スコアの登録可能期間 GS2-Schedule イベントGRN
accessPeriodEventId	string		~ 1024文字	ランキングデータへのアクセス可能期間 GS2-Schedule イベントGRN

scope に指定する列挙型の定義

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

EzGlobalRankingSetting

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

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

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

	型	必須	デフォルト	値の制限	説明
calculateIntervalMinutes	int	✓		15 ~ 1440	スコアの集計間隔(分)
additionalScopes	List<EzScope>			~ 10 items	スコープリスト

EzScope

集計スコープ

グローバルランキングモードで使用可能。
通常グローバルランキングは登録されたスコア全てを対象にランキングの集計が行われます。

	型	必須	デフォルト	値の制限	説明
name	string	✓		~ 128文字	スコープ名
targetDays	long	✓		1 ~ 365	集計対象日数

EzScore

スコア

ゲームプレイヤー毎×カテゴリ毎の登録されたスコアを保持するエンティティです。

	型	必須	デフォルト	値の制限	説明
categoryName	string	✓		~ 128文字	カテゴリ名
userId	string	✓		~ 128文字	ユーザーID
uniqueId	string	✓	UUID	~ 36文字	スコアのユニークID
scorerUserId	string	✓		~ 128文字	ユーザーID
score	long	✓		~ 9223372036854775805	スコア
metadata	string			~ 512文字	メタデータ

EzRanking

ランキング

ランキングには「参加者全員が同じボード上で競い合う」グローバルランキングと、「購読したプレイヤーのスコアと競い合う」スコープランキングがあります。

	型	必須	値の制限	説明
rank	long	✓	1 ~ 9223372036854775805	順位
index	long	✓	~ 9223372036854775805	1位からのインデックス
userId	string	✓	~ 128文字	ユーザーID
score	long	✓	~ 9223372036854775805	スコア
metadata	string		~ 512文字	メタデータ
createdAt	long	✓		作成日時 (UNIX時間単位：ミリ秒)

EzSubscribeUser

購読しているユーザーのユーザーID

	型	必須	デフォルト	値の制限	説明
userId	string	✓		~ 128文字	ユーザーID
targetUserId	string	✓		~ 128文字	購読する対象のユーザーID

メソッド

getCategory

カテゴリを取得

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 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 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 の実行によって変化したもののみが対象となります。

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

カテゴリの一覧を取得

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 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 CallbackId = Domain->SubscribeCategoryModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

Warning

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

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

listSubscribes

購読しているユーザーIDの一覧を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID

Result

	型	説明
items	List<EzSubscribeUser>	購読しているユーザーのユーザーIDのリスト

実装例

    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 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 CallbackId = Domain->SubscribeSubscribeUsers(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

Warning

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

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

対象ユーザーを購読

対象ユーザーを購読することで、その対象ユーザーに関する新着メッセージ投稿の通知を受けることができます
購読する際のオプションとして、「メッセージに付加されたカテゴリが特定の値のものだけ通知する」といった設定や
「通知を受けたときにオフラインだった場合、モバイルプッシュ通知に転送する」といった設定ができます。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID
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文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID
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

指定したスコア付近のランキングを取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
additionalScopeName	string		~ 128文字	スコープ名
score	long	✓	~ 9223372036854775805	スコア

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

順位を取得

ユーザID毎にスコアを1つしか登録できないカテゴリを指定する場合、ユニークIDは省略可能です

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
additionalScopeName	string			~ 128文字	スコープ名
scorerUserId	string	✓		~ 128文字	スコアを獲得したユーザーのユーザーID
accessToken	string	✓		~ 128文字	ランキングを取得するユーザーID（GS2-Schedule の期間判定に使用されます。）
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 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 CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Ranking::Model::FRanking> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

Warning

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

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

getRanking

ランキングを取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
additionalScopeName	string			~ 128文字	スコープ名
accessToken	string			~ 128文字	ユーザーID
limit	int	✓	30	1 ~ 1000	データの取得件数
pageToken	string			~ 4096文字	データの取得を開始する位置を指定するトークン
startIndex	long			~ 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 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 CallbackId = Domain->SubscribeRankings(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

Warning

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

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

putScore

スコアを登録

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリ名
accessToken	string	✓	~ 128文字	ユーザーID
score	long	✓	~ 9223372036854775805	スコア
metadata	string		~ 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

ゲームプレイヤーが登録したスコアを取得

ユーザID毎にスコアを1つしか登録できないカテゴリを指定する場合、ユニークIDは省略可能です

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
accessToken	string	✓		~ 128文字	ユーザーID
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 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 CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Ranking::Model::FScore> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

Warning

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

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

listScores

ゲームプレイヤーが登録したスコアの一覧を取得

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名
categoryName	string	✓		~ 128文字	カテゴリ名
scorerUserId	string	✓		~ 128文字	ユーザーID
accessToken	string	✓		~ 128文字	ユーザーID
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 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 CallbackId = Domain->SubscribeScores(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

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

Warning

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

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

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

モデル

EzCategoryModel

scope に指定する列挙型の定義

EzGlobalRankingSetting

EzScope

EzScore

EzRanking

EzSubscribeUser

メソッド

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