GS2-JobQueue SDK for Game Engine API Reference

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 to the dictionary.

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 dictionary service is stopped due to some failure, the game can continue without being registered in the dictionary. 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

Job Execution Results

Records the outcome of a single job execution attempt. Each attempt creates a separate JobResult, so a job that is retried multiple times will have multiple results. The statusCode indicates whether the job succeeded or failed.

EzJobEntry

Register Job

Represents the parameters for registering a new job to the job queue. Contains the script to execute, the JSON arguments, and the maximum retry count. Used as input when pushing jobs onto the queue.

EzJobResultBody

Job Execution Results

A lightweight representation of a job execution result, containing the attempt number, status code, response content, and execution timestamp.

Methods

run

Run the next job in the player’s job queue

GS2 uses job queues to handle deferred processing — for example, when a player obtains a character, the character is immediately added to their inventory, but registering it in the encyclopedia can be processed later via a job queue. This design makes the game more resilient: even if a related service is temporarily down, the game can continue, and the queued jobs will be retried and completed once the service recovers.

When you call this API, it executes the next pending job in the player’s queue and returns the result. The response includes an isLastJob flag — if it is false, there are more jobs waiting, so keep calling this API in a loop until isLastJob becomes true.

You can also set up push notifications on the namespace so your game client is notified whenever a new job is added — this way, you don’t need to poll and can simply call this API when notified.

If the namespace has enableAutoRun turned on, jobs are executed automatically on the server side, so calling this API is not required.

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

// 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

// Runs at the SDK level, so there is no need to explicitly call the API

getResult

Get the result of a completed job

Retrieves the execution result of a specific job by its name. The result includes a status code indicating success or failure and the response body returned by the job.

This is useful when you want to check whether a deferred process (such as registering to an encyclopedia or distributing rewards) completed successfully. If a job was retried multiple times, you can specify a try number to see the result of a particular attempt.

Note: Job results are kept for a limited time after execution and may be automatically cleaned up.

Request

Result

Implementation Example

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

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

Value change event handling

    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: null
    );
    
    // 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.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: null
    );
    
    // 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->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Job(
        "job-0001" // jobName
    )->JobResult(
        nullptr // tryNumber
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::JobQueue::Model::FJobResult> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Event Handler

OnPushNotification

Push notification used when a job is registered in the job queue

Implementation Example

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

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

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

OnRunNotification

Push notification used when a job in the job queue is executed

Implementation Example

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

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

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