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

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

EzAcquireAction

	Type	Require	Default	Limitation	Description
action	enum []	✓		~ 128 chars	Types of actions to be performed in the stamp sheet
request	string	✓		~ 1048576 chars	JSON of request

EzAcquireActionList

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

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	✓		~ 32 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.Model();
    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.Model();
    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	✓		~ 32 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(
    );
    for (auto Item : *It)
    {

    }

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	✓	~ 32 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.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->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.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->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	✓		~ 32 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(
        AccessToken
    );
    const auto It = Domain->Statuses(
    );
    for (auto Item : *It)
    {

    }

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(
        AccessToken
    );
    
    // 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	✓	~ 32 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.Model();
    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(
        AccessToken
    )->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 (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

receive

Receive rewards

Request

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

Result

	Type	Description
items	List<EzAcquireAction>	Rewards
transactionId	string	Transaction ID of the stamp sheet issued
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 stamp sheet auto-execution enabled?

Implementation Example

    var domain = gs2.Idle.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        categoryName: "category-0001"
    );
    var result = await domain.ReceiveAsync(
    );
    // 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.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;
    }
    // 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->Idle->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Status(
        "category-0001" // categoryName
    );
    const auto Future = Domain->Receive(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }