빠른 시작: PlayFab Online Subsystem

이 문서는 Unreal Engine 4 또는 Unreal Engine 5로 빌드된 게임에 대해 Lobby, Matchmaking, Party와 같은 PlayFab 멀티플레이어 기능을 설정하고 사용하는 데 도움이 됩니다. Unreal Engine 4 또는 Unreal Engine 5에서 지원되는 플랫폼 및 버전의 전체 목록은 지원되는 플랫폼을 참조하세요. 이 페이지에 설명된 대상 플랫폼에 대한 관련 단계를 따르면 PlayFab Online Subsystem(PF OSS)을 사용할 준비가 됩니다. 인증, 네트워킹, VOIP, lobby로 그룹화 및 매치메이킹은 다른 변경 없이도 대신 처리됩니다.

PlayFab Online Subsystem 다운로드 및 설치

PlayFab Online Subsystem으로 이동하여 PF OSS 소스를 다운로드하거나 복제합니다. 다운로드하거나 복제된 리포지토리 이름은 PlayFabMultiplayerUnreal입니다. 리포지토리 이름을 OnlineSubsystemPlayFab으로 바꿔야 합니다.

필요한 것

PlayFab TitleID: PlayFab Party와 Multiplayer SDK(Software Development Kits)에 대해 구성된 TitleID가 없는 경우 PlayFab Party 활성화를 참조하세요.

Microsoft Game Development Kit(GDK), PC, Switch, PlayStation®5 및 PlayStation®4

특정 플랫폼 PlayFab Party 및 Lobby, Matchmaking 라이브러리: PlayFab Party 및 Multiplayer 라이브러리 얻기를 참조하세요.

초기 설정

Unreal Engine 코드 베이스

OnlineSubsystemPlayFab 폴더와 그 내용을 Unreal Engine 디렉터리의 Engine\Plugins\Online 아래에 복사합니다.
GenerateProjectFiles.bat를 실행하여 엔진용 프로젝트 파일을 만듭니다.
새 UE5.sln 파일을 선택하여 프로젝트를 Visual Studio에 로드합니다.
솔루션 구성을 Development Editor로, 솔루션 플랫폼을 Win64로 설정합니다. Unreal Engine 5 대상을 선택한 다음 Build를 선택합니다.

게임 코드 베이스

플러그인 목록에 OnlineSubsystemPlayFab을 추가하려면 프로젝트 파일의 Plugins 섹션에 다음 변경 사항을 적용합니다.
- 출시하지 않는 플랫폼은 제거합니다.
- Unreal Engine 4를 사용하는 경우 XB1 대신 XboxOneGDK를 사용합니다. Unreal Engine 5는 XboxOneGDK를 더 이상 사용하지 않습니다.

{
    "Name": "OnlineSubsystemPlayFab",
    "Enabled": true,
    "PlatformAllowList": [
    "XB1",
    "WinGDK",
    "XSX",
    "Win64",
    "Switch",
    "PS4",
    "PS5"
    ],
    "SupportedTargetPlatforms": [
    "XB1",
    "WinGDK",
    "XSX",
    "Win64",
    "Switch",
    "PS4",
    "PS5"
    ]
}

{ProjectName}.uproject 파일을 선택한 다음 Unreal Engine 코드 경로로 Switch Unreal Engine Version을 선택하여 게임 솔루션 파일을 생성합니다.

게임 구성

대상 플랫폼에 관계없이 게임은 의도된 플랫폼 대상의 INI 파일([yourGameDirectory]/Platforms/[yourPlatform]/Config에 있음)에서 특정 PlayFab 관련 값을 구성해야 합니다.
- XBOX Series X GDK: XSXEngine.ini
- PC GDK: WinGDKEngine.ini
- XBOX One GDK: XB1Engine.ini (Unreal Engine 4를 사용하는 경우 XboxOneGDKEngine.ini)
- PC Steam: WindowsEngine.ini ([yourGameDirectory]/Config/Windows에서 찾을 수도 있음)
- Nintendo Switch SwitchEngine.ini
- PS4™ PS4Engine.ini
- PS5™ PS5Engine.ini
구성에서 이미 존재하는 INI 섹션(예: Engine.GameEngine)을 다음 섹션에 표시된 것으로 바꿉니다.
모든 <REPLACE ME> 필드를 데이터로 바꿔야 합니다.
UE 5.6 이상에서는 DriverClassName 매개 변수에 “/Script/” 접두사가 필요합니다. 예를 들어 "OnlineSubsystemPlayFab.PlayFabNetDriver" 대신 "/Script/OnlineSubsystemPlayFab.PlayFabNetDriver"를 사용합니다.

[OnlineSubsystemPlayFab]
bEnabled=true
PlayFabTitleID=<REPLACE ME with your PlayFab title ID>
MaxDeviceCount=<REPLACE ME with your max player count (note: split screen is still 1 device). In the example of an 8 player game, this would be 8.>
MaxDevicesPerUserCount=<REPLACE ME with your max player count per box (note: split screen is still 1 device) In the example of an 8 player game, this would be 1.>
MaxEndpointsPerDeviceCount=<REPLACE ME with your max player count per box (note: split screen is still 1 device)  In the example of an 8 player game, this would be 1.>
MaxUserCount=<REPLACE ME with your max player count (note: split screen is still 1 device)  In the example of an 8 player game, this would be 8.>
MaxUsersPerDeviceCount=<REPLACE ME with your max player count per box (note: split screen is still 1 device)  In the example of an 8 player game, this would be 1.>
DirectPeerConnectivityOptions=<REPLACE ME with your connectivity options, in the form of an array of strings. The default case corresponds to the following:
+DirectPeerConnectivityOptions=AnyPlatformType
+DirectPeerConnectivityOptions=AnyEntityLoginProvider.
If you want to disable P2P and use cloud relay instead, set DirectPeerConnectivityOptions=None>
bHasPlayFabVoiceEnabled=<REPLACE ME with true/false>

[/Script/OnlineSubsystemPlayFab.PlayFabNetDriver]
NetConnectionClassName="OnlineSubsystemPlayFab.PlayFabNetConnection"
ReplicationDriverClassName="<REPLACE ME with your existing replication driver class name>" . Skip if the game doesn't have a replication driver class (https://docs.unrealengine.com/5.2/en-US/replication-graph-in-unreal-engine/).
ConnectionTimeout=15.0
InitialConnectTimeout=30.0

[/Script/Engine.GameEngine]
!NetDriverDefinitions=ClearArray
+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/OnlineSubsystemPlayFab.PlayFabNetDriver",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")

플랫폼별 고려 사항

이 모든 작업으로 거의 완료되었습니다. 설정해야 할 몇 가지 주요 플랫폼별 매개 변수만 남아 있습니다.

GDK

GDK로 게임을 개발할 때 플랫폼 서비스를 설정합니다.

[OnlineSubsystem]
DefaultPlatformService=PlayFab
NativePlatformService=GDK

Steam

Steam이 있는 Win64용 게임을 개발하는 경우 플랫폼 서비스를 정의합니다.

[OnlineSubsystem]
DefaultPlatformService=PlayFab
NativePlatformService=Steam

Switch

Switch에 대한 자세한 내용은 Switch PlayFab OSS와 함께 제공되는 ReadMe.md 파일을 참조하세요. 액세스 권한이 없는 경우 프라이빗 리포지토리에 대한 액세스를 요청할 수 있습니다.

PS5™ 및 PS4™

PS5™ 및 PS4™에 대한 자세한 내용은 PS5™ 및 PS4™ PlayFab OSS와 함께 제공되는 ReadMe.md 파일을 참조하세요. 액세스 권한이 없는 경우 프라이빗 리포지토리에 대한 액세스를 요청할 수 있습니다.

크로스 플랫폼

게임에서 PlayFab의 크로스 플랫폼 네트워킹 지원을 사용하는 경우 연결을 허용하는 플랫폼을 정의합니다.

[/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
!CompatibleUniqueNetIdTypes=ClearArray
+CompatibleUniqueNetIdTypes=STEAM
+CompatibleUniqueNetIdTypes=GDK
+CompatibleUniqueNetIdTypes=SWITCH
+CompatibleUniqueNetIdTypes=PS4
+CompatibleUniqueNetIdTypes=PS5

모든 플랫폼은 기본적으로 VoIP를 허용합니다. 특정 플랫폼에 대해 VoIP를 비활성화하려면 다음 예에 표시된 것처럼 플랫폼 모델 이름을 Unreal Engine 구성 파일에 추가합니다.

[OnlineSubsystemPlayFabVoiceChatDisabledPlatforms]
!Platforms=ClearArray
+Platforms=WIN64
+Platforms=STEAM
+Platforms=SWITCH
+Platforms=PS4
+Platforms=PS5

이러한 단계는 게임에서 사용하는 데 필요한 OSS 설정을 완료합니다.

게임 코드에서 사용

PlayFab Online Subsystem은 Game Session 이름 지정을 NAME_GameSession으로만 지원합니다.

다른 Online Subsystem 플러그인을 사용하는 것과 유사합니다. Game.Build.cs에 PublicDependencyModuleNames.AddRange(new string[] { "OnlineSubsystem", "OnlineSubsystemUtils" });를 추가한 다음 다른 게임 플러그인과 동일한 방식으로 사용합니다. GameSession.cpp의 예시 코드:

#include "OnlineSubsystem.h"
#include "OnlineSubsystemUtils.h"

...

bool Game::JoinSession(const FUniqueNetIdPtr UserId, FName SessionName, const FOnlineSessionSearchResult& SearchResult)
{

    IOnlineSubsystem* OnlineSub = Online::GetSubsystem(GetWorld()); // Using OnlineSubsystemPlayFab plugin
    if (OnlineSub)
    {
        IOnlineSessionPtr Sessions = OnlineSub->GetSessionInterface(); // Using OnlineSessionInterfacePlayFab.h
        if (Sessions.IsValid() && UserId.IsValid())
        {
            // ...
        }
    }
    // ...
}

GameFriends.cpp의 예시 코드:

#include "OnlineSubsystem.h"
#include "OnlineSubsystemUtils.h"

...

void Game::ViewFriendProfile()
{
    IOnlineSubsystem* OnlineSub = Online::GetSubsystem(GetWorld()); // Using OnlineSubsystemPlayFab plugin
    if (OnlineSub)
    {
        IOnlineIdentityPtr Identity = OnlineSub->GetIdentityInterface(); // Using OnlineIdentityInterfacePlayFab.h
        if (Identity.IsValid() && Friends.IsValidIndex(FriendIndex))
        {
            // ....
        }
    }
}

문제 해결

문제 해결에 도움이 되는 방법입니다.

Unreal Engine 설치된 빌드

GDK 빌드 플레이버에서 OnlineSubsystemPlayFab로 Unreal Engine 설치된 빌드를 만들려고 할 때 사용자가 문제에 직면할 수 있습니다. 더 완전한 솔루션이 나올 때까지 이 문제를 성공적으로 극복하는 데 도움이 되는 지침을 제공합니다. Unreal Engine 5.4, 5.5, 5.6 또는 5.7을 사용하는 경우:

다음 런타임 오류가 발생할 수 있습니다: Runtime dependency Party.dll is configured to be staged from C:\Program Files (x86)\Microsoft GDK\<version>\Party.dll and Engine\Plugins\Online\OnlineSubsystemPlayFab\Platforms\GDK\Redist\Party.dll
Engine\Platforms\GDK\Plugins\Online\OnlineSubsystemGDK\로 이동합니다.
OnlineSubsystemGDK.uplugin을 열고 PlayFabParty를 disabled로 설정합니다.

{
    "Name": "PlayFabParty",
    "Enabled": false
}

Engine\Platforms\GDK\Plugins\Online\OnlineSubsystemGDK\Source\로 이동합니다.
OnlineSubsystemGDK.Build.cs를 열고 PlayFabParty 포함을 주석 처리합니다.

if (Target.bCompileAgainstEngine)
{
    //PublicDependencyModuleNames.Add("PlayFabParty");
}

Unreal Engine 5.0 - 5.3을 사용하는 경우:

컴퓨터에 Unreal Engine이 설치된 디렉터리를 찾습니다.
Engine\Platforms\GDK\Plugins\Online\PlayFabParty로 이동합니다.
PlayFabParty.uplugin을 열고 PlatformDenyList로 Modules 구성을 업데이트합니다.

"Modules": [
        {
            "Name": "PlayFabParty",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "HasExplicitPlatforms": true,
            "PlatformDenyList": [ "WinGDK", "Win64" ]
        }
    ],

Installed Build에 이러한 플랫폼이 필요한 경우 XB1(PlayFabParty_XB1.uplugin) 및 XSX(PlayFabParty_XSX.uplugin)에 대해 이 프로세스를 반복합니다. Installed Build에 Win64도 필수 플랫폼인 경우 PlatformDenyList 배열에 Win64를 추가합니다.

Unreal Engine 4.27+를 사용하는 경우:

컴퓨터에 Unreal Engine이 설치된 디렉터리를 찾습니다.
Engine\Platforms\GDK\Plugins\Online\PlayFabParty로 이동합니다.
PlayFabParty.uplugin을 엽니다.
키 WhitelistPlatforms를 BlacklistPlatforms로 바꿉니다.
Installed Build에 이러한 플랫폼이 필요한 경우 XboxOneGDK(PlayFabParty_XboxOneGDK.uplugin) 및 XSX(PlayFabParty_XSX.uplugin)에 대해 프로세스를 반복합니다. Installed Build에 Win64도 필수 플랫폼인 경우 BlacklistPlatforms 배열에 Win64를 추가합니다.

Unreal Engine 4.27+용 PlayFabParty.uplugin의 Modules 구성 예시:

"Modules": [
       {
            "Name": "PlayFabParty",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "BlacklistPlatforms": ["WinGDK", "Win64"]
        }
    ],

Steam에서 HandShake 실패

핸드셰이크 실패(예: LogHandshake: IncomingConnectionless: Error reading handshake packet)가 표시되면 설정을 확인하기 위해 이 Unreal Engine 포럼 게시물을 참조하세요.

OnlineSubsystemPlayFab의 워크플로

플랫폼별 고려 사항 섹션에 설명된 단계에서는 다음을 포함하도록 요청합니다.

[OnlineSubsystem]
DefaultPlatformService=PlayFab

Unreal Engine OnlineSubsystemModule은 PlayFab에 대한 온라인 서브시스템 인스턴스를 만들고 PlayFabSingleton 만들기를 시작합니다. 이 시점에서 SDK는 ⁠FOnlineSubsystemPlayFab::Init()에서 초기화되며, 여기서 PlayFab TitleID로 Party 및 Multiplayer SDK를 모두 초기화합니다(이 titleID는 게임 구성 파일 안에 정의됨). 초기화하는 동안 메인 온라인 서브시스템으로 ⁠CreatePlayFabSocketSubsystem()을 실행합니다. Multiplayer SDK의 워크플로: FOnlineSubsystemPlayFab::Init()은 타이틀에 대한 InitializeMultiplayer() multiplayer SDK 싱글톤을 초기화합니다. PlayFabLobby.cpp의 FPlayFabLobby::DoWork()는 Multiplayer API에 의해 트리거된 상태 변경을 처리합니다(API에 대해서는 Platforms/GDK/Include/PFLobby.h 참조). Party SDK의 워크플로: FOnlineSubsystemPlayFab::Init()은 타이틀에 대한 InitializeParty() multiplayer SDK 싱글톤을 초기화합니다. OnlineSubsystemPlayFab.cpp의 FOnlineSubsystemPlayFab::DoWork()는 Party API에 의해 트리거된 상태 변경을 처리합니다(API에 대해서는 Platforms/GDK/Include/Party.h 참조). “PlayStation”은 Sony Interactive Entertainment Inc.의 등록 상표 또는 상표입니다. “PS4”는 Sony Interactive Entertainment Inc.의 등록 상표 또는 상표입니다. “PS5”는 Sony Interactive Entertainment Inc.의 등록 상표 또는 상표입니다.

XBOX Services

PlayFab

PlayFab Online Subsystem (OSS) Quickstart

빠른 시작: PlayFab Online Subsystem

PlayFab Online Subsystem 다운로드 및 설치

필요한 것

Microsoft Game Development Kit(GDK), PC, Switch, PlayStation®5 및 PlayStation®4

초기 설정

Unreal Engine 코드 베이스

게임 코드 베이스

게임 구성

플랫폼별 고려 사항

GDK

Steam

Switch

PS5™ 및 PS4™

크로스 플랫폼

게임 코드에서 사용

문제 해결

Unreal Engine 설치된 빌드

Steam에서 HandShake 실패

OnlineSubsystemPlayFab의 워크플로

​빠른 시작: PlayFab Online Subsystem

​PlayFab Online Subsystem 다운로드 및 설치

​필요한 것

​Microsoft Game Development Kit(GDK), PC, Switch, PlayStation®5 및 PlayStation®4

​초기 설정

​Unreal Engine 코드 베이스

​게임 코드 베이스

​게임 구성

​플랫폼별 고려 사항

​GDK

​Steam

​Switch

​PS5™ 및 PS4™

​크로스 플랫폼

​게임 코드에서 사용

​문제 해결

​Unreal Engine 설치된 빌드

​Steam에서 HandShake 실패

​OnlineSubsystemPlayFab의 워크플로

빠른 시작: PlayFab Online Subsystem

PlayFab Online Subsystem 다운로드 및 설치

필요한 것

Microsoft Game Development Kit(GDK), PC, Switch, PlayStation®5 및 PlayStation®4

초기 설정

Unreal Engine 코드 베이스

게임 코드 베이스

게임 구성

플랫폼별 고려 사항

GDK

Steam

Switch

PS5™ 및 PS4™

크로스 플랫폼

게임 코드에서 사용

문제 해결

Unreal Engine 설치된 빌드

Steam에서 HandShake 실패

OnlineSubsystemPlayFab의 워크플로