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

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

モデル

EzCounter

回数制限の現在の値

各ユーザーの回数制限モデル配下の特定カウンターの現在の使用回数を追跡します。1つの回数制限モデルの下に複数のカウンターを作成できます（例：1回限りの報酬用にクエストごとに1つのカウンター）。カウント値はカウントアップ操作時に指定される最大値と比較され、回数制限モデルのリセットスケジュールに基づいて自動的にゼロにリセットされます。

	型	必須	デフォルト	値の制限	説明
counterId	string	※		~ 1024文字	カウンター GRN ※ サーバーが自動で設定
limitName	string	✓		~ 128文字	回数制限モデル名このカウンターが属する回数制限モデルの名前です。このカウンターの値に適用されるリセットスケジュール（毎日、毎週、毎月など）を決定します。
name	string	✓		~ 128文字	カウンターの名前回数制限モデル内でこのカウンターを一意に識別する名前です。同じ回数制限モデルを異なる名前の複数のカウンターで共有でき、個別の回数制限モデルを作成せずに別々の使用回数追跡（例：クエストごとや商品ごとに1カウンター）が可能です。
count	int		0	0 ~ 2147483646	カウント値このカウンターの現在の使用回数です。countUp操作でインクリメントされ、その際に指定された最大値と比較されます。回数制限モデルのリセットタイミングに達すると自動的にゼロにリセットされます。
createdAt	long	※	現在時刻		作成日時 UNIX 時間・ミリ秒 ※ サーバーが自動で設定
updatedAt	long	※	現在時刻		最終更新日時 UNIX 時間・ミリ秒 ※ サーバーが自動で設定

EzLimitModel

回数制限モデル

回数制限モデルには、使用回数をリセットするタイミングを設定できます。
リセット間隔は「毎日」「毎週」「毎月」「リセットしない」「一定日数」の 5 種類から選択できます。

また、回数制限の最大値はマスターデータ側では固定しません。
これは、ゲーム内のコンテキストに応じて、許可される最大回数を動的に変化させるためです。
たとえばステップアップガチャのように、

購入回数カウンターが 3 回未満の場合に購入できる商品
上記の商品が購入できない場合に、購入回数カウンターが 5 回未満なら購入できる別の商品

といったように、状況に応じて「最大回数」を切り替えられる設計を想定しています。

型

有効化条件

必須

デフォルト

値の制限

説明

limitModelId

string

※

~ 1024文字

回数制限モデル GRN

※ サーバーが自動で設定

name

string

✓

~ 128文字

回数制限モデル名

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

metadata

string

~ 2048文字

メタデータ

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

resetType

文字列列挙型
enum {
  “notReset”,
  “daily”,
  “weekly”,
  “monthly”,
  “days”
}

✓

リセットタイミング

この回数制限モデル配下のカウンター値が自動的にゼロにリセットされるタイミングを決定します。notReset（恒久的、リセットなし）、daily（毎日指定時刻にリセット）、weekly（指定曜日にリセット）、monthly（指定日にリセット）、days（基準日時から一定日数ごとにリセット）から選択します。すべての時刻はUTCです。

定義	説明
“notReset”	リセットしない
“daily”	毎日
“weekly”	毎週
“monthly”	毎月
“days”	一定日数ごと

resetDayOfMonth

int

{resetType} == “monthly”

✓※

1 ~ 31

リセット日

resetTypeが “monthly” の場合にカウンターがリセットされる月の日にちです。1〜31の値が有効です。指定した日がその月の日数を超える場合（例：2月の31日）、その月の最終日にリセットされます。

※ resetType が “monthly” であれば必須

resetDayOfWeek

文字列列挙型
enum {
  “sunday”,
  “monday”,
  “tuesday”,
  “wednesday”,
  “thursday”,
  “friday”,
  “saturday”
}

{resetType} == “weekly”

✓※

リセット曜日

resetTypeが “weekly” の場合にカウンターがリセットされる曜日です。この曜日のresetHour（UTC）で指定された時刻にリセットされます。

定義	説明
“sunday”	日曜日
“monday”	月曜日
“tuesday”	火曜日
“wednesday”	水曜日
“thursday”	木曜日
“friday”	金曜日
“saturday”	土曜日

※ resetType が “weekly” であれば必須

resetHour

int

{resetType} in [“monthly”, “weekly”, “daily”]

✓※

0 ~ 23

リセット時刻

daily、weekly、monthlyリセットタイプでカウンターがリセットされるUTCの時刻（0〜23）です。例えば0の場合、UTC午前0時にカウンターがリセットされます。

※ resetType が “monthly”,“weekly”,“daily"であれば必須

anchorTimestamp

long

{resetType} == “days”

✓※

経過日数のカウントをする基準日時

UNIX 時間・ミリ秒

※ resetType が “days” であれば必須

days

int

{resetType} == “days”

✓※

1 ~ 2147483646

リセットする日数

resetTypeが “days” の場合のカウンターリセットの間隔（日数）です。リセット周期はanchorTimestampから計算されます。例えばdaysが7でanchorTimestampが月曜日の正午なら、毎週月曜日の正午にカウンターがリセットされます。

※ resetType が “days” であれば必須

メソッド

countUp

回数制限カウンターをカウントアップする

指定したカウンターを指定した量だけ増加させます。カウンターが最大値を超える場合、操作は失敗します。これが回数制限の仕組みです。
たとえば、デイリー購入制限が3回で、プレイヤーがすでに2回購入している場合、1回のカウントアップは成功します（合計: 3）。しかし、さらにカウントアップしようとすると制限を超えるため失敗します。
増加量（countUpValue）と許可される最大値（maxValue）の両方を指定できます。
プレイヤーが制限付きアクションを実行する際に使います。たとえば、デイリーショップ購入やダンジョン入場時に呼びます。カウントアップが失敗した場合、プレイヤーが制限に達したことを意味します。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
limitName	string	✓		~ 128文字	回数制限モデル名このカウンターが属する回数制限モデルの名前です。このカウンターの値に適用されるリセットスケジュール（毎日、毎週、毎月など）を決定します。
counterName	string	✓		~ 128文字	カウンターの名前回数制限モデル内でこのカウンターを一意に識別する名前です。同じ回数制限モデルを異なる名前の複数のカウンターで共有でき、個別の回数制限モデルを作成せずに別々の使用回数追跡（例：クエストごとや商品ごとに1カウンター）が可能です。
gameSession	GameSession	✓			GameSession
countUpValue	int		1	1 ~ 2147483646	カウントアップする量
maxValue	int			1 ~ 2147483646	カウントアップを許容する最大値

Result

	型	説明
item	EzCounter	カウントを増やしたカウンター

Error

このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法はこちらのドキュメントを参考にしてください。

型	基底クラス	説明
OverflowException	BadRequestException	回数制限の上限に達しました

実装例

try {
    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    );
    var result = await domain.CountUpAsync(
        countUpValue: 1,
        maxValue: 100
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Limit.Exception.OverflowException e) {
    // The maximum number of times limit has been reached.
}

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    );
    var future = domain.CountUpFuture(
        countUpValue: 1,
        maxValue: 100
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Limit.Exception.OverflowException)
        {
            // The maximum number of times limit has been reached.
        }
        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->Limit->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Counter(
        "daily", // limitName
        "counter1" // counterName
    );
    const auto Future = Domain->CountUp(
        1, // countUpValue
        100 // maxValue
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Limit::Error::FOverflowError::Class))
        {
            // The maximum number of times limit has been reached.
        }
        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();

getCounter

特定の回数制限カウンターを取得する

回数制限モデル名とカウンター名を指定して、特定のカウンターを取得します。
カウンターは、現在の期間内にプレイヤーがこの特定のアクションを何回実行したかを示します。
特定のアクションの残り回数を確認するのに使います。たとえば、ダンジョン入場画面で「デイリーダンジョン: 3/5回使用済み — 残り2回」と表示するのに便利です。

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
limitName	string	✓	~ 128文字	回数制限モデル名このカウンターが属する回数制限モデルの名前です。このカウンターの値に適用されるリセットスケジュール（毎日、毎週、毎月など）を決定します。
counterName	string	✓	~ 128文字	カウンターの名前回数制限モデル内でこのカウンターを一意に識別する名前です。同じ回数制限モデルを異なる名前の複数のカウンターで共有でき、個別の回数制限モデルを作成せずに別々の使用回数追跡（例：クエストごとや商品ごとに1カウンター）が可能です。
gameSession	GameSession	✓		GameSession

Result

	型	説明
item	EzCounter	カウンター

実装例

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Limit->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Counter(
        "daily", // limitName
        "counter1" // counterName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

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

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

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

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

Warning

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

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

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

listCounters

プレイヤーの回数制限カウンターの一覧を取得する

プレイヤーのすべての回数制限カウンターを取得し、各制限付きアクションを何回実行したかを確認できます。
回数制限モデル名でフィルタリングすることもできます。省略するとすべての制限タイプのカウンターが返されます。
各カウンターは特定のアクションの現在のカウントを追跡します（例: 「デイリーショップ購入: 本日2/3回使用」）。
「残り回数」「デイリー制限」の概要画面を構築するのに使います。たとえば「ショップ購入: 2/3回、ダンジョン入場: 1/5回、無料ガチャ: 0/1回」のような表示に便利です。

Request

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

Result

	型	説明
items	List<EzCounter>	カウンターのリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.CountersAsync(
        limitName: "daily"
    ).ToListAsync();

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Counters(
        limitName: "daily"
    );
    List<EzCounter> items = new List<EzCounter>();
    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->Limit->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Counters(
        "daily" // limitName
    );
    TArray<Gs2::UE5::Limit::Model::FEzCounterPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

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

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

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

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

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

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

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

Warning

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

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

getLimitModel

名前を指定して回数制限定義を取得する

名前を指定して、回数制限モデルを1件取得します。
取得できる情報には、リセットタイプ（リセットなし / 日次 / 週次 / 月次）と関連設定が含まれます。
特定の制限のルールを表示するのに使います。たとえば、ショップ詳細画面で「デイリーショップ制限 — 毎日0時にリセット」と表示するのに便利です。

Request

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

Result

	型	説明
item	EzLimitModel	回数制限モデル

実装例

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).LimitModel(
        limitName: "limit-model-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).LimitModel(
        limitName: "limit-model-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Limit->Namespace(
        "namespace-0001" // namespaceName
    )->LimitModel(
        "limit-model-0001" // limitName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

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

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

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

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

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

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

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

Warning

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

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

listLimitModels

回数制限定義の一覧を取得する

このネームスペースに登録されているすべての回数制限モデルを取得します。
回数制限モデルは、カウンターの動作（特にリセットタイミング）を定義します。リセットの種類は以下の通りです:

リセットなし: カウンターがリセットされない（例: 初回クリアボーナスなどの1回限りの報酬）
日次: 毎日リセット（例: 「1日3回まで購入可能」）
週次: 毎週リセット（例: 週間ダンジョンの挑戦回数）
月次: 毎月リセット（例: 月間報酬の受け取り回数）
ゲームにどんな種類の回数制限があるかを確認するのに使います。たとえば、ショップや活動画面で「デイリー制限」「ウィークリー制限」のカテゴリを表示する際に便利です。

Request

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

Result

	型	説明
items	List<EzLimitModel>	回数制限モデルのリスト

実装例

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

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.LimitModels(
    );
    List<EzLimitModel> items = new List<EzLimitModel>();
    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->Limit->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->LimitModels(
    );
    TArray<Gs2::UE5::Limit::Model::FEzLimitModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

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

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

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

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

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

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

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

Warning

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

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