GS2-Experience SDK for Game Engine API リファレンス
モデル
EzExperienceModel
経験値モデル
経験値モデルとは、ランクアップに必要な経験値の閾値や、デフォルトのランクキャップ・最大ランクキャップ毎に設定するエンティティです。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | 経験値モデル名 | ||
| metadata | string | ~ 2048文字 | メタデータ | |||
| defaultExperience | long | ✓ | 0 | 0 ~ 9223372036854775805 | 経験値の初期値 | |
| defaultRankCap | long | ✓ | 0 ~ 9223372036854775805 | ランクキャップの初期値 | ||
| maxRankCap | long | ✓ | 0 ~ 9223372036854775805 | ランクキャップの最大値 | ||
| rankThreshold | EzThreshold | ✓ | ランクアップ閾値 | |||
| acquireActionRates | List<EzAcquireActionRate> | 0 ~ 100 items | 報酬加算テーブルリスト |
関連するメソッド
EzThreshold
ランクアップ閾値
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| metadata | string | ~ 2048文字 | メタデータ | |||
| values | List<long> | ✓ | 1 ~ 10000 items | ランクアップ経験値閾値リスト |
関連するモデル
EzStatus
ステータス
ステータスとはプロパティID毎に存在するエンティティで、
現在の経験値やランクキャップの値を保持します。
プロパティID とはステータス固有のIDで、開発者が任意の値を設定できます。
GS2 では経験値を有する GS2-Inventory のアイテムセットGRN や GS2-Dictionary のエントリーGRN の後ろに
経験値モデルとなるサフィックスを追加した値をプロパティIDとすることを推奨しています。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| experienceName | string | ✓ | ~ 128文字 | 経験値モデルの名前 | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID | ||
| experienceValue | long | ✓ | 0 | 0 ~ 9223372036854775805 | 累計獲得経験値 | |
| rankValue | long | ✓ | 0 | 0 ~ 9223372036854775805 | 現在のランク | |
| rankCapValue | long | ✓ | 0 ~ 9223372036854775805 | 現在のランクキャップ | ||
| nextRankUpExperienceValue | long | ✓ | 0 | 0 ~ 9223372036854775805 | 次のランクアップの計経験値量 |
関連するメソッド
EzAcquireAction
入手アクション
EzAcquireActionRate
報酬加算テーブル
ランクに応じて報酬の量を調整することができます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | 報酬加算テーブル名 | ||||||||
| mode | 文字列列挙型 enum { “double”, “big” } | ✓ | “double” | ~ 128文字 | 報酬加算テーブルの種類
| |||||||
| rates | List<double> | {mode} == “double” | ✓ | 1 ~ 10000 items | ランクごとの加算量(倍率) mode が “double” であれば 必須 | |||||||
| bigRates | List<string> | {mode} == “big” | ✓ | 1 ~ 10000 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 | 入手アクションの実行結果リスト |
メソッド
getExperienceModel
経験値モデル情報を取得
経験値モデル名 を指定してランクキャップの情報やランクアップ閾値の情報を取得します。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| experienceName | string | ✓ | ~ 128文字 | 経験値モデル名 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzExperienceModel | 経験値モデル |
実装例
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).ExperienceModel(
experienceName: "experience-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).ExperienceModel(
experienceName: "experience-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Experience->Namespace(
"namespace-0001" // namespaceName
)->ExperienceModel(
"experience-0001" // experienceName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).ExperienceModel(
experienceName: "experience-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).ExperienceModel(
experienceName: "experience-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Experience->Namespace(
"namespace-0001" // namespaceName
)->ExperienceModel(
"experience-0001" // experienceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Experience::Model::FExperienceModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listExperienceModels
経験値モデル情報の一覧を取得
ランクキャップの情報やランクアップ閾値の情報を取得します。
次のランクアップまでに必要な獲得経験値量などをゲーム内で表示したい場合はこのモデルデータを使ってください。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzExperienceModel> | 経験値モデルリスト |
実装例
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.ExperienceModelsAsync(
).ToListAsync(); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.ExperienceModels(
);
List<EzExperienceModel> items = new List<EzExperienceModel>();
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->Experience->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->ExperienceModels(
);
TArray<Gs2::UE5::Experience::Model::FEzExperienceModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeExperienceModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeExperienceModels(callbackId); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.ExperienceModels(
);
List<EzExperienceModel> items = new List<EzExperienceModel>();
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->Experience->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeExperienceModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeExperienceModels(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
getStatus
経験値モデル と プロパティID を指定してステータス情報を取得
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| experienceName | string | ✓ | ~ 128文字 | 経験値モデルの名前 | ||
| accessToken | string | ✓ | ~ 128文字 | アクセストークン | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzStatus | ステータス |
実装例
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
experienceName: "character_ssr",
propertyId: "property-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
experienceName: "character_ssr",
propertyId: "property-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Experience->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"character_ssr", // experienceName
"property-0001" // propertyId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
experienceName: "character_ssr",
propertyId: "property-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
experienceName: "character_ssr",
propertyId: "property-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Experience->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"character_ssr", // experienceName
"property-0001" // propertyId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Experience::Model::FStatus> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
getStatusWithSignature
ステータス値の署名を取得
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| experienceName | string | ✓ | ~ 128文字 | 経験値モデルの名前 | ||
| accessToken | string | ✓ | ~ 128文字 | アクセストークン | ||
| propertyId | string | ✓ | ~ 1024文字 | プロパティID | ||
| keyId | string | ✓ | “grn:gs2:{region}:{ownerId}:key:default:key:default” | ~ 1024文字 | 暗号鍵GRN |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzStatus | ステータス |
| body | string | 検証対象のオブジェクト |
| signature | string | 署名 |
実装例
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
experienceName: "character_ssr",
propertyId: "property-0001"
);
var result = await domain.GetStatusWithSignatureAsync(
keyId: "key-0001"
);
var item = await result.ModelAsync();
var body = result.Body;
var signature = result.Signature; var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
experienceName: "character_ssr",
propertyId: "property-0001"
);
var future = domain.GetStatusWithSignatureFuture(
keyId: "key-0001"
);
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 body = future.Result.Body;
var signature = future.Result.Signature; const auto Domain = Gs2->Experience->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"character_ssr", // experienceName
"property-0001" // propertyId
);
const auto Future = Domain->GetStatusWithSignature(
"key-0001" // keyId
);
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 Body = Result->Body;
const auto Signature = Result->Signature;listStatuses
ステータス情報の一覧を取得
経験値モデル名 は省略可能で、指定しなかった場合はゲームプレイヤーに属する全てのステータス情報が取得できます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | ||
| experienceName | string | ~ 128文字 | 経験値モデル名 | |||
| accessToken | string | ✓ | ~ 128文字 | アクセストークン | ||
| pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | |||
| limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzStatus> | ステータスのリスト |
| nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.StatusesAsync(
experienceName: "character_ssr"
).ToListAsync(); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Statuses(
experienceName: "character_ssr"
);
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->Experience->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Statuses(
"character_ssr" // experienceName
);
TArray<Gs2::UE5::Experience::Model::FEzStatusPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeStatuses(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeStatuses(callbackId); var domain = gs2.Experience.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Statuses(
experienceName: "character_ssr"
);
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->Experience->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 の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。