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
• Reset every N days from a specified base date.

Registering master data allows you to configure data and behaviors available to microservices.

Master data types include the following:

• LimitModel: Reset cycles and upper limits

Master data can be registered via the management console. Additionally, you can set up workflows to reflect data from GitHub or register via CI using GS2-Deploy.

Buff-Based Adjustments

When integrated with GS2-Buff, buffs can adjust the maxValue for CountUp/CountUpByUserId, enabling temporary increases or decreases to upper limits.

Transaction Actions

GS2-Limit provides the following transaction actions:

• Verify Action: Verify counter value
• Consume Action: Increment counter value (Count up)
• Acquire Action: Decrement counter value (Count down), delete counter

By using “Decrement counter value (Count down)” as an acquire action, it is possible to perform processes such as recovering the number of limited actions (effectively restoring the consumed count) when a specific item is acquired or as a reward for achieving a mission. This facilitates the design of rewards that encourage continuous play.

Implementation example

Obtain a list of counters

    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

    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.

    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