GS2-Buff

buffing function

GS2-Buff provides a centralised function to manage compensation and rewards for microservices provided by GS2, as well as corrections to the maximum value of user data. It can be used to realise functions such as increasing compensation for a limited period of time or increasing the maximum value of user data if the user is in a subscription contract state.

Buff entity.

This is the unit of correction to be added to each microservice. The base value is 1.0 and defines how much to increase or decrease for each parameter. Add and Mul are available for defining the correction value, where Add 1.5 will increase the correction value by 2.5 times and Mul 1.5 will increase the correction value by 1.5 times.

Application priority

The correction value can be set to an application priority. The correction values are calculated in order of priority, starting with the correction value with the lowest priority value. For example, if the following correction values are defined.

Correction value type	Correction value	Application priority
Add	0.2	1
Mul	1.5	2
Add	0.2	3

In this case, the calculation of the correction values is performed in the following order

1.0 + 0.2 = 1.2
1.2 * 1.5 = 1.8
1.8 + 0.2 = 2.0

The final correction value is then 2.0x.

Setting correction targets

There are two main types of buff correction targets: models and actions. Please refer to the documentation on buffing for each microservice to find out what models and actions can be set.

Models

Examples of models to be applied include.

GS2-Experience rank caps
GS2-Stamina Stamina maximum
GS2-Showcase acquisition actions
GS2-Showcase consumption actions

Actions

Examples of actions applied include

GS2-Experience amount of experience added
GS2-Stamina stamina recovery
GS2-Stamina stamina consumption

Setting the conditions for applying the correction

If applied to GS2-Showcase, to which DisplayItem is the correction value applied? If it is applied to GS2-Experience, to which Status should the correction value be applied? This parameter sets the application conditions.

Please refer to the documentation for each microservice buff to find out what application conditions can be set for each buff.

Models and GRNs

Specify the model and GRN for the applicability condition. Some buffs allow multiple models to be specified. For example, for GS2-Showcase, there is a pattern to specify the GRN of the Showcase in order to apply the correction to all DisplayItem in the Showcase, and A pattern that specifies the GRN of a DisplayItem to apply the correction only to a specific DisplayItem in the Showcase.

Multiple application conditions can be set for a buff, and if any of the conditions are met, the correction value will be applied. In other words, by setting multiple DisplayItem as applicable conditions for one buff entity, a single buff entity can define correction values for multiple DisplayItem.

How to apply corrections

Calling GS2-Buff’s ApplyBuff API results in a ‘context stack’ response. Every API provided by GS2 has an interface that allows you to set the context stack. The context stack responded to by GS2-Buff can be specified in each API call to apply buffs.

In some high-level SDKs, such as SDKs for game engines, the context stack specification is wrapped and does not need to be explicitly specified in some cases.

Scope of application of buffs

The scope of buffing is extensive, and buffing is also applied in the master data acquisition API. If the Master Data Acquisition API is called with the context stack specified, the value of the buffed state will be responded. If you want to annex the value of the unbuffed state in the game, you need to combine API accesses that do not grant context stacks.

Linking buff entities to GS2-Schedule

Buff information in the context stack retains its validity period. This means that if a buff entity has a GS2-Schedule event set as its validity period, the buff will automatically stop being applied when it falls outside the event period.

However, if the conditions for applying a new buff are changed or a new buff is added, you need to call ApplyBuff again to reflect the buff.

Expiry date of context stacks

Context stacks have an expiry date. After 24 hours from the time of the call to ApplyBuff, the context stack loses its effect.

ApplyBuff should be executed again within 24 hours, even if the conditions have not changed.

Example implementation

ApplyBuff

    var domain = gs2.Buff.Namespace(
        "buff"
    ).Me(
        GameSession
    ).Buff();
    gs2 = await domain.ApplyBuffAsync();

    // Accessed through a new gs2 object is processed with buffed values

Advanced Reference

[API reference](/api_reference/buff/