GS2-Limit

This mechanism is used to limit the number of times a player can act.

Counter

An entity used to represent the number of times a player can act. The count limit is achieved by a mechanism that allows the player to specify a maximum acceptable value when incrementing the counter and attempting to count up, so that if the maximum value is exceeded, the count up will fail and subsequent actions will fail. In this case, instead of setting a maximum value for the counter, you can set a maximum value for the incrementing action.

For example, consider the process of recovering stamina. In many games, there is a limit to the number of times you can recover your stamina in a day. And the more you recover, the higher cost required for recovery.

Such a specification can be expressed as follows

And this is taken as a count-up action with a count limit and the cost required for recovery is shown below.

The same counter is used for all tiers, and the lower the cost of recovery, the lower the maximum counter value.

In this way, the cheapest Tier.1 cannot be purchased first, forcing the purchase of Tier.2, and Tier.2 will eventually become unavailable, forcing you to purchase Tier.3.

Reset counters

Counters can have a reset cycle. There are the following types of reset cycles

• No reset
• Reset every day at X o’clock
• Reset every X days of the week at X o’clock
• Reset at X hours on X days of the month

The reset period for the frequency limit is defined in the master data called Limit Model.

Limit Model

Multiple counters can be stored under one limit model. Counter types do not need to be defined in the master data, but can be created and used by specifying counter names when performing counter operations.

Implementation example

Obtain a list of counters

• Game Engine:
• Unity
• Unreal Engine

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

    const auto Domain = Gs2->Limit->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Counters( // limitName
    );
    TArray<Gs2::UE5::Limit::Model::FEzCounterPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Get counter values

• Game Engine:
• Unity
• Unreal Engine

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

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

Raise counter value

It is not recommended to use this API to raise the counter. It is recommended to set the counter value increase as a consideration for executing a process for which you want to set a limit on the number of times, such as GS2-Exchange / GS2-Showcase / GS2-Quest.

• Game Engine:
• Unity
• Unreal Engine

    var result = await gs2.Limit.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Counter(
        limitName: "daily",
        counterName: "counter1"
    ).CountUpAsync(
        countUpValue: 1,
        maxValue: 100
    );

    const auto Domain = Gs2->Limit->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->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 false;
    const auto Result = Future2->GetTask().Result();

Force counter reset

Forced counter resets cannot be handled by the SDK for game engines.

Detailed Reference

• API Reference