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

```


##### 値の変更イベントハンドリング




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

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

## イベントハンドラ

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


---