간소화된 GDK 디렉터리 구조(헤더와 라이브러리)

이 문서에서 설명하는 헤더와 라이브러리의 새로운 Microsoft Game Development Kit(GDK) 레이아웃은 2025년 10월 GDK에서 출시될 예정입니다. 이 GDK의 프리뷰 빌드에 관심이 있다면 담당 Microsoft 어카운트 매니저에게 문의하세요.

현재 버전의 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 파일에 넣으세요. 이렇게 하면 새 레이아웃에 옵트인하고 프로젝트에서 사용하지 않더라도 대부분 또는 모든 확장 라이브러리를 포함합니다.

GDKExtLibNames 속성은 GDKCrossPlatform을 true로 설정하고 빌드할 때 MSBuild 규칙에 의해 사용되지 않습니다. 이 속성은 이전 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>

  <!--
    필요한 모든 라이브러리를 배포하도록 합니다. 사용되지 않는 DLL의 과다 포함을 줄이기 위해
    '기존 레이아웃'의 GDKExtLibNames 속성을 이용해 요청된 내용을 테스트합니다.
  -->

  <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 구성을 만듭니다.
라이브러리 경로를 업데이트합니다. ARM64 구성에 대한 VC++ Directories를 편집해 라이브러리 경로가 lib\x64 대신 lib\arm64를 참조하도록 합니다.
XSAPI 라이브러리 참조를 업데이트합니다. 모든 구성(ARM64뿐만 아니라)의 링크 구문을 업데이트해 Microsoft.Xbox.Services.142.GDK.C.lib 대신 Microsoft.Xbox.Services.143.GDK.C.lib를 사용하도록 합니다.
ReferenceCopyLocalPaths를 업데이트합니다. .vcxproj 파일에서 x64 대신 arm64 bin 폴더를 참조하도록 업데이트해야 할 수 있는 ReferenceCopyLocalPaths 사용을 확인합니다.

타이틀 시작이 오류 0xc000007b로 실패한다면, ARM64 프로세스에 실수로 x64 형식 DLL을 로드하려 한 것입니다. 프로젝트 시스템에서 업데이트가 필요할 수 있는 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

간소화된 GDK 디렉터리 구조(헤더와 라이브러리)

기존 헤더와 라이브러리 레이아웃

새로운 헤더와 라이브러리 레이아웃

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에서 새 레이아웃 사용

커스텀 빌드 시스템에서 새 레이아웃 사용

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