GS2-Grade SDK for Game Engine API リファレンス
ゲームエンジン向け GS2-SDK の モデルの仕様 と API のリファレンス
モデル
EzGradeModel
グレードモデル
グレードモデルとは、キャラクターや装備のランクを示すエンティティで、グレードによって GS2-Experience のランクキャップを設定することができます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | グレードモデル名 | ||
| metadata | string | ~ 2048文字 | メタデータ | |||
| experienceModelId | string | ✓ | ~ 1024文字 | グレードとランクキャップを連動させる経験値モデル GRN | ||
| gradeEntries | List<EzGradeEntryModel> | ✓ | 1 ~ 100 items | グレードエントリリスト | ||
| acquireActionRates | List<EzAcquireActionRate> | 0 ~ 100 items | 報酬加算テーブルリスト |
EzStatus
ステータス
ステータスとはプロパティID毎に存在するエンティティで、
現在のグレードの値を保持します。
プロパティID とはステータス固有のIDで、開発者が任意の値を設定できます。
連動する GS2-Experience のプロパティIDと完全に一致する値を使用することを強く推奨しています。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| gradeName | string | ✓ | ~ 128文字 | グレードモデルの名前 | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID | ||
| gradeValue | long | ✓ | 1 | 1 ~ 9223372036854775805 | 現在のグレード |
EzGradeEntryModel
グレードエントリ
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| metadata | string | ~ 2048文字 | メタデータ | |||
| rankCapValue | long | ✓ | 0 ~ 9223372036854775805 | GS2-Experience に設定するランクキャップ値 |
EzAcquireAction
入手アクション
EzAcquireActionRate
報酬加算テーブルマスター
グレードに応じて報酬の量を調整することができます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | 報酬加算テーブル名 | ||||||||
| mode | 文字列列挙型 enum { “double”, “big” } | ✓ | “double” | ~ 128文字 | 報酬加算テーブルの種類
| |||||||
| rates | List<double> | {mode} == “double” | ✓* | 1 ~ 1000 items | グレードごとの加算量(倍率) ※ mode が “double” であれば 必須 | |||||||
| bigRates | List<string> | {mode} == “big” | ✓* | 1 ~ 1000 items | グレードごとの加算量(倍率) ※ mode が “big” であれば 必須 |
EzVerifyActionResult
検証アクションの実行結果
EzConsumeActionResult
消費アクションの実行結果
EzAcquireActionResult
入手アクションの実行結果
EzTransactionResult
トランザクション実行結果
サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36文字 | トランザクションID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | 検証アクションの実行結果リスト | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | 消費アクションの実行結果リスト | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | 入手アクションの実行結果リスト |
メソッド
getGradeModel
グレードモデル情報を取得
グレードモデル名 を指定してランクキャップの情報やランクアップ閾値の情報を取得します。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| gradeName | string | ✓ | ~ 128文字 | グレードモデル名 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzGradeModel | グレードモデル |
実装例
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;
}値の変更イベントハンドリング
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).GradeModel(
gradeName: "grade-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
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
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Grade::Model::FGradeModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listGradeModels
グレードモデル情報の一覧を取得
ランクキャップの情報やランクアップ閾値の情報を取得します。
次のランクアップまでに必要な獲得グレード量などをゲーム内で表示したい場合はこのモデルデータを使ってください。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzGradeModel> | グレードモデルリスト |
実装例
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());
}値の変更イベントハンドリング
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGradeModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
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
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeGradeModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeGradeModels(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
applyRankCap
GS2-Experience にランクキャップを適用
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| gradeName | string | ✓ | ~ 128文字 | グレードモデルの名前 | ||
| accessToken | string | ✓ | ~ 128文字 | アクセストークン | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzStatus | ステータス |
| experienceNamespaceName | string | GS2-Experience ネームスペース名 |
| experienceStatus | EzStatus | ランクキャップ更新後の GS2-Experience ステータス |
実装例
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
グレードモデル と プロパティID を指定してステータス情報を取得
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| gradeName | string | ✓ | ~ 128文字 | グレードモデルの名前 | ||
| accessToken | string | ✓ | ~ 128文字 | アクセストークン | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzStatus | ステータス |
実装例
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;
}値の変更イベントハンドリング
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
gradeName: "grade-0001",
propertyId: "property-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
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
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Grade::Model::FStatus> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listStatuses
ステータス情報の一覧を取得
グレードモデル名 は省略可能で、指定しなかった場合はゲームプレイヤーに属する全てのステータス情報が取得できます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| gradeName | string | ~ 128文字 | グレードモデル名 | |||
| accessToken | string | ✓ | ~ 128文字 | アクセストークン | ||
| pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | |||
| limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzStatus> | ステータスのリスト |
| nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
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());
}値の変更イベントハンドリング
var domain = gs2.Grade.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeStatuses(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
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
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeStatuses(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeStatuses(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。