GS2-Exchange SDK for Game Engine API リファレンス
モデル
EzAwait
交換待機
報酬を受け取る前に実時間の経過が必要な交換の実行状態を表します。プレイヤーが await タイミングタイプの交換を開始した際に作成され、報酬が利用可能になるまでの待機期間を追跡します。待ち時間を短縮または解消するスキップ機能をサポートし、報酬取得時のデフォルト設定値を保存します。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 128文字 | ユーザーID | ||
| rateName | string | ✓ | ~ 128文字 | 交換レートモデル名 交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| name | string | ✓ | UUID | ~ 36文字 | 交換待機の名前 交換待機の一意な名前を保持します。 名前は UUID(Universally Unique Identifier)フォーマットで自動的に生成され、交換待機を識別するために使用されます。 | |
| skipSeconds | int | 0 | 0 ~ 2147483646 | スキップ秒数 待ち時間から差し引く秒数です。スキップ秒数が適用されると、acquirableAt のタイムスタンプがこの分だけ前倒しされます。プレイヤーがリソースを支払って待ち時間を短縮する仕組みを実装するために使用されます。 | ||
| config | List<EzConfig> | [] | 0 ~ 32 items | 報酬取得時に適用するデフォルト設定値 待機完了時に報酬が配布される際にトランザクションのプレースホルダ変数として使用されるキーと値のペアです。これらの値は交換開始時に設定され、入手アクションのトランザクションパラメータに適用されます。 | ||
| exchangedAt | long | 交換時間 交換が開始され待機が作成されたタイムスタンプです。報酬が利用可能になる時刻を計算するための基準時刻として使用されます(acquirableAt = exchangedAt + lockTime - skipSeconds)。 | ||||
| acquirableAt | long | 報酬を受け取れるようになる時間 待機期間が満了し報酬が受け取り可能になるタイムスタンプです。exchangedAt + lockTime - skipSeconds として計算されます。現在時刻がこのタイムスタンプを過ぎると、プレイヤーは取得 API を呼び出せるようになります。 |
EzRateModel
交換レートモデル
交換レートモデルはリソースとリソースを交換する際に使用するレートを定義するエンティティです。
直ちに交換できるレートだけでなく、現実時間で一定時間経過したのちに交換できるレートを設定できます。
現実時間での時間経過が必要な交換レートには、更に即時交換を実行するために必要なリソースを定義することが可能です。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | 交換レートモデル名 交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||
| metadata | string | ~ 2048文字 | メタデータ メタデータには任意の値を設定できます。 これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 | |||||||||
| timingType | 文字列列挙型 enum { “immediate”, “await” } | “immediate” | 交換の種類 交換実行後に報酬がいつ配送されるかを決定します。 immediate は交換実行時に即座に報酬を配送します。await は報酬を受け取る前に実時間の経過が必要で、待機期間(例: クラフト時間)を設けます。
| |||||||||
| lockTime | int | {timingType} == “await” | ✓※ | 0 ~ 538214400 | 交換実行から実際に報酬を受け取れるようになるまでの待ち時間(分) timingType が await の場合にのみ適用されます。交換が開始されてからプレイヤーが報酬を受け取れるようになるまでに経過する必要がある実時間の分数を指定します。待ち時間はスキップ機能を使用して短縮できます。※ timingType が “await” であれば 必須 | |||||||
| verifyActions | List<EzVerifyAction> | [] | 0 ~ 10 items | 検証アクションリスト 交換が実行される前にすべてパスする必要がある事前条件チェックです。いずれかの検証アクションが失敗すると、リソースを消費せずに交換が中止されます。レベル要件やインベントリ容量などの条件を強制するために使用されます。 | ||||||||
| consumeActions | List<EzConsumeAction> | [] | 0 ~ 10 items | 消費アクションリスト この交換を実行するためにプレイヤーが支払う必要があるリソース(コスト)を定義します。複数の消費アクションを指定でき、ゴールドとアイテムの両方を必要とするような複雑な交換コストを実現できます。これらのアクションは分散トランザクション内の消費アクションとして実行されます。 | ||||||||
| acquireActions | List<EzAcquireAction> | [] | 0 ~ 100 items | 入手アクションリスト 交換完了時にプレイヤーが受け取るリソース(報酬)を定義します。複数の入手アクションを指定して、さまざまなリソースタイプを同時に付与できます。これらのアクションは分散トランザクション内の入手アクションとして実行されます。 |
EzIncrementalRateModel
コスト上昇型交換レートモデル
通常の交換レートは常に一定のレートでの交換を提供します。
上昇型交換レートでは、交換回数に応じてコストが上昇していくレートを定義することができます。
例えば、1回目の交換では 1:1 で交換できるが、2回目の交換では 2:1 で交換できる、といったレートを定義することができます。
このようなレートを定義することで、プレイヤーがゲームを進めることで得られるリソースの価値を上げることができます。
交換回数は現実時間の経過でリセットすることができます。
この機能を利用することで、毎日あるいは毎週交換に必要なコストをリセットすることができます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | コスト上昇型交換レートモデルの名前 コスト上昇型交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||||
| metadata | string | ~ 2048文字 | メタデータ メタデータには任意の値を設定できます。 これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 | |||||||||||
| calculateType | 文字列列挙型 enum { “linear”, “power”, “gs2_script” } | ✓ | コスト上昇量の計算方式 交換回数に応じてコストがどのように上昇するかを決定します。 linear はコストを baseValue +(coefficientValue × 交換回数)として計算します。power はコストを coefficientValue ×(交換回数 + 1)^2 として計算します。gs2_script は任意のロジックのためにカスタム GS2-Script に計算を委任します。
| |||||||||||
| consumeAction | EzConsumeAction | ✓ | 消費アクション(数量/値は自動的に上書きされます) 交換のコストとして消費されるリソースの種類を定義します。実際の数量は交換回数と計算方式(線形、べき乗、スクリプト)に基づいて動的に計算されます。アクションの種類と対象リソースのみ指定すればよく、数量フィールドは自動的に上書きされます。 | |||||||||||
| baseValue | long | {calculateType} == “linear” | ✓※ | 0 ~ 9223372036854775805 | ベース値linear 計算方式を使用する場合の初回交換時の基本コストです。合計コストは baseValue +(coefficientValue × 交換回数)として計算されます。※ calculateType が “linear” であれば 必須 | |||||||||
| coefficientValue | long | {calculateType} in [“linear”, “power”] | ✓※ | 0 ~ 9223372036854775805 | 係数 交換回数に応じてコストがどれだけ速く上昇するかを制御する乗数です。 linear モードでは、各交換でこの値がコストに加算されます。power モードでは、コストは coefficientValue ×(交換回数 + 1)^2 として計算されます。※ calculateType が “linear”,“power"であれば 必須 | |||||||||
| exchangeCountId | string | ✓ | ~ 1024文字 | 交換実行回数を管理する GS2-Limit の回数制限モデル GRN 各ユーザーがこのコスト上昇型交換を何回実行したかを追跡する GS2-Limit の回数制限モデルを参照します。カウントは上昇するコストの計算に使用され、GS2-Limit のリセットタイミングを使用して定期的(例: 毎日または毎週)にリセットできます。 | ||||||||||
| maximumExchangeCount | int | 2147483646 | 0 ~ 2147483646 | 交換回数の上限 ユーザーがこのコスト上昇型交換を実行できる最大回数です。交換回数がこの上限に達すると、GS2-Limit によるカウントリセットまでそれ以降の交換が拒否されます。 | ||||||||||
| acquireActions | List<EzAcquireAction> | [] | 0 ~ 100 items | 入手アクションリスト コスト上昇型交換の完了時にプレイヤーが受け取るリソース(報酬)を定義します。報酬は交換回数に関わらず一定で、コストのみが交換ごとに増加します。 |
EzConfig
コンフィグ設定
トランザクションの変数に適用する設定値
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64文字 | 名前 | ||
| value | string | ~ 51200文字 | 値 |
EzAcquireAction
入手アクション
EzConsumeAction
消費アクション
EzVerifyAction
検証アクション
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 | 入手アクションの実行結果リスト |
メソッド
acquire
完了した時間制交換の報酬を受け取る
必要な待機時間が経過した時間制交換の報酬を受け取ります。
待機時間がまだ経過していない場合、この呼び出しは失敗します。事前に GetAwait で残り時間を確認してください。
受け取ると待機レコードは消費され、プレイヤーはレートモデルで定義された報酬を受け取ります。
たとえば、「鉄の剣」の製作で3時間待った後にこれを呼ぶと、プレイヤーに剣が付与されます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| awaitName | string | ✓ | UUID | ~ 36文字 | 交換待機の名前 交換待機の一意な名前を保持します。 名前は UUID(Universally Unique Identifier)フォーマットで自動的に生成され、交換待機を識別するために使用されます。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzAwait | 交換待機 |
| transactionId | string | 発行されたトランザクションID |
| stampSheet | string | 報酬取得処理の実行に使用するスタンプシート |
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
| autoRunStampSheet | bool | トランザクションの自動実行が有効か |
| atomicCommit | bool | トランザクションをアトミックにコミットするか |
| transaction | string | 発行されたトランザクション |
| transactionResult | EzTransactionResult | トランザクション実行結果 |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
var result = await domain.AcquireAsync(
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。 var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
var future = domain.AcquireFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。 const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Await(
"await-0001" // awaitName
);
const auto Future = Domain->Acquire(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}deleteAwait
待機中の時間制交換をキャンセルする
待機中の交換待機レコードを削除し、交換をキャンセルします。
報酬は付与されず、交換開始時に支払ったリソースも返還されません。
プレイヤーが製作中や建設中の注文をキャンセルしたい場合に使います。コストが戻らないため、確認ダイアログを表示することをおすすめします。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| awaitName | string | ✓ | UUID | ~ 36文字 | 交換待機の名前 交換待機の一意な名前を保持します。 名前は UUID(Universally Unique Identifier)フォーマットで自動的に生成され、交換待機を識別するために使用されます。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzAwait | 交換待機 |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
var result = await domain.DeleteAwaitAsync(
); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
var future = domain.DeleteAwaitFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Await(
"await-0001" // awaitName
);
const auto Future = Domain->DeleteAwait(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();getAwait
特定の待機中の時間制交換を取得する
特定の交換待機レコードの詳細を取得します。
取得できる情報には、交換タイプ、リクエストした数量、開始日時、残りの待機時間が含まれます。
特定の待機中交換の詳細画面を表示する際に使います。たとえば、「鉄の剣を製作中… 残り2時間30分」のような表示に便利です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| awaitName | string | ✓ | UUID | ~ 36文字 | 交換待機の名前 交換待機の一意な名前を保持します。 名前は UUID(Universally Unique Identifier)フォーマットで自動的に生成され、交換待機を識別するために使用されます。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzAwait | 交換待機 |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Await(
"await-0001" // awaitName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Await(
awaitName: "await-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Await(
"await-0001" // awaitName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Exchange::Model::FAwait> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listAwaits
待機中の時間制交換の一覧を取得する
プレイヤーの交換待機レコードを取得します。報酬を受け取る前に待機が必要な交換(クラフトや建設のような仕組み)の一覧です。
レート名を指定して、特定の交換タイプの待機のみを表示することもできます。
「製作中のアイテム」や「進行中」のリストを構築するのに使います。プレイヤーが何を待っていて、あとどのくらいかかるかを表示できます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| rateName | string | ~ 128文字 | 交換レートモデル名 交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzAwait> | 交換待機のリスト |
| nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.AwaitsAsync(
rateName: "material_n_to_r"
).ToListAsync(); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Awaits(
rateName: "material_n_to_r"
);
List<EzAwait> items = new List<EzAwait>();
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->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Awaits(
"material_n_to_r" // rateName
);
TArray<Gs2::UE5::Exchange::Model::FEzAwaitPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeAwaits(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeAwaits(callbackId); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeAwaits(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeAwaits(callbackId); const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeAwaits(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeAwaits(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
getRateModel
名前を指定して交換レートモデルを取得する
名前を指定して、交換レートモデルを1件取得します。
取得できる情報には、プレイヤーが支払うもの、受け取るもの、即時交換か待機が必要かが含まれます。
特定の交換の詳細を表示する際に使います。たとえば、ショップのアイテム詳細画面で「コスト: ゴールド100 → 報酬: 回復ポーション1個」のように表示するのに便利です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| rateName | string | ✓ | ~ 128文字 | 交換レートモデル名 交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzRateModel | 交換レートモデル |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
var item = await domain.ModelAsync(); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->RateModel(
"character-level" // rateName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->RateModel(
"character-level" // rateName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Exchange::Model::FRateModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listRateModels
交換レートモデルの一覧を取得する
このネームスペースに登録されているすべての交換レートモデルを取得します。
レートモデルは交換のレシピを定義します。プレイヤーが何を支払い(例: ゴールド100枚)、何を受け取るか(例: 回復ポーション1個)を設定します。
タイミングには2種類あります。「即時」交換はすぐに完了し、「待機」交換はプレイヤーが一定時間待ってから報酬を受け取ります(クラフトのような仕組み)。
ショップやクラフトUIを構築する際に、プレイヤーに利用可能な交換オプションを表示するのに使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzRateModel> | 交換レートモデルのリスト |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.RateModelsAsync(
).ToListAsync(); var domain = gs2.Exchange.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->Exchange->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->RateModels(
);
TArray<Gs2::UE5::Exchange::Model::FEzRateModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeRateModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeRateModels(callbackId); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeRateModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeRateModels(callbackId); const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeRateModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeRateModels(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
getIncrementalRateModel
名前を指定してコスト上昇型交換レートモデルを取得する
名前を指定して、コスト上昇型交換レートモデルを1件取得します。
取得できる情報には、コスト計算方法(線形計算式またはカスタムスクリプト)、基本コスト、交換ごとのコスト増加量、最大交換回数、プレイヤーが受け取るものが含まれます。
特定のコスト上昇型交換の詳細を表示する際に使います。たとえば、ショップ画面で「スタミナ回復: ジェム30個(本日3回目、最大5回)」のように表示するのに便利です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| rateName | string | ✓ | ~ 128文字 | コスト上昇型交換レートモデルの名前 コスト上昇型交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzIncrementalRateModel | コスト上昇型交換レートモデル |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).IncrementalRateModel(
rateName: "character-level"
);
var item = await domain.ModelAsync(); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).IncrementalRateModel(
rateName: "character-level"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->IncrementalRateModel(
"character-level" // rateName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).IncrementalRateModel(
rateName: "character-level"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).IncrementalRateModel(
rateName: "character-level"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->IncrementalRateModel(
"character-level" // rateName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Exchange::Model::FIncrementalRateModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listIncrementalRateModels
コスト上昇型交換レートモデルの一覧を取得する
このネームスペースに登録されているすべてのコスト上昇型交換レートモデルを取得します。
コスト上昇型モデルは、プレイヤーが使うたびに値段が上がる交換を定義します。たとえば、スタミナ回復1回目はジェム10個、2回目は20個、3回目は30個…というような仕組みです。
コストの上昇は、シンプルな線形計算式(基本値 + 係数 × 回数)またはカスタムスクリプトで計算できます。
利用可能なコスト上昇型交換と現在のコストを表示するUIを構築するのに使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzIncrementalRateModel> | コスト上昇型交換レートモデルのリスト |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.IncrementalRateModelsAsync(
).ToListAsync(); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.IncrementalRateModels(
);
List<EzIncrementalRateModel> items = new List<EzIncrementalRateModel>();
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->Exchange->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->IncrementalRateModels(
);
TArray<Gs2::UE5::Exchange::Model::FEzIncrementalRateModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeIncrementalRateModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeIncrementalRateModels(callbackId); var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeIncrementalRateModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeIncrementalRateModels(callbackId); const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeIncrementalRateModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeIncrementalRateModels(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
exchange
交換を実行する
指定した交換レートモデルに基づいてリソースを交換します。
プレイヤーはレートモデルで定義されたコストを支払い、報酬を受け取ります。たとえば、ゴールド100枚を回復ポーション1個と交換するといった処理です。
回数を指定して同じ交換をまとめて実行することもできます(例: ポーション5個をゴールド500枚で購入)。
レートモデルが「待機」タイミングの場合、即時完了ではなく時間待機型の交換が開始されます(報酬の受け取りは Await 系 API を参照してください)。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| rateName | string | ✓ | ~ 128文字 | 交換レートモデル名 交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| count | int | ✓ | 1 ~ 1073741821 | 交換回数 | ||
| config | List<EzConfig> | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzRateModel | 交換レートモデル |
| transactionId | string | 発行されたトランザクションID |
| stampSheet | string | 交換処理の実行に使用するスタンプシート |
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
| autoRunStampSheet | bool | トランザクションの自動実行が有効か |
| atomicCommit | bool | トランザクションをアトミックにコミットするか |
| transaction | string | 発行されたトランザクション |
| transactionResult | EzTransactionResult | トランザクション実行結果 |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Exchange(
);
var result = await domain.ExchangeAsync(
rateName: "rate-0001",
count: 1,
config: null
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。 var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Exchange(
);
var future = domain.ExchangeFuture(
rateName: "rate-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() でリトライが可能です。 const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Exchange(
);
const auto Future = Domain->Exchange(
"rate-0001", // rateName
1 // count
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}incrementalExchange
コスト上昇型の交換を実行する
使うたびにコストが上がるレートモデルを使ってリソースを交換します。
コストはプレイヤーがこれまでに何回交換したかに基づいて自動計算されます。たとえば、スタミナ回復1回目はジェム10個、2回目は20個…というように上がっていきます。
回数を指定してまとめて交換することもできます。その場合、合計コストは各回の価格の合計になります。
毎日のスタミナ回復、回数限定ショップ、繰り返し利用で値上がりさせたい仕組みに使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| rateName | string | ✓ | ~ 128文字 | コスト上昇型交換レートモデルの名前 コスト上昇型交換レートモデルの種類固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| count | int | ✓ | 1 ~ 1073741821 | 交換回数 | ||
| config | List<EzConfig> | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzIncrementalRateModel | コスト上昇型交換レートモデル |
| transactionId | string | 発行されたトランザクションID |
| stampSheet | string | 交換処理の実行に使用するスタンプシート |
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
| autoRunStampSheet | bool | トランザクションの自動実行が有効か |
| atomicCommit | bool | トランザクションをアトミックにコミットするか |
| transaction | string | 発行されたトランザクション |
| transactionResult | EzTransactionResult | トランザクション実行結果 |
実装例
var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Exchange(
);
var result = await domain.IncrementalExchangeAsync(
rateName: "rate-0001",
count: 1,
config: null
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。 var domain = gs2.Exchange.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Exchange(
);
var future = domain.IncrementalExchangeFuture(
rateName: "rate-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() でリトライが可能です。 const auto Domain = Gs2->Exchange->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Exchange(
);
const auto Future = Domain->IncrementalExchange(
"rate-0001", // rateName
1 // count
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}