PC용 C/C++ 사용자 지정 엔진 통합: 시작하기

아티클
11/06/2024

PC의 Microsoft Store에 게시하기 위해 게임을 준비 중이고 게임에서 GDK에 대한 지원이 기본 제공되지 않은 C/C++ 기반 엔진을 사용하는 경우 이 항목을 사용하세요.

파트너 센터에서 제품 만들기
GDK를 C/C++ 게임에 통합
게임에서 Xbox 서비스 테스트
게시

파트너 센터에서 제품 만들기

Microsoft Store에 게임을 게시하려면 먼저 파트너 센터에서 Xbox 서비스 지원 제품을 만들어야 합니다. 파트너 센터에 대한 자세한 내용은 관리 파트너를 위해 파트너 센터에서 앱 또는 게임 설정을 참조하세요.

GDK를 C/C++ 게임에 통합

GDK를 C/C++ 게임에 통합하려면 게임에 3가지가 필요합니다.

API 서명 및 데이터 구조를 설명하는 GDK 및 XSAPI(Xbox Services API) 헤더
내보낸 GDK 및 XSAPI DLL 함수에 대한 외부 참조를 해결하는 방법을 링커에 알려주는 가져오기 라이브러리
실제로 GDK 및 XSAPI 함수의 런타임 구현을 포함하는 동적 링크 라이브러리

게임이 필수 Xbox 에코시스템 환경과 통합되려면 GRTS(게이밍 런타임 서비스) 및 XSAPI라는 두 가지 구성 요소와 상호 작용해야 합니다. 다음은 관리되지 않는 게임에 필요한 파일입니다.

구성 요소	GRTS	XSAPI
헤더	GRTS 헤더: XUser, XGameSave, XGameUI 등(GDK에서)	XSAPI 헤더: profile_c.h, achievements_c.h 등 (GDK에서)
라이브러리 가져오기	xgameruntime.lib(GDK에서)	Microsoft.Xbox.Services.GDK.C.Thunks.lib (GDK에서)
동적 링크 라이브러리	xgameruntime.dll 및 기타 몇 가지 dll(GRTS에서 설치한 system32)	Microsoft.Xbox.Services.GDK.C.Thunks.dll(GDK에서 게임 패키지에 포함되어야 함)

프로젝트에 게임 런타임 서비스 및 XSAPI에 대한 요구 사항 추가

다음 단계에서는 게임 런타임 서비스 및 XSAPI를 사용하기 위한 모든 요구 사항이 있는지 확인하기 위해 프로젝트에 적용해야 하는 변경 사항을 간략하게 설명합니다.

x64가 대상으로 지정되어 있는지 확인하세요.

Visual Studio에서 빌드->Configuration Manager로 이동하여 활성 솔루션 플랫폼을 x64로 설정합니다.
다음 포함 경로를 추가합니다.

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 버전 번호는 릴리스의 연도, 월 및 하위 버전 번호로 명명된 디렉터리가 됩니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다.

Microsoft GDK(2024년 6월) 이하의 경우 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include 사용 및 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include

Visual Studio에서는 구성 속성->VC++ 디렉터리->디렉터리 포함 아래의 프로젝트 속성 페이지에 이러한 경로를 추가합니다.
가져오기 라이브러리에 대해 다음 라이브러리 경로를 추가합니다.

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 버전 번호는 릴리스의 연도, 월 및 하위 버전 번호로 명명된 디렉터리가 됩니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다.

Microsoft GDK(2024년 6월) 이하의 경우 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\ 를 사용합니다. 릴리스 및 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib

Visual Studio에서는 구성 속성->VC++ 디렉터리->라이브러리 디렉터리 아래의 프로젝트 속성 페이지에 이러한 경로를 추가합니다.
프로젝트에 연결된 라이브러리 목록에 다음 라이브러리를 추가합니다.

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

C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib

여기서 GDK 버전 번호는 릴리스의 연도, 월 및 하위 버전 번호로 명명된 디렉터리가 됩니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다.

Microsoft GDK(2024년 6월) 이하의 경우 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.Th 사용unks.lib 및 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib

Visual Studio에서 구성 속성->링커->입력->추가 종속성 아래의 프로젝트 속성 페이지에 라이브러리를 추가합니다.
_GAMING_DESKTOP 및 WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP를 정의합니다.

Visual Studio에서 프로젝트 속성 페이지의 C/C++->명령줄->추가 옵션 아래에 다음 줄을 추가합니다.

/D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"

MicrosoftGame.config 파일을 만들고 빌드하는 동안 .exe와 동일한 대상에 복사되었는지 확인합니다.

참고: 엔진에서 실행할 때 다른 .exe를 사용하는 모든 종류의 실행 편집기 기능을 지원하는 경우 MicrosoftGame.config를 해당 .exe와 동일한 디렉터리에 복사해야 합니다. Microsoft Game.config가 .exe와 동일한 디렉터리에 없으면 실행 편집기 기능을 사용할 때 Xbox 서비스가 작동하지 않습니다.

개발을 시작하기 위해 다음 예제와 같이 기본값이 있는 구성을 사용할 수 있습니다. ID 이름, 실행 파일 이름 및 실행 파일 별칭에 대한 값은 모두 실행 파일의 이름으로 바뀝니다.

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

<Identity Name="Direct3DGame1_test"
            Publisher="CN=Publisher"
            Version="1.0.0.0"/>

<ExecutableList>
    <Executable Name="Direct3DGame1_test.exe"
                Id="Game"
                Alias="Direct3DGame1_test.exe"/>
</ExecutableList>

<ShellVisuals DefaultDisplayName="Direct3DGame1_test"
                PublisherDisplayName="PublisherName"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="Direct3DGame1_test"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>
</Game>

Microsoft.Xbox.Services.GDK.C.Thunks.dll,XCurl.dll및 libHttpClient.GDK.dll 복사본이 빌드 중에 .exe 동일한 대상으로 복사되었는지 확인합니다.

참고: 엔진에서 실행할 때 다른 .exe를 사용하는 편집기의 실행 기능을 지원하는 경우 .exe가 이러한 .dls도 참조하는지 확인해야 합니다. .dlls가 .exe에서 참조되지 않으면 실행 편집기 기능을 사용할 때 Xbox 서비스가 작동하지 않습니다.

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 버전 번호는 릴리스의 연도, 월 및 하위 버전 번호로 명명된 디렉터리가 됩니다. 예를 들어 2022년 6월 GDK의 경우 디렉터리 이름은 220600입니다.

Microsoft GDK(2024년 6월) 이하의 경우 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\[Debug|릴리스], C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral, 및 C:\Program Files (x86)\Microsoft GDK\[GDK 버전 번호]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral

참고 항목

또는 GDK를 기존 Visual Studio 데스크톱 프로젝트에 통합하는 경우 Microsoft 게임 개발 키트를 기존 데스크톱 프로젝트에 추가하기 항목의 단계에 따라 프로젝트를 GDK 프로젝트로 변환할 수 있습니다.

MicrosoftGame.config 업데이트

이전 단계에서 만든 MicrosoftGame.config 파일에는 Gaming Runtime, Microsoft Store 및 타이틀 ID의 기능을 사용하기 시작할 때까지 추가 구성 없이 PC 및 Xbox에서 초기 개발을 허용하는 기본값이 있습니다. Xbox 서비스 기능을 사용하려면 파트너 센터 프로젝트 ID 세부 정보로 프로젝트의 MicrosoftGame.config를 업데이트해야 합니다.

파트너 센터 대시보드로 이동합니다.
제품 목록에서 게임을 선택합니다.
게임 설정 탭을 선택하고 ID 세부 정보를 선택합니다.
세부 정보 표시를 선택하요 ID 세부 정보 섹션을 확장합니다.
Identity details 섹션의 표에서 다음 값을 사용한 다음 파트너 센터에서 해당 값을 MicrosoftGame.config의 해당 요소 및 필드에 복사합니다.

파트너 센터의 이름	MicrosoftGame.config
Xbox 타이틀 ID	TitleId
Package/Identity/Name	ID->이름
Package/Identity/Publisher	ID->게시자
Xbox 서비스 -> Xbox 설정 -> MSAAppId	MSAAppId

예를 들어 파트너 센터에서 다음 ID 세부 정보를 사용하면 MicrosoftGame.config가 아래 샘플과 같이 표시됩니다.

파트너 센터의 이름	예제 값
Xbox 타이틀 ID	64353034
Package/Identity/Name	41336MicrosoftATG.Achievements2017Redux
Package/Identity/Publisher	CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
Xbox 서비스 -> Xbox 설정 -> MSAAppId	0000000000000000

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />


  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>
  
  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>
  
  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="Xbox Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>
</Game>

MicrosoftGame.config의 값에 대한 추가 정보는 MicrosoftGame.config 개요를 참조하세요.

게임 런타임 및 XSAPI 초기화

다음 단계는 게임에서 Gaming Runtime Services 및 XSAPI를 초기화하는 방법을 보여줍니다.

XGameRuntime 헤더와 XSAPI services-c 헤더를 포함합니다.
```
#include <XGameRuntime.h> 
#include <xsapi-c/services_c.h>
```

XGameRuntimeInitialize를 호출하여 GDK 런타임을 초기화합니다.

// Initialize the 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;

}

XblInitialize를 호출하여 XSAPI를 초기화합니다.

 XblInitArgs xblArgs = {};
 //xblArgs.queue = queue; // Uncomment this line if you've chosen to create your own XTaskQueue. Otherwise, by default, this line is not needed.
 xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Add your scid from your Partner Center project here;

 HRESULT hr = XblInitialize(&xblArgs);
 if (FAILED(hr))
 {
     // Handle failure
 }

게임 런타임 초기화 취소

게임이 종료되기 전에 게임 런타임 서비스 초기화를 취소해야 합니다. XSAPI는 종료하기 전에 명시적으로 정리할 필요가 없습니다.

XGameRuntimeUninitialize를 호출하여 GDK 런타임을 초기화 취소합니다.

 // Uninitialize the Gaming Runtime after
 // all other activity has been completed.
 XGameRuntimeUninitialize();

게임에서 XSAPI를 사용하는 방법에 대한 자세한 개요는 Xbox 서비스 API 시작하기를 참조하세요.
GDK 기능 구현에 대한 개요는 개요 및 방법을 참조하세요.

게임에서 Xbox 서비스 테스트

게임에서 도전 과제와 같은 Xbox 서비스 기능을 테스트하려면 샌드박스를 사용하고 해당 샌드박스에 액세스할 수 있는 계정을 테스트해야 합니다.

테스트 계정 만들기

게임에서 Xbox 서비스 기능을 테스트하려면 개발 샌드박스에 액세스할 수 있는 테스트 계정을 만들어야 합니다. 테스트 계정 만들기에 대한 자세한 내용은 테스트 계정 만들기를 참조하세요.

샌드박스 전환

테스트 계정을 만들었으면 다음 단계에 따라 계정을 사용하여 샌드박스에 액세스합니다.

샌드박스 ID를 찾으려면 파트너 센터로 이동합니다.
Xbox 서비스를 선택하고 Gameplay Settings(게임플레이 설정)를 선택합니다.

참고 항목

샌드박스 ID는 첫 번째 탭에 있으며 “ABCDEF.0”과 같이 이름이 지정됩니다.
시작 메뉴를 엽니다.
Microsoft GDK Command Prompts를 입력하고 키보드의 Enter 키를 누릅니다.
첫 번째 명령 프롬프트를 엽니다.
명령 프롬프트에 XblPCSandbox.exe [샌드박스 ID]를 입력합니다.
명령 프롬프트에서 여러 개 앱이 시작되면 테스트 계정을 사용하여 Xbox 앱에 로그인합니다.

성공적으로 로그인할 수 있으면 테스트 계정을 만들고 테스트를 시작하기 위해 샌드박스로 변경한 것입니다.

샌드박스에 대한 자세한 내용은 Xbox 서비스 샌드박스 개요를 참조하세요.

게시

게임을 게시할 준비를 하려면 다음을 수행해야 합니다.

GDK와 게임 통합 완료
MSIXVC 패키징 도구를 사용하여 PC용 타이틀 패키징 시작하기의 단계에 따라 게임 패키지를 만들었습니다.

이 두 가지 요구 사항을 완료하면 게시할 준비가 된 것입니다. 게임을 제출하려면 파트너 센터로 이동하고 UI의 지침에 따릅니다.

다음을 통해 공유