> ## 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.

# 빠른 시작 (Windows) - Party 및 Multiplayer

> PlayFab 통합 SDK를 사용하여 Windows에서 PlayFab Party 음성, 채팅, 네트워킹을 PlayFab Multiplayer 로비 및 매치메이킹과 통합합니다.

이 가이드에서는 통합 SDK를 사용하여 음성, 채팅, 데이터 네트워킹을 위한 PlayFab Party 및 로비와 매치메이킹 서비스를 위한 PlayFab Multiplayer를 통합하는 방법을 안내합니다.

## 필수 조건

시작하기 전에 다음을 준비했는지 확인하세요:

* [Core SDK 설정 및 인증](/services/playfab/sdks/unified-sdk/quickstart-core) 완료
* 로그인 프로세스에서 인증된 `PFEntityHandle`
* Game Manager에서 구성된 PlayFab 타이틀 ID
* 비동기 프로그래밍 패턴에 대한 기본 지식

<Note>
  이 가이드는 [Core 빠른 시작 가이드](/services/playfab/sdks/unified-sdk/quickstart-core)에 따라 이미 PlayFab SDK를 초기화하고 플레이어를 인증했다고 가정합니다. 아직 완료하지 않았다면, 먼저 해당 가이드를 완료하세요.
</Note>

## 달성하게 될 내용

이 빠른 시작이 끝나면 다음을 완료하게 됩니다:

* 네트워킹 및 채팅을 위한 PlayFab Party 초기화
* 로컬 사용자 및 채팅 컨트롤 생성
* 통신을 위한 Party 네트워크 설정
* PlayFab Multiplayer 초기화 및 로비 생성
* Party 및 Multiplayer 리소스에 대한 정리 절차 이해

## 헤더 및 포함

### 필수 헤더

PlayFab Party 및 Multiplayer 기능에 액세스하려면 헤더 파일에 SDK 헤더를 포함하세요:

```cpp theme={null}
#include <Party.h>
#include <Party_c.h>

#include <PFMultiplayer.h>
#include <PFLobby.h>

#include <playfab/services/PFServices.h>
```

### 구현 파일

구현 파일에 **PartyImpl.h**를 포함하고 Party 네임스페이스를 사용하세요:

```cpp theme={null}
#include <PartyImpl.h>

using namespace Party;
```

## 1단계: PlayFab Party 초기화

`PartyManager`에 대한 싱글톤 참조를 만들고, 타이틀 ID와 고급 스레드 제어를 위한 선택적 작업 큐로 구성하여 PlayFab Party를 초기화합니다.

```cpp theme={null}
PartyManager& partyManager = PartyManager::GetSingleton();
PartyInitializationConfiguration partyInitConfig = {};
PartyError err;

partyInitConfig.titleId = (PartyString) m_titleId; // Your PlayFab Title ID
partyInitConfig.audioTaskQueue = nullptr; // Optional: Custom XTaskQueue for audio operations, or nullptr for default
partyInitConfig.networkingTaskQueue = nullptr; // Optional: Custom XTaskQueue for networking operations, or nullptr for default

err = partyManager.Initialize(&partyInitConfig);
if (PARTY_FAILED(err))
{
    std::wcerr << L"Failed to initialize PartyManager: 0x" << std::hex << err << std::endl;
    return err;
}

std::wcout << L"PartyManager initialized successfully" << std::endl;
```

<Tip>
  `audioTaskQueue` 및 `networkingTaskQueue` 매개변수를 통해 사용자 정의 XTaskQueue 인스턴스를 제공하여 스레딩에 대한 세밀한 제어를 할 수 있습니다. 기본 스레딩 동작을 사용하려면 `nullptr`로 설정하세요.
</Tip>

## 2단계: 로컬 사용자 생성

디바이스에서 인증된 플레이어를 나타내는 로컬 사용자 개체를 만듭니다. 이 사용자는 모든 네트워킹 및 채팅 작업에 필요합니다.

```cpp theme={null}
PartyLocalUser* localUser{};
PartyError userErr;

// Use the entityHandle obtained from authentication
userErr = partyManager.CreateLocalUser(entityHandle, &localUser);
if (PARTY_FAILED(userErr))
{
    std::wcerr << L"Failed to create local user: 0x" << std::hex << userErr << std::endl;
    return userErr;
}

std::wcout << L"Local user created successfully" << std::endl;
```

## 3단계: 채팅 컨트롤 생성

이 디바이스에서 사용자의 음성 및 텍스트 채팅 작업을 관리하기 위한 채팅 컨트롤을 만듭니다.

```cpp theme={null}
PartyLocalDevice* localDevice;
PartyError deviceErr = partyManager.GetLocalDevice(&localDevice);
if (PARTY_FAILED(deviceErr))
{
    std::wcerr << L"Failed to get local device: 0x" << std::hex << deviceErr << std::endl;
    return deviceErr;
}

PartyLocalChatControl* chatControl;
PartyError chatErr = localDevice->CreateChatControl(localUser, nullptr, nullptr, &chatControl);
if (PARTY_FAILED(chatErr))
{
    std::wcerr << L"Failed to create chat control: 0x" << std::hex << chatErr << std::endl;
    return chatErr;
}

std::wcout << L"Chat control created successfully" << std::endl;
```

채팅 컨트롤은 오디오 입출력을 처리하고 음성 통신 기능을 활성화합니다.

## 4단계: Party 네트워크 생성

Party 네트워크(채팅 및 데이터를 교환할 수 있는 디바이스와 사용자의 보안 컬렉션)를 생성합니다. Party 네트워크는 일반적으로 게임의 멀티플레이어 세션이나 로비 개념과 일치합니다.

```cpp theme={null}
PartyNetworkDescriptor networkDescriptor = {};
PartyNetworkConfiguration networkConfiguration = {};

// Configure network limits
networkConfiguration.directPeerConnectivityOptions = PartyDirectPeerConnectivityOptions::None;
networkConfiguration.maxDeviceCount = 8;
networkConfiguration.maxDevicesPerUserCount = 1;
networkConfiguration.maxEndpointsPerDeviceCount = 1;
networkConfiguration.maxUserCount = 8;
networkConfiguration.maxUsersPerDeviceCount = 1;

// Configure invitation settings
PartyInvitationConfiguration invitationConfiguration = {
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", // Unique network identifier (generate a GUID)
    PartyInvitationRevocability::Anyone,
    0,
    nullptr
};

PartyError networkErr = partyManager.CreateNewNetwork(
    localUser,
    &networkConfiguration,
    0,
    nullptr,
    &invitationConfiguration,
    nullptr,
    &networkDescriptor,
    nullptr);

if (PARTY_FAILED(networkErr))
{
    std::wcerr << L"Failed to create Party network: 0x" << std::hex << networkErr << std::endl;
    return networkErr;
}

std::wcout << L"Party network created successfully" << std::endl;
```

<Info>
  `PartyInvitationConfiguration`에 유효하고 고유한 네트워크 식별자(GUID)를 제공해야 합니다. 이 ID는 다른 플레이어가 네트워크에 참여할 때 사용됩니다.
</Info>

🎉 **축하합니다!** PlayFab Party 네트워킹 및 채팅을 성공적으로 설정했습니다.

## 5단계: PlayFab Multiplayer 초기화

로비 및 매치메이킹 기능을 활성화하기 위해 PlayFab Multiplayer 서비스를 초기화합니다.

```cpp theme={null}
PFMultiplayerHandle pfmHandle{};
MultiplayerInitializationConfiguration multiplayerInitConfig{};

multiplayerInitConfig.titleId = m_titleId; // Your PlayFab Title ID

HRESULT hr = PFMultiplayerInitialize(&multiplayerInitConfig, &pfmHandle);
if (FAILED(hr))
{
    std::wcerr << L"Failed to initialize Multiplayer: 0x" << std::hex << hr << std::endl;
    return hr;
}

std::wcout << L"PlayFab Multiplayer initialized successfully" << std::endl;
```

## 6단계: 로비 생성

매치를 시작하기 전에 플레이어 그룹을 관리하기 위한 로비를 만듭니다. 로비는 소유자 마이그레이션 및 액세스 제어와 같은 기능을 지원합니다.

```cpp theme={null}
PFLobbyCreateConfiguration lobbyConfiguration{};
lobbyConfiguration.maxMemberCount = 8;
lobbyConfiguration.ownerMigrationPolicy = PFLobbyOwnerMigrationPolicy::Automatic;
lobbyConfiguration.accessPolicy = PFLobbyAccessPolicy::Private;

PFLobbyJoinConfiguration memberConfiguration{};

PFLobbyHandle lobby;
HRESULT hr = PFMultiplayerCreateAndJoinLobbyWithEntityHandle(
    pfmHandle,
    entityHandle,
    &lobbyConfiguration,
    &memberConfiguration,
    nullptr,
    &lobby);

if (FAILED(hr))
{
    std::wcerr << L"Failed to create and join lobby: 0x" << std::hex << hr << std::endl;
    return hr;
}

std::wcout << L"Lobby created and joined successfully" << std::endl;
```

🎉 **훌륭합니다!** 이제 Party 네트워킹과 Multiplayer 로비 서비스를 모두 설정했습니다.

## 리소스 정리

게임이 종료되거나 PlayFab 리소스를 정리해야 할 때, 올바른 순서로 적절한 정리를 보장하세요:

```cpp theme={null}
// Clean up Party singleton
partyManager.Cleanup();

// Clean up Multiplayer handle
PFMultiplayerUninitialize(pfmHandle);

// Close entity handle
PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;

// Close service config handle
PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

// Uninitialize PlayFab Services
XAsyncBlock asyncBlock{};
HRESULT hr = PFServicesUninitializeAsync(&asyncBlock);
if (SUCCEEDED(hr))
{
    hr = XAsyncGetStatus(&asyncBlock, true); // Blocking wait for cleanup completion
}
```

<Info>
  리소스는 항상 다음 순서로 정리하세요: Party, Multiplayer, 엔티티 핸들, 서비스 구성, 그다음 PlayFab Services.
</Info>

## 다음 단계

이제 Party 및 Multiplayer를 설정했으므로, 다음 추가 기능들을 살펴보세요:

### Party 네트워킹 기능

* **음성 채팅** - Azure Cognitive Services 통합으로 실시간 음성 통신 활성화
* **텍스트 채팅** - 번역 및 조정과 함께 텍스트 메시징 구현
* **데이터 채널** - 플레이어 간 사용자 정의 게임 데이터 전송
* **네트워크 관리** - 플레이어 연결, 연결 해제 및 네트워크 이벤트 처리

### Multiplayer 로비 기능

* **매치메이킹 통합** - PlayFab 매치메이킹과 로비 연결
* **로비 속성** - 게임 설정 및 메타데이터 저장 및 동기화
* **멤버 데이터** - 로비 내에서 플레이어별 정보 공유
* **검색 및 검색** - 공개 로비 찾기 및 참여

### 핵심 개념

* [비동기 작업](/services/playfab/sdks/unified-sdk/async-model) - PlayFab의 비동기 프로그래밍 모델 이해
* [메모리 관리](/services/playfab/sdks/unified-sdk/memory-management) - SDK 메모리 관리를 위한 모범 사례
* [추적 및 진단](/services/playfab/sdks/unified-sdk/debug-trace) - 통합 디버깅 및 모니터링

## 참조 문서

* [PlayFab Party SDK 문서](/services/playfab/multiplayer/networking/party-sdks/overview)
* [PlayFab Multiplayer SDK 문서](/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-sdks)


## Related topics

- [Windows용 C++ 빠른 시작](/ko/services/playfab/sdks/playfab-cpp/quickstart-windows.md)
- [PlayFab 통합 SDK 빠른 시작 설정](/ko/services/playfab/sdks/unified-sdk/quickstart-setup.md)
- [Photon 빠른 시작](/ko/services/playfab/live-service-management/service-gateway/add-ons/photon/quickstart.md)
- [빠른 시작 (Windows) - Core SDK 설정](/ko/services/playfab/sdks/unified-sdk/quickstart-core.md)
- [Lobby SDK 빠른 시작](/ko/services/playfab/multiplayer/lobby/lobby-getting-started.md)