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 の April 2025 バージョンを参照してください。 October 2025 GDK には、以前のスタイルと新しいスタイルの両方をサポートするために、以前のレイアウトも引き続き含まれています。既定では、新しいレイアウトと以前のレイアウトの両方がインストールされます。GDK のセットアップには、新しいレイアウトのみをインストールするオプションが追加されました。将来の GDK では、ハードドライブの使用量と全体的なダウンロードサイズを削減するために、以前のレイアウトが削除されます。以前のレイアウトの削除は、現時点では October 2025 GDK のリリースから 1 年後を目標としています。

新しいヘッダーとライブラリのレイアウト

October 2025 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 は、Microsoft GDK with XBOX Extensions によってのみ設定されます。そのため、Microsoft GDK の両方のバージョンのサイドバイサイドインストールを完全にサポートする新しい環境変数を導入しました。GameDKCoreLatest は Microsoft GDK によって設定されます。

Directory.Build.props ファイルを使用する

新しいレイアウトを使用して既存の GDK Gaming.*.x64 プロジェクトをすばやく検証する方法として、ソースツリー内の Directory.Build.props という名前のファイルに次の内容を配置します。これにより、新しいレイアウトが有効になり、プロジェクトで使用されていない場合でも、ほとんどまたはすべての拡張ライブラリが含まれます。

GDKCrossPlatform を true に設定してビルドする場合、GDKExtLibNames プロパティは 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>

  <!--
    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 構成を作成します。
ライブラリパスを更新します。 ARM64 構成の VC++ ディレクトリを編集して、ライブラリパスが lib\x64 ではなく lib\arm64 を参照するようにします。
XSAPI ライブラリの参照を更新します。 (ARM64 だけでなく) すべての 構成のリンクステートメントを更新して、Microsoft.Xbox.Services.142.GDK.C.lib ではなく Microsoft.Xbox.Services.143.GDK.C.lib を使用するようにします。
ReferenceCopyLocalPaths を更新します。 .vcxproj ファイル内で ReferenceCopyLocalPaths が使用されている箇所を確認し、x64 ではなく arm64 の bin フォルダーを参照するように更新が必要かどうかを確認します。

タイトルの起動がエラー 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 の使用を削除し、使用する拡張 DLL をレイアウトにコピーするために、次のコード (CMake 3.21 以降を想定) に置き換えます。

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 で新しいレイアウトを使用する

カスタムビルドシステムで新しいレイアウトを使用する

インストールされたファイルからビルドエディションを読み取る