GS2-Buff SDK for Game Engine API Reference

Specifications of models and API references for GS2-Buff SDK for Game Engine

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.

TypeConditionRequiredDefaultValue LimitsDescription
namestring
~ 128 charsBuff Entry Model name
Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
metadatastring~ 2048 charsMetadata
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.
targetTypeString 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).
DefinitionDescription
“model”Model
“action”Action
targetModelEzBuffTargetModel{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”
targetActionEzBuffTargetAction{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”
expressionString 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.
DefinitionDescription
“rate_add”Add to adjustment rate
“mul”Multiply by adjustment rate
“value_add”Directly add values (only numerical values for models or actions)
applyPeriodScheduleEventIdstring~ 1024 charsEvent 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.

TypeConditionRequiredDefaultValue LimitsDescription
targetModelNameString 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
targetFieldNamestring
~ 64 charsField 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.
conditionGrnsList<EzBuffTargetGrn>
1 ~ 10 itemsList 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.
ratefloat
0 ~ 1000000Adjustment 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.

TypeConditionRequiredDefaultValue LimitsDescription
targetActionNameString 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
targetFieldNamestring
~ 64 charsField 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.
conditionGrnsList<EzBuffTargetGrn>
1 ~ 10 itemsList 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.
ratefloat
0 ~ 1000000Rate
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.

TypeConditionRequiredDefaultValue LimitsDescription
targetModelNamestring
~ 64 charsBuff 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.
targetGrnstring
~ 1024 charsBuff 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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
buffEntryNamestring
~ 128 charsBuff Entry Model name
Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

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

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

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

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

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession

Result

TypeDescription
itemsList<EzBuffEntryModel>List of applied buffs
newContextStackstringContext 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();