GS2-Buff Master Data Reference

Reference for the master data format and the models to be imported

Master Data Format

{
  "version": "2024-04-15",
  "buffEntryModels": [
    {
      "name": "[string]Buff Entry Model name",
      "metadata": "[string?]Metadata",
      "expression": "[string (enum)]Application type of buff",
      "targetType": "[string (enum)]Type of target to apply buff",
      "targetModel": {
        "targetModelName": "[string]Model type to apply buffs",
        "targetFieldName": "[string]Field name to which the buff is applied",
        "conditionGrns": [
          {
            "targetModelName": "[string]Buff application condition model name",
            "targetGrn": "[string]Buff application condition GRN"
          }
        ],
        "rate": "[float]Adjustment rate"
      },
      "targetAction": {
        "targetActionName": "[string]Action type to apply buffs",
        "targetFieldName": "[string]Field name to which the buff is applied",
        "conditionGrns": [
          {
            "targetModelName": "[string]Buff application condition model name",
            "targetGrn": "[string]Buff application condition GRN"
          }
        ],
        "rate": "[float]Rate"
      },
      "priority": "[int]Priority of buff application",
      "applyPeriodScheduleEventId": "[string?]Event period GRN to apply buff"
    }
  ]
}

	Type	Condition	Required	Default	Value Limits	Description
version	string		✓	2024-04-15		Format version of master data
buffEntryModels	List<BuffEntryModel>				~ 100 items	Buff Entry Model The amount of buff is managed by BuffEntryModels, and multiple Buff Entry Models can be associated with the same target. The application order of BuffEntryModel is managed by the `priority` of BuffEntryModel, and the smaller the value of `priority`, the higher the `priority`. Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times. BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period.

Models

BuffEntryModel

Buff Entry Model

The amount of buff is managed by BuffEntryModels, and multiple Buff Entry Models can be associated with the same target. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority, the higher the priority.

Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times.

BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period.

Type

Condition

Required

Default

Value Limits

Description

buffEntryModelId

string

~ 1024 chars

Buff Entry Model GRN

* Set automatically by the server

name

string

✓

~ 128 chars

Buff Entry Model name

Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

metadata

string

~ 2048 chars

Metadata

Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game.

expression

string (enum)
enum {
  “rate_add”,
  “mul”,
  “value_add”
}

✓

Application type of buff

Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations.

Definition	Description
“rate_add”	Add to adjustment rate
“mul”	Multiply the adjustment rate by the specified value
“value_add”	Directly add values (only numerical values for models or actions)

targetType

string (enum)
enum {
“model”,
“action”
}

✓

Type of target to apply buff

Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts).

Definition	Description
“model”	Model
“action”	Action

targetModel

BuffTargetModel

{targetType} == “model”

✓*

Model to apply buff

Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value.

* Required if targetType is “model”

targetAction

BuffTargetAction

{targetType} == “action”

✓*

Action to apply buff

Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value.

* Required if targetType is “action”

priority

int

✓

0 ~ 2147483646

Priority of buff application

Determines the order in which BuffEntryModels are evaluated. Entries with smaller values are evaluated first. When multiple buffs target the same field, the application order affects the final result due to the interaction between Rate Add and Mul operations.

applyPeriodScheduleEventId

string

~ 1024 chars

Event period GRN to apply buff

GRN of a GS2-Schedule event that controls when this buff is active. When specified, the buff is only applied during the event’s scheduled period. If not specified, the buff is always active.

BuffTargetModel

Buff Target Model

Defines the target GS2 resource model and field for buff application. Specifies which model’s field value should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.

	Type	Required	Value Limits	Description
targetModelName	string (enum) enum { }	✓		Model type to apply buffs
targetFieldName	string	✓	~ 64 chars	Field name to which the buff is applied The name of the numeric field on the target model whose value will be modified by the buff. For example, a field representing experience points, attack power, or other numerical attributes.
conditionGrns	List<BuffTargetGrn>	✓	1 ~ 10 items	List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource.
rate	float	✓	0 ~ 1000000	Adjustment rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the field value after rate calculations.

BuffTargetAction

Buff Target Action

Defines the target GS2 action and parameter for buff application. Specifies which action’s parameter should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.

	Type	Required	Value Limits	Description
targetActionName	string (enum) enum { "Gs2Experience:AddExperienceByUserId", "Gs2Experience:SubExperience", "Gs2Experience:SubExperienceByUserId", "Gs2Inventory:AcquireItemSetByUserId", "Gs2Inventory:ConsumeItemSet", "Gs2Inventory:ConsumeItemSetByUserId", "Gs2Inventory:AcquireSimpleItemsByUserId", "Gs2Inventory:ConsumeSimpleItems", "Gs2Inventory:ConsumeSimpleItemsByUserId", "Gs2Inventory:AcquireBigItemByUserId", "Gs2Inventory:ConsumeBigItem", "Gs2Inventory:ConsumeBigItemByUserId", "Gs2Limit:CountUp", "Gs2Limit:CountUpByUserId", "Gs2Money:DepositByUserId", "Gs2Money:Withdraw", "Gs2Money:WithdrawByUserId", "Gs2Money2:DepositByUserId", "Gs2Money2:Withdraw", "Gs2Money2:WithdrawByUserId", "Gs2Stamina:ConsumeStamina", "Gs2Stamina:ConsumeStaminaByUserId", "Gs2Stamina:RecoverStaminaByUserId", }	✓		Action type to apply buffs
targetFieldName	string	✓	~ 64 chars	Field name to which the buff is applied The name of the numeric parameter on the target action whose value will be modified by the buff. For example, a parameter representing acquire count, consume amount, or reward quantity.
conditionGrns	List<BuffTargetGrn>	✓	1 ~ 10 items	List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource.
rate	float	✓	0 ~ 1000000	Rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the parameter value after rate calculations.

BuffTargetGrn

GRN pattern that identifies the resources used as conditions for applying buffs

Specifies a GRN template with placeholders to identify which resource instance the buff should be applied to. The model name identifies the GS2 service model, and the GRN pattern contains context variables (e.g., region, ownerId, namespaceName) that are resolved at runtime to match the target resource.

	Type	Condition	Required	Default	Value Limits	Description
targetModelName	string		✓		~ 64 chars	Buff application condition model name The name of the GS2 service model used to resolve the condition GRN. This identifies which service’s resource model the GRN pattern refers to.
targetGrn	string		✓		~ 1024 chars	Buff application condition GRN A GRN template with context placeholders (e.g., {region}, {ownerId}) that is resolved at runtime to identify the specific resource instance targeted by the buff.