GS2-Idle SDK for Game Engine API リファレンス

モデル

EzCategoryModel

カテゴリーモデルマスター

カテゴリーモデルとは、放置報酬を得られる待機カテゴリーの設定するエンティティです。設定には、待機時間ごとの報酬や、最大待機時間などの情報が含まれます。

	型	必須	値の制限	説明
name	string	✓	~ 128文字	カテゴリーモデル名
metadata	string		~ 2048文字	メタデータ
rewardIntervalMinutes	int	✓	~ 2147483646	待機報酬が得られる間隔(分）
defaultMaximumIdleMinutes	int	✓	~ 2147483646	待機報酬が得られる最大時間(分）
acquireActions	List<EzAcquireActionList>	✓		待機時間ごとに得られる入手アクションリスト
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	enum []	✓		~ 128文字	スタンプシートを使用して実行するアクションの種類
request	string	✓		~ 1048576文字	リクエストのJSON

EzAcquireActionList

	型	必須	デフォルト	値の制限	説明
acquireActions	List<EzAcquireAction>				入手アクションリスト

メソッド

getCategoryModel

カテゴリーモデル情報を取得

カテゴリーモデル名 を指定してランクキャップの情報やランクアップ閾値の情報を取得します。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
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;
    }

listCategoryModels

カテゴリーモデル情報の一覧を取得

ランクキャップの情報やランクアップ閾値の情報を取得します。次のランクアップまでに必要な獲得カテゴリー量などをゲーム内で表示したい場合はこのモデルデータを使ってください。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名

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(
    );
    for (auto Item : *It)
    {

    }

getStatus

カテゴリーモデルを指定してステータス情報を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
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(
        AccessToken
    )->Status(
        "category-0001" // categoryName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

listStatuses

ステータス情報の一覧を取得

カテゴリーモデル名は省略可能で、指定しなかった場合はゲームプレイヤーに属する全てのステータス情報が取得できます。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
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(
        AccessToken
    );
    const auto It = Domain->Statuses(
    );
    for (auto Item : *It)
    {

    }

prediction

獲得報酬の一覧を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
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.Prediction(
    );
    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(
        AccessToken
    )->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 (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

receive

報酬を受け取る

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
categoryName	string	✓	~ 128文字	カテゴリーモデル名
accessToken	string	✓	~ 128文字	ユーザーID

Result

	型	説明
items	List<EzAcquireAction>	報酬
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.Receive(
    );
    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(
        AccessToken
    )->Status(
        "category-0001" // categoryName
    );
    const auto Future = Domain->Receive(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }