GS2-Enhance SDK for Game Engine API Reference
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.
| 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.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| 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. 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.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| 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. | ||
| 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. | ||
| needCount | int | ✓ | 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. |
EzConfig
Configuration
Set values to be 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 results
Result of a transaction executed using the server-side automatic transaction 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 Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rateName | string | ✓ | ~ 128 chars | Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzRateModel | Enhanced 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);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<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);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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 Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rateName | string | ✓ | ~ 128 chars | Unleash Rate Model name Unleash Rate Model-specific 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;
}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);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<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);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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 Namespace-specific 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();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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be 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;
}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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| 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;
}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);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
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 Namespace-specific 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 for the enhanced Item Set | ||
| 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 | Set values to be 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;
}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
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rateName | string | ✓ | ~ 128 chars | Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| targetItemSetId | string | ✓ | ~ 1024 chars | GRN for the enhanced Item Set | ||
| materials | List<EzMaterial> | ✓ | 1 ~ 10 items | List of Material | ||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzRateModel | Enhanced 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;
}