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

モデル

EzContents

	型	必須	デフォルト	値の制限	説明
metadata	string			~ 256文字	メタデータ
completeAcquireActions	List<EzAcquireAction>		[]		クエストクリア時の報酬

EzConsumeAction

	型	必須	デフォルト	値の制限	説明
action	enum []	✓		~ 128文字	スタンプタスクで実行するアクションの種類
request	string	✓		~ 1048576文字	入手リクエストのJSON

EzAcquireAction

	型	必須	デフォルト	値の制限	説明
action	enum []	✓		~ 128文字	スタンプシートを使用して実行するアクションの種類
request	string	✓		~ 1048576文字	リクエストのJSON

EzReward

	型	必須	値の制限	説明
action	enum []	✓	~ 128文字	スタンプシートを使用して実行するアクションの種類
request	string	✓	~ 5242880文字	リクエストモデル
itemId	string	✓	~ 1024文字	入手するリソースGRN
value	int	✓	~ 2147483646	入手する数量

EzConfig

	型	必須	デフォルト	値の制限	説明
key	string			~ 64文字	名前
value	string			~ 51200文字	値

EzProgress

クエスト進行状況

クエストの開始時に作成され、終了時に削除されます。

インゲームの途中でアプリを終了した際にはこのデータが残った状態となりエンティティが保持する進行中のクエスト情報からゲームをリジュームすることが可能です。

	型	必須	デフォルト	値の制限	説明
progressId	string	✓		~ 1024文字	クエスト進行状況GRN
transactionId	string	✓	UUID	~ 36文字	トランザクションID
questModelId	string	✓		~ 1024文字	進行中のクエストモデルGRN
randomSeed	long	✓		~ 9223372036854775806	乱数シード
rewards	List<EzReward>		[]		クエストで得られる報酬の上限

EzCompletedQuestList

クリア済みのクエストリスト

	型	必須	デフォルト	値の制限	説明
questGroupName	string	✓		~ 128文字	クエストグループ名
completeQuestNames	List<string>				攻略済みのクエスト名一覧のリスト

EzQuestGroupModel

クエストグループモデル

クエストグループは複数のクエストをグルーピングするためのエンティティで、クエストの進行はグループ内で同時に1つしか実行できません。つまり、並列でクエストを進行できるようにする必要がある場合はグループを分ける必要があります。

	型	必須	値の制限	説明
name	string	✓	~ 128文字	クエストグループ名
metadata	string		~ 1024文字	メタデータ
quests	List<EzQuestModel>			グループに属するクエスト
challengePeriodEventId	string		~ 1024文字	クエストに挑戦可能な期間を設定した GS2-Schedule イベントGRN

EzQuestModel

クエストモデル

クエストはインゲームの開始に必要な対価とクリアしたときに得られる報酬を保持するエンティティです。

クリアしたときに得られる報酬は複数のバリエーションを用意でき、クエスト開始時に抽選することができます。例えば、クエストのクリアフラグ管理は同じコンテンツだが、レアモンスターの出現有無で2種類のコンテンツを用意することができます。

	型	必須	デフォルト	値の制限	説明
questModelId	string	✓		~ 1024文字	クエストモデルGRN
name	string	✓		~ 128文字	クエストモデル名
metadata	string			~ 1024文字	メタデータ
contents	List<EzContents>	✓			クエストの内容
challengePeriodEventId	string			~ 1024文字	クエストに挑戦可能な期間を設定した GS2-Schedule イベントGRN
firstCompleteAcquireActions	List<EzAcquireAction>		[]		初回クリア報酬アクションリスト
consumeActions	List<EzConsumeAction>		[]		クエストの参加料
failedAcquireActions	List<EzAcquireAction>		[]		クエスト失敗時の報酬
premiseQuestNames	List<string>		[]		クエストに挑戦するためにクリアしておく必要のあるクエスト名

メソッド

deleteProgress

クエストの進行情報を削除。

クエストの開始時に force オプションを使うのではなく、明示的に進行情報を削除したい場合に使用してください。

Request

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

Result

	型	説明
item	EzProgress	クエスト進行状況

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.DeleteProgressAsync(
    );

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.DeleteProgress(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto Future = Domain->DeleteProgress(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

end

クエストの完了を報告

クエストが完了したことを報告します。その際に isComplete にクエストに成功したか、失敗したかを渡します。クエストに成功した場合は rewards にクエスト内で入手した報酬を報告する必要があります。

rewards で報告された内容は評価され、開始時に渡した数量以上や入手できないリソースを入手したと報告してきた場合はエラーとなります。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
accessToken	string	✓		~ 128文字	ユーザーID
rewards	List<EzReward>		[]		クエストで実際に得た報酬
transactionId	string	✓	UUID	~ 36文字	トランザクションID
isComplete	bool	✓			クエストをクリアしたか
config	List<EzConfig>		[]		スタンプシートの変数に適用する設定値

Result

	型	説明
item	EzProgress	クエスト進行状況
transactionId	string	発行されたスタンプシートのトランザクションID
stampSheet	string	報酬付与処理の実行に使用するスタンプシート
stampSheetEncryptionKeyId	string	スタンプシートの署名計算に使用した暗号鍵GRN
autoRunStampSheet	bool	スタンプシートの自動実行が有効か

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var result = await domain.EndAsync(
        isComplete: true,
        rewards: new Gs2.Unity.Gs2Quest.Model.EzReward[] {
            new Gs2.Unity.Gs2Quest.Model.EzReward
            {},
        },
        config: null
    );
    // 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.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var future = domain.End(
        isComplete: true,
        rewards: new Gs2.Unity.Gs2Quest.Model.EzReward[] {
            new Gs2.Unity.Gs2Quest.Model.EzReward
            {},
        },
        config: null
    );
    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->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Progress(
    );
    const auto Future = Domain->End(
        true,
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Quest::Model::FReward>>>();
            v->Add({});
            return v;
        }(), // rewards
        nullptr // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

getProgress

クエストの進行情報を取得。

Request

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

Result

	型	説明
item	EzProgress	クエスト進行状況
questGroup	EzQuestGroupModel	クエストグループモデル
quest	EzQuestModel	クエストモデル

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Progress(
    );
    const auto item = Domain.Model();

start

クエストの開始を宣言

すでに同一ゲームプレイヤーで開始済みのクエストがある場合は失敗します。それでも強制的に開始したい場合は force オプションに true を指定してください。

クエストの開始が完了すると、そのクエストで得られる最大報酬に関する情報が応答されます。その内容をクエスト内の演出で排出してください。その際に、応答に含まれる乱数シードを使用してゲームプレイに再現性があるように設計しておくと、アプリで乱数起因の不具合が発生したときに調査しやすくなります。

進行中のクエストを一意に特定するためのIDとして クエストトランザクションID が応答されます。クエストの完了を報告する際には クエストトランザクションID を指定することで、どのクエストに対する完了報告かを識別します。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
questGroupName	string	✓		~ 128文字	クエストグループ名
questName	string	✓		~ 128文字	クエストモデル名
accessToken	string	✓		~ 128文字	ユーザーID
force	bool	✓	false		すでに開始しているクエストがある場合にそれを破棄して開始するか
config	List<EzConfig>		[]		スタンプシートの変数に適用する設定値

Result

	型	説明
transactionId	string	発行されたスタンプシートのトランザクションID
stampSheet	string	クエストの開始処理の実行に使用するスタンプシート
stampSheetEncryptionKeyId	string	スタンプシートの署名計算に使用した暗号鍵GRN
autoRunStampSheet	bool	スタンプシートの自動実行が有効か

Error

このAPIには特別な例外が定義されています。 GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。一般的なエラーの種類や、ハンドリング方法はこちらのドキュメントを参考にしてください。

型	基底クラス	説明
InProgressException	BadRequestException	クエストはすでに進行中です

実装例

try {
    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.StartAsync(
        questGroupName: "group-0001",
        questName: "quest-0001",
        force: null,
        config: null
    );
} catch(Gs2.Gs2Quest.Exception.InProgress e) {
    // Quest is already underway.
}
    // 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.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.Start(
        questGroupName: "group-0001",
        questName: "quest-0001",
        force: null,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Quest.Exception.InProgressException)
        {
            // Quest is already underway.
        }
        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->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto Future = Domain->Start(
        "group-0001",
        "quest-0001",
        nullptr, // force
        nullptr // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        if (Gs2::Quest::Error::FInProgressError::TypeString == Task->GetTask().Error()->Type())
        {
            // Quest is already underway.
        }
        return false;
    }

describeCompletedQuestLists

クエスト進行情報の一覧を取得

クエストグループごとに1つの クエスト進行情報 として登録されており、 クエスト進行情報 にはクエストグループ内でクリア済みのクエスト名の一覧が記録されています。

Request

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 32文字	ネームスペース名
accessToken	string	✓		~ 128文字	ユーザーID
pageToken	string			~ 1024文字	データの取得を開始する位置を指定するトークン
limit	int	✓	30	1 ~ 1000	データの取得件数

Result

	型	説明
items	List<EzCompletedQuestList>	クエスト進行のリスト
nextPageToken	string	リストの続きを取得するためのページトークン

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.CompletedQuestListsAsync(
    ).ToListAsync();

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.CompletedQuestLists(
    );
    List<EzCompletedQuestList> items = new List<EzCompletedQuestList>();
    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->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->CompletedQuestLists(
    );
    for (auto Item : *It)
    {

    }

getCompletedQuestList

クエスト進行情報を取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
questGroupName	string	✓	~ 128文字	クエストグループ名
accessToken	string	✓	~ 128文字	ユーザーID

Result

	型	説明
item	EzCompletedQuestList	クエスト進行

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).CompletedQuestList(
        questGroupName: "main"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).CompletedQuestList(
        questGroupName: "main"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->CompletedQuestList(
        "main" // questGroupName
    );
    const auto item = Domain.Model();

getQuestGroup

クエストグループの一覧を取得

Request

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

Result

	型	説明
item	EzQuestGroupModel	クエストグループモデル

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).QuestGroupModel(
        questGroupName: "quest-group-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).QuestGroupModel(
        questGroupName: "quest-group-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->QuestGroupModel(
        "quest-group-0001" // questGroupName
    );
    const auto item = Domain.Model();

listQuestGroups

クエストグループの一覧を取得

Request

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

Result

	型	説明
items	List<EzQuestGroupModel>	クエストグループモデルのリスト

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.QuestGroupModelsAsync(
    ).ToListAsync();

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.QuestGroupModels(
    );
    List<EzQuestGroupModel> items = new List<EzQuestGroupModel>();
    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->Quest->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->QuestGroupModels(
    );
    for (auto Item : *It)
    {

    }

getQuest

クエストモデルを取得

Request

	型	必須	値の制限	説明
namespaceName	string	✓	~ 32文字	ネームスペース名
questGroupName	string	✓	~ 128文字	クエストグループ名
questName	string	✓	~ 128文字	クエストモデル名

Result

	型	説明
item	EzQuestModel

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).QuestGroupModel(
        questGroupName: "quest-group-0001"
    ).QuestModel(
        questName: "quest-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).QuestGroupModel(
        questGroupName: "quest-group-0001"
    ).QuestModel(
        questName: "quest-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->QuestGroupModel(
        "quest-group-0001" // questGroupName
    )->QuestModel(
        "quest-0001" // questName
    );
    const auto item = Domain.Model();

listQuests

クエストモデルの一覧を取得

Request

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

Result

	型	説明
items	List<EzQuestModel>	クエストモデルのリスト

実装例

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).QuestGroupModel(
        questGroupName: "quest-group-0001"
    );
    var items = await domain.QuestModelsAsync(
    ).ToListAsync();

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).QuestGroupModel(
        questGroupName: "quest-group-0001"
    );
    var it = domain.QuestModels(
    );
    List<EzQuestModel> items = new List<EzQuestModel>();
    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->Quest->Namespace(
        "namespace-0001" // namespaceName
    )->QuestGroupModel(
        "quest-group-0001" // questGroupName
    );
    const auto It = Domain->QuestModels(
    );
    for (auto Item : *It)
    {

    }