API Reference of GS2-Limit SDK for Game Engine

Specifications of models and API references for GS2-SDK for Game Engine

Model

EzCounter

Current value of frequency limit

	Type	Required	Default	Value Limits	Description
counterId	string	✓		~ 1024 chars	Counter GRN
limitName	string	✓		~ 128 chars	Name of limit model
name	string	✓		~ 128 chars	Counter Name
count	int	✓	0	0 ~ 2147483646	count value
createdAt	long	✓	Now		Datetime of creation Unix time, milliseconds
updatedAt	long	✓	Now		Datetime of last update Unix time, milliseconds

EzLimitModel

Limit Model

You can set the timing for resetting the usage count for frequency limits. The reset interval can be selected from four options: “Daily,” “Weekly,” “Monthly,” or “Do not reset.”

Additionally, the maximum value for frequency limits is not fixed in the master data. This is to dynamically change the maximum allowed count based on the in-game context. For example, in a step-up gacha:

Items purchasable when the purchase counter is under 3
When the above items are unavailable, another item purchasable if the purchase counter is under 5

The design assumes the ability to switch the “maximum count” based on the situation.

Type

Condition

Required

Default

Value Limits

Description

limitModelId

string

✓

~ 1024 chars

Limit Model GRN

name

string

✓

~ 128 chars

Limit Model Name

metadata

string

~ 2048 chars

Metadata

resetType

String Enum
enum {
  “notReset”,
  “daily”,
  “weekly”,
  “monthly”,
  “days”
}

✓

~ 128 chars

Reset timing

Enumerator String Definition	Description
“notReset”	Not resetting.
“daily”	Daily
“weekly”	Weekly
“monthly”	Monthly
“days”	Days

resetDayOfMonth

int

{resetType} == “monthly”

✓*

1 ~ 31

Date to reset (If the value exceeds the days of the month, it is treated as the last day.)

* required if resetType is “monthly”

resetDayOfWeek

String Enum
enum {
  “sunday”,
  “monday”,
  “tuesday”,
  “wednesday”,
  “thursday”,
  “friday”,
  “saturday”
}

{resetType} == “weekly”

✓*

~ 128 chars

Day of the week to reset

Enumerator String Definition	Description
“sunday”	Sunday
“monday”	Monday
“tuesday”	Tuesday
“wednesday”	Wednesday
“thursday”	Thursday
“friday”	Friday
“saturday”	Saturday

* required if resetType is “weekly”

resetHour

int

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

✓*

0 ~ 23

Reset hour

* required if resetType is “monthly”,“weekly”,“daily”

Methods

countUp

Count up the count limit counter associated with the game player by specifying the name of the count limit and the name of the counter

Request

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name
limitName	string	✓		~ 128 chars	Name of limit model
counterName	string	✓		~ 128 chars	Counter Name
accessToken	string	✓		~ 128 chars	Access token
countUpValue	int	✓	1	1 ~ 2147483646	Amount to count up
maxValue	int			1 ~ 2147483646	Maximum value allowed to count up

Result

	Type	Description
item	EzCounter	Counter with increased count

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type	Base Type	Description
OverflowException	BadRequestException	The maximum number of times limit has been reached.

Implementation Example

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.Overflow 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

Get a count limit counter associated with a game player by specifying the name of the count limit and the name of the counter

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name
limitName	string	✓	~ 128 chars	Name of limit model
counterName	string	✓	~ 128 chars	Counter Name
accessToken	string	✓	~ 128 chars	Access token

Result

	Type	Description
item	EzCounter	Counter

Implementation Example

    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;
    }

Value change event handling

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Limit::Model::FCounter> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listCounters

Get list of frequency limit counters tied to game players

The name of the frequency limit can be omitted.

Request

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name
limitName	string			~ 128 chars	Limit Model Name
accessToken	string	✓		~ 128 chars	Access token
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzCounter>	List of Counter
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

    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());
    }

Value change event handling

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeCounters(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeCounters(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeCounters(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeCounters(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

getLimitModel

Get the limit model by specifying the limit name

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name
limitName	string		✓		~ 128 chars	Limit Model Name

Result

	Type	Description
item	EzLimitModel	Limit Model

Implementation Example

    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;
    }

Value change event handling

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).LimitModel(
        limitName: "limit-model-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Limit::Model::FLimitModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listLimitModels

Get list of limit models

Request

	Type	Condition	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name

Result

	Type	Description
items	List<EzLimitModel>	List of Limit Model

Implementation Example

    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());
    }

Value change event handling

    var domain = gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeLimitModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeLimitModels(callbackId);

    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeLimitModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeLimitModels(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.