> ## 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. # GDK를 커스텀 C/C++ 엔진에 통합 > GDK 기본 지원이 없는 C/C++ 엔진에 GDK, Gaming Runtime Services(GRTS), XSAPI를 통합해 PC용 Microsoft Store와 XBOX에 출시하세요. 이 항목은 Microsoft Store에 게임을 게시할 준비를 하고 있고, 게임이 GDK 기본 지원이 없는 C/C++ 기반 엔진을 사용하는 경우에 참고하세요. * [Partner Center에서 제품 만들기](#creating-a-product-in-partner-center) * [C/C++ 게임에 GDK 통합하기](#integrating-the-gdk-into-c-c-games) * [게임에서 XBOX 서비스 테스트하기](#testing-xbox-services-in-your-game) * [게시](#publishing) ## Partner Center에서 제품 만들기 Microsoft Store에 게임을 게시하려면 먼저 Partner Center에서 XBOX 서비스가 활성화된 제품을 생성해야 합니다. Partner Center에 대한 자세한 내용은 [Managed Partner를 위한 Partner Center에서 앱 또는 게임 설정](https://learn.microsoft.com/gaming/gdk/_content/gc/services/fundamentals/portal-config/live-setup-partner-center-partners)을 참조하세요. ## C/C++ 게임에 GDK 통합하기 GDK를 C/C++ 게임에 통합하려면 게임에는 네 가지가 필요합니다. 1. API 시그니처와 데이터 구조를 기술하는 GDK 및 XBOX Services API(XSAPI) *헤더*. 2. 내보낸 GDK 함수에 대한 외부 참조를 링커가 해결할 수 있게 하는 *임포트 라이브러리*. 3. 내보낸 XSAPI DLL 함수에 대한 외부 참조를 링커가 해결할 수 있게 하는 XSAPI 정적 라이브러리 또는 *임포트 라이브러리*. * XSAPI는 정적 및 동적 형태 모두로 제공됩니다. 자세한 내용은 아래 표를 참조하고 정적 또는 동적 중에서 선택하세요. 4. GDK와 XSAPI 함수의 실제 런타임 구현을 포함하는 *동적 링크 라이브러리*(XSAPI의 동적 버전을 사용하는 경우). 게임이 필수적인 XBOX 생태계 경험과 통합되려면 두 가지 구성 요소(Gaming Runtime Services(GRTS)와 XSAPI)와 상호작용해야 합니다. 관리되지 않는 게임에 필요한 파일은 다음과 같습니다. | 구성 요소 | GRTS (동적 전용) | XSAPI (동적) | XSAPI (정적) | | ----------- | ----------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------ | | 헤더 | GRTS 헤더: XUser, XGameSave, XGameUI 등(GDK) | XSAPI 헤더: profile\_c.h, achievements\_c.h 등(GDK) | XSAPI 헤더: profile\_c.h, achievements\_c.h 등(GDK) | | 임포트 라이브러리 | xgameruntime.lib (GDK) | Microsoft.Xbox.Services.GDK.C.Thunks.lib (GDK) | Microsoft.Xbox.Services.142.GDK.C.lib (GDK) | | 동적 링크 라이브러리 | xgameruntime.dll 및 몇 개의 dll(GRTS가 system32에 설치) | Microsoft.Xbox.Services.GDK.C.Thunks.dll(GDK, 게임 패키지에 포함 필요) | 필요 없음 | 기능이 여러 DLL에 분산된 플러그인 기반 아키텍처를 사용하는 게임의 경우, `Thunks.dll`을 이용해 XSAPI를 통합하는 것을 권장하며 이를 지원합니다. 이 방식은 PC와 XBOX 플랫폼 모두에서 안정적으로 동작합니다. XSAPI를 여러 DLL에 정적으로 링크하면 각 DLL은 자기만의 전역 상태 복사본을 유지합니다. 그 결과 어느 한 DLL에서 `XblInitialize`를 호출해도 다른 DLL에서 XSAPI가 초기화되지 않습니다. 서로 다른 정적 인스턴스를 가진 DLL 간에 XSAPI 핸들을 공유하면 크래시나 예측 불가한 동작이 발생할 수 있습니다. `Thunks.dll`은 XSAPI와 그 상태의 단일 공유 인스턴스를 제공해 이 문제를 해결합니다. 중복을 피하고 모든 DLL에서 일관된 동작을 보장합니다. 기술적으로는 XSAPI를 하나의 DLL에 정적으로 링크하고 심볼을 내보내는 것도 가능하지만, 이 방식은 더 복잡하고 오류가 나기 쉽습니다. `Thunks.dll`을 사용하는 것이 더 간단하고 안전하며 완전히 지원됩니다. ### 프로젝트에 Gaming Runtime Services와 XSAPI 요구 사항 추가 다음 단계는 Gaming Runtime Services와 XSAPI를 사용하기 위한 모든 요구 사항이 프로젝트에 갖추어지도록 하기 위한 변경 사항을 개략적으로 설명합니다. 1. x64를 타깃으로 하는지 확인합니다. Visual Studio에서는 **Build**->**Configuration Manager**로 이동해 **Active solution platform**을 x64로 설정합니다. 2. 다음 include 경로를 추가합니다. `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Include` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Include` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Include` 여기서 **GDK version number**는 릴리스의 연도, 월, 하위 버전 번호로 명명된 디렉터리입니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다. Microsoft GDK(2024년 6월) 또는 이전 버전의 경우 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include* 와 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include* 를 사용하세요. Visual Studio에서는 프로젝트 속성 페이지의 **Configuration Properties**->**VC++ Directories**->**Include Directories**에서 이 경로들을 추가합니다. 3. 임포트 라이브러리를 위한 다음 라이브러리 경로를 추가합니다. `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64` 여기서 **GDK version number**는 릴리스의 연도, 월, 하위 버전 번호로 명명된 디렉터리입니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다. Microsoft GDK(2024년 6월) 또는 이전 버전의 경우 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release* 와 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib* 를 사용하세요. Visual Studio에서는 프로젝트 속성 페이지의 **Configuration Properties**->**VC++ Directories**->**Library Directories**에서 이 경로들을 추가합니다. 4. 프로젝트에 링크되는 라이브러리 목록에 다음 라이브러리를 추가합니다. `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64\xgameruntime.lib` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (정적 링크 시 Microsoft.Xbox.Services.142.GDK.C.lib)` `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib` 여기서 **GDK version number**는 릴리스의 연도, 월, 하위 버전 번호로 명명된 디렉터리입니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다. Microsoft GDK(2024년 6월) 또는 이전 버전의 경우 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (정적 링크 시 Microsoft.Xbox.Services.142.GDK.C.lib)* 와 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib* 를 사용하세요. Visual Studio에서는 프로젝트 속성 페이지의 **Configuration Properties**->**Linker**->**Input**->**Additional Dependencies**에서 라이브러리를 추가합니다. 5. *\_GAMING\_DESKTOP* 과 *WINAPI\_FAMILY=WINAPI\_FAMILY\_DESKTOP\_APP* 을 정의합니다. Visual Studio에서는 프로젝트 속성 페이지의 **C/C++**->**Command Line**->**Additional Options**에 다음 줄을 추가합니다. `/D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"` 6. MicrosoftGame.config 파일을 만들고 빌드 시 .exe와 동일한 대상 위치에 복사되도록 합니다. **참고:** 엔진이 실행 시 다른 .exe를 사용하는 에디터 내 실행(run-in-editor) 기능을 지원한다면 해당 .exe와 동일한 디렉터리에도 MicrosoftGame.config가 복사되도록 해야 합니다. MicrosoftGame.config가 .exe와 동일한 디렉터리에 없다면 에디터 내 실행 기능 사용 시 XBOX 서비스가 작동하지 않습니다. 개발을 시작할 때는 아래 예시와 같이 기본값을 가진 설정을 사용할 수 있습니다. Identity Name, Executable Name, Executable Alias의 값은 모두 여러분의 실행 파일 이름으로 교체됩니다. ```xml theme={null} ``` 7. **Microsoft.Xbox.Services.GDK.C.Thunks.dll**(동적으로 링크한 경우), **XCurl.dll**, **libHttpClient.GDK.dll** 사본이 빌드 시 .exe와 동일한 대상 위치에 복사되도록 하세요. **참고:** 엔진이 실행 시 다른 .exe를 사용하는 에디터 내 실행 기능을 지원한다면 해당 .exe가 이 .dll들을 참조하도록 해야 합니다. .dll들이 .exe에 의해 참조되지 않으면 에디터 내 실행 기능 사용 시 XBOX 서비스가 작동하지 않습니다. XSAPI에 동적으로 링크하는 경우 **Microsoft.Xbox.Services.GDK.C.Thunks.dll**은 GDK 설치의 다음 디렉터리에서 찾을 수 있습니다. `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release]` **XCurl.dll**은 GDK 설치의 다음 디렉터리에서 찾을 수 있습니다. `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64` **libHttpClient.GDK.dll**은 GDK 설치의 다음 디렉터리에서 찾을 수 있습니다. `C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\x64` 여기서 **GDK version number**는 릴리스의 연도, 월, 하위 버전 번호로 명명된 디렉터리입니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다. Microsoft GDK(2024년 6월) 또는 이전 버전의 경우 *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\\\[Debug|Release]*, *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral*, *C:\Program Files (x86)\Microsoft GDK\\\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral* 을 사용하세요. 또는 GDK를 기존 Visual Studio Desktop 프로젝트에 통합하는 경우에는 이 항목의 단계를 따라 프로젝트를 GDK 프로젝트로 변환할 수 있습니다. [기존 데스크톱 프로젝트에 Microsoft Game Development Kit 추가](https://learn.microsoft.com/gaming/gdk/_content/gc/gdk-dev/pc-dev/overviews/gr-add-to-existing-project). ### MicrosoftGame.config 업데이트 이전 단계에서 생성한 MicrosoftGame.config 파일은 Gaming Runtime, Microsoft Store, 타이틀 신원 관련 기능을 사용하기 전까지는 추가 구성 없이 PC와 XBOX에서 초기 개발이 가능한 기본값을 가지고 있습니다. XBOX 서비스 기능을 사용하려면 프로젝트의 MicrosoftGame.config를 Partner Center 프로젝트의 신원 세부 정보로 업데이트해야 합니다. 1. [Partner Center 대시보드](https://partner.microsoft.com/dashboard/windows/overview)로 이동합니다. 2. 제품 목록에서 게임을 선택합니다. 3. **Game setup** 탭을 선택한 다음 **Identity details**를 선택합니다. 4. **Show Details**를 선택해 **Identity details** 섹션을 확장합니다. 5. **Identity details** 섹션의 표에서 다음 값을 사용해 Partner Center의 값을 MicrosoftGame.config의 해당 요소와 필드로 복사합니다. | Partner Center의 이름 | MicrosoftGame.config | | ------------------------------------------ | -------------------- | | XBOX Title ID | TitleId | | Package/Identity/Name | Identity->Name | | Package/Identity/Publisher | Identity->Publisher | | XBOX services -> XBOX Settings -> MSAAppId | MSAAppId | 예를 들어 Partner Center의 다음과 같은 신원 세부 정보는 MicrosoftGame.config를 아래 샘플과 같이 만듭니다. | Partner Center의 이름 | 예시 값 | | ------------------------------------------ | --------------------------------------- | | XBOX Title ID | 64353034 | | Package/Identity/Name | 41336MicrosoftATG.Achievements2017Redux | | Package/Identity/Publisher | CN=A4954634-DF4B-47C7-AB70-D3215D246AF1 | | XBOX services -> XBOX Settings -> MSAAppId | 0000000000000000 | ```xml theme={null} 64353034 0000000000000000 ``` MicrosoftGame.config의 값에 대한 추가 정보는 [MicrosoftGame.config 개요](https://learn.microsoft.com/gaming/gdk/_content/gc/features/common/game-config/MicrosoftGameConfig-Overview)를 참조하세요. ### 게임 런타임과 XSAPI 초기화 다음 단계는 게임에서 Gaming Runtime Services와 XSAPI를 초기화하는 방법을 보여줍니다. 1. XGameRuntime 헤더와 XSAPI services-c 헤더를 포함합니다. ```cpp theme={null} #include #include ``` 2. [XGameRuntimeInitialize](https://learn.microsoft.com/gaming/gdk/_content/gc/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize)를 호출해 GDK 런타임을 초기화합니다. ```cpp theme={null} // GameRuntime 초기화 HRESULT hr = XGameRuntimeInitialize(); if (FAILED(hr)) { if (hr == E_GAMERUNTIME_DLL_NOT_FOUND || hr == E_GAMERUNTIME_VERSION_MISMATCH) { (void)MessageBoxW(nullptr, L"Game Runtime is not installed on this system or needs updating.", g_szAppName, MB_ICONERROR | MB_OK); } return 1; } ``` 3. [XblInitialize](https://learn.microsoft.com/gaming/gdk/_content/gc/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize)를 호출해 XSAPI를 초기화합니다. ```cpp theme={null} XblInitArgs xblArgs = {}; //xblArgs.queue = queue; // 직접 XTaskQueue를 생성하도록 선택한 경우 이 줄의 주석을 해제하세요. 그렇지 않으면 기본적으로 이 줄은 필요하지 않습니다. xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Partner Center 프로젝트의 scid를 여기에 추가하세요. HRESULT hr = XblInitialize(&xblArgs); if (FAILED(hr)) { // 실패 처리 } ``` ### 게임 런타임 해제 Gaming Runtime Services는 게임이 종료되기 전에 해제되어야 합니다. XSAPI는 종료 전에 명시적으로 정리할 필요가 없습니다. [XGameRuntimeUninitialize](https://learn.microsoft.com/gaming/gdk/_content/gc/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize)를 호출해 GDK 런타임을 해제합니다. ```cpp theme={null} // 다른 모든 활동이 완료된 후 // Gaming Runtime 해제. XGameRuntimeUninitialize(); ``` 게임에서 XSAPI를 사용하는 자세한 개요는 [XBOX 서비스 API 시작하기](https://learn.microsoft.com/gaming/gdk/_content/gc/services/fundamentals/xbox-services-api/live-gs-xbl-apis)를 참조하세요.
GDK 기능 구현 개요는 [Game Development Kit(GDK) 기능](https://learn.microsoft.com/gaming/gdk/_content/gc/features/features-index)을 참조하세요. ## 게임에서 XBOX 서비스 테스트하기 게임에서 업적과 같은 XBOX 서비스 기능을 테스트하려면 샌드박스와 해당 샌드박스에 접근할 수 있는 테스트 계정을 사용해야 합니다. ### 테스트 계정 만들기 게임에서 XBOX 서비스 기능을 테스트하려면 개발 샌드박스에 접근할 수 있는 테스트 계정을 만들어야 합니다. 테스트 계정 생성에 대한 자세한 내용은 [테스트 계정 만들기](https://learn.microsoft.com/gaming/gdk/_content/gc/services/develop/test-accounts/live-setup-testaccounts)를 참조하세요. ### 샌드박스 전환 테스트 계정을 만든 후에는 다음 단계를 사용해 샌드박스에 접근하세요. 1. 샌드박스 ID를 찾으려면 [Partner Center](https://partner.microsoft.com/dashboard/windows/overview)로 이동합니다. 2. **XBOX services**를 선택한 다음 **Gameplay Settings**를 선택합니다. 샌드박스 ID는 첫 번째 탭에 있으며 “ABCDEF.0”과 같은 형태로 이름 지어져 있습니다. 3. **시작** 메뉴를 엽니다. 4. **Microsoft GDK Command Prompts**를 입력한 다음 키보드에서 **Enter**를 누릅니다. 5. 첫 번째 명령 프롬프트를 엽니다. 6. 명령 프롬프트에서 **XblPCSandbox.exe \[샌드박스 ID]** 를 입력합니다. 7. 명령 프롬프트가 여러 앱을 실행한 후 XBOX 앱에 테스트 계정으로 로그인합니다. 성공적으로 로그인할 수 있다면 테스트 계정을 만들고 샌드박스로 전환해 테스트를 시작할 수 있습니다. 샌드박스에 대한 자세한 내용은 [XBOX 서비스 샌드박스 개요](https://learn.microsoft.com/gaming/gdk/_content/gc/services/fundamentals/sandboxes/live-setup-sandbox)를 참조하세요. ## 게시 게임을 게시할 준비를 하려면 다음이 필요합니다. * 게임을 GDK와 통합하는 작업을 완료했어야 합니다. * [MSIXVC 패키징 도구로 PC용 타이틀 패키징 시작하기](https://learn.microsoft.com/gaming/gdk/_content/gc/features/common/packaging/overviews/packaging-getting-started-for-PC)의 단계를 따라 게임 패키지를 만들었어야 합니다. 두 가지 요구 사항을 완료한 후에는 게시할 준비가 된 것입니다. 게임을 제출하려면 [Partner Center](https://partner.microsoft.com/dashboard/windows/overview)로 이동해 UI의 지침을 따르세요. ## Related topics - [Godot & 커뮤니티 엔진 개요](/ko/paths/community-engines/overview.md) - [Unity, Unreal 및 기타 엔진과 함께 GDK 사용](/ko/build/gdk-and-engines/gdk-and-engines.md) - [포팅 개요](/ko/paths/porting/overview.md) - [PC 엔드투엔드 개요](/ko/build/gdk-and-engines/overview.md) - [GDK용 PlayFab Services](/ko/services/playfab/sdks/platforms/gdk.md)