GS2-Idle SDK for Game Engine API Reference
Model
EzStatus
Status
Created when GetIdleStatus is called for the first time, and the idle time count starts from that time. The idle time count is reset when you receive a reward.
If GS2-Schedule events are associated, you cannot access Category before the event is held, and you cannot create a status. If an event is associated, the status holds the number of repetitions of the event. If the current event ID and the event ID at the time of status creation do not match, if the number of repetitions of the current event and the number of repetitions held by the status do not match, or if the status is created before the start time of the event, the waiting time is reset.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| categoryName | string | ✓ | ~ 128 chars | Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. | ||
| randomSeed | long | 0 | 0 ~ 9223372036854775805 | Random Seed A seed value used for deterministic random number generation when calculating idle rewards. Ensures that reward calculations are reproducible and consistent, allowing the server to verify reward results. Updated each time rewards are received. | ||
| idleMinutes | int | ✓ | 0 ~ 2147483646 | Idle Minutes The accumulated idle time in minutes since the last reward claim or status creation. This value is calculated from the elapsed time since idleStartedAt and is capped at maximumIdleMinutes. The number of available rewards is determined by dividing this value by the category model’s rewardIntervalMinutes. | ||
| maximumIdleMinutes | int | 0 | 0 ~ 2147483646 | Maximum Idle Minutes The maximum idle time in minutes that this status can accumulate. Initialized from the category model’s defaultMaximumIdleMinutes when the status is created. Can be increased per-user via acquire actions, allowing premium users or event participants to accumulate more idle rewards. |
EzCategoryModel
Category Model
A Category Model is an entity that defines a waiting category in which idle rewards can be earned over time. The settings include information such as the reward for each waiting time and the maximum idle time.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 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. | |||
| rewardIntervalMinutes | int | ✓ | 0 ~ 2147483646 | Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. | ||
| defaultMaximumIdleMinutes | int | ✓ | 0 ~ 2147483646 | Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. | ||
| acquireActions | List<EzAcquireActionList> | [] | 1 ~ 100 items | List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. | ||
| idlePeriodScheduleId | string | ~ 1024 chars | Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. | |||
| receivePeriodScheduleId | string | ~ 1024 chars | Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. |
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 |
EzAcquireAction
Acquire Action
Represents a single acquire action used as an idle reward. Consists of an action type (e.g., add items, increase currency) and its request parameters. When idle rewards are claimed, these actions are assembled into transactions and executed to deliver the rewards to the user.
EzAcquireActionList
Acquire Action List
A wrapper that groups multiple acquire actions to be granted together for a single reward interval. Each AcquireActionList corresponds to one reward cycle in the category model’s acquireActions array, enabling different reward combinations at each interval.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| acquireActions | List<EzAcquireAction> | [] | 0 ~ 100 items | List of Acquire Actions The collection of acquire actions that are executed together when this reward interval is triggered. Multiple actions can be combined to grant different types of rewards simultaneously for a single idle reward cycle. Up to 100 actions per list. |
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
getCategoryModel
Get a specific idle reward category definition by name
Retrieves a single idle reward category model by specifying its name. The returned information includes the reward interval (how many minutes between each reward), the maximum idle time cap, what rewards are granted, and schedule settings. Use this to display the details of a specific idle reward type — for example, showing “Gold Mine — Earn 10 gold every 30 minutes — Max accumulation: 8 hours — Currently: 160 gold ready to claim”.
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 (.). | ||
| categoryName | string | ✓ | ~ 128 chars | Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzCategoryModel | Category Model |
Implementation Example
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.ModelFuture();
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;
}Value change event handling
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-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.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-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->Idle->Namespace(
"namespace-0001" // namespaceName
)->CategoryModel(
"category-0001" // categoryName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Idle::Model::FCategoryModel> 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.
listCategoryModels
Get a list of idle reward category definitions
Retrieves all idle reward categories registered in this namespace. A category model defines how AFK (idle) rewards work — how often rewards accumulate (e.g., every 10 minutes), the maximum idle time (e.g., up to 8 hours), what rewards the player gets, and whether the timer resets after claiming. You can also link categories to a schedule to control when idle rewards are active (e.g., only during weekday events). Use this to show the player what types of idle rewards are available — for example, “Gold Mine (10 gold every 30 min, max 8 hours)” and “XP Training (50 XP every hour, max 24 hours)”.
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<EzCategoryModel> | List of Category Model |
Implementation Example
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());
}Value change event handling
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeCategoryModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeCategoryModels(callbackId); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeCategoryModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeCategoryModels(callbackId); const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeCategoryModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeCategoryModels(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.
getStatus
Get the idle reward status for a specific category
Retrieves the player’s idle reward status for a specific category. The status includes when the idle timer started and the current maximum idle time. If no status exists yet, it is automatically created with the current time as the start. Use this to display a specific idle reward’s progress — for example, “Gold Mine — Idling for 4h 30m / 8h max — 90 gold ready to claim”.
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 (.). | ||
| categoryName | string | ✓ | ~ 128 chars | Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzStatus | Status |
Implementation Example
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.ModelFuture();
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;
}Value change event handling
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-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.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-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->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Idle::Model::FStatus> 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.
listStatuses
Get a list of the player’s idle reward statuses
Retrieves all idle reward statuses for the player across all categories. Each status shows when the player started idling (when they last claimed rewards or when the timer started) and the current maximum idle time. Use this to build an “Idle Rewards” overview screen — for example, showing “Gold Mine: 4h 30m accumulated, XP Training: 1h 15m accumulated” with a “Claim” button for each.
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<EzStatus> | List of Status |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
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());
}Value change event handling
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeStatuses(callbackId); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeStatuses(callbackId); const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeStatuses(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeStatuses(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.
prediction
Preview the idle rewards that can be claimed right now
Calculates and returns the rewards the player would receive if they claimed right now, without actually claiming them. The reward amount is based on how long the player has been idling divided by the reward interval, capped by the maximum idle time. This does not reset the timer or grant any rewards — it’s a read-only preview. Use this to show what the player will get before they press the “Claim” button — for example, “You will receive: 90 Gold, 5 Gems”.
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 (.). | ||
| categoryName | string | ✓ | ~ 128 chars | Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| items | List<EzAcquireAction> | Rewards |
| status | EzStatus | Status |
Implementation Example
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.ModelFuture();
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
Claim the accumulated idle rewards
Claims the idle rewards that have accumulated based on the player’s idle time for the specified category. The reward amount is calculated from how long the player has been idling, divided by the reward interval, and capped by the maximum idle time. After claiming, the idle timer resets and starts accumulating again from zero. Use this for the “Claim Rewards” or “Collect” button on the idle rewards screen — for example, the player taps “Collect” and receives “90 Gold, 5 Gems” that accumulated while they were away.
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 (.). | ||
| categoryName | string | ✓ | ~ 128 chars | Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| items | List<EzAcquireAction> | Rewards |
| status | EzStatus | Status updated |
| 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 |
Implementation Example
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var result = await domain.ReceiveAsync(
);
// 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;
}
// 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;
}