GS2-Enchant SDK for Game Engine API Reference
Model
EzBalanceParameterStatus
Balance Parameter Status
Represents the actual parameter values drawn for a specific resource owned by a user. Each status is associated with a Balance Parameter Model and contains the concrete values assigned to each parameter slot after the drawing process.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| parameterName | string | ✓ | ~ 128 chars | Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. | ||
| propertyId | string | ✓ | ~ 1024 chars | Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. | ||
| parameterValues | List<EzBalanceParameterValue> | ✓ | 1 ~ 10 items | List of balance parameter values The concrete values assigned to each parameter slot after the drawing process. Each entry corresponds to a parameter slot defined in the model and contains the actual numeric value allocated. The sum of all values equals the total value specified in the model. |
EzRarityParameterStatus
Rarity Parameter Status
Represents the actual parameter values drawn for a specific resource owned by a user. Each status is associated with a Rarity Parameter Model and contains the concrete values selected through weighted lottery for each granted parameter slot.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| parameterName | string | ✓ | ~ 128 chars | Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. | ||
| propertyId | string | ✓ | ~ 1024 chars | Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. | ||
| parameterValues | List<EzRarityParameterValue> | 0 ~ 10 items | List of rarity parameter values The concrete parameter values selected through weighted lottery for each granted slot. The number of entries is determined by the parameter count draw, and each entry’s value is selected from the value model pool. May contain fewer entries than the maximum parameter count. |
EzBalanceParameterModel
Balance Parameter Model
Defines the drawing conditions for balance parameters.
Balance parameters distribute a fixed total value across multiple parameter slots. For example, a weapon with a total power of 100 might have ATK=60, DEF=30, SPD=10. The initial value strategy determines how values are assigned: average distributes evenly, while lottery randomly allocates the total across parameters.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). | ||||||||
| 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. | |||||||||
| totalValue | long | ✓ | 0 ~ 9223372036854775805 | Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. | ||||||||
| initialValueStrategy | String Enum enum { “average”, “lottery” } | “average” | Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations.
| |||||||||
| parameters | List<EzBalanceParameterValueModel> | ✓ | 1 ~ 10 items | Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. |
EzBalanceParameterValueModel
Balance Parameter Value Model
Defines a single parameter slot available within a balance parameter. Each entry specifies a named slot (e.g., ATK, DEF, SPD) that receives a portion of the total value during the drawing process.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 64 chars | Name The identifier for this parameter slot (e.g., ATK, DEF, SPD). Must be unique within the balance parameter model. Used as the key when storing and retrieving drawn parameter values. | ||
| metadata | string | ~ 512 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. |
EzRarityParameterModel
Rarity Parameter Model
Defines the drawing conditions for rarity parameters. Rarity parameters use a weighted lottery system to determine both the number of parameters granted and the specific values assigned. First, the number of parameter slots to fill is determined by a weighted draw from the parameter count model list. Then, each slot’s value is selected by a weighted draw from the parameter value model list, providing randomized equipment attributes with controlled probability distributions.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). | ||
| 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. | |||
| maximumParameterCount | int | ✓ | 1 ~ 10 | Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. | ||
| parameterCounts | List<EzRarityParameterCountModel> | ✓ | 1 ~ 10 items | Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. | ||
| parameters | List<EzRarityParameterValueModel> | ✓ | 1 ~ 1000 items | Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. |
EzRarityParameterCountModel
Rarity Parameter Count Model
Defines a single entry in the weighted lottery for determining how many parameter slots are granted to a resource. Each entry pairs a parameter count with a draw weight, allowing fine-grained control over the probability distribution of parameter quantities.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| count | int | ✓ | 0 ~ 10 | Count The number of parameter slots to grant when this entry is drawn. For example, a count of 3 means the resource will receive 3 parameter values selected from the value model pool. | ||
| weight | int | ✓ | 1 ~ 2147483646 | Draw Weight The relative weight used in the weighted lottery when determining the parameter count. Higher values increase the probability of this count being selected. The actual probability is this weight divided by the sum of all weights in the count model list. |
EzRarityParameterValueModel
Rarity Parameter Value Model
Defines a single entry in the weighted lottery pool for rarity parameter values. Each entry specifies a parameter name, game-defined resource details, and a draw weight that determines its selection probability relative to other entries in the pool.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 64 chars | Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. | ||
| metadata | string | ~ 512 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. | |||
| resourceName | string | ✓ | ~ 64 chars | Parameter Resource Name for Game (Not used for GS2) A game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. | ||
| resourceValue | long | ✓ | 0 ~ 9223372036854775805 | Parameter Resource Value for Game (Not used for GS2) A game-defined numeric value for this parameter (e.g., 50 for +50 attack power). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. | ||
| weight | int | ✓ | 1 ~ 2147483646 | Draw Weight The relative weight used in the weighted lottery when selecting parameter values. Higher values increase the probability of this entry being selected. The actual probability is this weight divided by the sum of all weights in the pool. |
EzBalanceParameterValue
Balance Parameter Value
Represents the actual value assigned to a single parameter slot within a balance parameter status. Contains the slot name and its concrete numeric value after the drawing process.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 64 chars | Name The name of the parameter slot (e.g., ATK, DEF, SPD). Corresponds to a parameter slot defined in the Balance Parameter Value Model. | ||
| value | long | ✓ | 0 ~ 9223372036854775805 | Value The numeric value assigned to this parameter slot. Determined by the initial value strategy (average or lottery) when the balance parameter is first drawn. The sum of all slot values equals the total value defined in the model. |
EzRarityParameterValue
Rarity Parameter Value
Represents the actual value assigned to a single parameter slot within a rarity parameter status. Contains the slot name and the resource details (name and value) selected through weighted lottery from the value model pool.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 64 chars | Name The name of the parameter value selected from the value model pool. Corresponds to the name defined in the Rarity Parameter Value Model entry that was drawn. | ||
| resourceName | string | ✓ | ~ 64 chars | Resource Name The game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). Copied from the drawn Rarity Parameter Value Model entry for use in game logic. | ||
| resourceValue | long | ✓ | 0 ~ 9223372036854775805 | Resource Value The numeric value of the resource associated with this parameter. Copied from the drawn Rarity Parameter Value Model entry. Used by game logic to apply the parameter’s effect (e.g., +50 attack power). |
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
getBalanceParameterModel
Get a balance parameter definition by name
Retrieves a single balance parameter model by specifying its name. The returned information includes the total value to distribute, the list of parameter slots (e.g., ATK, DEF, SPD), and how the initial values are determined.
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 (.). | ||
| parameterName | string | ✓ | ~ 128 chars | Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzBalanceParameterModel | Balance Parameter Model |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).BalanceParameterModel(
parameterName: "balance-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).BalanceParameterModel(
parameterName: "balance-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
)->BalanceParameterModel(
"balance-0001" // parameterName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).BalanceParameterModel(
parameterName: "balance-0001"
);
// 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.Enchant.Namespace(
namespaceName: "namespace-0001"
).BalanceParameterModel(
parameterName: "balance-0001"
);
// 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->Enchant->Namespace(
"namespace-0001" // namespaceName
)->BalanceParameterModel(
"balance-0001" // parameterName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Enchant::Model::FBalanceParameterModel> 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.
listBalanceParameterModels
Get a list of balance parameter definitions
Retrieves all balance parameter models registered in this namespace. A balance parameter distributes a fixed total value across multiple stats — for example, splitting 100 points among ATK, DEF, and SPD so the total always equals 100. Use this to display available parameter types or to check the configuration of parameter models on a weapon/equipment 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 (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzBalanceParameterModel> | List of Balance Parameter Model |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.BalanceParameterModelsAsync(
).ToListAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.BalanceParameterModels(
);
List<EzBalanceParameterModel> items = new List<EzBalanceParameterModel>();
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->Enchant->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->BalanceParameterModels(
);
TArray<Gs2::UE5::Enchant::Model::FEzBalanceParameterModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeBalanceParameterModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBalanceParameterModels(callbackId); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeBalanceParameterModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBalanceParameterModels(callbackId); const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeBalanceParameterModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeBalanceParameterModels(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.
getBalanceParameterStatus
Get the balance parameter values of a specific item
Retrieves the current balance parameter values for a specific item (property) owned by the player. The values were randomly determined when the item was created (or last re-rolled), and the sum of all values always equals the model’s total value. Use this to display the individual stat breakdown (e.g., ATK: 40, DEF: 35, SPD: 25) 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 (.). | ||
| parameterName | string | ✓ | ~ 128 chars | Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. |
Result
| Type | Description | |
|---|---|---|
| item | EzBalanceParameterStatus | Balance Parameter Status |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).BalanceParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).BalanceParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->BalanceParameterStatus(
"balance-0001", // parameterName
"property-0001" // propertyId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).BalanceParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
// 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.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).BalanceParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
// 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->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->BalanceParameterStatus(
"balance-0001", // parameterName
"property-0001" // propertyId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Enchant::Model::FBalanceParameterStatus> 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.
listBalanceParameterStatuses
Get a list of the player’s balance parameter values
Retrieves the current balance parameter values assigned to the player’s items. You can filter by parameter name to see values for a specific parameter type only. For example, this returns the ATK/DEF/SPD distribution for each weapon the player owns.
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 (.). | ||
| parameterName | string | ~ 128 chars | Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzBalanceParameterStatus> | List of Balance Parameter Statuses |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.BalanceParameterStatusesAsync(
parameterName: "balance-0001"
).ToListAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.BalanceParameterStatuses(
parameterName: "balance-0001"
);
List<EzBalanceParameterStatus> items = new List<EzBalanceParameterStatus>();
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->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->BalanceParameterStatuses(
"balance-0001" // parameterName
);
TArray<Gs2::UE5::Enchant::Model::FEzBalanceParameterStatusPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeBalanceParameterStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBalanceParameterStatuses(callbackId); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeBalanceParameterStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBalanceParameterStatuses(callbackId); const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeBalanceParameterStatuses(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeBalanceParameterStatuses(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.
getRarityParameterModel
Get a rarity parameter definition by name
Retrieves a single rarity parameter model by specifying its name. The returned information includes the maximum number of parameter slots, how the slot count is determined, and the list of possible values with their rarity weights (drop rates).
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 (.). | ||
| parameterName | string | ✓ | ~ 128 chars | Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzRarityParameterModel | Rarity Parameter Model |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).RarityParameterModel(
parameterName: "rarity-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).RarityParameterModel(
parameterName: "rarity-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
)->RarityParameterModel(
"rarity-0001" // parameterName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).RarityParameterModel(
parameterName: "rarity-0001"
);
// 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.Enchant.Namespace(
namespaceName: "namespace-0001"
).RarityParameterModel(
parameterName: "rarity-0001"
);
// 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->Enchant->Namespace(
"namespace-0001" // namespaceName
)->RarityParameterModel(
"rarity-0001" // parameterName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Enchant::Model::FRarityParameterModel> 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.
listRarityParameterModels
Get a list of rarity parameter definitions
Retrieves all rarity parameter models registered in this namespace. A rarity parameter randomly assigns values to parameter slots based on rarity-weighted probabilities — for example, a weapon might get skill slots filled with Common, Rare, or Legendary abilities. Use this to display available parameter types or to check the rarity configuration on an equipment 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 (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzRarityParameterModel> | List of Rarity Parameter Models |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.RarityParameterModelsAsync(
).ToListAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.RarityParameterModels(
);
List<EzRarityParameterModel> items = new List<EzRarityParameterModel>();
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->Enchant->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->RarityParameterModels(
);
TArray<Gs2::UE5::Enchant::Model::FEzRarityParameterModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeRarityParameterModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeRarityParameterModels(callbackId); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeRarityParameterModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeRarityParameterModels(callbackId); const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeRarityParameterModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeRarityParameterModels(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.
getRarityParameterStatus
Get the rarity parameter values of a specific item
Retrieves the current rarity parameter values for a specific item (property) owned by the player. The values were randomly drawn based on the rarity weights defined in the model when the item was created (or last re-rolled). Use this to display the skills or abilities attached to a weapon or equipment on a 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 (.). | ||
| parameterName | string | ✓ | ~ 128 chars | Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. |
Result
| Type | Description | |
|---|---|---|
| item | EzRarityParameterStatus | Rarity Parameter Status |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RarityParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RarityParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RarityParameterStatus(
"balance-0001", // parameterName
"property-0001" // propertyId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RarityParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
// 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.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RarityParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
// 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->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RarityParameterStatus(
"balance-0001", // parameterName
"property-0001" // propertyId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Enchant::Model::FRarityParameterStatus> 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.
listRarityParameterStatuses
Get a list of the player’s rarity parameter values
Retrieves the current rarity parameter values assigned to the player’s items. You can filter by parameter name to see values for a specific parameter type only. For example, this returns which skill slots (Common, Rare, Legendary) each of the player’s weapons has.
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 (.). | ||
| parameterName | string | ~ 128 chars | Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzRarityParameterStatus> | List of Rarity Parameter Models |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.RarityParameterStatusesAsync(
parameterName: "rarity-0001"
).ToListAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.RarityParameterStatuses(
parameterName: "rarity-0001"
);
List<EzRarityParameterStatus> items = new List<EzRarityParameterStatus>();
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->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->RarityParameterStatuses(
"rarity-0001" // parameterName
);
TArray<Gs2::UE5::Enchant::Model::FEzRarityParameterStatusPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeRarityParameterStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeRarityParameterStatuses(callbackId); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeRarityParameterStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeRarityParameterStatuses(callbackId); const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeRarityParameterStatuses(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeRarityParameterStatuses(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.
verifyRarityParameterStatus
Verify the rarity parameters of a specific item
Checks whether a specific item’s rarity parameters meet a given condition. Three check types are available:
have: the item has a specific parameter value (e.g., has the “Fire Slash” skill)havent: the item does not have a specific parameter valuecount: the item has a specific number of parameter slots filled
Use this as a precondition — for example, requiring a weapon to have a certain skill before allowing an upgrade.
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 (.). | ||||||||||
| parameterName | string | ✓ | ~ 128 chars | Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. | ||||||||||
| gameSession | GameSession | ✓ | GameSession | |||||||||||
| propertyId | string | ✓ | ~ 1024 chars | Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. | ||||||||||
| verifyType | ✓ | Type of verification
| ||||||||||||
| parameterValueName | string | {verifyType} in [“havent”, “have”] | ✓* | ~ 64 chars | Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. | |||||||||
| parameterCount | int | {verifyType} in [“count”] | ✓* | 0 ~ 10 | Number of parameters to verify |
Result
| Type | Description | |
|---|---|---|
| item | EzRarityParameterStatus | Rarity Parameter Status |
Implementation Example
var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RarityParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
var result = await domain.VerifyRarityParameterStatusAsync(
verifyType: "have",
parameterValueName: "parameter-0001",
parameterCount: 0
);
var item = await result.ModelAsync(); var domain = gs2.Enchant.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RarityParameterStatus(
parameterName: "balance-0001",
propertyId: "property-0001"
);
var future = domain.VerifyRarityParameterStatusFuture(
verifyType: "have",
parameterValueName: "parameter-0001",
parameterCount: 0
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Enchant->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RarityParameterStatus(
"balance-0001", // parameterName
"property-0001" // propertyId
);
const auto Future = Domain->VerifyRarityParameterStatus(
"have", // verifyType
"parameter-0001", // parameterValueName
0 // parameterCount
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();