API Reference of GS2-JobQueue SDK for Game Engine

Model

EzJob

Job

A job queue is a mechanism for delaying the execution of a process rather than completing it immediately. For example, when a character is acquired, the process that must be executed immediately is to store the character in the possession. On the other hand, a process that does not have to be executed immediately is the process of `registering the character in the picture book.

By processing these processes that do not need to be processed immediately via a job queue, the design can be made more resilient to failures. This is because even if the illustrated book service is stopped due to some failure, the game can continue without being registered in the illustrated book. Even if the process packed in the job queue fails, it can be retried after the failure is resolved, resulting in a correct state.

GS2 recommends this kind of result matching process, and in various situations, job queues are used for delayed processing.

EzJobResult

EzJobEntry

EzJobResultBody

Methods

run

Executes jobs in the task queue.

You can receive a push notification when a new job is added to the task queue by configuring the task queue push notification settings. Call this API periodically or trigger a push notification to call this API. Repeat as long as isLastJob returns false.

Request

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.

Implementation Example

• Game Engine:
• Unity (UniTask)
• Unity (Vanilla)
• Unreal Engine 5

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API

// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API

// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// Runs at the SDK level, so there is no need to explicitly call the API

getResult

Get Job execution result

Request

Result

Implementation Example

• Game Engine:
• Unity (UniTask)
• Unity (Vanilla)
• Unreal Engine 5

    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: null
    );
    var item = await domain.ModelAsync();

    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: null
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Job(
        "job-0001" // jobName
    )->JobResult(
        nullptr // tryNumber
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Event Handler

OnPushNotification

Notification used when a job is registered in the job queue

Implementation Example

• Game Engine:
• Unity (UniTask)
• Unity (Vanilla)
• Unreal Engine 5

    gs2.JobQueue.OnPushNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
    };

    gs2.JobQueue.OnPushNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
    };

    Gs2->JobQueue->OnPushNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
    });

OnRunNotification

Notification used when a job in the job queue is executed

Implementation Example

• Game Engine:
• Unity (UniTask)
• Unity (Vanilla)
• Unreal Engine 5

    gs2.JobQueue.OnRunNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var jobName = notification.JobName;
    };

    gs2.JobQueue.OnRunNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var jobName = notification.JobName;
    };

    Gs2->JobQueue->OnRunNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto JobName = Notification->JobNameValue;
    });