UnityUnreal Engine 5 SDK 가이드 미리 보기 버전

설치

1. SDK 폴더 Assets/CasualTalk를 내 Unity 프로젝트의 Assets 폴더 아래에 그대로 복사합니다.
2. Unity 메뉴 Window → Package Manager에서 com.unity.nuget.newtonsoft-json 패키지가 설치되어 있는지 확인합니다. 없으면 설치합니다. 채팅에 추가 정보(메타데이터)를 실을 때 JSON으로 바꾸는 데 씁니다.
3. 발급받은 AppID를 준비합니다. 연습할 때는 개발용 AppID casualtalk-dev를 쓰면 됩니다.

1. 플러그인 폴더 Plugins/CasualTalk를 내 게임 프로젝트의 Plugins 폴더 아래에 그대로 복사합니다(폴더가 없으면 만듭니다). UE 5.8 기준이며, 엔진에 기본으로 들어 있는 모듈만 쓰므로 따로 설치할 것은 없습니다.
2. C++에서 쓰려면 게임 모듈의 .Build.cs 파일을 열고, 의존 모듈 목록에 "CasualTalk"를 추가합니다(아래 코드). 블루프린트에서만 쓴다면 이 단계는 건너뜁니다.
3. 발급받은 AppID를 준비합니다. 연습할 때는 개발용 AppID casualtalk-dev를 쓰면 됩니다.

// 내게임.Build.cs
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "CasualTalk" });

빠른 시작

아래 스크립트 하나로 연결 → 방 입장 → 채팅 보내기 → 새 채팅 받기까지 해 볼 수 있습니다. 빈 게임 오브젝트에 붙이고 플레이하면 콘솔에 대화가 찍힙니다.

• await는 서버 응답이 올 때까지 기다렸다가 다음 줄로 넘어갑니다. 기다리는 동안 게임은 멈추지 않습니다. await를 쓰는 함수에는 async를 붙입니다.
• 요청 함수의 결과는 IsSuccess로 확인합니다. false면 ErrorCode에 실패한 이유가 들어 있습니다.
• 새 채팅은 기다리지 않아도 Setup 때 등록한 함수(HandleNewChat)로 알아서 들어옵니다.

using UnityEngine;

public class ChatSample : MonoBehaviour
{
    // 1. 게임이 시작되면 채팅 서버에 연결합니다
    private async void Start()
    {
        CasualTalkSetupOption option = new CasualTalkSetupOption();
        option.AppID = "casualtalk-dev";      // 발급받은 게임 ID
        option.UserID = "player-1024";        // 게임에서 쓰는 플레이어 ID
        option.Mode = CasualTalkMode.Tcp;
        option.OnNewChat = HandleNewChat;    // 새 채팅이 오면 HandleNewChat 함수가 불립니다

        CasualTalkResponse setup = await CasualTalk.Setup(option);
        if (setup.IsSuccess == false)
        {
            Debug.LogError("연결 실패: " + setup.ErrorCode);
            return;
        }

        // 2. 방에 들어갑니다. 없는 방이면 새로 만들어집니다
        CasualTalkResponse<SC_JoinRoomAck> join = await CasualTalk.JoinRoom("guild-42");
        if (join.IsSuccess == false)
        {
            Debug.LogError("입장 실패: " + join.ErrorCode);
            return;
        }

        // 내가 들어오기 전에 오간 최근 대화
        foreach (DataChat chat in join.Data.Chats)
        {
            Debug.Log(chat.Chat);
        }

        // 3. 채팅을 보냅니다
        await CasualTalk.ChatRoom("guild-42", "안녕하세요!");
    }

    // 4. 들어가 있는 방에 새 채팅이 올라올 때마다 불립니다 (내가 보낸 채팅도 옵니다)
    private void HandleNewChat(string roomID, DataChat chat)
    {
        Debug.Log("[" + roomID + "] " + chat.UserIDX + ": " + chat.Chat);
    }

    // 5. 게임이 끝날 때 연결을 닫습니다
    private void OnApplicationQuit()
    {
        CasualTalk.Close();
    }
}

아래 플레이어 컨트롤러 하나로 연결 → 방 입장 → 채팅 보내기 → 새 채팅 받기까지 해 볼 수 있습니다. 게임 모드의 플레이어 컨트롤러로 지정하고 플레이하면 출력 로그에 대화가 찍힙니다.

• 서버에 요청을 보내는 함수는 결과를 바로 돌려주지 않고, 결과가 오면 마지막 인자로 넘긴 콜백을 불러 줍니다. 그래서 다음 단계는 콜백 안에서 이어 갑니다.
• [this](...) { ... }는 람다(이름 없는 함수)입니다. 이 예제에서는 람다가 하는 일이 우리 클래스의 함수(OnSetup 등)를 부르는 것뿐이라, 실제 처리는 그 함수 안에서 합니다.
• 결과는 IsSuccess()로 확인합니다. false면 ErrorCode에 실패한 이유가 들어 있습니다.
• 콜백은 모두 게임 스레드에서 불리므로 안에서 바로 UI나 액터를 바꿔도 됩니다.

#include "CasualTalkSubsystem.h"
#include "GameFramework/PlayerController.h"
#include "ChatPlayerController.generated.h"

UCLASS()
class AChatPlayerController : public APlayerController
{
    GENERATED_BODY()

protected:
    virtual void BeginPlay() override;

    // 서버 응답과 새 채팅을 받을 함수
    void OnSetup(const FCasualTalkResponse& Response);
    void OnJoinRoom(const TCasualTalkResponse<FSC_JoinRoomAck>& Response);
    void HandleNewChat(const FString& RoomID, const FDataChat& Chat);

    UPROPERTY()
    TObjectPtr<UCasualTalkSubsystem> CasualTalk;
};

#include "ChatPlayerController.h"

void AChatPlayerController::BeginPlay()
{
    Super::BeginPlay();

    // CasualTalk 기능은 모두 이 서브시스템에 있습니다
    CasualTalk = GetGameInstance()->GetSubsystem<UCasualTalkSubsystem>();

    // 1. 채팅 서버에 연결합니다
    FCasualTalkSetupOption Option;
    Option.AppID = TEXT("casualtalk-dev");    // 발급받은 게임 ID
    Option.UserID = TEXT("player-1024");      // 게임에서 쓰는 플레이어 ID
    Option.Mode = ECasualTalkMode::Tcp;

    // 새 채팅이 오면 HandleNewChat 함수를 부르도록 등록합니다
    Option.OnNewChat = [this](const FString& RoomID, const FDataChat& Chat)
    {
        HandleNewChat(RoomID, Chat);
    };

    // 연결 결과가 오면 OnSetup 함수를 부릅니다
    CasualTalk->Setup(Option, [this](const FCasualTalkResponse& Response)
    {
        OnSetup(Response);
    });
}

void AChatPlayerController::OnSetup(const FCasualTalkResponse& Response)
{
    if (!Response.IsSuccess())
    {
        UE_LOG(LogTemp, Error, TEXT("연결 실패"));
        return;
    }

    // 2. 방에 들어갑니다. 없는 방이면 새로 만들어집니다
    CasualTalk->JoinRoom(TEXT("guild-42"), [this](const TCasualTalkResponse<FSC_JoinRoomAck>& JoinResponse)
    {
        OnJoinRoom(JoinResponse);
    });
}

void AChatPlayerController::OnJoinRoom(const TCasualTalkResponse<FSC_JoinRoomAck>& Response)
{
    if (!Response.IsSuccess())
    {
        UE_LOG(LogTemp, Error, TEXT("입장 실패"));
        return;
    }

    // 내가 들어오기 전에 오간 최근 대화
    for (const FDataChat& Chat : Response.Data.Chats)
    {
        UE_LOG(LogTemp, Log, TEXT("%s"), *Chat.Chat);
    }

    // 3. 채팅을 보냅니다. 결과가 필요 없으면 콜백 자리에 nullptr 를 넣습니다
    CasualTalk->ChatRoom(TEXT("guild-42"), TEXT("안녕하세요!"), FString(), nullptr);
}

// 4. 들어가 있는 방에 새 채팅이 올라올 때마다 불립니다 (내가 보낸 채팅도 옵니다)
void AChatPlayerController::HandleNewChat(const FString& RoomID, const FDataChat& Chat)
{
    UE_LOG(LogTemp, Log, TEXT("[%s] %lld: %s"), *RoomID, Chat.UserIDX, *Chat.Chat);
}

연결 방식

서버와 연결하는 방법은 두 가지이고, Setup 옵션의 Mode로 고릅니다. 어느 쪽을 골라도 쓰는 함수는 똑같고, 두 방식의 플레이어끼리도 같은 방에서 대화할 수 있습니다. 잘 모르겠으면 기본값(Tcp)을 쓰세요.

데이터 타입

CasualTalkResponse / CasualTalkResponse<T>

요청 함수가 돌려주는 결과입니다. Setup은 CasualTalkResponse를, 나머지 함수는 서버가 보낸 데이터(Data)가 붙은 CasualTalkResponse<T>를 돌려줍니다.

FCasualTalkResponse / TCasualTalkResponse<T>

요청 콜백에 들어오는 결과입니다. Setup 콜백은 FCasualTalkResponse를, 나머지 함수의 콜백은 서버가 보낸 데이터(Data)가 붙은 TCasualTalkResponse<T>를 받습니다.

DataChatFDataChat

채팅 하나입니다. 새 채팅(OnNewChat)과 입장할 때 받는 최근 대화가 이 모양으로 옵니다.

SC_HistoryRoomAckFSC_HistoryRoomAck

불러온 이전 채팅입니다.

SC_TranslateRoomAckFSC_TranslateRoomAck

번역 결과입니다.

에러 코드

실패했을 때 ErrorCode에 들어오는 값입니다. Unity에서는 ErrorCode입니다.Unreal에서는 ECasualTalkErrorCode이고, 값은 Unity SDK와 같습니다.

제한 사항