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

[アーティクル]
05/10/2023

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

パートナーセンターで製品を作成する
C# ゲームへの GDK の統合
ゲームでの Xbox サービスのテスト
Publishing

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

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

C# ゲームへの GDK の統合

C# ゲームに GDK を組み込むには、ゲームに以下の 3 つが必要です。

ネイティブ実装に対して C# に適した機能を提供する「API レイヤー」。
管理対象レイヤー (Unity などの C# エンジン) と管理対象外のレイヤー (GRTS/XSAPI ランタイム DLL) の間の相互運用を処理する「相互運用レイヤー」。
関数の実行時の実装を実際に含むダイナミックリンクライブラリ。

ゲームランタイムサービスと Xbox サービス API の要件のプロジェクトへの追加

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

Unity GDK プラグインの Git リポジトリの .zip を https://github.com/microsoft/gdk-unity-package から複製またはダウンロードします。
gdk-unity-package/Tools/XGamingRuntimeSDK/ にある XGamingRuntimeSDK.sln を開きます。

ソリューションファイルは Visual Studio 2017 用で、必要な C# のバージョンは 6 以降です。
XGamingRuntime プロジェクトで XBL\Social\XblSocialRelationshipFilter.cs を開き、ファイルの上部にある using UnityEngine; 行をコメントアウトして保存します。
XGamingRuntimeThunks プロジェクトと XGamingRuntime プロジェクトをビルドします。
C# ゲームプロジェクトを開きます。
プロジェクトをターゲット x64 に設定します。
XGamingRuntime プロジェクトでビルドした XGamingRuntime.dll へのリファレンスを追加します。
この DLL は、 gdk-unity-package-main\Tools\XGamingRuntimeSDK\Gaming.Desktop.x64\Debug|Release にあります。
XGamingRuntime.dll、XGamingRuntimeThunks.dll、XCurl.dll が .exe がビルドされているのと同じディレクトリにコピーされていることを確認してください。
この DLL は、gdk-unity-package-main\Tools\XGamingRuntimeSDK\Gaming.Desktop.x64\Debug|Releaseの下にあります。

注: 実行中に別の .exe を使用する任意の種類のエディター内実行機能がエンジンでサポートされている場合は、.exe がこれらの .dll も参照していることを確認する必要があります。 .dll が .exe によって参照されていない場合、エディターで実行する機能を使用している間は、Xbox サービスは機能しません。
Microsoft.Xbox.Services.GDK.C.Thunks.dll が、.exe がビルドされているディレクトリと同じディレクトリにコピーされていることをご確認ください。
この DLL は、GDK のインストールパスで次のセクションで確認できます:
- (2024 年 10 月以降) C:\Program Files (x86)\Microsoft GDK\241000\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Debug|Release
- (2024 年 6 月以前) C:\Program Files (x86)\Microsoft GDK\220300\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Debug|Release。
  GDK では、DLL 名にアンダースコアの代わりにピリオドが使用されているため、ピリオドの代わりにアンダースコアを使用するように名前を変更する必要があることに注意してください。
注: 実行中に別の .exe を使用する任意の種類のエディター内実行機能がエンジンでサポートされている場合は、.exe がこの .dll も参照していることを確認する必要があります。 .dll が .exe によって参照されていない場合、エディターで実行する機能を使用している間は、Xbox サービスは機能しません。
MicrosoftGame.congif ファイルを作成し、.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>
```

MicrosoftGame.config の更新

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

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

パートナーセンターに表示される名前	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"/>

  <DesktopRegistration>
    <DependencyList>
      <KnownDependency Name="VC14"/>
    </DependencyList>
  </DesktopRegistration>

</Game>

MicrosoftGame.config の値の詳細については、MicrosoftGame.config overview を参照してください。

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

以下の手順では、ゲームでゲームランタイムサービスと XSAPI を初期化する方法を示しています。

プロジェクトの .csファイルに using XGamingRuntime; を追加します。
プロジェクトの .csファイルに using XGamingRuntime.Interop; を追加します。
呼び出しを追加して、ゲームランタイムを初期化します。
```
Int32 hr = SDK.XGameRuntimeInitialize();
```
呼び出しを追加して、Xbox サービスを初期化します。
```
Int32 hresult = SDK.XBL.XblInitialize(SCID);
```
SCID をパートナーセンタープロジェクトの SCID を含む文字列に置き換えます。

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

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

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

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

ゲームで 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 の統合

ゲームランタイムサービスと Xbox サービス API の要件のプロジェクトへの追加

MicrosoftGame.config の更新

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

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

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

テストアカウントの作成

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

公開

その他のリソース

次の方法で共有

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

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

C# ゲームへの GDK の統合

ゲーム ランタイム サービスと Xbox サービス API の要件のプロジェクトへの追加

MicrosoftGame.config の更新

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

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

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

テスト アカウントの作成

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

公開

その他のリソース

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

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

ゲームランタイムサービスと Xbox サービス API の要件のプロジェクトへの追加

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

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

テストアカウントの作成