GS2-Grade SDK for Game Engine API Reference
Model
EzStatus
Status
A status is an entity that exists for each property ID and holds the value of the current grade.
The property ID is a status-specific ID and can be set to any value by the developer. It is strongly recommended that the value be the same as the property ID of the GS2-Experience.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| gradeName | string | ✓ | ~ 128 chars | Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. | ||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. | ||
| gradeValue | long | 1 | 1 ~ 9223372036854775805 | Current Grade The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. |
EzGradeModel
Grade Model
A Grade Model is an entity that indicates the rank of characters and equipment, and allows you to set the rank cap for GS2-Experience based on the grade.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Grade Model name Grade 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. | |||
| experienceModelId | string | ✓ | ~ 1024 chars | GS2-Experience Experience Model GRN The GRN of the GS2-Experience experience model to link with this grade model. When a grade value changes, the corresponding rank cap in the linked experience model is automatically updated based on the grade entry mappings. This enables grade-driven progression where higher grades unlock higher rank caps. | ||
| gradeEntries | List<EzGradeEntryModel> | ✓ | 1 ~ 100 items | List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. | ||
| acquireActionRates | List<EzAcquireActionRate> | 0 ~ 100 items | List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). |
EzGradeEntryModel
Grade Entry Model
Defines the mapping between a grade value and a rank cap for the linked GS2-Experience model. Each entry also specifies regex patterns for matching property IDs, enabling the system to determine which resources can be used for grade-up operations and how their property IDs are transformed.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| 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. | |||
| rankCapValue | long | ✓ | 0 ~ 9223372036854775805 | Rank Cap Value The rank cap value to set in the linked GS2-Experience model when this grade is applied. When a player’s grade changes to the value corresponding to this entry, the rank cap of the associated experience status is automatically updated to this value, controlling the maximum achievable rank. |
EzAcquireAction
Acquire Action
EzAcquireActionRate
Reward Addition Table
Defines a named multiplier table that scales reward amounts based on the current grade value. Each grade value maps to a multiplier applied to acquire actions in transactions, allowing higher-graded characters or equipment to receive proportionally more rewards. Supports both standard double-precision mode and big number mode for extremely large values.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. | ||||||||
| mode | String Enum enum { “double”, “big” } | “double” | Reward Addition Table Type Selects the numeric precision mode for multiplier values. “double” mode uses standard floating-point numbers suitable for most cases. “big” mode uses string-represented numbers supporting up to 1024 digits, for games requiring extremely large value calculations.
| |||||||||
| rates | List<double> | {mode} == “double” | ✓* | 1 ~ 1000 items | Multiplier List per Grade (double mode) An array of reward multipliers indexed by grade value, using double-precision floating-point numbers. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “double”. * Required if mode is “double” | |||||||
| bigRates | List<string> | {mode} == “big” | ✓* | 1 ~ 1000 items | Multiplier List per Grade (big mode) An array of reward multipliers indexed by grade value, using string-represented numbers for extended precision. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “big” for games requiring very large number calculations. * Required if mode is “big” |
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
getGradeModel
Get a specific limit break / ascension model by name
Retrieves a single grade model by specifying its name. The returned information includes the grade entries (which define how the max level increases at each grade), the default starting grade, and the reward multiplier rates. Use this to display the details of a specific limit break system — for example, showing “Iron Sword: Grade 2 → Max Lv 70, Grade 3 → Max Lv 80” or “Current reward bonus: 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 (.). | ||
| gradeName | string | ✓ | ~ 128 chars | Grade Model name Grade Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzGradeModel | Grade Model |
Implementation Example
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).GradeModel(
gradeName: "grade-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).GradeModel(
gradeName: "grade-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Grade->Namespace(
"namespace-0001" // namespaceName
)->GradeModel(
"grade-0001" // gradeName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).GradeModel(
gradeName: "grade-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.Grade.Namespace(
namespaceName: "namespace-0001"
).GradeModel(
gradeName: "grade-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->Grade->Namespace(
"namespace-0001" // namespaceName
)->GradeModel(
"grade-0001" // gradeName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Grade::Model::FGradeModel> 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.
listGradeModels
Get a list of limit break / ascension models
Retrieves all grade models registered in this namespace. A grade model defines a “limit break” or “ascension” system — it controls how much the max level (rank cap) of an item or character increases as the player raises its grade. For example, a weapon at Grade 0 might have a max level of 50, but after limit breaking to Grade 1, the max level increases to 60, Grade 2 to 70, and so on. The model also defines reward multiplier rates, which can increase the amount of rewards based on grade level (e.g., a Grade 3 character earns 1.5x gold). Use this to build limit break or ascension UI — for example, showing “Grade 2/5 — Max Lv: 70 — Next: requires 3 copies”.
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<EzGradeModel> | List of Grade Models |
Implementation Example
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.GradeModelsAsync(
).ToListAsync(); var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.GradeModels(
);
List<EzGradeModel> items = new List<EzGradeModel>();
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->Grade->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->GradeModels(
);
TArray<Gs2::UE5::Grade::Model::FEzGradeModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeGradeModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGradeModels(callbackId); var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeGradeModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGradeModels(callbackId); const auto Domain = Gs2->Grade->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeGradeModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGradeModels(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.
applyRankCap
Sync the max level with the current limit break grade
Updates the max level (rank cap) in GS2-Experience to match the current grade (limit break level). For example, if a character was limit broken from Grade 2 (max Lv 70) to Grade 3 (max Lv 80), calling this ensures the Experience system knows the new max level is 80. This is useful when the grade was changed externally and the max level in Experience needs to be synchronized. Normally, the max level is updated automatically when grade changes, but you can call this manually if the data gets out of sync.
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 (.). | ||
| gradeName | string | ✓ | ~ 128 chars | Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
Result
| Type | Description | |
|---|---|---|
| item | EzStatus | Status |
| experienceNamespaceName | string | GS2-Experience Namespace Name |
| experienceStatus | EzStatus | GS2-Experience Status after addition |
Implementation Example
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
gradeName: "grade-0001",
propertyId: "property-0001"
);
var result = await domain.ApplyRankCapAsync(
);
var item = await result.ModelAsync();
var experienceNamespaceName = result.ExperienceNamespaceName; var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
gradeName: "grade-0001",
propertyId: "property-0001"
);
var future = domain.ApplyRankCapFuture(
);
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;
var experienceNamespaceName = future.Result.ExperienceNamespaceName; const auto Domain = Gs2->Grade->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"grade-0001", // gradeName
"property-0001" // propertyId
);
const auto Future = Domain->ApplyRankCap(
);
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();
const auto ExperienceNamespaceName = Result->ExperienceNamespaceName;getStatus
Get the limit break / ascension status of a specific item or character
Retrieves the current grade (limit break level) for a specific property owned by the player. The property is identified by the grade model name (which limit break system to use) and the property ID (which specific item or character). Use this to display a limit break detail screen — for example, “Iron Sword — Grade: ★3 — Max Lv: 80 — Next limit break requires 2 more copies”.
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 (.). | ||
| gradeName | string | ✓ | ~ 128 chars | Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
Result
| Type | Description | |
|---|---|---|
| item | EzStatus | Status |
Implementation Example
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
gradeName: "grade-0001",
propertyId: "property-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
gradeName: "grade-0001",
propertyId: "property-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Grade->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"grade-0001", // gradeName
"property-0001" // propertyId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
gradeName: "grade-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.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
gradeName: "grade-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->Grade->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"grade-0001", // gradeName
"property-0001" // propertyId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Grade::Model::FStatus> 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.
listStatuses
Get a list of the player’s limit break / ascension statuses
Retrieves the player’s current grade (limit break level) for their items or characters. You can optionally filter by grade model name — if omitted, all grade statuses across all grade types are returned. Each status includes the current grade value and which property (item or character) it belongs to. Use this to build a list showing all limit-broken items — for example, “Iron Sword ★3, Fire Staff ★1, Dragon Armor ★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 (.). | ||
| gradeName | string | ~ 128 chars | Grade Model name | |||
| 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<EzStatus> | List of Status |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.StatusesAsync(
gradeName: "grade-0001"
).ToListAsync(); var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Statuses(
gradeName: "grade-0001"
);
List<EzStatus> items = new List<EzStatus>();
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->Grade->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Statuses(
"grade-0001" // gradeName
);
TArray<Gs2::UE5::Grade::Model::FEzStatusPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeStatuses(callbackId); var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeStatuses(callbackId); const auto Domain = Gs2->Grade->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeStatuses(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeStatuses(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.