GS2-Realtime SDK for Game Engine API Reference

Specifications of models and API references for GS2-Realtime SDK for Game Engine

Model

EzRoom

Room

Represents a dedicated game server instance for handling real-time communication in multiplayer matches. Room creation is asynchronous: after the request, the system provisions a server and assigns an IP address, port, and encryption key once the instance is ready. Clients should wait for the create notification (or poll) before attempting to connect. The encryption key is used to establish a secure communication channel between the game clients and the relay server.

	Type	Required	Value Limits	Description
name	string	✓	~ 128 chars	Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
ipAddress	string		~ 128 chars	IP Address The IP address of the provisioned game server. Assigned automatically by the system after the room’s server instance is ready. Not available immediately after room creation. Maximum 128 characters.
port	int		0 ~ 65535	Port The listening port number of the provisioned game server. Assigned automatically along with the IP address after the server instance is ready. Range: 0-65535.
encryptionKey	string		~ 256 chars	Encryption Key The encryption key for securing communication between game clients and the relay server. Assigned automatically along with the IP address and port after the server instance is ready. Clients must use this key to encrypt/decrypt messages sent through the relay server. Maximum 256 characters.

Methods

now

Get the current server time

Returns the current time on the GS2 server as a Unix timestamp in milliseconds. Use this to synchronize the game client’s clock with the server — for example, to accurately display countdown timers, event start/end times, or cooldown periods.

Since the client device’s clock can be wrong or manipulated, using the server time ensures all players see consistent timing.

Common use cases:

Calculate the time offset between client and server at game startup, then apply it throughout the session
Display accurate “time remaining” for limited-time events or ranking periods
Validate timing-sensitive actions on the client side before sending them to the server

Request

	Type	Condition	Required	Default	Value Limits	Description

Result

	Type	Description
timestamp	long	Current time Unix time, milliseconds

Implementation Example

    var domain = gs2.Realtime;
    var result = await domain.NowAsync(
    );
    var timestamp = result.Timestamp;

    var domain = gs2.Realtime;
    var future = domain.NowFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var timestamp = future.Result.Timestamp;

    const auto Domain = Gs2->Realtime;
    const auto Future = Domain->Now(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();
    const auto Timestamp = Result->Timestamp;

getRoom

Get the connection details for a real-time game room

Retrieves the information needed to connect to a real-time game server room, including the IP address, port number, and encryption key.

Real-time rooms are used for multiplayer gameplay that requires low-latency communication — for example, action games, fighting games, or co-op dungeon runs.

The typical flow for using real-time rooms:

A player requests room creation (this is done through a separate API and is processed asynchronously)
When the room is ready, participating players receive a push notification
Each player calls GetRoom to get the connection details (IP address, port, encryption key)
The game client connects to the room server using these details and starts real-time communication

The encryption key is used to secure communication between the client and the game server. Each room has a unique key.

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 (.).
roomName	string		✓		~ 128 chars	Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Result

	Type	Description
item	EzRoom	Room Information

Implementation Example

    var domain = gs2.Realtime.Namespace(
        namespaceName: "namespace-0001"
    ).Room(
        roomName: "room-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Realtime.Namespace(
        namespaceName: "namespace-0001"
    ).Room(
        roomName: "room-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Realtime->Namespace(
        "namespace-0001" // namespaceName
    )->Room(
        "room-0001" // roomName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Realtime.Namespace(
        namespaceName: "namespace-0001"
    ).Room(
        roomName: "room-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.Realtime.Namespace(
        namespaceName: "namespace-0001"
    ).Room(
        roomName: "room-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->Realtime->Namespace(
        "namespace-0001" // namespaceName
    )->Room(
        "room-0001" // roomName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Realtime::Model::FRoom> 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.

Event Handler

OnCreateNotification

Push notification used when room creation is complete

Name	Type	Description
namespaceName	string	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
roomName	string	Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

Implementation Example

    gs2.Realtime.OnCreateNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var roomName = notification.RoomName;
    };

    gs2.Realtime.OnCreateNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var roomName = notification.RoomName;
    };

    Gs2->Realtime->OnCreateNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto RoomName = Notification->RoomNameValue;
    });