GS2-Quest SDK for Game Engine API Reference
Model
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 in-game, this data will remain. It is possible to resume the game from the ongoing quest information maintained by the entity.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| progressId | string | * | ~ 1024 chars | Quest Progress GRN * Set automatically by the server | ||
| transactionId | string | ✓ | UUID | ~ 36 chars | Transaction ID Unique identifier for the quest transaction. Used to associate the quest progress with the transaction that manages reward distribution. | |
| questModelId | string | ✓ | ~ 1024 chars | Quest Model GRN GRN of the quest model currently in progress. Identifies which quest the user is playing, enabling game resume if the application is closed mid-quest. | ||
| randomSeed | long | ✓ | 0 ~ 9223372036854775805 | Random Seed Random number seed assigned at quest start. Used to determine the content variation (reward set) selected for this quest attempt, ensuring reproducible results. | ||
| metadata | string | ~ 256 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| rewards | List<EzReward> | [] | 0 ~ 1000 items | Completion Rewards List of rewards to be granted upon successful quest completion. Determined at quest start based on the content variation selected by the random seed. | ||
| failedRewards | List<EzReward> | [] | 0 ~ 1000 items | Failed Rewards List of rewards to be granted when the quest fails. Determined at quest start, providing consolation rewards or partial cost refunds upon failure. |
EzCompletedQuestList
Completed Quest List
Tracks the quests a user has completed within a quest group. Used to determine prerequisite quest completion and first-clear bonus eligibility. Each quest name is recorded only once regardless of how many times it is cleared.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| questGroupName | string | ✓ | ~ 128 chars | Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. | ||
| completeQuestNames | List<string> | [] | 0 ~ 1000 items | Completed Quest Names List of quest names that the user has completed within this quest group. Quest names are added upon first completion and are deduplicated. Used to evaluate prerequisite quest conditions and first-clear bonus eligibility. |
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.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| quests | List<EzQuestModel> | [] | 0 ~ 1000 items | Quests belonging to the group List of quest models that belong to this quest group. Only one quest within the group can be in progress at a time. | ||
| challengePeriodEventId | string | ~ 1024 chars | Challenge Period Event GRN GS2-Schedule event GRN that sets the time period during which quests in this group can be attempted. When specified, quests in this group can only be started while the event is active. |
EzQuestModel
Quest Model
A Quest Model is an entity that defines the cost required to start a quest and the rewards obtained upon completion.
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.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| questModelId | string | * | ~ 1024 chars | Quest Model GRN * Set automatically by the server | ||
| name | string | ✓ | ~ 128 chars | Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| contents | List<EzContents> | [] | 1 ~ 10 items | Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. | ||
| challengePeriodEventId | string | ~ 1024 chars | Challenge Period Event GRN GS2-Schedule event GRN that sets the time period during which this quest can be attempted. When specified, the quest can only be started while the event is active. This setting takes precedence over the quest group’s challenge period. | |||
| firstCompleteAcquireActions | List<EzAcquireAction> | [] | 0 ~ 10 items | First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. | ||
| verifyActions | List<EzVerifyAction> | [] | 0 ~ 10 items | Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. | ||
| consumeActions | List<EzConsumeAction> | [] | 0 ~ 10 items | Consume Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. | ||
| failedAcquireActions | List<EzAcquireAction> | [] | 0 ~ 100 items | Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. | ||
| premiseQuestNames | List<string> | [] | 0 ~ 10 items | Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. |
EzContents
Contents
Represents one variation of quest content. Each quest can have multiple content variations with different rewards, and one is selected by weighted random draw at quest start. The metadata supports template variable substitution with user ID and config values.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| metadata | string | ~ 256 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| completeAcquireActions | List<EzAcquireAction> | [] | 0 ~ 10 items | Complete Acquire Actions Acquire actions executed as rewards when the quest is completed with this content variation. These define the actual rewards the player receives upon clearing the quest. |
EzConsumeAction
Consume Action
EzVerifyAction
Verify Action
EzAcquireAction
Acquire Action
EzReward
Reward
Represents a single reward item determined at quest start. Contains the acquire action to execute, the target resource, and the quantity to grant. Stored in the Progress entity and used to distribute rewards upon quest completion or failure.
EzConfig
Configuration
Set values to be applied to transaction variables
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64 chars | Name | ||
| value | string | ~ 51200 chars | Value |
EzVerifyActionResult
Verify Action execution result
EzConsumeActionResult
Consume Action execution result
EzAcquireActionResult
Acquire Action execution result
EzTransactionResult
Transaction execution results
Result of a transaction executed using the server-side automatic transaction execution feature
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of Consume Action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List of Acquire Action execution results |
Methods
deleteProgress
Cancel the player’s current quest
Deletes the player’s quest in progress, allowing them to start a different quest.
Use this when the player wants to abandon a quest — for example, showing a “Give up this quest?” confirmation dialog, and calling this API when they confirm.
This is an alternative to using the force option when starting a new quest. Use this when you want to give the player an explicit “abandon quest” button rather than silently discarding the previous quest.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzProgress | Quest 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.DeleteProgressFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
const auto Future = Domain->DeleteProgress(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();end
Report quest completion or failure
Tells the server that the player has finished playing the quest. You need to report two things:
isComplete: Whether the player cleared the quest (true) or failed (false).rewards: The actual rewards the player earned during the quest. These must not exceed the maximum values received when the quest started.
If the player cleared the quest (isComplete = true), the reported rewards are granted to the player (e.g., items added to inventory, currency added to wallet). If the player failed (isComplete = false), the rewards parameter is ignored and the failure rewards configured in the quest definition are granted instead.
The server validates the reported rewards — if you report more than the allowed maximum or items that don’t exist in this quest, an error occurs. Use this when the quest gameplay ends — for example, after the player beats the boss or the “Game Over” screen appears.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| rewards | List<EzReward> | [] | 0 ~ 1000 items | The actual rewards from the quest | ||
| isComplete | bool | ✓ | Whether the quest has been completed | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzProgress | Quest Progress |
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the reward granting process |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
Implementation Example
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var result = await domain.EndAsync(
isComplete: true,
rewards: null,
config: null
);
// 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.EndFuture(
isComplete: true,
rewards: null,
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// 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(
GameSession
)->Progress(
);
const auto Future = Domain->End(
true // isComplete
// rewards
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}getProgress
Get the player’s current quest progress
Retrieves the quest that the player is currently playing, along with the quest group and quest definition details. This is useful for resuming a quest after the app is restarted — for example, if the player was in the middle of “Stage 1-3” and closed the app, you can call this on launch to detect the unfinished quest and show a “Resume Quest?” dialog. If the player has no quest in progress, no progress data is returned.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzProgress | Quest Progress |
| questGroup | EzQuestGroupModel | Quest Group Model |
| quest | EzQuestModel | Quest 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.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Quest::Model::FProgress> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
start
Start a quest
Tells the server that the player is starting a quest. The player can only have one quest in progress per quest group — if another quest is already running, this will fail (use force = true to discard the previous quest and start a new one).
When the quest starts successfully, the response includes:
- The maximum rewards available in this quest (e.g., “up to 3 Swords, up to 100 Gold”). Use this to determine what the player can earn during gameplay.
- A random number seed for reproducible gameplay. By using this seed, the game can be replayed under the same conditions — helpful for debugging or resuming after a crash.
- A transaction ID that uniquely identifies this quest run. You’ll need this when reporting the quest result.
Use this when the player taps “Start” on a quest — for example, starting “Stage 1-3” in the “Chapter 1” group. The quest costs (like stamina) are automatically consumed.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| questGroupName | string | ✓ | ~ 128 chars | Quest Group Model name | ||
| questName | string | ✓ | ~ 128 chars | Quest Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| force | bool | false | If have a quest already started, you can discard it and start it | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the quest initiation process |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
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.
| Type | Base Type | Description |
|---|---|---|
| InProgressException | BadRequestException | Quest 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.InProgressException e) {
// Quest is already underway.
}
// 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.StartFuture(
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;
}
// 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(
GameSession
);
const auto Future = Domain->Start(
"group-0001", // questGroupName
"quest-0001" // questName
// force
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Quest::Error::FInProgressError::Class))
{
// Quest is already underway.
}
return false;
}describeCompletedQuestLists
Get a list of the player’s completed quest records
Retrieves the player’s cleared quest records for all quest groups. Each entry corresponds to one quest group and contains a list of quest names that the player has successfully completed within that group. Use this to build a quest progress overview — for example, showing “Chapter 1: 5/10 cleared”, “Chapter 2: 0/8 cleared”, “Event Dungeon: 3/3 cleared” on a quest selection screen. This information is also useful for determining which quests are unlocked, since some quests require clearing specific previous quests as a prerequisite.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzCompletedQuestList> | List of Completed Quest lists |
| nextPageToken | string | Page 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(
GameSession
);
const auto It = Domain->CompletedQuestLists(
);
TArray<Gs2::UE5::Quest::Model::FEzCompletedQuestListPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}getCompletedQuestList
Get the player’s completed quest record for a specific group
Retrieves the list of quest names that the player has cleared within the specified quest group. Use this to check which quests in a specific group the player has already completed — for example, showing cleared/uncleared status for each stage in “Chapter 1”, or checking if the player has cleared the prerequisite quest to unlock the next stage.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| questGroupName | string | ✓ | ~ 128 chars | Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzCompletedQuestList | Completed Quest List |
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.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->CompletedQuestList(
"main" // questGroupName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).CompletedQuestList(
questGroupName: "main"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).CompletedQuestList(
questGroupName: "main"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->CompletedQuestList(
"main" // questGroupName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Quest::Model::FCompletedQuestList> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getQuestGroup
Get a specific quest group definition by name
Retrieves a single quest group by specifying its name. The returned information includes the list of quests in the group and optional challenge period settings (e.g., event dungeons that are only available during certain time periods). Use this to display the details of a specific quest category — for example, showing all stages in “Chapter 1” or all available quests in the “Event Dungeon” category.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| questGroupName | string | ✓ | ~ 128 chars | Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzQuestGroupModel | Quest 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.ModelFuture();
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;
}Value change event handling
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->QuestGroupModel(
"quest-group-0001" // questGroupName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Quest::Model::FQuestGroupModel> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listQuestGroups
Get a list of quest group definitions
Retrieves all quest groups registered in this namespace. A quest group is a category that organizes related quests together — for example, “Chapter 1”, “Event Dungeon”, or “Daily Quests”. Players can only have one quest in progress per group, so groups also serve as a way to manage concurrent quest limits. Use this to build a quest selection screen — for example, showing categories like “Main Story”, “Side Quests”, “Event Dungeons” for the player to choose from.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<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(
);
TArray<Gs2::UE5::Quest::Model::FEzQuestGroupModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeQuestGroupModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeQuestGroupModels(callbackId); var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeQuestGroupModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeQuestGroupModels(callbackId); const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeQuestGroupModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeQuestGroupModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getQuest
Get a specific quest definition by name
Retrieves a single quest by specifying the group name and quest name. The returned information includes the quest’s reward settings, consume actions (costs to start), and prerequisite quest conditions. Use this to display the details of a specific quest before the player starts it — for example, showing “Stage 1-3: Rewards: Sword x1, Gold x100 | Cost: Stamina x10 | Requires: Clear Stage 1-2” on a quest detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| questGroupName | string | ✓ | ~ 128 chars | Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| questName | string | ✓ | ~ 128 chars | Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzQuestModel |
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.ModelFuture();
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;
}Value change event handling
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
).QuestModel(
questName: "quest-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
).QuestModel(
questName: "quest-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->QuestGroupModel(
"quest-group-0001" // questGroupName
)->QuestModel(
"quest-0001" // questName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Quest::Model::FQuestModel> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listQuests
Get a list of quest definitions in a group
Retrieves all quests that belong to the specified quest group. Each quest defines its rewards (what the player can earn), costs (items or currency consumed to start), and prerequisites (quests that must be cleared first). Use this to display the quest list within a category — for example, showing “Stage 1-1”, “Stage 1-2”, “Stage 1-3 (locked — clear 1-2 first)” inside the “Chapter 1” group.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| questGroupName | string | ✓ | ~ 128 chars | Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<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(
);
TArray<Gs2::UE5::Quest::Model::FEzQuestModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
// Start event handling
var callbackId = domain.SubscribeQuestModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeQuestModels(callbackId); var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
// Start event handling
var callbackId = domain.SubscribeQuestModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeQuestModels(callbackId); const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->QuestGroupModel(
"quest-group-0001" // questGroupName
);
// Start event handling
const auto CallbackId = Domain->SubscribeQuestModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeQuestModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.