> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Realtime SDK for Game Engine API Reference

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



## 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<br>Unique Room name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| ipAddress | string |  |  |  |  ~ 128 chars | IP Address<br>The IP address of the provisioned game server.<br>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<br>The listening port number of the provisioned game server.<br>Assigned automatically along with the IP address after the server instance is ready. Range: 0-65535. |
| encryptionKey | string |  |  |  |  ~ 256 chars | Encryption Key<br>The encryption key for securing communication between game clients and the relay server.<br>Assigned automatically along with the IP address and port after the server instance is ready.<br>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

Request parameters: None

#### Result

|  | Type | Description |
| --- | --- | --- |
| timestamp | long | Current time<br>Unix time, milliseconds|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Realtime;
    var result = await domain.NowAsync(
    );
    var timestamp = result.Timestamp;

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| roomName | string |  | ✓|  |  ~ 128 chars | Room name<br>Unique Room name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |

#### Result

|  | Type | Description |
| --- | --- | --- |
| item | [EzRoom](#ezroom) | Room Information|

#### Implementation Example




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

```

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

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

## Event Handlers

### OnCreateNotification

Push notification used when room creation is complete

 | Name | Type | Description |
| --- | --- | --- |
| namespaceName | string |Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).|
| roomName | string |Room name<br>Unique Room name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).|

#### Implementation Example





**Unity (UniTask)**
```csharp

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

**Unity (Vanilla)**
```cs

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

**Unreal Engine 5**
```cpp

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


---