GDK를 커스텀 C/C++ 엔진에 통합

이 항목은 Microsoft Store에 게임을 게시할 준비를 하고 있고, 게임이 GDK 기본 지원이 없는 C/C++ 기반 엔진을 사용하는 경우에 참고하세요.

Partner Center에서 제품 만들기
C/C++ 게임에 GDK 통합하기
게임에서 XBOX 서비스 테스트하기
게시

Partner Center에서 제품 만들기

Microsoft Store에 게임을 게시하려면 먼저 Partner Center에서 XBOX 서비스가 활성화된 제품을 생성해야 합니다. Partner Center에 대한 자세한 내용은 Managed Partner를 위한 Partner Center에서 앱 또는 게임 설정을 참조하세요.

C/C++ 게임에 GDK 통합하기

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

API 시그니처와 데이터 구조를 기술하는 GDK 및 XBOX Services API(XSAPI) 헤더.
내보낸 GDK 함수에 대한 외부 참조를 링커가 해결할 수 있게 하는 임포트 라이브러리.
내보낸 XSAPI DLL 함수에 대한 외부 참조를 링커가 해결할 수 있게 하는 XSAPI 정적 라이브러리 또는 임포트 라이브러리.
- XSAPI는 정적 및 동적 형태 모두로 제공됩니다. 자세한 내용은 아래 표를 참조하고 정적 또는 동적 중에서 선택하세요.
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를 사용하기 위한 모든 요구 사항이 프로젝트에 갖추어지도록 하기 위한 변경 사항을 개략적으로 설명합니다.

x64를 타깃으로 하는지 확인합니다. Visual Studio에서는 Build->Configuration Manager로 이동해 Active solution platform을 x64로 설정합니다.
다음 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에서 이 경로들을 추가합니다.
임포트 라이브러리를 위한 다음 라이브러리 경로를 추가합니다. 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에서 이 경로들을 추가합니다.
프로젝트에 링크되는 라이브러리 목록에 다음 라이브러리를 추가합니다. 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에서 라이브러리를 추가합니다.
_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"

MicrosoftGame.config 파일을 만들고 빌드 시 .exe와 동일한 대상 위치에 복사되도록 합니다. 참고: 엔진이 실행 시 다른 .exe를 사용하는 에디터 내 실행(run-in-editor) 기능을 지원한다면 해당 .exe와 동일한 디렉터리에도 MicrosoftGame.config가 복사되도록 해야 합니다. MicrosoftGame.config가 .exe와 동일한 디렉터리에 없다면 에디터 내 실행 기능 사용 시 XBOX 서비스가 작동하지 않습니다. 개발을 시작할 때는 아래 예시와 같이 기본값을 가진 설정을 사용할 수 있습니다. Identity Name, Executable Name, Executable Alias의 값은 모두 여러분의 실행 파일 이름으로 교체됩니다.

<?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가 이 .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 추가.

MicrosoftGame.config 업데이트

이전 단계에서 생성한 MicrosoftGame.config 파일은 Gaming Runtime, Microsoft Store, 타이틀 신원 관련 기능을 사용하기 전까지는 추가 구성 없이 PC와 XBOX에서 초기 개발이 가능한 기본값을 가지고 있습니다. XBOX 서비스 기능을 사용하려면 프로젝트의 MicrosoftGame.config를 Partner Center 프로젝트의 신원 세부 정보로 업데이트해야 합니다.

Partner Center 대시보드로 이동합니다.
제품 목록에서 게임을 선택합니다.
Game setup 탭을 선택한 다음 Identity details를 선택합니다.
Show Details를 선택해 Identity details 섹션을 확장합니다.
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 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 런타임을 초기화합니다.

// 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; // 직접 XTaskQueue를 생성하도록 선택한 경우 이 줄의 주석을 해제하세요. 그렇지 않으면 기본적으로 이 줄은 필요하지 않습니다.
 xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Partner Center 프로젝트의 scid를 여기에 추가하세요.
 HRESULT hr = XblInitialize(&xblArgs);
 if (FAILED(hr))
 {
     // 실패 처리
 }

게임 런타임 해제

Gaming Runtime Services는 게임이 종료되기 전에 해제되어야 합니다. XSAPI는 종료 전에 명시적으로 정리할 필요가 없습니다. XGameRuntimeUninitialize를 호출해 GDK 런타임을 해제합니다.

 // 다른 모든 활동이 완료된 후
 // Gaming Runtime 해제.
 XGameRuntimeUninitialize();

게임에서 XSAPI를 사용하는 자세한 개요는 XBOX 서비스 API 시작하기를 참조하세요.
GDK 기능 구현 개요는 Game Development Kit(GDK) 기능을 참조하세요.

게임에서 XBOX 서비스 테스트하기

게임에서 업적과 같은 XBOX 서비스 기능을 테스트하려면 샌드박스와 해당 샌드박스에 접근할 수 있는 테스트 계정을 사용해야 합니다.

테스트 계정 만들기

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

샌드박스 전환

테스트 계정을 만든 후에는 다음 단계를 사용해 샌드박스에 접근하세요.

샌드박스 ID를 찾으려면 Partner Center로 이동합니다.
XBOX services를 선택한 다음 Gameplay Settings를 선택합니다.
샌드박스 ID는 첫 번째 탭에 있으며 “ABCDEF.0”과 같은 형태로 이름 지어져 있습니다.
시작 메뉴를 엽니다.
Microsoft GDK Command Prompts를 입력한 다음 키보드에서 Enter를 누릅니다.
첫 번째 명령 프롬프트를 엽니다.
명령 프롬프트에서 XblPCSandbox.exe [샌드박스 ID] 를 입력합니다.
명령 프롬프트가 여러 앱을 실행한 후 XBOX 앱에 테스트 계정으로 로그인합니다.

성공적으로 로그인할 수 있다면 테스트 계정을 만들고 샌드박스로 전환해 테스트를 시작할 수 있습니다. 샌드박스에 대한 자세한 내용은 XBOX 서비스 샌드박스 개요를 참조하세요.

게시

게임을 게시할 준비를 하려면 다음이 필요합니다.

게임을 GDK와 통합하는 작업을 완료했어야 합니다.
MSIXVC 패키징 도구로 PC용 타이틀 패키징 시작하기의 단계를 따라 게임 패키지를 만들었어야 합니다.

두 가지 요구 사항을 완료한 후에는 게시할 준비가 된 것입니다. 게임을 제출하려면 Partner Center로 이동해 UI의 지침을 따르세요.

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Partner Center에서 제품 만들기

C/C++ 게임에 GDK 통합하기

프로젝트에 Gaming Runtime Services와 XSAPI 요구 사항 추가

MicrosoftGame.config 업데이트

게임 런타임과 XSAPI 초기화

게임 런타임 해제

게임에서 XBOX 서비스 테스트하기

테스트 계정 만들기

샌드박스 전환

게시

​Partner Center에서 제품 만들기

​C/C++ 게임에 GDK 통합하기

​프로젝트에 Gaming Runtime Services와 XSAPI 요구 사항 추가

​MicrosoftGame.config 업데이트

​게임 런타임과 XSAPI 초기화

​게임 런타임 해제

​게임에서 XBOX 서비스 테스트하기

​테스트 계정 만들기

​샌드박스 전환

​게시

Partner Center에서 제품 만들기

C/C++ 게임에 GDK 통합하기

프로젝트에 Gaming Runtime Services와 XSAPI 요구 사항 추가

MicrosoftGame.config 업데이트

게임 런타임과 XSAPI 초기화

게임 런타임 해제

게임에서 XBOX 서비스 테스트하기

테스트 계정 만들기

샌드박스 전환

게시