API Reference of GS2-Limit SDK for Game Engine

Model

EzCounter

Current value of frequency limit

	Type	Require	Default	Limitation	Description
counterId	string	✓		~ 1024 chars	Counter GRN
limitName	string	✓		~ 128 chars	Name of limit model
name	string	✓		~ 128 chars	Counter Name
count	int	✓	0	~ 2147483646	count value
createdAt	long	✓	Now		Datetime of creation (Unix time unit:milliseconds)
updatedAt	long	✓	Now		Datetime of last update (Unix time unit:milliseconds)

EzLimitModel

Limit model

The reset interval can be set for the limit. The reset interval can be selected from daily, weekly, monthly, or not reset.

The maximum number of times limit is not set in the master data. Because the system works like a step-up gacha, a product can be purchased when the purchase count counter is less than 3 times. A product that can be purchased when the aforementioned product cannot be purchased and the purchase count counter is less than 5 times. This is so that the maximum value can be changed depending on the context.

	Type	Require	Limitation	Description
limitModelId	string	✓	~ 1024 chars	Limit Model GRN
name	string	✓	~ 128 chars	Limit Model Name
metadata	string		~ 2048 chars	metadata
resetType	enum { “notReset”, “daily”, “weekly”, “monthly” }	✓	~ 128 chars	Reset timing
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.)
resetDayOfWeek	enum { “sunday”, “monday”, “tuesday”, “wednesday”, “thursday”, “friday”, “saturday” }	{resetType} == “weekly”	~ 128 chars	Day of the week to reset
resetHour	int	{resetType} in [“monthly”, “weekly”, “daily”]	~ 23	Reset hour

Enumeration type definition to specify as resetType

Enumerator String Definition	Description
notReset	Not resetting.
daily	Daily
weekly	Weekly
monthly	Monthly

Enumeration type definition to specify as resetDayOfWeek

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

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	Require	Default	Limitation	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	User Id
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.Model();
    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	Require	Limitation	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	User Id

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.Model();
    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.Model();
    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	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
limitName	string			~ 128 chars	Limit Model Name
accessToken	string	✓		~ 128 chars	User Id
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	Require	Default	Limitation	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.Model();
    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.Model();
    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	Require	Default	Limitation	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.