GS2-Enhance SDK for Game Engine API Reference

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

Model

EzProgress

Enhance Progress

It is created at the beginning of the enhance and deleted at the end.

When you exit the application in the middle of an enhance, this data will remain. It is possible to resume the game from the ongoing enhance information maintained by the entity.

TypeConditionRequiredDefaultValue LimitsDescription
namestring
UUID~ 36 charsProgress ID
Maintains a unique name for each enhance progress.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each enhance progress.
rateNamestring
~ 128 charsEnhancement Rate Model name
The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates.
propertyIdstring
~ 1024 charsProperty ID to be enhanced
The property ID of the GS2-Inventory item being enhanced. Identifies the specific item instance that will receive experience points upon completion of the enhancement.
experienceValuelong
0 ~ 9223372036854775805Experience value obtainable
The base experience value calculated from the consumed materials. This value is determined by summing the experience values defined in each material’s metadata, multiplied by the material quantity.
ratefloat
0 ~ 100.0Experience value scale factor
The bonus multiplier applied to the base experience value. Determined by weighted lottery from the Enhancement Rate Model’s bonus rates. A value of 1.0 means no bonus, while values greater than 1.0 represent a “great success” bonus (e.g., 1.5 for 150% experience).

EzRateModel

Enhancement Rate Model

The enhancement rate is data that defines the materials used for enhancement and the target of enhancement.

Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored.

A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity.

TypeConditionRequiredDefaultValue LimitsDescription
namestring
~ 128 charsEnhancement Rate Model name
Enhancement Rate 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.
targetInventoryModelIdstring
~ 1024 charsGS2-Inventory Inventory Model GRN usable for enhancement targets
Specifies the GS2-Inventory inventory model that holds the items eligible for enhancement. The item to be enhanced must belong to this inventory model.
acquireExperienceSuffixstring
~ 1024 charsSuffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience
A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity).
materialInventoryModelIdstring
~ 1024 charsGS2-Inventory Inventory Model GRN usable as enhancement material
Specifies the GS2-Inventory inventory model that holds the items usable as enhancement materials. The experience value each material provides is defined in the item model’s metadata using the JSON hierarchy specified by acquireExperienceHierarchy.
acquireExperienceHierarchyList<string>0 ~ 10 itemsHierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata
GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata.
For example, to define metadata with a structure like: { “aaa”: { “bbb”: { “experienceValue”: 100 } } } Specify it as: [ “aaa”, ‘bbb’, “experienceValue” ]
Details are explained in the Microservices Introduction / GS2-Enhance section.
experienceModelIdstring
~ 1024 charsGS2-Experience Experience Model GRN gained as a result of enhancement
Specifies the GS2-Experience experience model where the experience points obtained from enhancement are recorded. The experience is added to the property identified by combining the target item’s property ID with the acquireExperienceSuffix.

EzUnleashRateModel

Unleash Rate Model

Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step.

TypeConditionRequiredDefaultValue LimitsDescription
namestring
~ 128 charsUnleash Rate Model name
Unleash Rate 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.
targetInventoryModelIdstring
~ 1024 charsGS2-Inventory Inventory Model GRN usable for unleash targets
Specifies the GS2-Inventory inventory model that holds the items eligible for limit breaking. The item to be unleashed and the duplicate items consumed as material must both belong to this inventory model.
gradeModelIdstring
~ 1024 charsGrade Model GRN
Specifies the GS2-Grade grade model that tracks the limit break level of the target item. When a limit break is successfully performed, the item’s grade is incremented in this grade model.
gradeEntriesList<EzUnleashRateEntryModel>
1 ~ 1000 itemsList of Grade Entry
Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. For example, grade 1 might require 1 duplicate, grade 2 might require 3 duplicates, and so on.

EzUnleashRateEntryModel

Unleash Rate Entry Model

Defines the material cost for a single grade level in a limit break progression. Each entry specifies which grade value it applies to and how many duplicate items of the same type must be consumed to achieve that grade.

TypeConditionRequiredDefaultValue LimitsDescription
gradeValuelong
1 ~ 1000Target grade
The grade value that this entry defines the cost for. When performing a limit break to this grade level, the number of items specified by needCount will be consumed.
needCountint
1 ~ 1000How many items of the same type to consume
The number of duplicate items that must be consumed to perform the limit break to the target grade. These items are of the same item model as the item being unleashed.

EzConfig

Configuration

Set values to be applied to transaction variables

TypeConditionRequiredDefaultValue LimitsDescription
keystring
~ 64 charsName
valuestring~ 51200 charsValue

EzMaterial

Enhance Material

Represents a material item to be consumed during an enhancement operation. Each material references a specific GS2-Inventory item set and specifies the quantity to consume. The experience value provided by the material is determined from the item model’s metadata.

TypeConditionRequiredDefaultValue LimitsDescription
materialItemSetIdstring
~ 1024 charsGRN of Item Set that will be used as materials for enhancement
References the specific GS2-Inventory item set to consume as enhancement material. The item must belong to the material inventory model specified in the Enhancement Rate Model.
countint10 ~ 2147483645Number of consumption
The quantity of this material item to consume. The total experience gained from this material is calculated by multiplying the per-item experience value (from the item model metadata) by this count.

EzVerifyActionResult

Verify Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2Dictionary:VerifyEntryByUserId",
"Gs2Distributor:IfExpressionByUserId",
"Gs2Distributor:AndExpressionByUserId",
"Gs2Distributor:OrExpressionByUserId",
"Gs2Enchant:VerifyRarityParameterStatusByUserId",
"Gs2Experience:VerifyRankByUserId",
"Gs2Experience:VerifyRankCapByUserId",
"Gs2Grade:VerifyGradeByUserId",
"Gs2Grade:VerifyGradeUpMaterialByUserId",
"Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
"Gs2Guild:VerifyIncludeMemberByUserId",
"Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId",
"Gs2Inventory:VerifyItemSetByUserId",
"Gs2Inventory:VerifyReferenceOfByUserId",
"Gs2Inventory:VerifySimpleItemByUserId",
"Gs2Inventory:VerifyBigItemByUserId",
"Gs2Limit:VerifyCounterByUserId",
"Gs2Matchmaking:VerifyIncludeParticipantByUserId",
"Gs2Mission:VerifyCompleteByUserId",
"Gs2Mission:VerifyCounterValueByUserId",
"Gs2Ranking2:VerifyGlobalRankingScoreByUserId",
"Gs2Ranking2:VerifyClusterRankingScoreByUserId",
"Gs2Ranking2:VerifySubscribeRankingScoreByUserId",
"Gs2Schedule:VerifyTriggerByUserId",
"Gs2Schedule:VerifyEventByUserId",
"Gs2SerialKey:VerifyCodeByUserId",
"Gs2Stamina:VerifyStaminaValueByUserId",
"Gs2Stamina:VerifyStaminaMaxValueByUserId",
"Gs2Stamina:VerifyStaminaRecoverIntervalMinutesByUserId",
"Gs2Stamina:VerifyStaminaRecoverValueByUserId",
"Gs2Stamina:VerifyStaminaOverflowValueByUserId",
}
Type of action to be executed in the Verify Action
verifyRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
verifyResultstring~ 1048576 charsResult payload

EzConsumeActionResult

Consume Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2AdReward:ConsumePointByUserId",
"Gs2Dictionary:DeleteEntriesByUserId",
"Gs2Enhance:DeleteProgressByUserId",
"Gs2Exchange:DeleteAwaitByUserId",
"Gs2Experience:SubExperienceByUserId",
"Gs2Experience:SubRankCapByUserId",
"Gs2Formation:SubMoldCapacityByUserId",
"Gs2Grade:SubGradeByUserId",
"Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
"Gs2Inbox:OpenMessageByUserId",
"Gs2Inbox:DeleteMessageByUserId",
"Gs2Inventory:ConsumeItemSetByUserId",
"Gs2Inventory:ConsumeSimpleItemsByUserId",
"Gs2Inventory:ConsumeBigItemByUserId",
"Gs2JobQueue:DeleteJobByUserId",
"Gs2Limit:CountUpByUserId",
"Gs2LoginReward:MarkReceivedByUserId",
"Gs2Mission:ReceiveByUserId",
"Gs2Mission:BatchReceiveByUserId",
"Gs2Mission:DecreaseCounterByUserId",
"Gs2Mission:ResetCounterByUserId",
"Gs2Money:WithdrawByUserId",
"Gs2Money:RecordReceipt",
"Gs2Money2:WithdrawByUserId",
"Gs2Money2:VerifyReceiptByUserId",
"Gs2Quest:DeleteProgressByUserId",
"Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId",
"Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId",
"Gs2Schedule:DeleteTriggerByUserId",
"Gs2SerialKey:UseByUserId",
"Gs2Showcase:IncrementPurchaseCountByUserId",
"Gs2SkillTree:MarkRestrainByUserId",
"Gs2Stamina:DecreaseMaxValueByUserId",
"Gs2Stamina:ConsumeStaminaByUserId",
}
Type of action to be executed in the Consume Action
consumeRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
consumeResultstring~ 1048576 charsResult payload

EzAcquireActionResult

Acquire Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2AdReward:AcquirePointByUserId",
"Gs2Dictionary:AddEntriesByUserId",
"Gs2Enchant:ReDrawBalanceParameterStatusByUserId",
"Gs2Enchant:SetBalanceParameterStatusByUserId",
"Gs2Enchant:ReDrawRarityParameterStatusByUserId",
"Gs2Enchant:AddRarityParameterStatusByUserId",
"Gs2Enchant:SetRarityParameterStatusByUserId",
"Gs2Enhance:DirectEnhanceByUserId",
"Gs2Enhance:UnleashByUserId",
"Gs2Enhance:CreateProgressByUserId",
"Gs2Exchange:ExchangeByUserId",
"Gs2Exchange:IncrementalExchangeByUserId",
"Gs2Exchange:CreateAwaitByUserId",
"Gs2Exchange:AcquireForceByUserId",
"Gs2Exchange:SkipByUserId",
"Gs2Experience:AddExperienceByUserId",
"Gs2Experience:SetExperienceByUserId",
"Gs2Experience:AddRankCapByUserId",
"Gs2Experience:SetRankCapByUserId",
"Gs2Experience:MultiplyAcquireActionsByUserId",
"Gs2Formation:AddMoldCapacityByUserId",
"Gs2Formation:SetMoldCapacityByUserId",
"Gs2Formation:AcquireActionsToFormProperties",
"Gs2Formation:SetFormByUserId",
"Gs2Formation:AcquireActionsToPropertyFormProperties",
"Gs2Friend:UpdateProfileByUserId",
"Gs2Grade:AddGradeByUserId",
"Gs2Grade:ApplyRankCapByUserId",
"Gs2Grade:MultiplyAcquireActionsByUserId",
"Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
"Gs2Idle:SetMaximumIdleMinutesByUserId",
"Gs2Idle:ReceiveByUserId",
"Gs2Inbox:SendMessageByUserId",
"Gs2Inventory:AddCapacityByUserId",
"Gs2Inventory:SetCapacityByUserId",
"Gs2Inventory:AcquireItemSetByUserId",
"Gs2Inventory:AcquireItemSetWithGradeByUserId",
"Gs2Inventory:AddReferenceOfByUserId",
"Gs2Inventory:DeleteReferenceOfByUserId",
"Gs2Inventory:AcquireSimpleItemsByUserId",
"Gs2Inventory:SetSimpleItemsByUserId",
"Gs2Inventory:AcquireBigItemByUserId",
"Gs2Inventory:SetBigItemByUserId",
"Gs2JobQueue:PushByUserId",
"Gs2Limit:CountDownByUserId",
"Gs2Limit:DeleteCounterByUserId",
"Gs2LoginReward:DeleteReceiveStatusByUserId",
"Gs2LoginReward:UnmarkReceivedByUserId",
"Gs2Lottery:DrawByUserId",
"Gs2Lottery:ResetBoxByUserId",
"Gs2Mission:RevertReceiveByUserId",
"Gs2Mission:IncreaseCounterByUserId",
"Gs2Mission:SetCounterByUserId",
"Gs2Money:DepositByUserId",
"Gs2Money:RevertRecordReceipt",
"Gs2Money2:DepositByUserId",
"Gs2Quest:CreateProgressByUserId",
"Gs2Schedule:TriggerByUserId",
"Gs2Schedule:ExtendTriggerByUserId",
"Gs2Script:InvokeScript",
"Gs2SerialKey:RevertUseByUserId",
"Gs2SerialKey:IssueOnce",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
}
Type of action to be executed in the Acquire Action
acquireRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
acquireResultstring~ 1048576 charsResult payload

EzTransactionResult

Transaction execution results

Result of a transaction executed using the server-side automatic transaction execution feature

TypeConditionRequiredDefaultValue LimitsDescription
transactionIdstring
36 ~ 36 charsTransaction ID
verifyResultsList<EzVerifyActionResult>0 ~ 10 itemsList of verify action execution results
consumeResultsList<EzConsumeActionResult>[]0 ~ 10 itemsList of Consume Action execution results
acquireResultsList<EzAcquireActionResult>[]0 ~ 100 itemsList of Acquire Action execution results

Methods

getRateModel

Get an enhancement rate model by name

Retrieves a single enhancement rate model by specifying its name. The returned information includes which inventory the target item belongs to, which inventory the materials come from, how experience is calculated from materials, and the bonus rate probability table. Use this to display the details of a specific enhancement recipe — for example, showing the material requirements and possible bonus rates on a weapon’s enhance screen.

Request

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

Result

TypeDescription
itemEzRateModelEnhanced Rate Model

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->RateModel(
        "character-level" // rateName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "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.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "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->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->RateModel(
        "character-level" // rateName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Enhance::Model::FRateModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listRateModels

Get a list of enhancement rate models

Retrieves all enhancement rate models registered in this namespace. A rate model defines an enhancement recipe — which items can be used as materials, how much experience each material gives, and whether there’s a chance for a bonus multiplier. Use this to build the enhancement UI, for example to show which weapons can be enhanced and what materials they accept.

Request

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

Result

TypeDescription
itemsList<EzRateModel>List of Enhanced Rate Models

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.RateModelsAsync(
    ).ToListAsync();
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.RateModels(
    );
    List<EzRateModel> items = new List<EzRateModel>();
    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->Enhance->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->RateModels(
    );
    TArray<Gs2::UE5::Enhance::Model::FEzRateModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeRateModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeRateModels(callbackId);
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeRateModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeRateModels(callbackId);
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeRateModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeRateModels(CallbackId);

getUnleashRateModel

Get a limit break rate model by name

Retrieves a single limit break (unleash) rate model by specifying its name. The returned information includes the target inventory, the grade model used for tracking the item’s grade, and the list of grade entries that define the material requirements for each grade level. Use this to display the details of a specific limit break recipe — for example, showing “Grade 1 -> 2: requires 1 duplicate” and “Grade 2 -> 3: requires 2 duplicates” on an item detail screen.

Request

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

Result

TypeDescription
itemEzUnleashRateModelUnleash Rate Model

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).UnleashRateModel(
        rateName: "character-level"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).UnleashRateModel(
        rateName: "character-level"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->UnleashRateModel(
        "character-level" // rateName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).UnleashRateModel(
        rateName: "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.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).UnleashRateModel(
        rateName: "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->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->UnleashRateModel(
        "character-level" // rateName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Enhance::Model::FUnleashRateModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

listUnleashRateModels

Get a list of limit break rate models

Retrieves all limit break (unleash) rate models registered in this namespace. A limit break rate model defines how to raise an item’s grade (level cap) — for example, consuming duplicate copies of the same weapon to increase its maximum level. Each model specifies the materials required at each grade level, so the cost can increase as the item grows stronger. Use this to build a limit break UI that shows players which items can be limit-broken and what materials they need.

Request

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

Result

TypeDescription
itemsList<EzUnleashRateModel>List of Unleash Rate Model

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.UnleashRateModelsAsync(
    ).ToListAsync();
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.UnleashRateModels(
    );
    List<EzUnleashRateModel> items = new List<EzUnleashRateModel>();
    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->Enhance->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->UnleashRateModels(
    );
    TArray<Gs2::UE5::Enhance::Model::FEzUnleashRateModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeUnleashRateModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeUnleashRateModels(callbackId);
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeUnleashRateModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeUnleashRateModels(callbackId);
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeUnleashRateModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeUnleashRateModels(CallbackId);

deleteProgress

Cancel an in-progress enhancement

Deletes the progress of the player’s in-progress enhancement, effectively canceling it. Note that materials consumed during Start are NOT refunded — only the pending experience grant is canceled. Use this if the player wants to cancel an enhancement, or use it to clean up before starting a different enhancement. Alternatively, you can set force to true when calling Start to automatically discard any existing progress.

Request

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

Result

TypeDescription
itemEzProgressProgress information for enhancement

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var result = await domain.DeleteProgressAsync(
    );
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var future = domain.DeleteProgressFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Progress(
    );
    const auto Future = Domain->DeleteProgress(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

end

Complete an enhancement (2-phase flow)

Finishes the enhancement process that was started with the Start API. Takes the experience and bonus rate that were pre-calculated during Start and applies them to the target item. The progress is automatically deleted after completion. The result includes the acquired experience and bonus rate, so you can show a final result screen like “Enhancement complete! +1200 EXP”.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
configList<EzConfig>[]0 ~ 32 itemsSet values to be applied to transaction variables

Result

TypeDescription
itemEzProgressprogress information for enhancement
transactionIdstringIssued transaction ID
stampSheetstringStamp sheet used to execute the reward granting process
stampSheetEncryptionKeyIdstringCryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheetboolWhether automatic transaction execution is enabled
atomicCommitboolWhether to commit the transaction atomically
transactionstringIssued transaction
transactionResultEzTransactionResultTransaction execution result
acquireExperiencelongAmount of experience gained
bonusRatefloatExperience bonus multiplier (1.0 = no bonus)

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var result = await domain.EndAsync(
        config: null
    );
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var future = domain.EndFuture(
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Progress(
    );
    const auto Future = Domain->End(
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

getProgress

Get the current enhancement progress

Retrieves the progress of the player’s in-progress enhancement. The progress contains the rate model name, target item, materials used, the pre-calculated experience, and the drawn bonus rate. Use this to restore the enhancement confirmation screen if the player leaves and comes back — for example, to re-display “You will gain +1200 EXP (Great Success x1.5)”.

Request

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

Result

TypeDescription
itemEzProgressProgress information for the enhancement currently in the running

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Progress(
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    
    // 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.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    
    // 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->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Progress(
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Enhance::Model::FProgress> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

start

Start an enhancement (2-phase flow)

Begins the enhancement process by consuming materials and calculating the experience and bonus rate, but does NOT apply the experience yet. The calculated results are saved as progress, so you can show the player a preview — for example, “You will gain +1200 EXP (Great Success x1.5)” — before they confirm. After the player confirms, call End to actually apply the experience to the target item. If the player already has an in-progress enhancement, set force to true to discard it and start a new one.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
rateNamestring
~ 128 charsEnhancement Rate Model name
The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates.
targetItemSetIdstring
~ 1024 charsGRN for the enhanced Item Set
materialsList<EzMaterial>0 ~ 10 itemsList of materials
gameSessionGameSession
GameSession
forceboolfalseIf there is an enhancement that has already been started, it can be discarded and started, or
configList<EzConfig>[]0 ~ 32 itemsSet values to be applied to transaction variables

Result

TypeDescription
transactionIdstringIssued transaction ID
stampSheetstringStamp sheet used to execute the enhancement initiation process
stampSheetEncryptionKeyIdstringCryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheetboolWhether automatic transaction execution is enabled
atomicCommitboolWhether to commit the transaction atomically
transactionstringIssued transaction
transactionResultEzTransactionResultTransaction execution result

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var result = await domain.StartAsync(
        rateName: "character-level",
        targetItemSetId: "item-set-0001",
        materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
            new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
                MaterialItemSetId = "material-0001",
                Count = 1,
            },
        },
        force: null,
        config: null
    );
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var future = domain.StartFuture(
        rateName: "character-level",
        targetItemSetId: "item-set-0001",
        materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
            new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
                MaterialItemSetId = "material-0001",
                Count = 1,
            },
        },
        force: null,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Progress(
    );
    const auto Future = Domain->Start(
        "character-level", // rateName
        "item-set-0001", // targetItemSetId
        []
        {
            auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Enhance::Model::FEzMaterial>>>();
            v->Add(
                MakeShared<Gs2::UE5::Enhance::Model::FEzMaterial>()
                ->WithMaterialItemSetId(TOptional<FString>("material-0001"))
                ->WithCount(TOptional<int32>(1))
            );
            return v;
        }() // materials
        // force
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

enhance

Enhance an item

Consumes the specified materials to grant experience to the target item in a single step. The amount of experience gained is calculated based on the enhancement rate model, and a bonus multiplier may be drawn from the bonus rate probability table — for example, a “Great Success” that gives 1.5x experience. The result includes how much experience was gained and what bonus rate was applied, so you can display a result screen like “Weapon leveled up! +1200 EXP (Great Success x1.5)”. This is the simplest way to enhance — if you want to show the player the result before confirming, use the Start/End flow instead.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
rateNamestring
~ 128 charsEnhancement Rate Model name
Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
targetItemSetIdstring
~ 1024 charsGRN for the enhanced Item Set
materialsList<EzMaterial>
1 ~ 10 itemsList of Material
configList<EzConfig>[]0 ~ 32 itemsSet values to be applied to transaction variables

Result

TypeDescription
itemEzRateModelEnhanced Rate Model
transactionIdstringIssued transaction ID
stampSheetstringStamp sheet used to perform the enhancement process
stampSheetEncryptionKeyIdstringCryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheetboolWhether automatic transaction execution is enabled
atomicCommitboolWhether to commit the transaction atomically
transactionstringIssued transaction
transactionResultEzTransactionResultTransaction execution result
acquireExperiencelongAmount of experience gained
bonusRatefloatExperience bonus multiplier (1.0 = no bonus)

Implementation Example

    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Enhance(
    );
    var result = await domain.EnhanceAsync(
        rateName: "rate-0001",
        targetItemSetId: "item-set-0001",
        materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
            new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
                MaterialItemSetId = "material-0001",
                Count = 1,
            },
        },
        config: null
    );
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    var domain = gs2.Enhance.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Enhance(
    );
    var future = domain.EnhanceFuture(
        rateName: "rate-0001",
        targetItemSetId: "item-set-0001",
        materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
            new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
                MaterialItemSetId = "material-0001",
                Count = 1,
            },
        },
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    const auto Domain = Gs2->Enhance->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Enhance(
    );
    const auto Future = Domain->Enhance(
        "rate-0001", // rateName
        "item-set-0001", // targetItemSetId
        []
        {
            auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Enhance::Model::FEzMaterial>>>();
            v->Add(
                MakeShared<Gs2::UE5::Enhance::Model::FEzMaterial>()
                ->WithMaterialItemSetId(TOptional<FString>("material-0001"))
                ->WithCount(TOptional<int32>(1))
            );
            return v;
        }() // materials
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }