GS2-Enhance SDK for Game Engine API Reference
Models
EzProgress
Enhance Progress
It is created when enhancement starts and deleted when enhancement ends.
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 enhancement information maintained by the entity.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ |
UUID | ~ 36 chars | Progress 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. |
|
| rateName | string | ✓ |
~ 128 chars | Enhancement 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. |
||
| propertyId | string | ✓ |
~ 1024 chars | Property 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. |
||
| experienceValue | long | ✓ |
0 ~ 9223372036854775805 | Experience 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. |
||
| rate | float | ✓ |
0 ~ 100.0 | Experience 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.
targetInventoryModelId specifies the inventory model that holds the items to be enhanced, and materialInventoryModelId the inventory model that holds the items usable as material.
These can be separate inventory models, so an arrangement in which characters are the target and enhancement-only items are the material is possible.
The experience each material grants is written in the metadata of its item model, and acquireExperienceHierarchy tells GS2-Enhance where in that JSON it is stored.
For a structure such as { "aaa": { "bbb": { "experienceValue": 100 } } }, specify [ "aaa", "bbb", "experienceValue" ]. Up to 10 levels can be specified.
The gained experience is added to GS2-Experience, on the experience model specified by experienceModelId.
The property ID it is added to is the property ID of the target item with acquireExperienceSuffix appended, so a single item can hold several kinds of experience, such as level for the character level and like for affection.
bonusRates defines a weighted draw over the bonus multipliers applied to the gained experience.
Each entry holds a multiplier (1.5 meaning 150%) and a draw weight, one entry is chosen by weighted draw on each enhancement, and up to 1,000 entries can be registered.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ |
~ 128 chars | Enhancement Rate Model name Unique Enhancement Rate Model 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. |
|||
| targetInventoryModelId | string | ✓ |
~ 1024 chars | GS2-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. |
||
| acquireExperienceSuffix | string | ✓ |
~ 1024 chars | Suffix 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). |
||
| materialInventoryModelId | string | ✓ |
~ 1024 chars | GS2-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. |
||
| acquireExperienceHierarchy | List<string> | 0 ~ 10 items | Hierarchical 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. |
|||
| experienceModelId | string | ✓ |
~ 1024 chars | GS2-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.
A limit break here is an enhancement that raises the grade managed by GS2-Grade by consuming duplicates of the same item as material. Raising the grade raises the rank cap on the GS2-Experience side, which lets the target be grown to a higher level.
targetInventoryModelId specifies the GS2-Inventory inventory model that holds the items eligible for a limit break.
Both the item being unleashed and the duplicates consumed as material must belong to this inventory model.
gradeModelId specifies the GS2-Grade grade model that tracks the grade of the target item; the grade is raised by 1 on a successful limit break.
gradeEntries defines, for each grade, how many duplicates must be consumed to reach it, and between 1 and 1,000 entries can be registered.
Setting, for example, 1 duplicate for grade 1 and 3 duplicates for grade 2 lets you control the cost of each limit break step individually.
A resource consumed as material is discarded together with whatever it held. Even when the material holds experience or other resources, they are not carried over to the target, so convert them into a resource for handover beforehand if that is required.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ |
~ 128 chars | Unleash Rate Model name Unique Unleash Rate Model 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. |
|||
| targetInventoryModelId | string | ✓ |
~ 1024 chars | GS2-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. |
||
| gradeModelId | string | ✓ |
~ 1024 chars | Grade 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. |
||
| groupKeyHierarchy | List<string> | [] | 0 ~ 10 items | Hierarchy of the JSON data that stores the group key in the ItemModel metadata The group key classifies item models, such as the equipment slot, and is used by recipes to compare materials with the target. For metadata with a structure like { “unleash”: { “group”: “weapon” } }, specify [ “unleash”, “group” ]. The value must be a string. Required when a recipe uses “Same Group” or targetGroupKeys. |
||
| gradeEntries | List<EzUnleashRateEntryModel> | ✓ |
1 ~ 1000 items | List 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.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| gradeValue | long | ✓ |
1 ~ 1000 | Target 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. |
||||||||
| type | string (enum) enum { “simple”, “recipe” } |
“simple” | Type of material condition “Simple (simple)” consumes needCount duplicates of the same item model as the target. This is the conventional behavior. “Recipe (recipe)” lets the player choose one of the recipes, and consumes the materials defined by the chosen recipe.
|
|||||||||
| needCount | int | {type} == “simple” | ✓* |
1 ~ 1000 | How 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. * Required if type is “simple” |
|||||||
| recipes | List<EzUnleashRecipe> | {type} == “recipe” | ✓* |
1 ~ 10 items | Recipes Used when type is “Recipe”. The player chooses one of these recipes when executing an unleash. * Required if type is “recipe” |
EzUnleashRecipe
Unleash Recipe
One way to raise the grade by one step. When a grade entry has several recipes, the player chooses one of them, and all the materials of the chosen recipe are required.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ |
~ 128 chars | Recipe name A name unique within the grade entry. The player specifies the recipe by this name when executing an unleash. |
||
| 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. |
|||
| targetGroupKeys | List<string> | [] | 0 ~ 10 items | Group keys of the targets this recipe can be used for When empty, the recipe can be used for any target. When set, the recipe can be used only when the group key of the target’s item model is included. The group key is read from the item model metadata using groupKeyHierarchy of the Unleash Rate Model. |
||
| materials | List<EzUnleashMaterial> | ✓ |
1 ~ 10 items | Materials required by this recipe All the materials are consumed when this recipe is used. |
EzUnleashMaterial
Unleash Material
Defines one kind of material required by a recipe. “Individual (individual)” consumes item sets chosen by the player, such as duplicate equipment. “Quantity (quantity)” consumes a quantity of an item decided by the setting, such as a general-purpose enhancement material.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ |
~ 128 chars | Material name A name unique within the recipe. When executing an unleash, the player specifies the item sets for each individual material by this name. |
||||||||
| materialType | string (enum) enum { “individual”, “quantity” } |
✓ |
Type of material “Individual (individual)” consumes item sets chosen by the player. “Quantity (quantity)” consumes a quantity of an item decided by the setting.
|
|||||||||
| individualSetting | EzUnleashIndividualMaterialSetting | {materialType} == “individual” | ✓* |
Individual material setting Used when materialType is “Individual”. * Required if materialType is “individual” |
||||||||
| quantitySetting | EzUnleashQuantityMaterialSetting | {materialType} == “quantity” | ✓* |
Quantity material setting Used when materialType is “Quantity”. * Required if materialType is “quantity” |
EzUnleashIndividualMaterialSetting
Individual Material Setting
Defines a material that is consumed as individual item sets, such as a duplicate piece of equipment. The player chooses which item sets to consume, and each chosen item set must belong to the same inventory model as the item being unleashed. Because each individual can have its own grade in GS2-Grade, the grade of the material can also be made a condition.
| Type | Condition | Required | Default | Value Limits | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| matchType | string (enum) enum { “sameItem”, “sameGroup” } |
✓ |
How the material is matched against the target “Same Item (sameItem)” accepts only item sets of the same item model as the target. “Same Group (sameGroup)” accepts item sets whose item model has the same group key as the target’s item model. The group key is read from the item model metadata using groupKeyHierarchy of the Unleash Rate Model.
|
|||||||||||
| gradeCondition | string (enum) enum { “any”, “sameAsTarget”, “equal” } |
“any” | Grade condition of the material “Any (any)” does not check the grade of the material. “Same as Target (sameAsTarget)” requires the material to have the same grade as the target’s current grade. “Equal (equal)” requires the material to have the grade specified by gradeValue. The grade is verified in the transaction with GS2-Grade, using the grade model of the Unleash Rate Model.
|
|||||||||||
| gradeValue | long | {gradeCondition} == “equal” | ✓* |
0 ~ 1000 | Grade the material must have Used when gradeCondition is “Equal”. * Required if gradeCondition is “equal” |
|||||||||
| count | int | ✓ |
1 ~ 1000 | Number of item sets to consume The number of item sets the player must specify for this material. Each item set is consumed by one. |
EzUnleashQuantityMaterialSetting
Quantity Material Setting
Defines a material that is consumed by quantity, such as a general-purpose enhancement material. The player does not choose the item; the item model to consume is decided by this setting, and the specified quantity is consumed. Both GS2-Inventory standard inventories and simple inventories can be used.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| matchType | string (enum) enum { “sameGroup”, “specified” } |
✓ |
How the item model to consume is decided “Same Group (sameGroup)” consumes the item model in materialInventoryModelId whose group key is the same as the target’s item model. Exactly one item model must have that group key. “Specified (specified)” consumes the item model specified by itemModelId.
|
|||||||||
| materialInventoryModelId | string | {matchType} == “sameGroup” | ✓* |
~ 1024 chars | GS2-Inventory inventory model
GRN
to search for the material Used when matchType is “Same Group”. A simple inventory model GRN can also be specified. * Required if matchType is “sameGroup” |
|||||||
| itemModelId | string | {matchType} == “specified” | ✓* |
~ 1024 chars | GS2-Inventory item model
GRN
to consume Used when matchType is “Specified”. A simple item model GRN can also be specified. * Required if matchType is “specified” |
|||||||
| count | int | ✓ |
1 ~ 2147483645 | Quantity to consume |
EzConfig
Configuration
Configuration values applied to transaction variables
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ |
~ 64 chars | Name | ||
| value | string | ~ 51200 chars | Value |
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.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| materialItemSetId | string | ✓ |
~ 1024 chars |
GRN
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. |
||
| count | int | 1 | 0 ~ 2147483645 | Number 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
EzConsumeActionResult
Consume Action execution result
EzAcquireActionResult
Acquire Action execution result
EzTransactionResult
Transaction Execution Result
Result of a transaction executed using the server-side automatic execution feature
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ |
36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of Consume Action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List 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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| rateName | string | ✓ |
~ 128 chars | Enhancement Rate Model name Unique Enhancement Rate Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzRateModel | Enhancement 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;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).rate_model(
"character-level"
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultValue 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);var domain = ez.enhance.namespace_(
"namespace-0001"
).rate_model(
"character-level"
)
# Start event handling
var callback_id = domain.subscribe_model(func(value):
# Called when the value changes
# The value after the change is passed to "value".
pass
)
# Stop event handling
domain.unsubscribe_model(callback_id)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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listRateModels
List 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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzRateModel> | List of Enhancement 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);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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| rateName | string | ✓ |
~ 128 chars | Unleash Rate Model name Unique Unleash Rate Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzUnleashRateModel | Unleash 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;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).unleash_rate_model(
"character-level"
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultValue 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);var domain = ez.enhance.namespace_(
"namespace-0001"
).unleash_rate_model(
"character-level"
)
# Start event handling
var callback_id = domain.subscribe_model(func(value):
# Called when the value changes
# The value after the change is passed to "value".
pass
)
# Stop event handling
domain.unsubscribe_model(callback_id)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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listUnleashRateModels
List Unleash Rate Models
Retrieves all Unleash Rate Models registered in this Namespace. A Unleash 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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<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);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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| gameSession | GameSession | ✓ |
GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzProgress | Progress 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();var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
var async_result = await domain.delete_progress(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultend
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| gameSession | GameSession | ✓ |
GameSession | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Configuration values applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzProgress | progress information for enhancement |
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the reward granting process |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction Execution Result |
| acquireExperience | long | Amount of experience gained |
| bonusRate | float | Experience 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;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
var async_result = await domain.end(
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultgetProgress
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| gameSession | GameSession | ✓ |
GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzProgress | Progress 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;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultValue 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);var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
# Start event handling
var callback_id = domain.subscribe_model(func(value):
# Called when the value changes
# The value after the change is passed to "value".
pass
)
# Stop event handling
domain.unsubscribe_model(callback_id)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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| rateName | string | ✓ |
~ 128 chars | Enhancement 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. |
||
| targetItemSetId | string | ✓ |
~ 1024 chars | GRN of the Item Set to be enhanced | ||
| materials | List<EzMaterial> | 0 ~ 10 items | List of materials | |||
| gameSession | GameSession | ✓ |
GameSession | |||
| force | bool | false | If there is an enhancement that has already been started, it can be discarded and started, or | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Configuration values applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the enhancement initiation process |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction 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;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
var async_result = await domain.start(
"character-level", # rate_name
"item-set-0001", # target_item_set_id
[
Gs2EnhanceEzMaterial.new()
.with_material_item_set_id("material-0001")
.with_count(1),
], # materials
null, # force
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultenhance
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ |
~ 128 chars | Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| rateName | string | ✓ |
~ 128 chars | Enhancement Rate Model name Unique Enhancement Rate Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
||
| gameSession | GameSession | ✓ |
GameSession | |||
| targetItemSetId | string | ✓ |
~ 1024 chars | GRN of the Item Set to be enhanced | ||
| materials | List<EzMaterial> | ✓ |
1 ~ 10 items | List of Material | ||
| config | List<EzConfig> | [] | 0 ~ 32 items | Configuration values applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzRateModel | Enhancement Rate Model |
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to perform the enhancement process |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction Execution Result |
| acquireExperience | long | Amount of experience gained |
| bonusRate | float | Experience 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;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).enhance(
)
var async_result = await domain.enhance(
"rate-0001", # rate_name
"item-set-0001", # target_item_set_id
[
Gs2EnhanceEzMaterial.new()
.with_material_item_set_id("material-0001")
.with_count(1),
], # materials
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result