API Reference of GS2-Grade SDK for Game Engine
Model
EzGradeModel
Grade Model
A grade model is an entity that sets the threshold of grade required for rank advancement and for each default and maximum rank cap.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Grade Model Name | ||
| metadata | string | ~ 2048 chars | Metadata | |||
| experienceModelId | string | ✓ | ~ 1024 chars | Experience model GRN to link grade and rank cap | ||
| gradeEntries | List<EzGradeEntryModel> | ✓ | 1 ~ 100 items | List of Grade entry | ||
| acquireActionRates | List<EzAcquireActionRate> | 0 ~ 100 items | List of Remuneration addition table |
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 | ||
| propertyId | string | ✓ | ~ 1024 chars | Property ID | ||
| gradeValue | long | ✓ | 1 | 1 ~ 9223372036854775805 | Current Grade |
EzGradeEntryModel
Grade Entry
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| metadata | string | ~ 2048 chars | Metadata | |||
| rankCapValue | long | ✓ | 0 ~ 9223372036854775805 | Rank cap value to be set in GS2-Experience |
EzAcquireAction
Acquire Action
EzAcquireActionRate
Remuneration addition table master
You can adjust the amount of rewards according to the rank.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Remuneration addition table name | ||||||||
| mode | String Enum enum { “double”, “big” } | ✓ | “double” | ~ 128 chars | Remuneration addition table type
| |||||||
| rates | List<double> | {mode} == “double” | ✓* | 1 ~ 1000 items | Amount added per grade (multiplier) * required if mode is “double” | |||||||
| bigRates | List<string> | {mode} == “big” | ✓* | 1 ~ 1000 items | Amount added per grade (multiplier) * required if mode is “big” |
EzVerifyActionResult
Verify action execution result
EzConsumeActionResult
Consume action execution result
EzAcquireActionResult
Acquire action execution result
EzTransactionResult
Transaction execution results
Transaction execution results executed using server-side transaction auto-execution functionality
| 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
Obtain grade and rank-up threshold model information
Get rank cap information and rank-up threshold information by specifying grade type name.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| gradeName | string | ✓ | ~ 128 chars | Grade Model Name |
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"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listGradeModels
Get list of grade and rank-up threshold model information
Obtain information on rank caps and rank advancement thresholds. Use this model data if you want to display in-game information such as the amount of grade required to gain before the next rank-up.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name |
Result
| Type | Description | |
|---|---|---|
| items | List<EzGradeModel> | List of Grade Model |
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"
);
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
);
// 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
applyRankCap
Apply rank cap to GS2-Experience
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| gradeName | string | ✓ | ~ 128 chars | Grade Model Name | ||
| accessToken | string | ✓ | ~ 128 chars | Access token | ||
| propertyId | string | ✓ | ~ 1024 chars | Property ID |
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 status information by grade type and property ID
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| gradeName | string | ✓ | ~ 128 chars | Grade Model Name | ||
| accessToken | string | ✓ | ~ 128 chars | Access token | ||
| propertyId | string | ✓ | ~ 1024 chars | Property ID |
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"
);
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
);
// 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listStatuses
Get list of status information
The grade type name is optional; if not specified, all status information belonging to the game player is retrieved.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| gradeName | string | ~ 128 chars | Grade Model Name | |||
| accessToken | string | ✓ | ~ 128 chars | Access token | ||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | ✓ | 30 | 1 ~ 1000 | Number of data acquired |
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
);
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
);
// 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.