API Reference of GS2-Idle SDK for Game Engine

Model

EzCategoryModel

Category Model Master

A category model is an entity that sets the idle category that can be obtained as a reward for leaving. The settings include information such as the reward for each waiting time and the maximum idle time.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Category Model Name
metadata	string		~ 2048 chars	metadata
rewardIntervalMinutes	int	✓	~ 2147483646	Interval at which idle rewards can be obtained (minutes)
defaultMaximumIdleMinutes	int	✓	~ 2147483646	Maximum time to get idle rewards (minutes)
acquireActions	List<EzAcquireActionList>	✓	1 ~ 100 items	List of acquire actions for each waiting time
idlePeriodScheduleId	string		~ 1024 chars	GS2-Schedule event GRN with time period used for idle rewards calculation
receivePeriodScheduleId	string		~ 1024 chars	GS2-Schedule EventGRN that sets the period during which idle rewards can be obtained

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	Require	Default	Limitation	Description
categoryName	string	✓		~ 128 chars	Category Model Name
randomSeed	long	✓	0	~ 9223372036854775805	Random seed
idleMinutes	int	✓		~ 2147483646	Idle time
maximumIdleMinutes	int	✓	0	~ 2147483646	Maximum idle time

EzConfig

Configration

Set values to be applied to transaction variables

	Type	Require	Default	Limitation	Description
key	string	✓		~ 64 chars	Name
value	string			~ 51200 chars	Value

EzAcquireAction

Acquire Action

	Type	Require	Default	Limitation	Description
action	enum { "Gs2AdReward:AcquirePointByUserId", "Gs2Dictionary:AddEntriesByUserId", "Gs2Enchant:ReDrawBalanceParameterStatusByUserId", "Gs2Enchant:SetBalanceParameterStatusByUserId", "Gs2Enchant:ReDrawRarityParameterStatusByUserId", "Gs2Enchant:AddRarityParameterStatusByUserId", "Gs2Enchant:SetRarityParameterStatusByUserId", "Gs2Enhance:DirectEnhanceByUserId", "Gs2Enhance:UnleashByUserId", "Gs2Enhance:CreateProgressByUserId", "Gs2Exchange:ExchangeByUserId", "Gs2Exchange:IncrementalExchangeByUserId", "Gs2Exchange:CreateAwaitByUserId", "Gs2Exchange:AcquireForceByUserId", "Gs2Exchange:SkipByUserId", "Gs2Experience:AddExperienceByUserId", "Gs2Experience:SetExperienceByUserId", "Gs2Experience:AddRankCapByUserId", "Gs2Experience:SetRankCapByUserId", "Gs2Experience:MultiplyAcquireActionsByUserId", "Gs2Formation:AddMoldCapacityByUserId", "Gs2Formation:SetMoldCapacityByUserId", "Gs2Formation:AcquireActionsToFormProperties", "Gs2Formation:SetFormByUserId", "Gs2Formation:AcquireActionsToPropertyFormProperties", "Gs2Friend:UpdateProfileByUserId", "Gs2Grade:AddGradeByUserId", "Gs2Grade:ApplyRankCapByUserId", "Gs2Grade:MultiplyAcquireActionsByUserId", "Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName", "Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName", "Gs2Idle:IncreaseMaximumIdleMinutesByUserId", "Gs2Idle:SetMaximumIdleMinutesByUserId", "Gs2Idle:ReceiveByUserId", "Gs2Inbox:SendMessageByUserId", "Gs2Inventory:AddCapacityByUserId", "Gs2Inventory:SetCapacityByUserId", "Gs2Inventory:AcquireItemSetByUserId", "Gs2Inventory:AcquireItemSetWithGradeByUserId", "Gs2Inventory:AddReferenceOfByUserId", "Gs2Inventory:DeleteReferenceOfByUserId", "Gs2Inventory:AcquireSimpleItemsByUserId", "Gs2Inventory:SetSimpleItemsByUserId", "Gs2Inventory:AcquireBigItemByUserId", "Gs2Inventory:SetBigItemByUserId", "Gs2JobQueue:PushByUserId", "Gs2Limit:CountDownByUserId", "Gs2Limit:DeleteCounterByUserId", "Gs2LoginReward:DeleteReceiveStatusByUserId", "Gs2LoginReward:UnmarkReceivedByUserId", "Gs2Lottery:DrawByUserId", "Gs2Lottery:ResetBoxByUserId", "Gs2Mission:RevertReceiveByUserId", "Gs2Mission:IncreaseCounterByUserId", "Gs2Mission:SetCounterByUserId", "Gs2Money:DepositByUserId", "Gs2Money:RevertRecordReceipt", "Gs2Money2:DepositByUserId", "Gs2Quest:CreateProgressByUserId", "Gs2Schedule:TriggerByUserId", "Gs2Script:InvokeScript", "Gs2SerialKey:RevertUseByUserId", "Gs2SerialKey:IssueOnce", "Gs2Showcase:DecrementPurchaseCountByUserId", "Gs2Showcase:ForceReDrawByUserId", "Gs2SkillTree:MarkReleaseByUserId", "Gs2Stamina:RecoverStaminaByUserId", "Gs2Stamina:RaiseMaxValueByUserId", "Gs2Stamina:SetMaxValueByUserId", "Gs2Stamina:SetRecoverIntervalByUserId", "Gs2Stamina:SetRecoverValueByUserId", "Gs2StateMachine:StartStateMachineByUserId", }	✓		~ 128 chars	Types of actions to be performed in the acquire action
request	string	✓		~ 1048576 chars	JSON of request

EzAcquireActionList

Acquisition Action List

	Type	Require	Default	Limitation	Description
acquireActions	List<EzAcquireAction>			~ 100 items	List of Acquire Action

EzVerifyActionResult

Verify action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the verify task
verifyRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
verifyResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzConsumeActionResult

Consume action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the consume action
consumeRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
consumeResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzAcquireActionResult

Acquire action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the acquire action
acquireRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
acquireResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzTransactionResult

Transaction execution results

Transaction execution results executed using server-side transaction auto-execution functionality

	Type	Require	Limitation	Description
transactionId	string	✓	36 ~ 36 chars	Transaction ID
verifyResults	List<EzVerifyActionResult>		~ 10 items	List of verify action execution results
consumeResults	List<EzConsumeActionResult>		~ 10 items	List of consume action execution results
acquireResults	List<EzAcquireActionResult>		~ 100 items	List of acquire action execution results

Methods

getCategoryModel

Obtain category model information

Get rank cap information and rank-up threshold information by specifying idle type name.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
categoryName	string	✓		~ 128 chars	Category Model Name

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"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    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 called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listCategoryModels

Get list of category model information

Obtain information on rank caps and rank advancement thresholds. Use this model data if you want to display in-game information such as the amount of idle required to gain before the next rank-up.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name

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"
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

getStatus

Get status information by idle type and property ID

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
categoryName	string	✓	~ 128 chars	Category Model Name
accessToken	string	✓	~ 128 chars	User Id

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"
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listStatuses

Get list of status information

The idle type name is optional; if not specified, all status information belonging to the game player is retrieved.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

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
    );
    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
    );
    
    // 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 called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

prediction

Get list of rewards

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
categoryName	string	✓	~ 128 chars	Category Model Name
accessToken	string	✓	~ 128 chars	User Id

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

Receive rewards

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
categoryName	string	✓	~ 128 chars	Category Model Name
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
items	List<EzAcquireAction>	Rewards
status	EzStatus	Updated Status
transactionId	string	Issed 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	Is transaction auto-execution enabled?
atomicCommit	bool	Transaction to commit 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;
    }