GS2-Idle SDK for Game Engine API リファレンス
モデル
EzCategoryModel
カテゴリーモデルマスター
カテゴリーモデルとは、放置報酬を得られる待機カテゴリーの設定するエンティティです。
設定には、待機時間ごとの報酬や、最大待機時間などの情報が含まれます。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128文字 | カテゴリーモデル名 | |
metadata | string | ~ 2048文字 | メタデータ | ||
rewardIntervalMinutes | int | ✓ | ~ 2147483646 | 待機報酬が得られる間隔(分) | |
defaultMaximumIdleMinutes | int | ✓ | ~ 2147483646 | 待機報酬が得られる最大時間(分) | |
acquireActions | List<EzAcquireActionList> | ✓ | 1 ~ 100 items | 待機時間ごとに得られる入手アクションリスト | |
idlePeriodScheduleId | string | ~ 1024文字 | 放置報酬計算に使用される期間を設定した GS2-Schedule イベントGRN | ||
receivePeriodScheduleId | string | ~ 1024文字 | 放置報酬を受け取れる期間を設定した GS2-Schedule イベントGRN |
EzStatus
ステータス
初めて GetIdleStatus を呼び出した時に作成され、その時間から放置時間のカウントが始まります。
放置時間のカウントは報酬を受け取るとリセットされます。
GS2-Schedule のイベントが関連づけられている場合、イベントの開催前には Category にアクセスできず、ステータスを作成することもできません。
イベントが関連づけられている場合、ステータス はイベントの繰り返し回数を保持します。
現在のイベントIDとステータス作成時のイベントIDが一致しない場合、現在のイベントの繰り返し回数とステータスが保持する繰り返し回数が一致しない場合、またはイベントの開始時刻より前にステータスが作成されている場合、待機時間 はリセットされます。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
categoryName | string | ✓ | ~ 128文字 | カテゴリーモデル名 | |
randomSeed | long | ✓ | 0 | ~ 9223372036854775805 | 乱数シード |
idleMinutes | int | ✓ | ~ 2147483646 | 放置時間 | |
maximumIdleMinutes | int | ✓ | 0 | ~ 2147483646 | 最大放置時間 |
EzConfig
コンフィグ設定
トランザクションの変数に適用する設定値
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
key | string | ✓ | ~ 64文字 | 名前 | |
value | string | ~ 51200文字 | 値 |
EzAcquireAction
入手アクション
action に指定する列挙型の定義
定義 | 説明 |
---|
EzAcquireActionList
入手アクションリスト
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
acquireActions | List<EzAcquireAction> | ~ 100 items | 入手アクションリスト |
メソッド
getCategoryModel
カテゴリーモデル情報を取得
カテゴリーモデル名
を指定してランクキャップの情報やランクアップ閾値の情報を取得します。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
categoryName | string | ✓ | ~ 128文字 | カテゴリーモデル名 |
Result
型 | 説明 | |
---|---|---|
item | EzCategoryModel | カテゴリーモデル |
実装例
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
var item = await domain.ModelAsync();
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->CategoryModel(
"category-0001" // categoryName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
値の変更イベントハンドリング
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->CategoryModel(
"category-0001" // categoryName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Idle::Model::FCategoryModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listCategoryModels
カテゴリーモデル情報の一覧を取得
ランクキャップの情報やランクアップ閾値の情報を取得します。
次のランクアップまでに必要な獲得カテゴリー量などをゲーム内で表示したい場合はこのモデルデータを使ってください。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 |
Result
型 | 説明 | |
---|---|---|
items | List<EzCategoryModel> | カテゴリーモデルリスト |
実装例
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.CategoryModelsAsync(
).ToListAsync();
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.CategoryModels(
);
List<EzCategoryModel> items = new List<EzCategoryModel>();
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->Idle->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->CategoryModels(
);
TArray<Gs2::UE5::Idle::Model::FEzCategoryModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
値の変更イベントハンドリング
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeCategoryModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeCategoryModels(callbackId);
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.CategoryModels(
);
List<EzCategoryModel> items = new List<EzCategoryModel>();
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->Idle->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeCategoryModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeCategoryModels(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
getStatus
カテゴリーモデル
を指定してステータス情報を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
categoryName | string | ✓ | ~ 128文字 | カテゴリーモデル名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
item | EzStatus | ステータス |
実装例
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var item = await domain.ModelAsync();
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
値の変更イベントハンドリング
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Idle::Model::FStatus> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listStatuses
ステータス情報の一覧を取得
カテゴリーモデル名 は省略可能で、指定しなかった場合はゲームプレイヤーに属する全てのステータス情報が取得できます。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | ||
limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
型 | 説明 | |
---|---|---|
items | List<EzStatus> | ステータスのリスト |
nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.StatusesAsync(
).ToListAsync();
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Statuses(
);
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->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Statuses(
);
TArray<Gs2::UE5::Idle::Model::FEzStatusPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
値の変更イベントハンドリング
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeStatuses(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeStatuses(callbackId);
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Statuses(
);
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->Idle->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 の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
prediction
獲得報酬の一覧を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
categoryName | string | ✓ | ~ 128文字 | カテゴリーモデル名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
items | List<EzAcquireAction> | 報酬 |
status | EzStatus | ステータス |
実装例
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var result = await domain.PredictionAsync(
);
var item = await result.ModelAsync();
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var future = domain.PredictionFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.Model();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
const auto Future = Domain->Prediction(
);
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();
receive
報酬を受け取る
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
categoryName | string | ✓ | ~ 128文字 | カテゴリーモデル名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
items | List<EzAcquireAction> | 報酬 |
status | EzStatus | 更新したステータス |
transactionId | string | 発行されたトランザクションID |
stampSheet | string | クエストの開始処理の実行に使用するスタンプシート |
stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
autoRunStampSheet | bool | トランザクションの自動実行が有効か |
実装例
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var result = await domain.ReceiveAsync(
);
// 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.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var future = domain.ReceiveFuture(
);
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->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
const auto Future = Domain->Receive(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}