GS2-Limit

Number of times limit function

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

Tier	Cost required to recover	Number of times you can perform
Tier.1	5	10
Tier.2	10	10
Tier.3	20	10
Tier.4	40	10

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

Tier	counter name	counter increase	maximum counter value	cost required to recover
Tier.1	RecoveryStaminaCounter	1	10	5
Tier.2	RecoveryStaminaCounter	1	20	10
Tier.3	RecoveryStaminaCounter	1	30	20
Tier.4	RecoveryStaminaCounter	1	40	40

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

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

Get counter values

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

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

Force counter reset

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

Detailed reference.

API Reference