GS2-Buff SDK for Game Engine API Reference
Model
EzBuffEntryModel
Buff Entry Model
The amount of buff is managed by BuffEntryModels, and it is possible to associate multiple BuffEntryModels with a specific target entry.
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 is an instruction that multiplies the buff application rate. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and 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 holding period.
| Type | Condition | Required | Default | Value Limits | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 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. | |||||||||||
| 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).
| |||||||||||
| targetModel | EzBuffTargetModel | {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 | EzBuffTargetAction | {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” | ||||||||||
| 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.
| |||||||||||
| applyPeriodScheduleEventId | string | ~ 1024 chars | Event holding 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. |
EzBuffTargetModel
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 | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| targetModelName | String Enum enum { "Gs2Exchange:RateModel", "Gs2Exchange:IncrementalRateModel", "Gs2Experience:Status", "Gs2Formation:Mold", "Gs2Idle:Status", "Gs2Idle:CategoryModel", "Gs2Inventory:Inventory", "Gs2LoginReward:BonusModel", "Gs2Mission:MissionTaskModel", "Gs2Quest:QuestModel", "Gs2Showcase:DisplayItem", "Gs2Showcase:RandomDisplayItemModel", "Gs2SkillTree:NodeModel", "Gs2Stamina:Stamina", } | ✓ | Types of model 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<EzBuffTargetGrn> | ✓ | 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. |
EzBuffTargetAction
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 | Condition | Required | Default | 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", } | ✓ | Types of action 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<EzBuffTargetGrn> | ✓ | 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. |
EzBuffTargetGrn
GRN pattern that defines 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. |
Methods
getBuffEntryModel
Get a buff definition by name
Retrieves a single buff entry model by specifying its name. The returned information includes the application method (Rate Add / Mul / Value Add), what the buff targets, its priority, and the linked event period if configured.
Use this to display the details of a specific buff, such as its effect description or active period.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| buffEntryName | string | ✓ | ~ 128 chars | Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzBuffEntryModel | Buff Entry Model |
Implementation Example
var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
).BuffEntryModel(
buffEntryName: "character-level"
);
var item = await domain.ModelAsync(); var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
).BuffEntryModel(
buffEntryName: "character-level"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Buff->Namespace(
"namespace-0001" // namespaceName
)->BuffEntryModel(
"character-level" // buffEntryName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
).BuffEntryModel(
buffEntryName: "character-level"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
).BuffEntryModel(
buffEntryName: "character-level"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Buff->Namespace(
"namespace-0001" // namespaceName
)->BuffEntryModel(
"character-level" // buffEntryName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Buff::Model::FBuffEntryModel> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listBuffEntryModels
Get a list of buff definitions
Retrieves all buff entry models registered in this namespace. Each buff entry model defines a single buff effect — what it targets (e.g., a stat on a model or an action parameter), how it is applied (Rate Add / Mul / Value Add), its priority, and optionally an event period during which it is active.
Use this to display available buffs in the game UI or to check which buffs are currently configured.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzBuffEntryModel> | List of Buff Entry Models |
Implementation Example
var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.BuffEntryModelsAsync(
).ToListAsync(); var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.BuffEntryModels(
);
List<EzBuffEntryModel> items = new List<EzBuffEntryModel>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
} const auto Domain = Gs2->Buff->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->BuffEntryModels(
);
TArray<Gs2::UE5::Buff::Model::FEzBuffEntryModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeBuffEntryModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBuffEntryModels(callbackId); var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeBuffEntryModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBuffEntryModels(callbackId); const auto Domain = Gs2->Buff->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeBuffEntryModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeBuffEntryModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
applyBuff
Apply buffs to the current player
Evaluates all buff entries registered in this namespace and applies the matching ones to the player. For example, you can set up buffs such as “double EXP gain during an event” or “+10% gold drop rate when a certain item is owned.”
There are three application methods:
- Rate Add: Adds to the multiplier (e.g., base 1.0 + 0.2 = 1.2x)
- Mul: Multiplies the current multiplier (e.g., multiplier * 0.5)
- Value Add: Adds a flat value after all rate calculations
Buffs linked to a GS2-Schedule event are only active during that event period. Multiple buffs are applied in priority order (lower number = higher priority).
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| items | List<EzBuffEntryModel> | List of applied buffs |
| newContextStack | string | Context stack after applying buff |
Implementation Example
var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Buff(
);
var result = await domain.ApplyBuffAsync(
);
var item = await result.ModelAsync(); var domain = gs2.Buff.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Buff(
);
var future = domain.ApplyBuffFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Buff->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Buff(
);
const auto Future = Domain->ApplyBuff(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();