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

# GS2-Realtime SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-Realtime SDK의 모델 사양과 API 레퍼런스



## 모델

### EzRoom

룸<br>

멀티플레이어 대전에서 실시간 통신을 처리하기 위한 전용 게임 서버 인스턴스를 나타냅니다.<br>
룸 생성은 비동기로 이루어지며, 요청 후 시스템이 서버를 프로비저닝하고 인스턴스 준비가 완료되면 IP 주소, 포트, 암호화 키가 할당됩니다.<br>
클라이언트는 접속을 시도하기 전에 생성 완료 알림을 기다리거나 폴링해야 합니다.<br>
암호화 키는 게임 클라이언트와 릴레이 서버 간의 안전한 통신 채널을 확립하는 데 사용됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128자 | 룸 이름<br>룸 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| ipAddress | string |  |  |  |  ~ 128자 | IP 주소<br>프로비저닝된 게임 서버의 IP 주소.<br>룸의 서버 인스턴스 준비가 완료된 후 시스템에 의해 자동으로 할당됩니다. 룸 생성 직후에는 이용할 수 없습니다. 최대 128자. |
| port | int |  |  |  | 0 ~ 65535 | 대기 포트<br>프로비저닝된 게임 서버의 대기 포트 번호.<br>서버 인스턴스 준비가 완료된 후 IP 주소와 함께 자동으로 할당됩니다. 범위: 0~65535. |
| encryptionKey | string |  |  |  |  ~ 256자 | 암호화 키<br>게임 클라이언트와 릴레이 서버 간의 통신을 암호화하기 위한 키.<br>서버 인스턴스 준비가 완료된 후 IP 주소 및 포트와 함께 자동으로 할당됩니다.<br>클라이언트는 릴레이 서버를 통해 송수신하는 메시지의 암호화·복호화에 이 키를 사용해야 합니다. 최대 256자. |

**관련 메서드:**
getRoom - 실시간 게임 룸의 접속 정보 취득


---

## 메서드

### now

현재 서버 시각 취득<br>

GS2 서버의 현재 시각을 Unix 타임스탬프(밀리초)로 반환합니다.<br>
게임 클라이언트의 시계를 서버와 동기화하는 데 사용합니다. 예를 들어 카운트다운 타이머, 이벤트 시작·종료 시각, 쿨다운 기간을 정확히 표시할 때 유용합니다.<br>

클라이언트 단말의 시계는 부정확하거나 조작될 수 있으므로, 서버 시각을 사용하면 모든 플레이어에게 일관된 타이밍을 표시할 수 있습니다.<br>

주요 사용 방법:<br>
- 게임 시작 시 클라이언트와 서버의 시각 차이를 계산하여 세션 동안 계속 그 차이를 적용<br>
- 기간 한정 이벤트나 랭킹 기간의 정확한 "남은 시간" 표시<br>
- 타이밍에 민감한 액션을 서버로 전송하기 전에 클라이언트 측에서 검증

#### Request

요청 파라미터: 없음

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| timestamp | long | 현재 시각<br>Unix 시간·밀리초|

#### 구현 예제




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

실시간 게임 룸의 접속 정보 취득<br>

실시간 게임 서버 룸에 접속하는 데 필요한 정보를 취득합니다. IP 주소, 포트 번호, 암호화 키가 포함됩니다.<br>

실시간 룸은 저지연 통신이 필요한 멀티플레이어 게임플레이에 사용됩니다. 예를 들어 액션 게임, 격투 게임, 협력 던전 등입니다.<br>

실시간 룸을 사용하는 일반적인 흐름:<br>
1. 플레이어가 룸 생성을 요청합니다(별도의 API로 이루어지며 비동기로 처리됩니다)<br>
2. 룸 준비가 완료되면 참가 플레이어에게 푸시 알림이 전송됩니다<br>
3. 각 플레이어가 GetRoom을 호출하여 접속 정보(IP 주소, 포트, 암호화 키)를 취득합니다<br>
4. 게임 클라이언트가 이 정보를 사용하여 룸 서버에 접속하고 실시간 통신을 시작합니다<br>

암호화 키는 클라이언트와 게임 서버 간의 통신을 보호하는 데 사용됩니다. 각 룸에는 고유한 키가 할당됩니다.

#### Request

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128자 | 네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| roomName | string |  | ✓|  |  ~ 128자 | 룸 이름<br>룸 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |

#### Result

|  | 타입 | 설명 |
| --- | --- | --- |
| item | [EzRoom](#ezroom) | 룸 정보|

#### 구현 예제




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

```

**Godot**
```gdscript

var domain = ez.realtime.namespace_(
        "namespace-0001"
    ).room(
        "room-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

```


##### 값 변경 이벤트 핸들링




**Unity (UniTask)**
```csharp
    var domain = gs2.Realtime.Namespace(
        namespaceName: "namespace-0001"
    ).Room(
        roomName: "room-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Realtime.Namespace(
        namespaceName: "namespace-0001"
    ).Room(
        roomName: "room-0001"
    );
    
    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Realtime->Namespace(
        "namespace-0001" // namespaceName
    )->Room(
        "room-0001" // roomName
    );
    
    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Realtime::Model::FRoom> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

```

**Godot**
```gdscript

var domain = ez.realtime.namespace_(
        "namespace-0001"
    ).room(
        "room-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

```


**⚠️ Warning**

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

---

## 이벤트 핸들러

### OnCreateNotification

룸 생성이 완료되었을 때 전송되는 푸시 알림

 | 이름 | 타입 | 설명 |
| --- | --- | --- |
| namespaceName | string |네임스페이스 이름<br>네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.|
| roomName | string |룸 이름<br>룸 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.|

#### 구현 예제





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

**Godot**
```gdscript

    ez.realtime.create_notification.connect(func(notification):
        var namespace_name = notification.namespace_name
        var room_name = notification.room_name
    )
```


---