GS2-Buff
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 how much to increase or decrease each parameter is defined. Rate Add", “Mul” and “Value Add” are available for defining correction values. Rate Add" and “Mul” are operations on the coefficient of the correction value. Value Add" is an operation that directly adds values, not coefficients, and “Value Add 5” gives a correction value of +5. Value Add" can only be applied to model or action values, not to Transaction Actions.
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 |
|---|---|---|
| Rate Add | 0.2 | 1 |
| Mul | 1.5 | 2 |
| Rate 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.
Correction calculations involving Value Add
If a correction value contains a “Value Add,” the correction calculation is calculated once before the priority at which the “Value Add” is defined, and then the value is added to the calculated value.
| Correction Value Type | Correction Value | Application Priority |
|---|---|---|
| Rate Add | 0.2 | 1 |
| Mul | 1.5 | 2 |
| Value Add | 2 | 3 |
| Rate Add | 0.2 | 4 |
In this case, the calculation of correction values up to just before the appearance of Value Add is performed first.
1.0 + 0.2 = 1.2
1.2 * 1.5 = 1.8
This correction value is then applied once to the input value. For example, if the input is 10, multiply by 1.8 and the corrected value is 18. The “Value Add” of +2 is then applied to the corrected value, resulting in a corrected value of 20.
The calculation of the corrected value is then performed immediately after the appearance of Value Add.
1.0 + 0.2 = 1.2
This correction value is then applied once to the input value. If the input is 10, it is multiplied by 1.2 and the corrected value is 12. Add this value to the corrected value after “Value Add”.
20 + 12 = 32
Now the final corrected value for an input of 10 is 32.
The entire equation can be summarized as follows The input value is x.
((x(1.0 + 0.2) * 1.5) + 2) + (1.0 + 0.2)
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