> ## 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 디렉터리 구조(헤더와 라이브러리)

> MSBuild, CMake, 커스텀 빌드용 GDKCrossPlatform으로 2025년 10월 GDK의 간소화된 디렉터리 레이아웃에 옵트인하고, x64 타이틀에 ARM64를 추가하세요.

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

현재 버전의 Microsoft Game Development Kit(GDK)에서 레이아웃은 코드 공유를 중심으로 최적화되었고 특정 플랫폼에 초점을 맞추었습니다. 이 레이아웃에 대한 빌드 통합은 MSBuild 커스텀 플랫폼에 복잡성을 숨기는 데 크게 의존했습니다. 새로운 레이아웃의 초점은 통합을 단순화하고, 늘어나는 타깃 플랫폼 목록을 지원하며, 표준 MSBuild 플랫폼과 비 Microsoft 빌드 시스템 모두에 대한 지원을 개선하는 것입니다.

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

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

```text theme={null}
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](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample)의 2025년 4월 버전을 참조하세요.

기존 레이아웃은 이전 스타일과 새 스타일을 모두 지원하기 위해 2025년 10월 GDK에도 여전히 존재합니다. 새 레이아웃과 기존 레이아웃은 기본적으로 모두 설치됩니다. GDK 설정에는 이제 새 레이아웃만 설치하는 옵션이 포함됩니다. 향후 GDK에서는 하드 드라이브 사용량과 전체 다운로드 크기를 줄이기 위해 기존 레이아웃을 제거할 예정입니다. 기존 레이아웃 제거의 현재 목표 시점은 2025년 10월 GDK 출시 후 1년입니다.

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

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

```text theme={null}
251000\
    windows\
        bin\
            arm64
            x64\
        include\
        lib\
            arm64
            x64\
        redist
```

## MSBuild 커스텀 플랫폼에서 새 레이아웃 사용

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

```xml theme={null}
<PropertyGroup Label="Globals">
...
  <GDKCrossPlatform>true</GDKCrossPlatform>
</PropertyGroup>
```

이렇게 하면 기존 레이아웃에서 사용하던 여러 복잡한 경로 대신 적절한 include/lib 경로가 프로젝트에 추가됩니다.

이 새로운 간소화된 통합에서는 확장 라이브러리 메커니즘을 더 이상 사용하지 않습니다. 모든 콘텐츠가 기본적으로 빌드 타임에 include/lib 경로에서 사용 가능합니다.

그런 다음 프로젝트는 사용하는 추가 라이브러리에 링크해야 합니다. 이전 GDK 프로젝트 템플릿에서 빌드된 프로젝트에는 다음과 같은 구문이 포함되어야 합니다.

```xml theme={null}
<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을 나열하지만, 개별 프로젝트는 이 중 일부만 필요합니다.

```xml theme={null}
  <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>
```

<Note>
  `GameDKLatest`는 XBOX Extensions가 포함된 Microsoft GDK에서만 설정됩니다. 그 결과로 두 버전의 Microsoft GDK를 나란히 설치할 수 있도록 완전히 지원하는 새 환경 변수를 도입했습니다. `GameDKCoreLatest`는 Microsoft GDK에서 설정됩니다.
</Note>

### Directory.Build.props 파일 사용

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

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

```xml theme={null}
<?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 지원을 추가하려면 다음 단계를 따르세요.

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

<Note>
  타이틀 시작이 오류 0xc000007b로 실패한다면, ARM64 프로세스에 실수로 x64 형식 DLL을 로드하려 한 것입니다. 프로젝트 시스템에서 업데이트가 필요할 수 있는 `ReferenceCopyLocalPaths` 항목을 확인하세요.
</Note>

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

**Gaming.Desktop.x64** 플랫폼 대신 표준 **x64** 플랫폼을 사용해 PC용으로 빌드할 수 있습니다. 기존 레이아웃에서는 Microsoft Game Development Kit(GDK)과 함께 x64 플랫폼을 사용하는 방법에 자세히 설명된 것처럼 확장 라이브러리에 대한 `<Import Project="...\ExtensionLibrary.props">` 구문을 추가해야 했습니다.

새 레이아웃에서는 통합 지침이 간소화됩니다.

```xml theme={null}
  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>
```

```xml theme={null}
<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>
```

```xml theme={null}
<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**에 추가합니다.

```xml theme={null}
<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 플랫폼을 사용하는 경우, 다음 코드를 사용해 새 레이아웃을 활성화합니다.

```text theme={null}
set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true")
```

[CMakeGDKExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeGDKExample)에서 `VS_GLOBAL_GDKExtLibNames` 사용을 제거하고 다음 코드로 교체합니다(CMake 3.21 이상 가정). 이 코드는 사용된 확장 DLL을 레이아웃에 복사합니다.

```text theme={null}
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용으로 빌드하려면 다음이 필요합니다.

```cmd theme={null}
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 예시입니다.

```powershell theme={null}
$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)
```


## Related topics

- [NDA 토픽 디렉터리 - Microsoft Learn 라이브 링크](/ko/nda/nda-topic-directory.md)
- [PlayFab 통합 SDK 빠른 시작 설정](/ko/services/playfab/sdks/unified-sdk/quickstart-setup.md)
- [PlayFab 독립 실행형 SDK v1에서 Unified SDK v2로 마이그레이션](/ko/services/playfab/sdks/unified-sdk/migrating-from-v1.md)
- [XBOX 개발용 Visual Studio 속성](/ko/tools/tools-console/visualstudio/durango-property-pages.md)
- [PlayFab 통합 SDK](/ko/services/playfab/sdks/unified-sdk/overview.md)