> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiplayer Unity 플러그인 빠른 시작

> GDK 설정 고려 사항을 포함하여 PlayFab Multiplayer Unity 플러그인을 설치하고 Unity 프로젝트에서 첫 번째 Lobby 및 Matchmaking API 호출을 수행합니다.

# 빠른 시작: PlayFab Multiplayer Unity 플러그인

PlayFab Multiplayer Unity 플러그인을 시작하세요. 아래 단계를 따라 패키지를 설치하고 기본 작업에 대한 예제 코드를 시도해 보세요.

이 빠른 시작은 Unity용 PlayFab Multiplayer SDK를 사용하여 첫 번째 API 호출을 수행하는 데 도움이 됩니다. 계속하기 전에, PlayFab 계정이 있고 게임 및 PlayFab Game Manager에서 PlayFab에 로그인하는 방법에 익숙한지 확인하기 위해 [빠른 시작: Unity에서 C#용 PlayFab Client 라이브러리](/services/playfab/sdks/unity3d/quickstart)를 완료했는지 확인하세요.

<Note>
  이 플러그인을 사용하여 Microsoft Game Development Kit(GDK) 기반 게임을 개발할 계획이라면, GDK를 별도로 획득하고 설치해야 합니다. XBOX 콘솔의 Game Core용 Unity 애드온에 대한 자세한 내용도 참조하세요.
</Note>

## 요구 사항

* [PlayFab 개발자 계정](https://developer.playfab.com).

* Unity Editor의 설치된 사본. Unity Hub를 통해 개인용 Unity를 설치하거나 전문가용 Unity+를 설치하려면 [Unity 다운로드](https://unity3d.com/get-unity/download)를 참조하세요. 필요한 경우 특정 플랫폼의 문서에서 Unity 지원을 확인하세요. 지원되는 최소 Unity 버전은 Unity 2017 LTS입니다.

* Unity 프로젝트 – 다음 중 하나일 수 있습니다.

  * 완전히 새로운 프로젝트: 자세한 내용은 [처음으로 Unity 시작](/services/playfab/sdks/unity3d/quickstart)을 참조하세요.
  * 가이드 자습서 프로젝트. 자세한 내용은 [Unity 시작하기](https://learn.unity.com/)를 참조하세요.
  * 기존 프로젝트.

* PlayFab "코어" Unity3D SDK(Multiplayer Unity 플러그인에도 포함되어 있음). Unity3D SDK 설치에 대한 자세한 내용은 [빠른 시작: Unity에서 C#용 PlayFab Client 라이브러리](/services/playfab/sdks/unity3d/quickstart#download-and-install-playfab-sdk)의 "PlayFab SDK 다운로드 및 설치" 섹션을 참조하세요.

## PlayFab Multiplayer Unity 플러그인 다운로드 및 설치

PlayFab Multiplayer Unity 플러그인을 다운로드하고 설치하는 단계를 따르세요.

1. PlayFab [Multiplayer Unity Plugin](https://github.com/PlayFab/PlayFabMultiplayerUnity) Asset Package를 다운로드합니다(플랫폼에 따라 배포 지점 사용).
2. **중요!** 플러그인과 함께 게시된 README 파일의 정보를 참조하세요. 각 특정 버전에 맞게 조정되어 있으며 플랫폼에 특정한 중요한 지침이 포함될 수 있습니다.
3. Unity 프로젝트를 엽니다.
4. .unitypackage를 저장한 위치로 이동하여 두 번 클릭하여 가져오기 대화 상자를 엽니다.
5. PlayFab Multiplayer Unity 플러그인을 프로젝트로 가져오려면 **Import**를 선택합니다.

참고: 필요한 경우 최신 버전의 PlayFab "코어" Unity SDK를 설치해야 할 수도 있습니다.

## 씬 설정

이 가이드 부분에서는 Unity에서 PlayFab Multiplayer API를 호출할 수 있도록 씬에 `PlayfabMultiplayerEventProcessor`를 추가하는 방법을 보여줍니다.

Multiplayer API를 사용하려면 먼저 **PlayFab 플레이어가 로그인되어 있어야 합니다**. 플레이어 로그인에 대한 자세한 내용은 [빠른 시작: Unity에서 C#용 PlayFab Client 라이브러리의 첫 API 호출 만들기](/services/playfab/sdks/unity3d/quickstart#making-your-first-api-call)를 참조하세요.

1. Unity 편집기의 Project 창에서 **Assets > PlayFabMultiplayerSDK > Prefabs**로 이동합니다.

2. Prefabs 폴더에서 **PlayfabMultiplayerEventProcessor**를 **Hierarchy** 창의 씬으로 끌어다 놓습니다.

3. 씬에 "HelloMultiplayerLogic"이라는 빈 Game Object를 만듭니다.

4. HelloMultiplayerLogic Game Object를 선택하여 **Inspector**를 엽니다.

5. **Add Component**를 선택합니다.

6. "HelloMultiplayerLogic"을 입력하고 Enter 키를 눌러 새 스크립트 메뉴를 표시합니다.

7. Enter 키를 다시 눌러 새 스크립트 HelloMultiplayerLogic.cs를 만듭니다.

8. **Project** 창에서 스크립트를 찾고 두 번 클릭하여 스크립트를 편집합니다.

9. 스크립트에 다음 using 문을 추가합니다.

   ```csharp theme={null}
   using PlayFab;
   using PlayFab.Multiplayer;
   using PlayFab.ClientModels;
   ```

10. PlayFab에 로그인하기 위해 Start 메서드에 다음 코드를 추가합니다.

    ```csharp theme={null}
    // Log into playfab
    var request = new LoginWithCustomIDRequest { CustomId = UnityEngine.Random.value.ToString(), CreateAccount = true };
    PlayFabClientAPI.LoginWithCustomID(request, OnLoginSuccess, OnLoginFailure);
    ```

11. 클래스에 다음 메서드를 추가합니다.

    ```csharp theme={null}
    private void OnLoginSuccess(LoginResult result)
    {
    }

    private void OnLoginFailure(PlayFabError error)
    {
    }
    ```

<Note>
  다음 오류가 표시될 수 있습니다: `C \# Error CS0227 Unsafe code may only appear if compiling with /unsafe The plugin requires unsafe code because it interops with a native DLL. Mismatch between the processor architecture of the project being built "MSIL" and the processor architecture of the reference "XGamingRuntime", "AMD64".`
</Note>

Microsoft GDK 및 Windows는 x64만 지원합니다.

이러한 문제를 해결하려면:

1. Unity Editor에서 **File > Build Settings**를 선택합니다.
2. 플랫폼을 선택합니다. 그런 다음 **Architecture** 드롭다운에서 x86\_64 또는 x64를 선택합니다.
3. **Player Settings**를 선택합니다.
4. 오른쪽 창에서 Other Setting을 선택합니다.
5. **Allow unsafe Code** 설정을 찾아 선택합니다.
6. **Build Settings** 및 **Project Settings** 창을 닫습니다.

## 로비 만들기 및 참여

이 가이드 부분에서는 로비를 만들고 참여하는 방법을 보여줍니다.

1. HelloMultiplayerLogic.cs 스크립트를 엽니다. `OnLoginSuccess` 메서드에서 로비를 만들고 참여하는 다음 코드를 추가합니다.

   ```csharp theme={null}
   string entityId = ...; // PlayFab user's entity Id
   string entityType = ...; // PlayFab user's entity type

   PlayFabMultiplayer.OnLobbyCreateAndJoinCompleted += this.PlayFabMultiplayer_OnLobbyCreateAndJoinCompleted;
   PlayFabMultiplayer.OnLobbyDisconnected += this.PlayFabMultiplayer_OnLobbyDisconnected;

   var createConfig = new LobbyCreateConfiguration()
   {
       MaxMemberCount = 10,
       OwnerMigrationPolicy = LobbyOwnerMigrationPolicy.Automatic,
       AccessPolicy = LobbyAccessPolicy.Public
   };

   createConfig.LobbyProperties["Prop1"] = "Value1";
   createConfig.LobbyProperties["Prop2"] = "Value2";

   var joinConfig = new LobbyJoinConfiguration();
   joinConfig.MemberProperties["MemberProp1"] = "MemberValue1";
   joinConfig.MemberProperties["MemberProp2"] = "MemberValue2";

   PlayFabMultiplayer.CreateAndJoinLobby(
       new PFEntityKey(
           entityId,
           entityType),
       createConfig,
       joinConfig);
   ```

2. OnLobbyCreateAndJoinCompleted 이벤트 핸들러를 정의하려면 클래스에 다음 코드를 추가합니다.

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyCreateAndJoinCompleted(Lobby lobby, int result)
   {
       if (LobbyError.SUCCEEDED(result))
       {
           // Lobby was successfully created
           Debug.Log(lobby.ConnectionString);
       }
       else
       {
           // Error creating a lobby
           Debug.Log("Error creating a lobby");
       }
   }
   ```

3. OnLobbyDisconnected 이벤트 핸들러를 정의하려면 클래스에 다음 코드를 추가합니다.

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyDisconnected(Lobby lobby)
   {
       // Disconnected from lobby
       Debug.Log("Disconnected from lobby!");
   }
   ```

4. Unity Editor에서 저장하고 Play를 선택합니다. 로비 연결 문자열이 Console 창에 표시됩니다.

## 로비 참여

이 가이드 부분에서는 다른 클라이언트가 만든 기존 로비에 참여하는 방법을 보여줍니다.

1. HelloMultiplayerLogic.cs 스크립트를 엽니다. OnLoginSuccess 메서드에서 로비에 참여하는 다음 코드를 추가합니다.

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key

   string connectionString = "<your lobby connection string>";

   PlayFabMultiplayer.JoinLobby(
           entityKey,
           connectionString,
           null);
   ```

2. 로컬 클라이언트가 로비에 참여할 때 실행되는 이벤트를 정의하려면 `OnLoginSuccess` 메서드에 다음 코드를 추가합니다.

   ```csharp theme={null}
   PlayFabMultiplayer.OnLobbyJoinCompleted += this.PlayFabMultiplayer_OnLobbyJoinCompleted;
   ```

3. OnLobbyJoinCompleted 이벤트 핸들러를 정의하려면 클래스에 다음 코드를 추가합니다.

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyJoinCompleted(Lobby lobby, PFEntityKey newMember, int reason)
   {
       if (LobbyError.SUCCEEDED(reason))
       {
           // Successfully joined a lobby
           Debug.Log("Joined a lobby");
       }
       else
       {
           // Error joining a lobby
           Debug.Log("Error joining a lobby");
       }
   }
   ```

4. Unity Editor에서 저장하고 Play를 선택합니다. "Joined a lobby" 문자열이 Console 창에 표시됩니다.

## 로비 찾기

이 가이드 부분에서는 다른 클라이언트가 만든 기존 로비를 찾는 방법을 보여줍니다.

1. HelloMultiplayerLogic.cs 스크립트를 엽니다. OnLoginSuccess 메서드에서 로비를 찾는 다음 코드를 추가합니다.

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key

   LobbySearchConfiguration config = new LobbySearchConfiguration();
   PlayFabMultiplayer.FindLobbies(entityKey, config);
   ```

2. 로컬 클라이언트가 로비를 찾을 때 실행되는 이벤트를 정의하려면 `OnLoginSuccess` 메서드에 다음 코드를 추가합니다.

   ```csharp theme={null}
   PlayFabMultiplayer.OnLobbyFindLobbiesCompleted += this.PlayFabMultiplayer_OnLobbyFindLobbiesCompleted;
   ```

3. OnLobbyFindLobbiesCompleted 이벤트 핸들러를 정의하려면 클래스에 다음 코드를 추가합니다.

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnLobbyFindLobbiesCompleted(
       IList<LobbySearchResult> searchResults, 
       PFEntityKey newMember, 
       int reason)
   {
       if (LobbyError.SUCCEEDED(reason))
       {
           // Successfully found lobbies
           Debug.Log("Found lobbies");

           // Iterate through lobby search results
           foreach (LobbySearchResult result in searchResults)
           {
               // Examine a search result
           }
       }
       else
       {
           // Error finding lobbies
           Debug.Log("Error finding lobbies");
       }
   }
   ```

4. Unity Editor에서 저장하고 Play를 선택합니다. "Found lobbies" 문자열이 Console 창에 표시됩니다.

## 매치메이킹 티켓 만들기

이 가이드 부분에서는 매치메이킹 티켓을 만드는 방법을 보여줍니다. 아래의 다른 클라이언트에서 "매치메이킹 티켓 참여" 시나리오와 함께 실행하세요.

1. HelloMultiplayerLogic.cs 스크립트를 엽니다. `OnLoginSuccess` 메서드에서 매치메이킹 티켓을 만드는 다음 코드를 추가합니다.

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key
   PFEntityKey remoteEntityKey = ...; // another PlayFab user's entity key
   string remoteUserAttributesJson = ...; // JSON string with another PlayFab user's attributes for matchmaking

   PlayFabMultiplayer.OnMatchmakingTicketStatusChanged += PlayFabMultiplayer_OnMatchmakingTicketStatusChanged;

   List<MatchUser> localUsers = new List<MatchUser>();
   localUsers.Add(new MatchUser(entityKey, remoteUserAttributesJson));

   List<PFEntityKey> membersToMatchWith = new List<PFEntityKey>();
   membersToMatchWith.Add(remoteEntityKey);

   PlayFabMultiplayer.CreateMatchmakingTicket(
       localUsers,
       "QuickMatchQueueName",
       membersToMatchWith);
   ```

2. OnMatchmakingTicketStatusChanged 이벤트 핸들러를 정의하려면 클래스에 다음 코드를 추가합니다.

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnMatchmakingTicketStatusChanged(MatchmakingTicket ticket)
   {
       // Store and print matchmaking ticket
       Debug.Log(ticket.TicketId);

       // Examine matchmaking ticket status
       Debub.Log(ticket.Status)

       // Share matchmaking ticket with other clients taking part in matchmaking

       // Examine ticket
   }
   ```

3. Unity Editor에서 저장하고 Play를 선택합니다.

membersToMatchWith가 지정되면, 하나의 OnMatchmakingTicketStatusChanged 이벤트 핸들러가 트리거되고 Status는 WaitingForPlayers가 됩니다. 이 경우, 다른 클라이언트가 JoinMatchmakingTicketFromId를 호출하면 새로운 OnMatchmakingTicketStatusChanged 이벤트 핸들러가 트리거되며 이번에는 status가 WaitingForMatch가 됩니다.

또는, 하나의 OnMatchmakingTicketStatusChanged 이벤트 핸들러가 트리거되고 status는 WaitingForMatch가 됩니다.

## 매치메이킹 티켓 참여

이 가이드 부분에서는 다른 클라이언트가 만든 기존 매치메이킹 티켓에 참여하는 방법을 보여줍니다. 위의 다른 클라이언트에서 "매치메이킹 티켓 만들기" 시나리오와 함께 실행하세요.

1. HelloMultiplayerLogic.cs 스크립트를 엽니다. OnLoginSuccess 메서드에서 매치메이킹 티켓에 참여하는 다음 코드를 추가합니다.

   ```csharp theme={null}
   PFEntityKey entityKey = ...; // PlayFab user's entity key
   string ticketId = ...; // Matchmaking ticket obtained from the client that created the ticket

   PlayFabMultiplayer.OnMatchmakingTicketCompleted += PlayFabMultiplayer_OnMatchmakingTicketStatusChanged;

   // Create JSON string with PlayFab user's attributes for matchmaking. This will need to be shared with other clients taking part in matchmaking
   string uniqueId = System.Guid.NewGuid().ToString();
   string userAttributesJson = "{\"MatchIdentifier\": \"" + uniqueId + "\"}";

   PlayFabMultiplayer.JoinMatchmakingTicketFromId(
       new MatchUser(entityKey, userAttributesJson),
       ticketId,
       "QuickMatchQueueName",
       new List<PFEntityKey>());
   ```

2. OnMatchmakingTicketStatusChanged 이벤트 핸들러를 정의하려면 클래스에 다음 코드를 추가합니다.

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnMatchmakingTicketStatusChanged(MatchmakingTicket ticket)
   {
       // Store and print matchmaking ticket
       Debug.Log(ticket.TicketId);

       // Examine matchmaking ticket status
       Debub.Log(ticket.Status)

       // Share matchmaking ticket with other clients taking part in matchmaking

       // Examine ticket
   }
   ```

3. Unity Editor에서 저장하고 Play를 선택합니다.

Status가 WaitingForMatch인 하나의 OnMatchmakingTicketStatusChanged가 트리거됩니다.

## 매치메이킹 티켓 완료

이 가이드 부분에서는 매치메이킹이 어떻게 완료되는지 보여줍니다. 위의 다른 클라이언트에서 "매치메이킹 티켓 만들기" 시나리오와 함께 실행하세요. 선택적으로, "매치메이킹 티켓 참여" 시나리오와 함께 실행할 수도 있습니다.

1. 동일한 큐의 여러 티켓이 매칭될 자격이 있으면 매치가 발견됩니다. 이 경우, OnMatchmakingTicketCompleted 이벤트 핸들러가 트리거됩니다.

2. OnMatchmakignTicketCompleted 핸들러를 구독합니다.

   ```csharp theme={null}
   PlayFabMultiplayer.OnMatchmakingTicketCompleted += PlayFabMultiplayer_OnMatchmakingTicketCompleted;
   ```

3. OnMatchmakingTicketCompleted 이벤트 핸들러를 정의하려면 클래스에 다음 코드를 추가합니다.

   ```csharp theme={null}
   private void PlayFabMultiplayer_OnMatchmakingTicketCompleted(MatchmakingTicket ticket, int result)
   {
       if (LobbyError.SUCCEEDED(result))
       {
           // Successfully completed matchmaking ticket
           Debug.Log("Completed matchmaking ticket");

           // Examine matchmaking details
           MatchmakingMatchDetails details = ticket.GetMatchDetails();
       }
       else
       {
           // Error completing a matchmaking ticket
           Debug.Log("Error completing a matchmaking ticket");
       }
   }
   ```


## Related topics

- [PlayFab Multiplayer Unity 플러그인 개요](/ko/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-overview.md)
- [Party Unity plugin quickstart](/ko/services/playfab/multiplayer/networking/party-unity-plugin-quickstart.md)
- [Integrate the PlayFab Unreal Engine Marketplace plugin](/ko/services/playfab/multiplayer/networking/party-unreal-engine-oss-playfab-plugin-integration.md)
- [Party Unity plugin overview](/ko/services/playfab/multiplayer/networking/party-unity-overview.md)
- [푸시 알림 빠른 시작](/ko/services/playfab/live-service-management/game-configuration/title-communications/push-notifications/quickstart.md)