GS2-Realtime SDK for Game Engine API Reference

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

Models

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 Condition Required Default 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.
Related methods:
getRoom - Get the connection details for a real-time game room

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:

  1. A player requests room creation (this is done through a separate API and is processed asynchronously)
  2. When the room is ready, participating players receive a push notification
  3. Each player calls GetRoom to get the connection details (IP address, port, encryption key)
  4. 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);

Event Handlers

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;
    });