API Reference of GS2-Buff SDK for Game Engine

Model

EzBuffEntryModel

Buff Model

The amount of buff is managed by BuffEntryModel, and it is possible to associate multiple BuffEntryModels with a specific entry. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority, the higher the priority.

There are two types of buff application methods, “Add” and “Mul”. Add is an instruction to add to the buff application rate, and Mul is an instruction to multiply the buff application rate. The default rate is 1.0, and setting Add 0.2 will make the buff application rate 1.2. Setting Mul 0.5 will make the buff application rate 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	Require	Limitation	Description
name	string	✓	~ 128 chars	Buff entity name
metadata	string		~ 2048 chars	metadata
targetType	enum { “model”, “action” }	✓	~ 128 chars	Type of target to apply buff
targetModel	EzBuffTargetModel	{targetType} == “model”		Model to apply buff
targetAction	EzBuffTargetAction	{targetType} == “action”		Action to apply buff
expression	enum { “rate_add”, “mul”, “value_add” }	✓	~ 128 chars	Application type of buff
applyPeriodScheduleEventId	string		~ 1024 chars	Event ID to apply buff

Enumeration type definition to specify as targetType

Enumerator String Definition	Description
model	Model
action	Action

Enumeration type definition to specify as expression

Enumerator String Definition	Description
rate_add	Rate Add
mul	Mul
value_add	Value Add

EzBuffTargetModel

Buff Target Model

	Type	Require	Limitation	Description
targetModelName	enum { "Gs2Exchange:RateModel", "Gs2Exchange:IncrementalRateModel", "Gs2Experience:Status", "Gs2Formation:Mold", "Gs2Idle:CategoryModel", "Gs2Idle:Status", "Gs2Inventory:Inventory", "Gs2LoginReward:BonusModel", "Gs2Mission:MissionTaskModel", "Gs2Quest:QuestModel", "Gs2Showcase:DisplayItem", "Gs2Showcase:RandomDisplayItemModel", "Gs2SkillTree:NodeModel", "Gs2Stamina:Stamina", }	✓	~ 128 chars	Types of model to apply buffs
targetFieldName	string	✓	~ 64 chars	Field name to which the buff is applied
conditionGrns	List<EzBuffTargetGrn>	✓	1 ~ 10 items	List of buff application condition GRNs
rate	float	✓	~ 1000000	Rate

EzBuffTargetAction

Buff Target Action

	Type	Require	Limitation	Description
targetActionName	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", }	✓	~ 128 chars	Types of action to apply buffs
targetFieldName	string	✓	~ 64 chars	Field name to which the buff is applied
conditionGrns	List<EzBuffTargetGrn>	✓	1 ~ 10 items	List of buff application condition GRNs
rate	float	✓	~ 1000000	Rate

EzBuffTargetGrn

Buff Target GRN pattern

	Type	Require	Default	Limitation	Description
targetModelName	string	✓		~ 64 chars	Buff application condition model name
targetGrn	string	✓		~ 1024 chars	Buff application condition GRN

Methods

getBuffEntryModel

Get buff rate model information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
buffEntryName	string	✓		~ 128 chars	Buff entity name

Result

	Type	Description
item	EzBuffEntryModel	Buff entity 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"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    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 called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listBuffEntryModels

Get list of buff rate model information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name

Result

	Type	Description
items	List<EzBuffEntryModel>	List of buff rate 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"
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

applyBuff

Perform buff

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id

Result

	Type	Description
items	List<EzBuffEntryModel>	List of applied buff models
newContextStack	string	Request of context in which buff is applied

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();