將 GDK 與自訂 C/C++ 引擎整合

如果您正在準備將遊戲發行至 PC 版 Microsoft Store，而且遊戲使用的是沒有內建 GDK 支援的 C/C++ 架構引擎，請使用本主題。

在 Partner Center 中建立產品
將 GDK 整合到 C/C++ 遊戲中
在遊戲中測試 XBOX services
發行

在 Partner Center 中建立產品

在將遊戲發行至 Microsoft Store 之前，您必須先在 Partner Center 中建立已啟用 XBOX services 的產品。如需 Partner Center 的詳細資訊，請參閱在 Partner Center 中設定應用程式或遊戲 (適用於受管理的合作夥伴)。

將 GDK 整合到 C/C++ 遊戲中

若要將 GDK 整合到 C/C++ 遊戲中，遊戲需要 4 項內容：

描述 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 整合到這些 DLL 中。此方法在 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 (or Microsoft.Xbox.Services.142.GDK.C.lib, if statically linking) 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 的編輯器內執行功能，也請將 MicrosoftGame.config 複製到該 .exe 所在的目錄。如果 MicrosoftGame.config 不在 .exe 所在的目錄中，使用編輯器內執行功能時 XBOX services 將無法運作。開始開發時，您可以使用具有預設值的設定，如下列範例所示。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。如果 .exe 未參考這些 .dll，使用編輯器內執行功能時 XBOX services 將無法運作。如果是動態連結至 XSAPI，可以在 GDK 安裝的下列目錄中找到 Microsoft.Xbox.Services.GDK.C.Thunks.dll：C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release] 可以在 GDK 安裝的下列目錄中找到 XCurl.dll：C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64 可以在 GDK 安裝的下列目錄中找到 libHttpClient.GDK.dll：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 桌面專案中，可以依照本主題中的步驟將專案轉換為 GDK 專案：將 Microsoft Game Development Kit 新增至現有的桌面專案。

更新 MicrosoftGame.config

上一個步驟中建立的 MicrosoftGame.config 檔案具有預設值，可讓您在 PC 和 XBOX 上進行早期開發，而不需要進一步設定。只有在開始使用 Gaming Runtime、Microsoft Store 和遊戲識別的功能時，才需要更新這些值。若要使用 XBOX services 功能，請以您的 Partner Center 專案識別詳細資料更新專案的 MicrosoftGame.config。

移至 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 執行階段。

// Initialize the 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; // Uncomment this line if you've chosen to create your own XTaskQueue. Otherwise, by default, this line is not needed.
 xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Add your scid from your Partner Center project here;
 HRESULT hr = XblInitialize(&xblArgs);
 if (FAILED(hr))
 {
     // Handle failure
 }

取消初始化遊戲執行階段

您必須在遊戲結束之前取消初始化 Gaming Runtime Services。XSAPI 不需要在結束前明確清除。呼叫 XGameRuntimeUninitialize 以取消初始化 GDK 執行階段。

 // Uninitialize the Gaming Runtime after
 // all other activity has been completed.
 XGameRuntimeUninitialize();

如需在遊戲中使用 XSAPI 的詳細概觀，請參閱開始使用 XBOX services API。
如需實作 GDK 功能的概觀，請參閱 Game Development Kit (GDK) 功能。

在遊戲中測試 XBOX services

若要在遊戲中測試成就等 XBOX services 功能，您需要使用沙箱以及可存取該沙箱的測試帳戶。

建立測試帳戶

若要在遊戲中測試任何 XBOX services 功能，請建立可存取您開發沙箱的測試帳戶。如需建立測試帳戶的相關資訊，請參閱建立測試帳戶。

切換沙箱

建立測試帳戶之後，請使用下列步驟以該帳戶存取您的沙箱。

若要尋找您的沙箱 ID，請移至 Partner Center。
選取 XBOX services，然後選取 Gameplay Settings。
您的沙箱 ID 位於第一個索引標籤上，名稱類似 “ABCDEF.0”。
開啟開始功能表。
輸入 Microsoft GDK Command Prompts，然後按下鍵盤上的 Enter。
開啟第一個命令提示字元。
在命令提示字元中，輸入 XblPCSandbox.exe [your sandbox ID]。
命令提示字元啟動數個應用程式之後，使用您的測試帳戶登入 XBOX 應用程式。

如果您能成功登入，表示您已建立測試帳戶並切換至您的沙箱，可以開始測試。如需沙箱的詳細資訊，請參閱 XBOX services 沙箱概觀。

發行

若要準備好發行遊戲，您需要：

完成遊戲與 GDK 的整合
依照使用 MSIXVC 封裝工具開始封裝 PC 遊戲中的步驟建立遊戲套件

完成這兩項需求之後，您就可以發行了。若要提交遊戲，請移至 Partner Center，並依照 UI 中的指示操作。

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

在 Partner Center 中建立產品

將 GDK 整合到 C/C++ 遊戲中

將 Gaming Runtime Services 和 XSAPI 的需求新增至您的專案

更新 MicrosoftGame.config

初始化遊戲執行階段和 XSAPI

取消初始化遊戲執行階段

在遊戲中測試 XBOX services

建立測試帳戶

切換沙箱

發行

​在 Partner Center 中建立產品

​將 GDK 整合到 C/C++ 遊戲中

​將 Gaming Runtime Services 和 XSAPI 的需求新增至您的專案

​更新 MicrosoftGame.config

​初始化遊戲執行階段和 XSAPI

​取消初始化遊戲執行階段

​在遊戲中測試 XBOX services

​建立測試帳戶

​切換沙箱

​發行

在 Partner Center 中建立產品

將 GDK 整合到 C/C++ 遊戲中

將 Gaming Runtime Services 和 XSAPI 的需求新增至您的專案

更新 MicrosoftGame.config

初始化遊戲執行階段和 XSAPI

取消初始化遊戲執行階段

在遊戲中測試 XBOX services

建立測試帳戶

切換沙箱

發行