EOS × Unreal
연동 가이드

Epic Online Services는 에픽게임즈가 제공하는 무료 크로스플랫폼 게임 백엔드입니다. 자체 서버를 구축하지 않고도 로그인, 친구, 세션, 매치메이킹, 업적, 보이스챗 같은 온라인 기능을 붙일 수 있습니다.

EOS는 크게 두 갈래의 서비스로 나뉩니다. 이 구분을 이해하면 이후 플러그인과 설정이 훨씬 명확해집니다.

routes언리얼에서 EOS를 붙이는 두 가지 길

언리얼 엔진에서 EOS에 접근하는 방법은 크게 두 가지입니다. 프로젝트 성격에 맞는 길을 먼저 정하세요.

코드를 만지기 전에 환경부터 갖춰 둡니다. 빠진 항목이 있으면 뒤에서 빌드가 막히는 경우가 많습니다.

• Unreal Engine 5.x C++ 프로젝트 — EOS 플러그인은 C++ 컴파일이 필요합니다. 블루프린트 전용 프로젝트라면 C++ 클래스를 하나라도 추가해 C++ 프로젝트로 전환하세요.
• 최신 엔진 버전 권장 (5.8 이상) — 함께 배포되는 EOS SDK가 최신이며, 구버전 엔진의 SDK에는 알려진 WebRTC 취약점(Chromium M102 이전)이 있습니다. P2P를 쓴다면 EOS SDK를 1.16 이상으로 갱신하거나 최신 엔진을 쓰는 것이 안전합니다.
• Visual Studio (Windows) 또는 Xcode (macOS) — C++ 모듈 빌드 도구.
• Epic Games 계정과 Epic Developer Portal 접근 권한.

EOS와 통신하려면 포털에서 제품을 등록하고, 엔진에 넣을 자격 증명(credentials)을 발급받아야 합니다. 이 값들이 5단계 설정의 핵심 재료가 됩니다.

step조직과 제품 만들기

1. Epic Developer Portal에 로그인하고 Organization을 생성합니다(없을 경우).
2. 조직 안에서 Product를 새로 만듭니다. 이것이 곧 여러분의 게임 한 개에 해당합니다.
3. 제품의 Product Settings 페이지로 들어가면 아래 표의 식별자들을 확인할 수 있습니다.

stepClient와 Client Policy 설정

제품 설정에서 Clients 탭으로 이동해 새 Client를 만들고, 권한을 정의하는 Client Policy를 연결합니다. 정책에는 이 클라이언트가 어떤 기능(세션, 로비, 친구 등)을 호출할 수 있는지가 담깁니다. 개발 단계에서는 Peer2Peer나 광범위한 권한이 포함된 정책을 쓰고, 출시 전에 최소 권한으로 좁히는 방식이 일반적입니다.

stepEpic Account Services 활성화

에픽 계정 로그인·친구·프레즌스를 쓰려면 Epic Account Services(EAS)를 별도로 설정해야 합니다. Brand 설정과 권한(Scopes)을 구성하고, 가능하면 도메인 인증을 마쳐 두세요. 도메인 인증이 없으면 플레이어 로그인 시 경고 화면이 노출됩니다.

에픽 포털 준비가 끝났으면 엔진 쪽에서 플러그인을 켭니다. 에디터 메뉴 Edit → Plugins에서 검색해 활성화한 뒤 에디터를 재시작합니다.

OSSv1Online Subsystem EOS 경로

• Online Subsystem EOS — EOS용 OSS 구현체(필수).
• EOS Shared — EOS SDK 공유 모듈(필수).
• Online Subsystem EOS Plus — Steam·콘솔 등 네이티브 플랫폼과 EOS를 함께 쓰는 크로스플레이용. 세션 미러링 등을 제공하지만 베타·기능 제한적입니다(선택).
• EOS Voice Chat / EOS RTC IVoiceChat — 보이스챗이 필요할 때(선택).

OSSv2Online Services EOS 경로

차세대 방식을 쓴다면 Edit → Plugins에서 Online Platform 카테고리를 열어 다음을 켭니다. 기본 Online Services 베이스 플러그인은 보통 이미 활성화되어 있습니다.

• Online Services EOSGS — EOS 게임 서비스 기능.
• Online Services EOS — EAS(에픽 계정 서비스) 기능을 보강. 두 개를 함께 켜면 게임 서비스와 계정 서비스를 모두 사용할 수 있습니다.

코드 모듈 의존성과 DefaultEngine.ini 설정을 채워 EOS를 기본 온라인 플랫폼으로 지정합니다.

cppBuild.cs 모듈 의존성

C++에서 OSS API를 호출하려면 게임 모듈의 Build.cs에 의존성을 추가합니다.

PublicDependencyModuleNames.AddRange(new string[]{
    "Core", "CoreUObject", "Engine", "InputCore",
    "OnlineSubsystem",          // OSS 코어
    "OnlineSubsystemEOS",       // EOS 구현체
    "OnlineSubsystemUtils"      // 세션/넷드라이버 유틸
});

iniDefaultEngine.ini — OSSv1 설정

03단계에서 발급받은 값들을 채워 넣습니다. 아래는 EOS를 기본 플랫폼으로 쓰는 표준 구성입니다.

; --- EOS를 기본 온라인 플랫폼으로 지정 ---
[OnlineSubsystem]
DefaultPlatformService=EOS

[OnlineSubsystemEOS]
bEnabled=true

; --- 넷드라이버: 접속을 EOS 소켓 위로 ---
[/Script/Engine.GameEngine]
+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOSBase",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")

; --- 포털에서 받은 제품 자격 증명 ---
[/Script/OnlineSubsystemEOS.EOSSettings]
ProductId=<PRODUCT_ID>
SandboxId=<SANDBOX_ID>
DeploymentId=<DEPLOYMENT_ID>
ClientId=<CLIENT_ID>
ClientSecret=<CLIENT_SECRET>
EncryptionKey=<64자리 16진수 키>

; --- 사용할 기능 토글 ---
bUseEAS=true          ; 에픽 계정 로그인/친구
bUseEOSConnect=true   ; 익명/플랫폼 연결
bUseEOSSessions=true  ; 세션·매치메이킹
bMirrorStatsToEOS=true
bMirrorAchievementsToEOS=true

iniDefaultEngine.ini — OSSv2(Online Services) 설정

차세대 방식을 쓴다면 자격 증명 블록의 형식이 다릅니다.

[OnlineServices.EOS]
ProductId=<PRODUCT_ID>
SandboxId=<SANDBOX_ID>
DeploymentId=<DEPLOYMENT_ID>
ClientId=<CLIENT_ID>
ClientSecret=<CLIENT_SECRET>
ClientEncryptionKey=<ENCRYPTION_KEY>

guiProject Settings로 채우기

ini를 직접 편집하는 대신 Edit → Project Settings → Plugins → Online Subsystem EOS에서 같은 값을 GUI로 채울 수도 있습니다. 포털에서 받은 크리덴셜을 Artifacts 배열의 첫 항목에 매핑하면 됩니다. 저장하면 같은 DefaultEngine.ini에 기록됩니다.

EOS의 첫 관문은 로그인입니다. IOnlineIdentity 인터페이스의 Login(또는 AutoLogin)을 호출하며, 어떤 자격 증명 타입을 쓰느냐로 동작이 갈립니다.

types자격 증명 타입

toolDev Auth Tool 사용 가이드

Developer Authentication Tool(EOS_DevAuthTool)은 Epic Online Services SDK에 포함된 개발용 인증 도구입니다. 에디터에서 게임을 반복 실행할 때 브라우저로 에픽 계정 로그인을 매번 거치지 않고, 미리 인증해 둔 자격증명으로 자동 로그인하게 해줍니다. 개발 중 로그인 반복 작업과 멀티플레이 로컬 테스트를 빠르게 만드는 것이 목적입니다.

whatDev Auth Tool이란

EOS 인증(EOS_Auth)으로 로그인하려면 에픽 계정 인증이 필요합니다. 기본 흐름에서는 매 실행마다 브라우저가 떠서 계정 로그인을 거쳐야 하는데, 실행을 수십 번 반복하는 개발 단계에서는 비효율적입니다.

EOS_DevAuthTool은 에픽 계정 인증을 한 번만 수행해 자격증명을 로컬에 보관하고, 에디터/게임이 로컬 포트로 그 자격증명을 받아 AUTH_TYPE=Developer 방식으로 자동 로그인하게 합니다. 결과적으로 실행할 때마다 브라우저 인증을 건너뜁니다.

• 로그인 자동화: 실행 시 브라우저 인증 생략
• 멀티 계정: 하나의 툴에 여러 자격증명을 등록해 로컬 멀티플레이 테스트
• 개발 전용: 출시 빌드에는 사용하지 않음(아래 가이드라인 참조)

find어디서 받나

툴은 EOS SDK(C SDK)에 동봉되어 있습니다. Epic Dev Portal에서 SDK를 받아야 얻을 수 있습니다.

1. Epic Dev Portal에서 다운로드: dev.epicgames.com에서 EOS SDK(C SDK)를 받아 압축을 풀면 SDK/Tools 폴더에 도구가 들어 있습니다.
2. 엔진 번들 SDK에는 보통 없음: 언리얼 엔진에 번들된 EOS SDK에는 일반적으로 Tools 폴더(=DevAuthTool)가 포함되지 않습니다. 엔진은 런타임 라이브러리/헤더만 번들하므로, DevAuthTool은 위처럼 Dev Portal에서 별도로 받아야 합니다.

SDK/Tools 폴더 안에는 바로 실행되는 파일이 아니라 플랫폼별 버전 zip이 들어 있어, 이를 한 번 더 풀어야 실행 파일이 나옵니다.

# dev.epicgames.com에서 받은 EOS SDK 압축 해제 후
<EOS-SDK>/SDK/Tools/
  EOS_DevAuthTool-win32-x64-X.X.X.zip    # Windows
  EOS_DevAuthTool-darwin-x64-X.X.X.zip   # macOS

# 위 zip을 한 번 더 풀면 실행 파일이 나온다
EOS_DevAuthTool.exe    # Windows
EOS_DevAuthTool.app    # macOS

run실행과 로그인 절차

1. EOS_DevAuthTool 실행.
2. 상단 Port 입력란에 사용할 로컬 포트를 입력(예: 6300, 7777, 8081).
3. Login 버튼 클릭. 이 동작이 입력한 포트에서 로컬 서버 리스닝을 시작하는 동시에 기본 브라우저로 에픽 계정 인증 페이지를 엽니다.
4. 에픽 계정으로 로그인/승인.
5. 인증이 끝나면 해당 항목에 credential name(이름표)을 지정합니다. 예: dev1. 이 이름이 에디터 연결 시 핵심 키가 됩니다.

connectUE 에디터 연결

에디터가 게임 실행 시 위 자격증명을 쓰도록 런치 파라미터를 지정합니다. Editor Preferences → Level Editor → Play → Play in Standalone Game 섹션의 Additional Launch Parameters에 아래를 입력합니다.

-AUTH_TYPE=Developer -AUTH_LOGIN=localhost:6300 -AUTH_PASSWORD=dev1

• -AUTH_TYPE=Developer: Dev Auth Tool 방식 사용 선언
• -AUTH_LOGIN=localhost:<port>: 툴에서 입력한 포트와 정확히 일치해야 함
• -AUTH_PASSWORD=<credentialName>: 툴에서 지은 이름표(예 dev1)

multi멀티플레이 로컬 테스트

한 PC에서 서로 다른 플레이어로 동시에 로그인하려면 툴에 자격증명을 여러 개 등록합니다. 같은 툴 인스턴스에서 Login을 반복해 dev1, dev2 등 서로 다른 에픽 계정을 각각 이름표로 추가합니다.

그다음 Number of Players를 늘리고, 클라이언트마다 다른 -AUTH_PASSWORD를 쓰게 하면 각 창이 다른 플레이어로 로그인합니다. 멀티 클라이언트는 보통 별도 프로세스(Standalone)로 띄워 테스트합니다.

1. 툴에 dev1, dev2 등 자격증명 등록(서로 다른 에픽 계정)
2. Play 설정에서 Number of Players 2 이상으로 설정
3. 각 클라이언트가 다른 credential을 쓰도록 파라미터 분기(또는 인스턴스별로 Standalone 실행 시 커맨드라인에 각각 전달)
4. split-screen 대신 Standalone/별도 프로세스 모드로 실제 네트워크 경로 검증

tips가이드라인과 주의점

• 개발 중에만 사용: Developer 인증은 개발 편의용입니다. 출시 빌드는 런처/스토어 연동 방식(예: exchangecode, Account Portal 등 정식 로그인)을 씁니다.
• 툴은 계속 띄워둘 것: Dev Auth Tool이 실행 중이고 포트를 리스닝 중이어야 에디터가 포트로 자격증명을 받습니다. 개발 세션 내내 켜 두세요.
• 포트·이름 정확히 일치: -AUTH_LOGIN의 포트와 툴 포트, -AUTH_PASSWORD와 credential name이 한 글자라도 다르면 로그인 실패합니다.
• 패키징 Standalone exe: 빌드한 개발용 exe도 동일 파라미터를 커맨드라인으로 넘기면 똑같이 동작합니다. 예: MyGame.exe -AUTH_TYPE=Developer -AUTH_LOGIN=localhost:6300 -AUTH_PASSWORD=dev1
• 방화벽/포트 충돌: 입력한 포트가 다른 프로세스에 점유되어 있으면 리스닝이 실패하거나 연결되지 않습니다. 충돌 시 다른 포트로 바꾸고 파라미터도 함께 수정하세요.
• 자격증명 보존: Dev Auth Tool은 자격증명을 사용 간(between uses)에 기억하고, 선택한 포트도 다음 실행 시 자동 선택되도록 보존합니다. 도구를 닫았다 다시 켜도 자격증명이 남아 있어 재로그인이 필요 없는 것이 정상 동작입니다. (단, 토큰이 만료되면 갱신이 필요할 수 있으며, 이는 '종료=휘발'과는 별개 사안입니다.)
• 다중 보유: 하나의 툴 인스턴스가 여러 credential을 동시에 보유할 수 있습니다. 멀티 계정 테스트에 별도 인스턴스를 띄울 필요는 없습니다.

cpp로그인 코드 예시

게임 인스턴스나 적절한 곳에서 Identity 인터페이스를 얻어 로그인을 호출하고, 완료 델리게이트로 결과를 받습니다.

void UMyGameInstance::Login()
{
    IOnlineSubsystem* OSS = IOnlineSubsystem::Get();
    if (!OSS) return;

    IOnlineIdentityPtr Identity = OSS->GetIdentityInterface();
    if (!Identity.IsValid()) return;

    // 완료 콜백 등록
    Identity->AddOnLoginCompleteDelegate_Handle(
        0, FOnLoginCompleteDelegate::CreateUObject(
            this, &UMyGameInstance::OnLoginComplete));

    // AutoLogin은 위 Launch Parameters를 사용
    Identity->AutoLogin(0);
}

void UMyGameInstance::OnLoginComplete(
    int32 LocalUserNum, bool bWasSuccessful,
    const FUniqueNetId& UserId, const FString& Error)
{
    if (bWasSuccessful)
        UE_LOG(LogTemp, Log, "EOS 로그인 성공: %s", *UserId.ToString());
    else
        UE_LOG(LogTemp, Warning, "EOS 로그인 실패: %s", *Error);
}

로그인이 되면 나머지는 각 인터페이스를 통해 호출합니다. 자주 쓰는 기능과 담당 인터페이스를 정리했습니다.

flow방 만들고 참가하기

로그인이 끝났다면 이제 실제로 방(세션)을 만들고 → 찾고 → 참가하는 흐름을 붙일 차례입니다. 호스트와 클라이언트 모두 IOnlineSession 인터페이스 하나로 처리하며, 각 호출은 완료 델리게이트로 결과를 돌려받습니다.

호스트가 세션 옵션을 채워 CreateSession을 호출하고, 완료되면 listen 옵션으로 맵을 열어 리슨 서버가 됩니다.

void UMyGameInstance::HostSession()
{
    IOnlineSessionPtr Session = IOnlineSubsystem::Get()->GetSessionInterface();

    FOnlineSessionSettings S;
    S.bIsLANMatch            = false;   // EOS 릴레이로 연결
    S.NumPublicConnections   = 4;       // 최대 인원
    S.bShouldAdvertise       = true;    // 검색 목록에 노출
    S.bUsesPresence          = true;
    S.bUseLobbiesIfAvailable = true;    // EOS 로비로 생성
    S.Set(SEARCH_KEYWORDS, FString("MyGame"),
          EOnlineDataAdvertisementType::ViaOnlineService);

    Session->OnCreateSessionCompleteDelegates.AddUObject(
        this, &UMyGameInstance::OnCreateSessionComplete);
    Session->CreateSession(0, NAME_GameSession, S);
}

void UMyGameInstance::OnCreateSessionComplete(FName Name, bool bOK)
{
    if (bOK)                                  // 리슨 서버로 맵 오픈
        GetWorld()->ServerTravel("/Game/Maps/Lobby?listen");
}

참가할 클라이언트는 FindSessions로 조건에 맞는 세션 목록을 받습니다. 검색 결과는 FOnlineSessionSearch에 채워집니다.

TSharedPtr<FOnlineSessionSearch> Search;

void UMyGameInstance::FindGames()
{
    IOnlineSessionPtr Session = IOnlineSubsystem::Get()->GetSessionInterface();

    Search = MakeShared<FOnlineSessionSearch>();
    Search->MaxSearchResults = 20;
    Search->QuerySettings.Set(SEARCH_LOBBIES, true,
                              EOnlineComparisonOp::Equals);

    Session->OnFindSessionsCompleteDelegates.AddUObject(
        this, &UMyGameInstance::OnFindGamesComplete);
    Session->FindSessions(0, Search.ToSharedRef());
}

void UMyGameInstance::OnFindGamesComplete(bool bOK)
{
    if (bOK && Search->SearchResults.Num() > 0)
        JoinGame(Search->SearchResults[0]);   // 첫 결과에 참가
}

고른 결과로 JoinSession을 호출하고, 완료되면 GetResolvedConnectString으로 얻은 접속 문자열로 ClientTravel 하면 호스트의 맵으로 들어갑니다.

void UMyGameInstance::JoinGame(const FOnlineSessionSearchResult& Result)
{
    IOnlineSessionPtr Session = IOnlineSubsystem::Get()->GetSessionInterface();
    Session->OnJoinSessionCompleteDelegates.AddUObject(
        this, &UMyGameInstance::OnJoinGameComplete);
    Session->JoinSession(0, NAME_GameSession, Result);
}

void UMyGameInstance::OnJoinGameComplete(
    FName Name, EOnJoinSessionCompleteResult::Type Type)
{
    IOnlineSessionPtr Session = IOnlineSubsystem::Get()->GetSessionInterface();
    FString Connect;
    if (Session->GetResolvedConnectString(NAME_GameSession, Connect))
        GetFirstLocalPlayerController()
            ->ClientTravel(Connect, TRAVEL_Absolute);   // 호스트 맵으로 입장
}

개발 중 쓰던 Dev Auth Tool·Account Portal은 출시 빌드에서 쓰지 않습니다. 배포 채널에 맞는 인증으로 바꾸고 환경을 라이브로 승격합니다.

• Epic Games Store 배포 — 런처가 실행 시 넘겨주는 코드로 자동 로그인됩니다. 인증 타입을 exchangecode로 처리하세요. 별도 Dev Auth Tool이 필요 없습니다.
• 샌드박스 → 라이브 승격 — 개발용 Sandbox/Deployment ID로 검증을 마쳤다면 출시용 환경의 ID로 교체합니다. 환경마다 데이터가 분리됩니다.
• Client Policy 최소화 — 개발 중 넓게 열어 둔 권한을, 출시 빌드가 실제로 호출하는 기능만 남기도록 좁힙니다.
• 패키징 후 검증 — 에디터(PIE)와 패키징된 빌드는 인증 경로가 다릅니다. 반드시 패키징된 Standalone 빌드로 로그인·세션을 다시 확인하세요.

연동 초반에 반복되는 막힘들과 점검 포인트입니다.

공식 문서와 검증된 학습 자료입니다. 엔진 버전에 따라 화면과 설정이 조금씩 다를 수 있으니 본인 버전의 문서를 확인하세요.

• Online Subsystem EOS Plugin — 공식 문서
• Enable and Configure Online Services EOS (OSSv2)
• EOS Online Subsystem (OSS) Plugin — 공식 강의
• EpicGames/EOS-Getting-Started — 예제 저장소
• Epic Developer Portal