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

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

모델

EzRoom

룸

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

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

메서드

now

현재 서버 시각 취득

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

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

주요 사용 방법:

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

Request

요청 파라미터: 없음

Result

	타입	설명
timestamp	long	현재 시각 Unix 시간·밀리초

구현 예제

    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

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

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

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

실시간 룸을 사용하는 일반적인 흐름:

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

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

Request

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

Result

	타입	설명
item	EzRoom	룸 정보

구현 예제

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

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

값 변경 이벤트 핸들링

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

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

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

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

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

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

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

구현 예제

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

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