PC 用の C/C++ カスタムエンジン統合: 使用を開始する

[アーティクル]
11/06/2024

PC 上の Microsoft Store に公開するゲームを準備していて、ゲームで GDK のサポートに組み込まれた C/C++ ベースのエンジンを使用している場合は、このトピックを使用します。

パートナーセンターで製品を作成する
GDK を C/C++ ゲームに統合しています
ゲームでの Xbox サービスのテスト
Publishing

パートナーセンターで製品を作成する

ゲームを Microsoft Store に公開する前に、パートナーセンターで Xbox サービス対応商品を作成する必要があります。パートナーセンターの詳細については、「パートナーセンターでアプリまたはゲームをセットアップする (対象パートナー向け)」をご覧ください。

GDK を C/C++ ゲームに統合しています

GDK を C/C++ ゲームに統合するには、次の 3 つのことが必要です。

API シグネチャとデータ構造を記述した GDK および XSAPI ヘッダー
エクスポートされた GDK および XSAPI DLL 関数への外部参照を解決する方法をリンカーに指示するインポートライブラリ
GDK と XSAPI 関数の実行時の実装を実際に含むダイナミックリンクライブラリ。

ゲームを Xbox エコシステムの重要なエクスペリエンスと統合するには、ゲームランタイムサービス (GRTS) と XSAPI の 2 つのコンポーネントを操作する必要があります。アンマネージドゲームで必要なファイルを次に示します。

コンポーネント	GRTS	XSAPI
ヘッダー	GRTS ヘッダー: XUser、XGameSave、XGameUI など (GDK から)	XSAPI ヘッダー: profile_c.h、achievements_c.h など (GDK から)
ライブラリをインポートする	xgameruntime.lib (GDK から)	Microsoft.Xbox.Services.GDK.C.Thunks.lib (GDK から)
ダイナミックリンクライブラリ	xgameruntime.dll とその他のいくつかの dll (GRTS によってインストールされた system32)	Microsoft.Xbox.Services.GDK.C.Thunks.dll (GDK から、ゲームパッケージに含める必要があります)

ゲームランタイムサービスと XSAPI の要件をプロジェクトに追加する

次の手順では、ゲームランタイムサービスと XSAPI を使用するためのすべての要件を確実に満たすために、プロジェクトに加える必要がある変更の概要を示します。

x64 がターゲットに設定されている必要があります。

Visual Studioで、[ビルド]->[構成マネージャー] に移動し、アクティブソリューションプラットフォーム を x64 に設定します。
次のインクルードパスを追加します。

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 バージョン番号 は、リリースの年、月、およびサブバージョン番号で命名されるディレクトリになります。たとえば、2022 年 6 月の GDK の場合、ディレクトリ名は 220600 になります。

Microsoft GDK (2024 年 6 月) 以前の場合、C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include および C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include を使用します。

Visual Studioでは、 [プロジェクトのプロパティ] ページの、[構成プロパティ]>[VC++ ディレクトリ]>[インクルードディレクトリ] に、これらのパスを追加します。
インポートライブラリの次のライブラリパスを追加します。

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 バージョン番号 は、リリースの年、月、およびサブバージョン番号で命名されるディレクトリになります。たとえば、2022 年 6 月の GDK の場合、ディレクトリ名は 220600 になります。

Microsoft GDK (2024 年 6 月) 以前の場合、C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release および C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib を使用します。

Visual Studioでは、 [プロジェクトのプロパティ] ページの、[構成プロパティ]->[VC++ ディレクトリ]->[ライブラリディレクトリ] に、これらのパスを追加します。
プロジェクトにリンクされているライブラリのリストに次のライブラリを追加します。

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

C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib

ここの GDK バージョン番号 は、リリースの年、月、およびサブバージョン番号で命名されるディレクトリになります。たとえば、2022 年 6 月の GDK の場合、ディレクトリ名は 220600 になります。

Microsoft GDK (2024 年 6 月) 以前の場合、C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.を使用します。 Thunks.lib および C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib を使用します。

Visual Studio では、プロジェクトプロパティページの [構成プロパティ] - [>リンカー] - [>入力] - >[追加の依存関係] の下にライブラリを追加します。
_GAMING_DESKTOP と WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP を定義します。

Visual Studio では、プロジェクトプロパティページの C/C++->[コマンドライン]->[の他のオプション] の下に次の行を追加します。

/D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"
MicrosoftGame.config ファイルを作成し、.exe がビルドされているのと同じコピー先にコピーされていることを確認してください。

注: 実行中に別の .exe を使用する任意の種類のエディター内実行機能がエンジンでサポートされている場合は、MicrosoftGame.config がその .exe と同じディレクトリにもコピーされていることを確認する必要があります。 MicrosoftGame.config が .exe と同じディレクトリに存在しない場合、エディターで実行する機能を使用している間は、Xbox サービスは機能しません。

開発を開始するには、以下の例のように既定値を設定した構成を使用できます。 ID 名、実行可能な名前、実行可能なエイリアスは、すべて実行可能ファイルの名前に置き換えられます。
```
<?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 も参照していることを確認する必要があります。 .dll が .exe によって参照されていない場合、エディターで実行する機能を使用している間は、Xbox サービスは機能しません。

Microsoft.Xbox.Services.GDK.C.Thunks.dll は、次のディレクトリの GDK インストールにあります。

C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release]

XCurl.dll は、次のディレクトリの GDK インストールにあります。

C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64

libHttpClient.GDK.dll は、次のディレクトリの GDK インストールにあります。

C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\x64

ここの GDK バージョン番号 は、リリースの年、月、およびサブバージョン番号で命名されるディレクトリになります。たとえば、2022 年 6 月の GDK の場合、ディレクトリ名は 220600 になります。

Microsoft GDK (2024 年 6 月) 以前の場合は、C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\[Debug|リリース]、C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral、および C:\Program Files (x86)\Microsoft GDK\[GDK バージョン番号]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral を使用します。

注意

または、GDK を既存の Visual Studio Desktop プロジェクトに統合する時は、このトピックの手順に従ってプロジェクトを GDK プロジェクトに変換し、Microsoft ゲーム開発キットを既存のデスクトッププロジェクトに追加することができます。

MicrosoftGame.config を更新する

以前の手順で作成された MicrosoftGame.config ファイルには PC と Xbox における初期段階の開発を可能にする既定値が用意されており、ゲームランタイム、Microsoft Store、およびタイトル ID 内の機能を使い始めるまで追加の構成は必要ありません。 Xbox サービス機能を使用するには、プロジェクトの MicrosoftGame.config をパートナーセンタープロジェクト ID の詳細情報で更新する必要があります。

パートナーセンターダッシュボードに移動します。
製品の一覧からゲームを選択します。
[ゲームの設定] タブを選択し、[Identity details] を選択します。
[Show Details] を選択して、[Identity details] セクションを展開します。
[ID の詳細] セクションのテーブルから以下の値を使用し、パートナーセンターから MicrosoftGame.config で対応する要素とフィールドにそれらの値をコピーします。

パートナーセンターに表示される名前	MicrosoftGame.config
Xbox タイトル ID	TitleId
Package/Identity/Name	ID->名前
Package/Identity/Publisher	ID->発行元
Xbox サービス -> Xbox 設定 -> MSAAppId	MSAAppId

たとえば、パートナーセンターの次の ID の詳細は、MicrosoftGame.config は以下のサンプルのように表示されます。

パートナーセンターに表示される名前	値の例
Xbox タイトル ID	64353034
Package/Identity/Name	41336MicrosoftATG.Achievements2017Redux
Package/Identity/Publisher	CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
Xbox サービス -> Xbox 設定 -> 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 overview を参照してください。

ゲームランタイムと XSAPI を初期化する

以下の手順では、ゲームでゲームランタイムサービスと 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
 }

ゲームランタイムの初期化を解除する

ゲームランタイムサービスは、ゲームが終了する前に初期化を解除する必要があります。 XSAPI は、終了する前に明示的にクリーンアップする必要はありません。

XGameRuntimeUninitialize を呼び出して、GDK ランタイムの初期化を解除します。

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

ゲームで XSAPI を使用する詳細な概要については、「Xbox サービス API の使用を開始する」を参照してください。
GDK 機能を実装する概要については、「概要と使い方」を参照してください。

ゲームでの Xbox サービスのテスト

実績など、ゲーム内で Xbox サービス機能をテストするには、サンドボックスを使用し、そのサンドボックスにアクセスできるアカウントをテストする必要があります。

テストアカウントの作成

ゲーム内で Xbox サービス機能をテストするには、開発サンドボックスにアクセスできるテストアカウントを作成する必要があります。テストアカウントの作成の詳細については、「テストアカウントを作成する」をご覧ください。

サンドボックスを切り替える

テストアカウントを作成したら、次の手順に従って、アカウントを使用してサンドボックスにアクセスします。

サンドボックス ID を検索するには、パートナーセンターに移動します。
[Xbox サービス] を選び、[ゲームプレイの設定] を選びます。

注意

サンドボックス ID は最初のタブにあり、"ABCDEF.0" のような名前です。
スタート メニューを開きます。
Microsoft GDK Command Prompts と入力し、キーボードの Enter を選びます。
最初のコマンドプロンプトを開きます。
コマンドプロンプトで、「XblPCSandbox.exe [サンドボックス ID]」を入力します。
コマンドプロンプトで複数のアプリを起動した後、Xbox アプリにテストアカウントを使用してサインインします。

正常にサインインできる場合は、テストアカウントが作成済みで、テストを開始するサンドボックスに変更済みです。

サンドボックスの詳細については、「Xbox サービスのサンドボックスの概要」を参照してください。

公開

ゲームを公開するための準備を行うには、次の操作を行う必要があります。

ゲームと GDK の統合の完了
「MSIXVC パッケージ化ツールを使用してタイトルを PC 用にパッケージする方法についてのスタートガイド」の手順に従って作成したゲームパッケージ

この 2 つの要件を完了したら、公開する準備が整います。ゲームを提出するには、パートナーセンターに移動し、UI の指示に従います。

次の方法で共有

PC 用の C/C++ カスタムエンジン統合: 使用を開始する

パートナーセンターで製品を作成する

GDK を C/C++ ゲームに統合しています

ゲームランタイムサービスと XSAPI の要件をプロジェクトに追加する

MicrosoftGame.config を更新する

ゲームランタイムと XSAPI を初期化する

ゲームランタイムの初期化を解除する

ゲームでの Xbox サービスのテスト

テストアカウントの作成

サンドボックスを切り替える

公開

その他のリソース

次の方法で共有

PC 用の C/C++ カスタム エンジン統合: 使用を開始する

パートナー センターで製品を作成する

GDK を C/C++ ゲームに統合しています

ゲーム ランタイム サービスと XSAPI の要件をプロジェクトに追加する

MicrosoftGame.config を更新する

ゲーム ランタイムと XSAPI を初期化する

ゲーム ランタイムの初期化を解除する

ゲームでの Xbox サービスのテスト

テスト アカウントの作成

サンドボックスを切り替える

公開

その他のリソース

PC 用の C/C++ カスタムエンジン統合: 使用を開始する

パートナーセンターで製品を作成する

ゲームランタイムサービスと XSAPI の要件をプロジェクトに追加する

ゲームランタイムと XSAPI を初期化する

ゲームランタイムの初期化を解除する

テストアカウントの作成