GDK 헤더 및 라이브러리 디렉터리 구조

현재 버전의 Microsoft Game Development Kit (GDK)에서 레이아웃은 코드 공유를 중심으로 최적화되었으며 특정 플랫폼에 초점을 맞추었습니다. 이 레이아웃의 빌드 통합은 MSBuild 사용자 지정 플랫폼에 복잡성을 숨기는 방식에 크게 의존했습니다. 새 레이아웃에서는 통합을 간소화하고, 점점 늘어나는 대상 플랫폼 목록을 지원하며, 기본 MSBuild 플랫폼과 Microsoft 이외의 빌드 시스템 모두에 대한 지원을 개선하는 데 중점을 둡니다.

이전 헤더 및 라이브러리 레이아웃

Microsoft GDK의 기존 파일 레이아웃은 다음과 같이 요약됩니다.

251000\
    GRDK\
        ExtensionLibraries\
            Xbox.Services.API.C\
                ExtensionLibrary.props
                DesignTime\CommonConfiguration\Neutral\
                    Include\
                    Lib\
                    Redist\
            ...
        GameKit\
            Include\
            Lib\
                amd64\

Gaming.Desktop.x64 사용자 지정 MSBuild 플랫폼은 이 모든 콘텐츠를 다양한 방식으로 결합하는 include/lib 경로를 빌드하는 논리를 구현합니다. CMake 또는 사용자 지정 make 솔루션을 사용한 경우 이 논리를 해당 솔루션에서도 구현해야 했습니다. 자세한 예제는 CMakeExample의 2025년 4월 버전을 참조하세요. 이전 스타일과 새 스타일을 모두 지원하기 위해 2025년 10월 GDK에도 이전 레이아웃이 여전히 포함되어 있습니다. 기본적으로 새 레이아웃과 이전 레이아웃이 모두 설치됩니다. 이제 GDK 설치 프로그램에는 새 레이아웃만 설치하는 옵션이 포함되어 있습니다. 향후 GDK에서는 하드 드라이브 사용 공간과 전체 다운로드 크기를 줄이기 위해 이전 레이아웃이 제거될 예정입니다. 이전 레이아웃 제거의 현재 목표 날짜는 2025년 10월 GDK 릴리스 시점으로부터 1년 후입니다.

새 헤더 및 라이브러리 레이아웃

2025년 10월 GDK 릴리스에서 새 레이아웃은 헤더와 라이브러리에 대한 대체 레이아웃을 제공하여 플랫폼 통합을 더 쉽게 만들고 시간이 지남에 따라 추가 플랫폼을 수용할 수 있도록 합니다.

251000\
    windows\
        bin\
            arm64
            x64\
        include\
        lib\
            arm64
            x64\
        redist

MSBuild 사용자 지정 플랫폼에서 새 레이아웃 사용

기존 Gaming.*.x64 MSBuild 플랫폼은 기본적으로 이전 레이아웃을 사용하지만, GDKCrossPlatform 속성을 설정하여 새 레이아웃을 옵트인할 수 있습니다.

<PropertyGroup Label="Globals">
...
  <GDKCrossPlatform>true</GDKCrossPlatform>
</PropertyGroup>

이렇게 하면 이전 레이아웃에서 사용하던 다양하고 복잡한 경로 대신 적절한 include/lib 경로가 프로젝트에 추가됩니다. 이 새로운 간소화된 통합에서는 확장 라이브러리 메커니즘이 더 이상 사용되지 않습니다. 기본적으로 모든 콘텐츠를 빌드 시 include/lib 경로에서 사용할 수 있습니다. 그런 다음 프로젝트는 사용하는 추가 라이브러리에 연결해야 합니다. 이전 GDK 프로젝트 템플릿을 기반으로 빌드된 프로젝트에는 다음과 같은 문이 포함되어 있어야 합니다.

<AdditionalDependencies>uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies)</AdditionalDependencies>

새 레이아웃의 경우 Console_Libs 속성에 필수 핵심 라이브러리가 나열됩니다.

플랫폼	핵심 라이브러리
Gaming.*.x64	xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib

확장 라이브러리는 각각 ‘옵트인’ 방식이므로 프로젝트에서 사용하는 확장 라이브러리를 AdditionalDependencies에 추가해야 합니다.

플랫폼	핵심 라이브러리
Xbox.LibHttpClient	libHttpClient.lib
Xbox.XCurl.API	XCurl.lib
Xbox.Game.Chat.2.Cpp.API	GameChat2.lib
Xbox.Services.API.C (Debug)	Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.Debug.lib
Xbox.Services.API.C (Release)	Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.lib
PlayFab.Party.Cpp	Party.lib
PlayFab.PartyXboxLive.Cpp	PartyXboxLive.lib
PlayFab.Services.C	PlayFabCore.lib PlayFabGameSave.lib PlayFabServices.lib
PlayFab.Multiplayer.Cpp	PlayFabMultiplayer.lib

또한 프로젝트는 사용하는 추가 DLL을 레이아웃에 복사해야 합니다. 이 작업은 많은 DLL 라이브러리 통합에서 일반적으로 사용되는 사용자 지정 빌드 단계를 통해 수행하거나, vcxproj를 편집하거나 props 파일을 추가하여 ReferenceCopyLocalPaths 항목 그룹 목록을 사용하여 수행할 수 있습니다. 아래 MSBuild에는 가능한 모든 DLL이 나열되어 있지만 개별 프로젝트에는 이 중 일부만 필요합니다.

  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>

GameDKLatest는 XBOX Extensions가 포함된 Microsoft GDK에서만 설정됩니다. 따라서 두 버전의 Microsoft GDK를 나란히 설치하는 것을 완벽하게 지원하는 새 환경 변수를 도입했습니다. GameDKCoreLatest는 Microsoft GDK에서 설정됩니다.

Directory.Build.props 파일 사용

새 레이아웃을 사용하여 기존 GDK Gaming.*.x64 프로젝트를 빠르게 검증하는 방법으로, 소스 트리의 Directory.Build.props라는 파일에 다음 내용을 넣습니다. 이렇게 하면 새 레이아웃이 옵트인되며, 프로젝트에서 사용하지 않더라도 대부분 또는 모든 확장 라이브러리가 포함됩니다.

GDKCrossPlatform을 true로 설정하여 빌드할 때는 MSBuild 규칙에서 GDKExtLibNames 속성을 사용하지 않습니다. 이 속성은 이전 MSBuild 규칙으로 빌드하기 위해 이미 존재하므로, 이 props 파일에서는 레이아웃에 일부 추가 DLL을 옵트인하는 방법으로 사용됩니다.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <PropertyGroup>
    <GDKCrossPlatform>true</GDKCrossPlatform>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
    <AllExtensionLibs>Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.lib</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'=='Debug'">Microsoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs)</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'!='Debug'">Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs)</AllExtensionLibs>
  </PropertyGroup>

  <ItemDefinitionGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <Link>
      <AdditionalDependencies>$(AllExtensionLibs);%(AdditionalDependencies)</AdditionalDependencies>
    </Link>
  </ItemDefinitionGroup>

  <!--
    Makes sure we deploy all the libs we need. We use the 'old layout' GDKExtLibNames property as a way to test
    what is requested to try to reduce the over-inclusion of unused DLLs.
  -->

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('Xbox.Game.Chat.2.Cpp.API'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('PlayFab'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>

</Project>

x64 게임을 업데이트하여 ARM64를 추가하는 방법

기존 x64 게임 프로젝트에 ARM64 지원을 추가하려면 다음 단계를 따르세요.

Visual Studio 2022를 사용합니다. ARM64 지원에는 Visual Studio 2022가 필요합니다. Visual Studio 2019는 ARM64 빌드에 지원되지 않습니다.
새 레이아웃을 활성화합니다. 프로젝트 파일에서 GDKCrossPlatform을 true로 설정하여 프로젝트가 새 레이아웃을 사용하도록 합니다.
ARM64 구성을 만듭니다. 기존 x64 구성(예: Debug 및 Release)을 복사하여 해당하는 ARM64 구성을 만듭니다.
라이브러리 경로를 업데이트합니다. 라이브러리 경로가 lib\x64 대신 lib\arm64를 참조하도록 ARM64 구성의 VC++ 디렉터리를 편집합니다.
XSAPI 라이브러리 참조를 업데이트합니다. ARM64뿐 아니라 모든 구성의 링크 문을 Microsoft.Xbox.Services.142.GDK.C.lib 대신 Microsoft.Xbox.Services.143.GDK.C.lib를 사용하도록 업데이트합니다.
ReferenceCopyLocalPaths를 업데이트합니다. .vcxproj 파일에서 x64 대신 arm64 bin 폴더를 참조하도록 업데이트해야 할 수 있는 ReferenceCopyLocalPaths 사용을 확인합니다.

타이틀 시작이 오류 0xc000007b로 실패하는 경우 실수로 x64 형식 DLL을 ARM64 프로세스에 로드하려고 시도했음을 의미합니다. 프로젝트 시스템에서 업데이트해야 할 수 있는 ReferenceCopyLocalPaths 항목을 확인하세요.

MSBuild x64 플랫폼에서 새 레이아웃 사용

Gaming.Desktop.x64 플랫폼을 사용하는 대신 기본 x64 플랫폼을 사용하여 PC용으로 빌드할 수 있습니다. 이전 레이아웃에서는 Microsoft Game Development Kit (GDK)에서 x64 플랫폼 사용에 자세히 설명된 대로 확장 라이브러리에 대한 <Import Project="...\ExtensionLibrary.props"> 문을 추가해야 했습니다. 새 레이아웃에서는 통합 지침이 간소화되었습니다.

  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>

필요한 모든 확장 라이브러리를 원래 목록과 함께 AdditionalDependencies에 추가합니다.

<AdditionalDependencies>xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies)</AdditionalDependencies>

옵트인 확장 라이브러리 DLL은 위와 같이 사용자 지정 빌드 작업을 사용하거나 최종 레이아웃에 ReferenceCopyLocalPaths 항목 그룹을 사용하여 바이너리 디렉터리에 복사해야 합니다. PreprocessorDefinitions 및 이미지 자산이 포함된 .mgc 파일 처리에 대한 나머지 지침은 변경되지 않습니다.

CMake에서 새 레이아웃 사용

CMake에서 Microsoft Visual Studio 생성기를 사용하고 Gaming.*.x64 사용자 지정 MSBuild 플랫폼을 사용하는 경우 다음 코드를 사용하여 새 레이아웃을 활성화합니다.

set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true")

CMakeGDKExample에서 VS_GLOBAL_GDKExtLibNames 사용을 제거하고 다음 코드(CMake 3.21 이상 가정)로 바꾸어 사용된 확장 DLL을 레이아웃에 복사합니다.

add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E $<IF:$<BOOL:$<TARGET_RUNTIME_DLLS:${PROJECT_NAME}>>,copy,true>
    $<TARGET_RUNTIME_DLLS:${PROJECT_NAME}> $<TARGET_FILE_DIR:${PROJECT_NAME}>
    COMMAND_EXPAND_LISTS
    )

사용자 지정 빌드 시스템에서 새 레이아웃 사용

GDK를 사용하여 Windows x64용으로 빌드하려면 다음이 필요합니다.

set INCLUDE=%GameDKCoreLatest%windows\include;%INCLUDE%
set LIB=%GameDKCoreLatest%windows\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKCoreLatest%windows\bin\x64;%PATH%

설치된 파일에서 빌드 에디션 읽기

새 레이아웃에는 grdk.ini 파일이 포함되어 있지 않습니다. 파일을 구문 분석하여 에디션 정보를 찾으려면 grdk.h를 사용합니다. 다음은 이전 GDK 릴리스에서도 작동하는 PowerShell 예제입니다.

$result = Get-ChildItem -Path $env:GameDKCoreLatest -Filter "grdk.h" -Recurse
if ($result.Count -eq 0)
{
    $result = Get-ChildItem -Path $env:GRDKLatest -Filter "grdk.h" -Recurse
}
if ($result.Count -eq 0)
{
    Write-Error "##[error]Failed to find grdk.h in either GameDKCoreLatest or GRDKLatest" -ErrorAction Stop
}

$content = Get-Content -Path $result[0].FullName

if (-not ([string]$content -match '#define\s+_GRDK_EDITION\s+([0-9][0-9][0-9][0-9][0-9][0-9])')) {
    Write-Error "##[error]Failed to find edition define" -ErrorAction Stop
}

$xbld_edition = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDKVER_PRODUCTBUILDVER_FULL\s+([0-9]+\.[0-9]+\.([0-9]+)\.[0-9]+)')) {
    Write-Error "##[error]Failed to find full version define" -ErrorAction Stop
}

$xbld_full_productbuild = $Matches[1]
$xbld_build = $Matches[2]

if (-not ([string]$content -match '#define\s+_GRDK_MM_NUM\s+([0-9]{1,2})')) {
    Write-Error "##[error]Failed to find month define" -ErrorAction Stop
}

$month = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDK_FULLYY\s+([0-9]{4})')) {
    Write-Error "##[error]Failed to find full year define" -ErrorAction Stop
}

$year = $Matches[1]

Write-Output ("_xbld_name={0} {1} GRDK" -f (Get-Culture).DateTimeFormat.GetMonthName([int]$month), $year)
Write-Output ("_xbld_edition={0}" -f $xbld_edition)
Write-Output ("_xbld_full_productbuild={0}" -f $xbld_full_productbuild)
Write-Output ("_xbld_build={0}" -f $xbld_build)

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

이전 헤더 및 라이브러리 레이아웃

새 헤더 및 라이브러리 레이아웃

MSBuild 사용자 지정 플랫폼에서 새 레이아웃 사용

Directory.Build.props 파일 사용

x64 게임을 업데이트하여 ARM64를 추가하는 방법

MSBuild x64 플랫폼에서 새 레이아웃 사용

CMake에서 새 레이아웃 사용

사용자 지정 빌드 시스템에서 새 레이아웃 사용

설치된 파일에서 빌드 에디션 읽기

​이전 헤더 및 라이브러리 레이아웃

​새 헤더 및 라이브러리 레이아웃

​MSBuild 사용자 지정 플랫폼에서 새 레이아웃 사용

​Directory.Build.props 파일 사용

​x64 게임을 업데이트하여 ARM64를 추가하는 방법

​MSBuild x64 플랫폼에서 새 레이아웃 사용

​CMake에서 새 레이아웃 사용

​사용자 지정 빌드 시스템에서 새 레이아웃 사용

​설치된 파일에서 빌드 에디션 읽기

이전 헤더 및 라이브러리 레이아웃

새 헤더 및 라이브러리 레이아웃

MSBuild 사용자 지정 플랫폼에서 새 레이아웃 사용

Directory.Build.props 파일 사용

x64 게임을 업데이트하여 ARM64를 추가하는 방법

MSBuild x64 플랫폼에서 새 레이아웃 사용

CMake에서 새 레이아웃 사용

사용자 지정 빌드 시스템에서 새 레이아웃 사용

설치된 파일에서 빌드 에디션 읽기