API Reference of GS2-Quest SDK for Game Engine

Model

EzContents

TypeRequireDefaultLimitationDescription
metadatastring~ 256 charsmetadata
completeAcquireActionsList<EzAcquireAction>[]Rewards for completing quests

EzConsumeAction

TypeRequireDefaultLimitationDescription
actionenum []~ 128 charsTypes of actions to be performed in the stamp task
requeststring~ 1048576 charsJSON of the obtain request

EzAcquireAction

TypeRequireDefaultLimitationDescription
actionenum []~ 128 charsTypes of actions to be performed in the stamp sheet
requeststring~ 1048576 charsJSON of request

EzReward

TypeRequireDefaultLimitationDescription
actionenum []~ 128 charsTypes of actions to be performed in the stamp sheet
requeststring~ 5242880 charsRequest Model
itemIdstring~ 1024 charsObtain Resource GRN
valueint~ 2147483646Quantity to be obtained

EzConfig

TypeRequireDefaultLimitationDescription
keystring~ 64 charsName
valuestring~ 51200 charsValue

EzProgress

Quest Progress

It is created at the beginning of the quest and deleted at the end.

When you exit the application in the middle of an ingame, this data will remain. It is possible to resume the game from the ongoing quest information maintained by the entity.

TypeRequireDefaultLimitationDescription
progressIdstring~ 1024 charsQuest Progress GRN
transactionIdstringUUID~ 36 charsTransaction ID
questModelIdstring~ 1024 charsQuest model GRN in progress
randomSeedlong~ 9223372036854775805Random number seed
rewardsList<EzReward>[]Maximum rewards earned from quests

EzCompletedQuestList

List of completed quests

TypeRequireDefaultLimitationDescription
questGroupNamestring~ 128 charsQuest Group Name
completeQuestNamesList<string>List of Names of the quests already conquered

EzQuestGroupModel

Quest Group Model

A quest group is an entity for grouping multiple quests, and only one quest progression can be executed simultaneously within the group. This means that if you need to be able to progress quests in parallel, you must separate the groups.

TypeRequireDefaultLimitationDescription
namestring~ 128 charsQuest Group Name
metadatastring~ 1024 charsmetadata
questsList<EzQuestModel>Quests belonging to the group
challengePeriodEventIdstring~ 1024 charsGS2-Schedule event GRN that sets the time period during which the quest can be attempted.

EzQuestModel

Quest Model

A quest is an entity that holds the consideration required to start ingame and the reward for completing it.

The reward obtained upon completion of the quest can have multiple variations and can be drawn at the start of the quest. For example, the same content can be used to manage the clear flag of a quest, but two types of content can be prepared based on whether or not a rare monster appears.

TypeRequireDefaultLimitationDescription
questModelIdstring~ 1024 charsQuest Model GRN
namestring~ 128 charsQuest Model Name
metadatastring~ 1024 charsmetadata
contentsList<EzContents>Quest Description
challengePeriodEventIdstring~ 1024 charsGS2-Schedule event GRN that sets the time period during which the quest can be attempted.
firstCompleteAcquireActionsList<EzAcquireAction>[]List of First Clear Reward Actions
consumeActionsList<EzConsumeAction>[]Quest entry fee
failedAcquireActionsList<EzAcquireAction>[]Reward for quest failure
premiseQuestNamesList<string>[]Name of the quest that must be completed in order to attempt the quest

Methods

deleteProgress

Delete quest progress information.

Use this option if you want to explicitly remove progress information instead of using the force option at the beginning of the quest.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itemEzProgressQuest Progress

Implementation Example

    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    var result = await domain.DeleteProgressAsync(
    );
    var domain = gs2.Quest.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Progress(
    );
    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
    )->Progress(
    );
    const auto Future = Domain->DeleteProgress(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

end

Declare the start of a quest

If a quest has already been started by the same game player, it will fail. If you still want to force a start, specify true for the force option.

Once a quest has been started, information about the maximum reward available for that quest will be responded to. You can exhaust that information in the quest by directing it in the quest. In doing so, design the gameplay to be reproducible using the random number seed contained in the response, so that it is easier to investigate when a random number-caused problem occurs in the application.

A Quest Transaction ID is responded to as an ID to uniquely identify the quest in progress. When reporting the completion of a quest, the Quest Transaction ID is used to identify which quest the completion report is for.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id
rewardsList<EzReward>[]The actual rewards from the quest
isCompleteboolCompleted the quest
configList<EzConfig>[]Set values to be applied to stamp sheet variables

Result

TypeDescription
itemEzProgressQuest Progress
transactionIdstringTransaction ID of the stamp sheet issued
stampSheetstringStamp sheet used to execute the reward granting process
stampSheetEncryptionKeyIdstringCryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheetboolIs stamp sheet auto-execution enabled?

Implementation Example

    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

Obtain information on the progress of the quest.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itemEzProgressQuest Progress
questGroupEzQuestGroupModelQuest Group Model
questEzQuestModelQuest Model

Implementation Example

    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 Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

start

Declare the start of a quest

If a quest has already been started by the same game player, it will fail. If you still want to force a start, specify true for the force option.

Once a quest has been started, information about the maximum reward available for that quest will be responded to. You can exhaust that information in the quest by directing it in the quest. In doing so, design the gameplay to be reproducible using the random number seed contained in the response, so that it is easier to investigate when a random number-caused problem occurs in the application.

A Quest Transaction ID is responded to as an ID to uniquely identify the quest in progress. When reporting the completion of a quest, the Quest Transaction ID is used to identify which quest the completion report is for.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
questGroupNamestring~ 128 charsQuest Group Name
questNamestring~ 128 charsQuest Name
accessTokenstring~ 128 charsUser Id
forceboolfalseIf have a quest already started, you can discard it and start it
configList<EzConfig>[]Set values to be applied to stamp sheet variables

Result

TypeDescription
transactionIdstringTransaction ID of the stamp sheet issued
stampSheetstringStamp sheet used to execute the quest initiation process
stampSheetEncryptionKeyIdstringCryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheetboolIs stamp sheet auto-execution enabled?

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

TypeBase TypeDescription
InProgressExceptionBadRequestExceptionQuest is already underway.

Implementation Example

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

Get list of quest progress information

Each quest group is registered as a single Quest Progress Information The Quest Progress Information` contains list of completed quest names in the quest group.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
accessTokenstring~ 128 charsUser Id
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data acquired

Result

TypeDescription
itemsList<EzCompletedQuestList>List of Quest Progressios
nextPageTokenstringPage token to retrieve the rest of the listing

Implementation Example

    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

Get quest progress information

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
questGroupNamestring~ 128 charsQuest Group Name
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itemEzCompletedQuestListQuest Progression

Implementation Example

    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 Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

getQuestGroup

Get list of quest groups

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
questGroupNamestring~ 128 charsQuest Group Name

Result

TypeDescription
itemEzQuestGroupModelQuest Group Model

Implementation Example

    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 Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

listQuestGroups

Get list of quest groups

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name

Result

TypeDescription
itemsList<EzQuestGroupModel>List of Quest Group Models

Implementation Example

    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

Get Quest Model

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
questGroupNamestring~ 128 charsQuest Group Name
questNamestring~ 128 charsQuest Model Name

Result

TypeDescription
itemEzQuestModel

Implementation Example

    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 Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

listQuests

Get list of quest models

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 32 charsNamespace name
questGroupNamestring~ 128 charsQuest Group Name

Result

TypeDescription
itemsList<EzQuestModel>List of Quest Models

Implementation Example

    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)
    {

    }