API Reference of GS2-Enhance SDK for Game Engine
Model
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 | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128 chars | Enhanced Rate Name | |
metadata | string | ~ 2048 chars | metadata | ||
targetInventoryModelId | string | ✓ | ~ 1024 chars | Inventory available for enhancement targets | |
acquireExperienceSuffix | string | ✓ | ~ 1024 chars | Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience | |
materialInventoryModelId | string | ✓ | ~ 1024 chars | Inventory model GRN | |
acquireExperienceHierarchy | List<string> | ~ 10 items | Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata | ||
experienceModelId | string | ✓ | ~ 1024 chars | Experience Model GRN |
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 | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
name | string | ✓ | UUID | ~ 36 chars | Conduct ID |
rateName | string | ✓ | ~ 128 chars | Rate Model Name | |
propertyId | string | ✓ | ~ 1024 chars | Property ID to be enhanced | |
experienceValue | long | ✓ | ~ 9223372036854775805 | Experience value | |
rate | float | ✓ | ~ 100.0 | Experience value scale factor |
EzConfig
Configration
Set values to be applied to transaction variables
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
key | string | ✓ | ~ 64 chars | Name | |
value | string | ~ 51200 chars | Value |
EzMaterial
Balance Parameter Value Model
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
materialItemSetId | string | ✓ | ~ 1024 chars | Quantity of items held per expiration date GRN | |
count | int | ✓ | 1 | ~ 2147483645 | Number of consumption |
Methods
getRateModel
Obtain enhanced rate model information
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
rateName | string | ✓ | ~ 128 chars | Enhanced Rate Name |
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.Model();
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"
);
var future = domain.Model();
yield return future;
var item = future.Result;
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 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.
listRateModels
Get list of enhanced rate model information
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name |
Result
Type | Description | |
---|---|---|
items | List<EzRateModel> | List of Enhanced Rate Model |
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"
);
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
);
// 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 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.
deleteProgress
Delete reinforcement progress information.
Use this option if you want to explicitly remove progress information rather than using the force
option at the start of the reinforcement.
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
accessToken | string | ✓ | ~ 128 chars | User Id |
Result
Type | Description | |
---|---|---|
item | EzProgress | Running 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
Reported completion of enhancements
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
config | List<EzConfig> | [] | ~ 32 items | Set values to be applied to transaction variables |
Result
Type | Description | |
---|---|---|
item | EzProgress | Running enhancement |
transactionId | string | Issed 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 | Is transaction auto-execution enabled? |
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
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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
Obtain information on the progress of the enhancement.
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
accessToken | string | ✓ | ~ 128 chars | User Id |
Result
Type | Description | |
---|---|---|
item | EzProgress | Running enhancement |
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.Model();
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(
);
var future = domain.Model();
yield return future;
var item = future.Result;
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 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.
start
Start enhancements
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
rateName | string | ✓ | ~ 128 chars | Rate Model Name | |
targetItemSetId | string | ✓ | ~ 1024 chars | Quantity of items held per expiration date GRN | |
materials | List<EzMaterial> | ~ 10 items | List of materials | ||
accessToken | string | ✓ | ~ 128 chars | User Id | |
force | bool | ✓ | false | If there is an enhancement that has already been started, it can be discarded and started, or | |
config | List<EzConfig> | [] | ~ 32 items | Set values to be applied to transaction variables |
Result
Type | Description | |
---|---|---|
transactionId | string | Issed transaction ID |
stampSheet | string | Stamp sheet used to execute the reinforcement initiation process |
stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
autoRunStampSheet | bool | Is transaction auto-execution enabled? |
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
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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
Perform enhancements
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
rateName | string | ✓ | ~ 128 chars | Enhanced Rate Name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
targetItemSetId | string | ✓ | ~ 1024 chars | Quantity of items held per expiration date GRN | |
materials | List<EzMaterial> | ✓ | 1 ~ 10 items | List of Material | |
config | List<EzConfig> | [] | ~ 32 items | Set values to be applied to transaction variables |
Result
Type | Description | |
---|---|---|
item | EzRateModel | Enhanced Rate Model |
transactionId | string | Issed 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 | Is transaction auto-execution enabled? |
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
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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;
}