> ## 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.

# GDKX で最初のコンソール タイトルをビルドして実行する

> エンドツーエンドのウォークスルー: ネイティブ GDKX プロジェクトを作成し、DirectXTK12 を追加して XBOX Series X|S 向けにビルドし、開発機にデプロイして、インストール可能な XVC を生成します。

このウォークスルーは、小規模な `sample-game` タイトルの作成、XBOX Series X|S コンソール向けのビルド、ゲーム一式の XBOX 開発機へのデプロイ、起動失敗の診断、インストール可能な XVC の作成までの、エンドツーエンドのプロセスをドキュメント化したものです。

完成したサンプルは C++、Direct3D 12、および XBOX 拡張を伴う GDK (GDKX) を使用しています。また、オプションのレンダリング ヘルパーとして [DirectXTK12](https://github.com/microsoft/DirectXTK12) も使用しています。両方のパドルはコンピューター制御なので、グラフィックス、ゲームプレイ、エフェクトを反復しながらゲームを無人で実行できます。

<Warning>
  GitHub や WinGet 経由で入手できる公開版 GDK は、Windows PC のゲーム開発のみをサポートします。XBOX コンソールの実行ファイルをコンパイルしてデプロイするには、XBOX Secure Downloads から XBOX 拡張を伴う GDK (GDKX) をインストールしてください。アクセスには承認済みの XBOX 開発者アカウントが必要です。[ID@XBOX オンボーディング](/home/onboarding) と [GDK のリソースとダウンロードにアクセスする](/home/onboarding-access/access-resources) を参照してください。
</Warning>

## 何を作るか

このウォークスルーの最後には、以下が得られます:

* ネイティブ XBOX GDK プロジェクト (UWP プロジェクトではない)。
* XBOX Series X|S コンソールおよび XBOX One ファミリー コンソール向けの Debug、Profile、Release 構成。
* スコアリング、予測的なパドル AI、パーティクル エフェクト、モーション トレイル、テクスチャ付き円形パックを備えたオートプレイのサンプル ゲーム。
* XBOX 開発機上で実行される完全なルーズ ファイル デプロイ。
* 開発機にインストールしてテストできる、オプションの Store 関連付け済み XVC。

## 開始する前に

このウォークスルーは以下の環境で検証しました:

* Visual Studio 2022 Enterprise 17.14。
* April 2026 Update 2 GDKX、エディション `260402`。
* XBOX Series X|S コンソール向け `Gaming.XBOX.Scarlett.x64`。
* XBOX One ファミリー コンソール向け `Gaming.XBOX.XboxOne.x64`。
* DirectXTK12 コミット `e656d54637b2830fc6eb5ecd9b329a9c72cb87d4`。

別のリリースでウォークスルーを実施している場合は、`260402` の代わりに開発 PC にインストールされている GDK エディションを使用してください。

## ステップ 1: 作業フォルダーを作成する

PowerShell を開いて、空のルート フォルダーを作成します。

```powershell theme={null}
New-Item -ItemType Directory -Path D:\repos\sample-game -Force
```

このウォークスルーで使用する最終的なプロジェクト レイアウトは以下のとおりです:

```text theme={null}
D:\repos\sample-game
|-- external
|   `-- DirectXTK12
|-- tools
|   `-- BuildAssets.ps1
|-- sample-game
|   |-- Assets
|   |-- DeviceResources.cpp
|   |-- DeviceResources.h
|   |-- Game.cpp
|   |-- Game.h
|   |-- GameTuning.h
|   |-- GraphicsLogo.png
|   |-- LargeLogo.png
|   |-- Main.cpp
|   |-- MicrosoftGameConfig.mgc
|   |-- ParticleSystem.cpp
|   |-- ParticleSystem.h
|   |-- sample-gameSimulation.cpp
|   |-- sample-gameSimulation.h
|   |-- pch.cpp
|   |-- pch.h
|   |-- SmallLogo.png
|   |-- SplashScreen.png
|   |-- StepTimer.h
|   |-- StoreLogo.png
|   `-- sample-game.vcxproj
`-- sample-game.sln
```

Visual Studio は **Direct3D 12 XBOX Game** テンプレートから `DeviceResources.*`、`Main.cpp`、`pch.*`、`StepTimer.h`、シェル ビジュアルの PNG ファイルを生成します。サンプル固有のソースを追加する際も、これらの生成ファイルは残してください。

## ステップ 2: XBOX GDK のインストールを検証する

GDKX と共にインストールされる **XBOX Series X|S VS 2022 Gaming Command Prompt** を開きます。ショートカットは通常、スタート メニューの **Microsoft GDK** の下にあります。

環境は通常のコマンド プロンプトから初期化することもできます:

```cmd theme={null}
call "C:\Program Files (x86)\Microsoft GDK\Command Prompts\GamingXboxVars.cmd" GamingXboxScarlettVS2022 260402
```

XBOX のビルドおよびデプロイ ツールが利用できることを確認します:

```cmd theme={null}
echo %GXDKEDITION%
where msbuild
where cl
where xbconnect
where xbapp
where makepkg
```

以下の場合、GDK のインストールはコンソール開発の準備が整っていません:

* `GXDKEDITION` が空である。
* XBOX コマンド プロンプトのショートカットがない。
* Visual Studio に XBOX プロジェクト テンプレートが表示されない。
* `Gaming.XBOX.Scarlett.x64` MSBuild プラットフォームが利用できない。
* `xbconnect` や `xbapp` が見つからない。

Desktop GDK のコマンド プロンプトと Desktop テンプレートのみが利用可能な場合、GDKX ではなく公開版の PC GDK がインストールされている可能性があります。

## ステップ 3: ネイティブ XBOX プロジェクトを作成する

<Steps>
  <Step title="Visual Studio 2022 を開いて [新しいプロジェクトの作成] を選択します">
    **\[言語]** を **C++**、**\[プラットフォーム]** を **XBOX**、**\[プロジェクトの種類]** を **Games** に設定します。
  </Step>

  <Step title="Direct3D 12 XBOX Game を選択します">
    プロジェクト名を `sample-game`、場所を `D:\repos\sample-game` に設定します。
  </Step>

  <Step title="[ソリューションとプロジェクトを同じディレクトリに配置する] のチェックは外したままにします">
    ソリューションがルートに、プロジェクトが `D:\repos\sample-game\sample-game` に配置されるようにします。
  </Step>

  <Step title="プロジェクトを作成します" />
</Steps>

サポートされているワークフローは、Visual Studio からプロジェクトを作成することです。手動で `d3d12game_gx` テンプレート ファイルをコピーする方法は復旧手段であり、推奨される新規プロジェクト ワークフローではありません。

### プロジェクトが UWP でないことを確認する

ゲーム コードを追加する前に、プロジェクトが以下を満たすことを確認します:

* `MicrosoftGameConfig.mgc` を含む。
* `Gaming.XBOX.*.x64` プロジェクト プラットフォームを使用する。
* XBOX GDK プラットフォーム ライブラリをリンクする。
* `Package.appxmanifest` をタイトル構成として使用しない。
* Universal Windows テンプレートではなく **Direct3D 12 XBOX Game** から作成された。

プロジェクトが UWP である場合は削除して、XBOX GDK テンプレートから新しいプロジェクトを作成してください。生成された UWP プロジェクトを変換するよりも、正しいテンプレートから始める方がエラーが少なくなります。

## ステップ 4: GDK エディションをピン留めし、コンソール ターゲットを構成する

GDK エディションをピン留めすることで、将来の GDK インストールがプロジェクトで使用されるツールチェーンを気づかないうちに変更することを防げます。

`sample-game.vcxproj` の main プロパティ グループに次を設定します:

```xml theme={null}
<XdkEditionTarget>260402</XdkEditionTarget>
```

Visual Studio Configuration Manager を使って、以下のソリューション構成を確認します:

| 構成      | プラットフォーム                   |
| ------- | -------------------------- |
| Debug   | `Gaming.XBOX.Scarlett.x64` |
| Profile | `Gaming.XBOX.Scarlett.x64` |
| Release | `Gaming.XBOX.Scarlett.x64` |
| Debug   | `Gaming.XBOX.XboxOne.x64`  |
| Profile | `Gaming.XBOX.XboxOne.x64`  |
| Release | `Gaming.XBOX.XboxOne.x64`  |

タイトルが XBOX Series X|S コンソールのみをサポートする場合は、XBOX One ファミリー コンソールの構成を省略できます。同じタイトルを世代間で出荷する方法については、[Cross-gen](/build/console-features/cross-gen/cross-gen-overview) を参照してください。

## ステップ 5: 未変更のテンプレートをビルドする

依存関係やゲーム コードを追加する前に、生成されたテンプレートをビルドします。これにより、ツールチェーンの問題とサンプルによって混入した問題を分離できます。

**XBOX Series X|S VS 2022 Gaming Command Prompt** から:

```cmd theme={null}
msbuild D:\repos\sample-game\sample-game.sln /m /restore /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal
```

XBOX One ファミリー コンソール向けには、XBOX One コマンド環境を初期化して XBOX One プラットフォームをビルドします:

```cmd theme={null}
call "C:\Program Files (x86)\Microsoft GDK\Command Prompts\GamingXboxVars.cmd" GamingXboxVS2022 260402
msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Debug /p:Platform=Gaming.XBOX.XboxOne.x64 /nologo /verbosity:minimal
```

<Warning>
  素の XBOX テンプレートが正常にビルドされるまでは、続行しないでください。
</Warning>

## ステップ 6: DirectXTK12 をオプション ヘルパーとして追加する

DirectXTK12 は GDK タイトルの作成に必須ではありません。XBOX GDK テンプレートは、Direct3D 12 に対して直接ゲームをビルドするために必要な Direct3D 12 デバイス、コマンド キュー、スワップ チェーン、ゲーム ループを既に提供しています。

このサンプルでは、スプライト レンダリング、ディスクリプタ管理、テクスチャ ローディング、リソース アップロード、グラフィックス メモリ管理に必要な低レベル レンダリング ユーティリティ コードの量を減らすため、独立した Microsoft オープン ソース ライブラリの DirectXTK12 を使用します。タイトル側は、これらのヘルパーを独自のエンジンや直接の D3D12 実装に置き換えても構いません。

DirectXTK12 をプロジェクトにクローンします:

```powershell theme={null}
Set-Location D:\repos\sample-game
New-Item -ItemType Directory -Path .\external -Force
git clone https://github.com/microsoft/DirectXTK12.git .\external\DirectXTK12
git -C .\external\DirectXTK12 checkout e656d54637b2830fc6eb5ecd9b329a9c72cb87d4
```

Visual Studio で:

1. `external\DirectXTK12\DirectXTK_GDKX_2022.vcxproj` をソリューションに追加します。
2. `sample-game` から DirectXTK12 をプロジェクト参照として追加します。
3. `$(SolutionDir)external\DirectXTK12\Inc` をインクルード ディレクトリに追加します。
4. 両方のプロジェクトを同じ XBOX プラットフォームと構成でビルドします。

`sample-game` プロジェクトは次のプロパティを使用します:

```xml theme={null}
<DirectXTK12Dir>$(SolutionDir)external\DirectXTK12\</DirectXTK12Dir>
```

そして、インクルード パスとプロジェクト参照を追加します:

```xml theme={null}
<AdditionalIncludeDirectories>$(DirectXTK12Dir)Inc;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
```

```xml theme={null}
<ProjectReference Include="$(DirectXTK12Dir)DirectXTK_GDKX_2022.vcxproj">
  <Project>{94F17A4D-611B-4B81-8806-B6735910AB31}</Project>
  <Name>DirectXTK12</Name>
</ProjectReference>
```

このプロジェクトでは、DirectXTK12 のシェーダー ビルド コマンドを変更し、`CompileShaders.cmd` を明示的なプロジェクト相対パスで呼び出すようにしました:

```xml theme={null}
Command="&quot;$(ProjectDir)Src\Shaders\CompileShaders.cmd&quot; gxdk scarlett"
```

これにより、MSBuild がシェーダー コンパイラを呼び出す際に、現在のコマンド ディレクトリに依存することを避けられます。

## ステップ 7: ゲーム コードを追加する

サンプルはゲームプレイの状態とレンダリングを分離しているため、Direct3D コードを変更せずにシミュレーションを調整できます。

`DeviceResources.*`、`Main.cpp`、`pch.*`、`StepTimer.h`、および 5 つのシェル ビジュアル PNG ファイルなど、テンプレートで生成されたファイルはそのまま残してください。以下のサンプル固有のファイルをプロジェクトに追加します:

| ファイル                           | 目的                              |
| ------------------------------ | ------------------------------- |
| `GameTuning.h`                 | アリーナ、パドル、パック、AI、トレイル、パーティクルの定数。 |
| `sample-gameSimulation.h/.cpp` | パックの動き、パドルの動き、衝突、スコアリング、サーブ、AI。 |
| `ParticleSystem.h/.cpp`        | 固定サイズのパーティクル プールと衝突エミッター。       |
| `Game.h/.cpp`                  | DirectXTK12 リソース、ゲームの更新、レンダリング。 |
| `tools\BuildAssets.ps1`        | 白いスプライトとパック用の再現可能な DDS 生成。      |

### 固定ステップ シミュレーションを使用する

このプロジェクトは、テンプレートの `StepTimer` を **120 Hz 固定更新** で使用します。固定ステップは、フレーム時間が変動しても衝突応答と AI 挙動を安定させます。

シミュレーションは以下を含みます:

* 2 つのパドル状態。
* 1 つの円形パック状態。
* 左右のサイドのスコア。
* サーブ遅延とサーブ方向の交代。
* パドル、壁、ゴール衝突の衝突イベント。

### 円形パックの衝突を実装する

各パドルを軸整列の矩形として、パックを円として扱います:

1. パドル矩形上でパック中心に最も近い点を見つけます。
2. その点からパック中心までの二乗距離を計算します。
3. 距離がパック半径の二乗以下の場合、衝突が発生しています。
4. 重複を繰り返さないよう、パックをパドルの外側に移動します。
5. 衝突オフセットとパドル速度から出射角を計算します。
6. パックの速度を最大値まで少しずつ上げます。

これにより、パックが正方形のテクスチャから描画されていても、物理演算は円形のままに保たれます。

### 予測的なオートプレイを追加する

各パドルは:

* パックがその水平位置と交差する場所を予測します。
* 予測座標をアリーナの上下の壁で反射します。
* 一定の反応間隔でターゲットを更新します。
* スナップではなく、加速度と最大速度の制限を使用します。
* 決定的な小さなターゲティング誤差を加えます。

ゲームで得点が入るようにするため、各サイドは時折、短いミス ウィンドウに入り、予測した迎撃点から意図的に離れます。両方のパドルが同時に外さないよう、最初のミス タイマーはずらしてください。

### DirectXTK12 でシーンをレンダリングする

以下を作成します:

* `GraphicsMemory`。
* 白テクスチャとパック テクスチャを含むディスクリプタ ヒープ。
* 通常アルファの `SpriteBatch`。
* パーティクル用の加算 `SpriteBatch`。
* `ResourceUploadBatch` と `CreateDDSTextureFromFile` による DDS テクスチャ。

`SpriteBatch` を使ってアリーナ、センター ライン、パドル、スコア、パック トレイル、パックを描画します。パーティクルは加算パスで描画します。

完成したサンプルは 1920 × 1080 の仮想座標系でレンダリングし、そのシーンを出力ビューポートにスケールします。

### エフェクトを控えめに保つ

最終的なチューニングでは以下を使用しました:

* 短く指数的に減衰する画面揺れ。
* より小さな筋状の衝突パーティクル。
* 壁の衝突よりもパドルの衝突で多くのパーティクル。
* ゴール時のより強いバースト。
* 低アルファのパック トレイル。
* 短時間の緑色の衝突フラッシュ。

これらの変更により、ゲームが漫画的に見えたり、パドルの衝突が視覚的に不快になったりせず、衝突フィードバックが保たれました。

## ステップ 8: テクスチャ アセットを作成してデプロイする

サンプルには以下が必要です:

* `Assets\white.dds`: 矩形とパーティクルの描画に使用する 1 × 1 の白 RGBA テクスチャ。
* `Assets\xbox_logo.dds`: パックに使用する 256 × 256 の RGBA テクスチャ。

アセット スクリプトは以下を行います:

1. ソースのロゴを読み込みます。
2. 256 × 256 にリサイズします。
3. フェザリングされた円形のアルファ マスクを適用します。
4. DX10 ヘッダー付きの RGBA8 DDS を書き出します。
5. 1 × 1 の白 DDS を作成します。

PowerShell から実行します:

```powershell theme={null}
Set-Location D:\repos\sample-game
.\tools\BuildAssets.ps1
```

両方の DDS ファイルを `sample-game.vcxproj` のデプロイ コンテンツとして登録します:

```xml theme={null}
<CopyFileToFolders Include="Assets\white.dds">
  <DeploymentContent>true</DeploymentContent>
  <DestinationFileName>Assets\%(Filename)%(Extension)</DestinationFileName>
</CopyFileToFolders>
<CopyFileToFolders Include="Assets\xbox_logo.dds">
  <DeploymentContent>true</DeploymentContent>
  <DestinationFileName>Assets\%(Filename)%(Extension)</DestinationFileName>
</CopyFileToFolders>
```

<Note>
  標準ヘッダーに DX10 拡張を加えた DDS ファイルは、ピクセル データの前に **148 バイト** あります。当初のセッションでは、独自の DDS ライターが 152 バイトを出力し、タイトルはテクスチャの読み込み中に `0x8007000D` で失敗しました。独自の DDS ライターを使用する場合は、デプロイ前にヘッダー レイアウトを検証してください。
</Note>

## ステップ 9: ゲームをビルドする

XBOX Series X|S VS 2022 Gaming Command Prompt から:

```cmd theme={null}
msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal
```

ルーズ ビルドの出力先は以下です:

```text theme={null}
D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug
```

出力に以下が含まれていることを確認します:

* `sample-game.exe`
* `MicrosoftGame.config`
* シェル ビジュアルの PNG ファイル
* `Assets\white.dds`
* `Assets\xbox_logo.dds`
* 必要なランタイム DLL
* ビルドで生成される Game OS イメージまたはその他のデプロイ メタデータ

プロジェクト ソースは `MicrosoftGameConfig.mgc` という名前です。GDK の `MGCCompile` ビルド項目がこれを検証して、ビルド出力に `MicrosoftGame.config` を出力します。デプロイとパッケージングはどちらも生成された `.config` ファイルを使用します。[Game config](/build/core-features/common/game-config/MicrosoftGameConfig-Overview) を参照してください。

## ステップ 10: XBOX 開発機に接続する

Tools IP アドレスまたはホスト名を使って既定のコンソールを設定します:

```cmd theme={null}
xbconnect <console-address>
```

保存されているコンソールを確認します:

```cmd theme={null}
xbconnect /B
```

接続の診断を実行します:

```cmd theme={null}
xbconnect /DX
```

タイトルが Partner Center のサンドボックスを使用する場合は、大文字と小文字を区別するサンドボックス ID を設定してコンソールを再起動します:

```cmd theme={null}
xbconfig sandboxid=<sandbox-id>
xbreboot
xbconnect /WS
```

現在のサンドボックスを表示します:

```cmd theme={null}
xbconfig sandboxid
```

## ステップ 11: ゲーム全体をデプロイする

ビルド出力フォルダー全体をデプロイします:

```cmd theme={null}
xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug"
```

<Warning>
  `sample-game.exe` だけをコピーしないでください。タイトルには `MicrosoftGame.config`、アセット、ランタイム依存関係、シェル イメージ、デプロイ メタデータも必要です。実行ファイルだけをコピーしたものは、有効な完全デプロイではありません。
</Warning>

アセットや構成を変更した後にクリーンに再デプロイする場合は:

```cmd theme={null}
xbapp list
xbapp terminate <package-family-name-or-AUMID>
xbapp uninstall <package-full-name>
xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug"
```

デプロイ後は `xbapp list` を使って、登録されたパッケージのフル名とアプリケーション ユーザー モデル ID (AUMID) を確認します。AUMID の末尾は `!Game` です。

## ステップ 12: ゲームを起動して検証する

`xbapp list` が報告した AUMID を厳密に指定して起動します:

```cmd theme={null}
xbapp launch <package-family-name>!Game
```

タイトル プロセスを待機します:

```cmd theme={null}
xbconnect /WTP:60
```

パッケージが実行中であることを確認します:

```cmd theme={null}
xbapp query <package-full-name>
```

期待される結果は以下です:

```text theme={null}
Package execution state: 1 (running)
```

この時点で、オートプレイの試合が開発機に表示されているはずです。

## ステップ 13: 起動直後の失敗を診断する

ゲームが即座に終了した場合、実行ファイルがコピーされたというだけでデプロイが成功したと決めつけないでください。

### 直近のタイトル実行結果を取得する

```cmd theme={null}
xbapp lastgamedetails
```

### デバッグ出力を監視する

あるコマンド プロンプトでデバッグ出力モニターを起動します:

```cmd theme={null}
xbdbgmon /t /v
```

別のコマンド プロンプトからゲームを起動します:

```cmd theme={null}
xbapp launch <package-family-name>!Game
```

サンプルでは以下の周辺に `OutputDebugStringA` メッセージを追加しました:

* ゲームの初期化。
* DirectXTK12 のリソース作成。
* 各テクスチャの読み込み。
* スプライト パイプラインの作成。
* テクスチャ アップロードの完了。
* フレーム内の例外。

当初のセッションでの起動失敗は、`white.dds` の読み込みに切り分けられました。ローダーは `0x8007000D` を返し、これは不正な DDS データを示します。DDS ヘッダーを修正し、クリーンに完全デプロイし直すことで起動が修正されました。

より詳しい起動診断には、失敗を再現しながら `xbWatson` を実行してください。[エラー ハンドリング](/build/core-features/common/async/index) も参照してください。

## ステップ 14: 安全に反復する

コードのみの変更の場合はほとんど:

1. Debug をビルドします。
2. 実行中のパッケージを終了します。
3. 出力フォルダー全体をデプロイします。
4. 登録済みの AUMID を起動します。
5. パッケージの状態を照会します。

`MicrosoftGameConfig.mgc`、アセット、デプロイ メタデータへの変更については、再デプロイ前に古いルーズ デプロイをアンインストールしてください。これにより、古いファイルや登録データが修正を隠してしまうことを防ぎます。

## オプション: XVC を作成してテストする

ルーズ デプロイは最速の開発ループです。製品版に近いインストールをテストしたり、Partner Center 用にパッケージを準備したりする必要があるときに XVC を作成します。完全なパッケージング リファレンスについては [Packaging](/build/core-features/common/packaging/overviews/packaging) を参照してください。

### MicrosoftGame.config を Partner Center に関連付ける

以下の値は製品の **\[Game setup]** > **\[Identity details]** から取得します:

* Package Identity Name。
* Package Identity Publisher。
* Publisher Display Name。
* Store ID。
* XBOX Title ID。
* MSA App ID。

ソース管理の例ではプレースホルダーを使用してください。別製品のアイデンティティをコピーしないでください。

XBOX Series X|S コンソールの場合、重要な構造は以下です:

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
  <Identity Name="REPLACE-WITH-PACKAGE-IDENTITY-NAME"
            Publisher="REPLACE-WITH-PACKAGE-IDENTITY-PUBLISHER"
            Version="1.0.0.0"/>

  <ExecutableList>
    <Executable Name="sample-game.exe"
                TargetDeviceFamily="Scarlett"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="sample-game"
                PublisherDisplayName="REPLACE-WITH-PUBLISHER-DISPLAY-NAME"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="sample-game"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>

  <MSAAppId>REPLACE-WITH-MSA-APP-ID</MSAAppId>
  <TitleId>REPLACE-WITH-XBOX-TITLE-ID</TitleId>
  <StoreId>REPLACE-WITH-STORE-ID</StoreId>
</Game>
```

XBOX Series X|S コンソールのパッケージには `TargetDeviceFamily="Scarlett"` が必要です。XBOX One ファミリー コンソール用パッケージには別の構成を使用してください。

### Release 構成をビルドする

```cmd theme={null}
msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Release /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal
```

### パッケージ コンテンツをステージングする

Release 出力をステージング ディレクトリにコピーしますが、`gameos.xvd` はコンテンツ マップの外側に置き、PDB ファイルは通常のパッケージ コンテンツとしては含めません。

```powershell theme={null}
$source  = 'D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release'
$root    = 'D:\repos\sample-game\packages\Scarlett\Release'
$staging = Join-Path $root 'staging'
$output  = Join-Path $root 'output'

Remove-Item $staging, $output -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path $staging, $output -Force | Out-Null

Get-ChildItem $source -Force |
    Where-Object { $_.Name -ne 'gameos.xvd' -and $_.Extension -ne '.pdb' } |
    Copy-Item -Destination $staging -Recurse -Force
```

### レイアウトを生成する

```cmd theme={null}
makepkg genmap /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging"
```

この小さなサンプルでは、生成されたレイアウトには 1 つの起動チャンクが含まれます:

```xml theme={null}
<Package>
  <Chunk Id="1000" Marker="Launch">
    <FileGroup DestinationPath="."        SourcePath="."        Include="*.*" />
    <FileGroup DestinationPath=".\Assets" SourcePath=".\Assets" Include="*.*" />
  </Chunk>
</Package>
```

### 開発機向けのテスト パッケージを作成する

既定のテスト暗号化は開発機へのローカル インストールに便利です:

```cmd theme={null}
makepkg pack /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging" /pd "D:\repos\sample-game\packages\Scarlett\Release\output" /gameos "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release\gameos.xvd" /symbolpaths "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release" /validationcritical /loggable
```

<Tip>
  `MicrosoftGame.config` に `StoreId` が含まれている場合、通常の Store 提出には `/productid` は不要です。ドキュメント化されたオフラインまたはディスク シナリオが特に要求する場合を除き、省略してください。
</Tip>

### Partner Center パッケージには提出用暗号化を使用する

sample-game パッケージは、インストールと起動を検証できるよう、最初は開発機向けのテスト暗号化で作成されました。提出予定のパッケージについては、現行のパッケージング ポリシーに従い、`/lk` または `/l` を使用してください。

推奨される再現可能な `/lk` ワークフローは以下です:

```cmd theme={null}
makepkg genkey /ekb D:\secure\sample-game.lekb
makepkg pack /lk D:\secure\sample-game.lekb /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging" /pd "D:\repos\sample-game\packages\Scarlett\Release\output" /gameos "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release\gameos.xvd" /symbolpaths "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release" /validationcritical /loggable
```

<Warning>
  LEKB を安全に保管してください。ソース管理にコミットしないでください。
</Warning>

### XVC をインストールして起動する

```cmd theme={null}
xbapp install "<path-to-package>.xvc"
xbapp list
xbapp launch <store-associated-package-family-name>!Game
xbapp query <store-associated-package-full-name>
```

テストが完了したらパッケージを終了します:

```cmd theme={null}
xbapp terminate <store-associated-package-family-name>!Game
```

## よくある問題と修正

| 症状                                                 | 原因                                               | 修正                                                                           |
| -------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| Desktop テンプレートのみが利用可能                              | XBOX 拡張なしの公開版 PC GDK がインストールされている                | XBOX Secure Downloads から GDKX とその Visual Studio 統合をインストールします。                |
| プロジェクトが `Package.appxmanifest` を含み UWP をターゲットにしている | 誤った Visual Studio テンプレートを選択した                    | **Direct3D 12 XBOX Game** でプロジェクトを作り直します。                                    |
| `Gaming.XBOX.Scarlett.x64` が利用できない                 | XBOX GDK プラットフォームまたは Visual Studio 拡張が欠落している     | 一致する GDKX リリースと Visual Studio 統合を修復または再インストールします。                            |
| タイトルが起動して即座に終了する                                   | デプロイ ファイルの欠落またはランタイム初期化の失敗                       | ビルド出力全体をデプロイし、`xbapp lastgamedetails` と `xbdbgmon` を確認します。                   |
| DDS の読み込みが `0x8007000D` を返す                        | 不正な DDS ヘッダーまたはサポートされていないデータ                     | DDS を再生成し、148 バイトの DDS と DX10 ヘッダーを検証します。                                    |
| アセットの変更が反映されない                                     | 古いルーズ デプロイが残っている                                 | 終了、アンインストールしてから完全に再デプロイします。                                                  |
| `makepkg` が構成を拒否する                                 | `TargetDeviceFamily` の欠落または誤り                    | XBOX Series X\|S コンソールには `Scarlett`、XBOX One ファミリー コンソールには `XboxOne` を設定します。 |
| 製品アイデンティティが 2 か所以上で指定されている                         | ゲーム構成に既に Store アイデンティティがあるのに `/productid` が追加された | ゲーム構成に `StoreId` を残し、通常の Store 提出では `/productid` を省略します。                     |
| PDB ファイルがパッケージ マップまたは検証の問題を引き起こす                   | シンボルがゲーム コンテンツとして含まれた                            | PDB をステージングから除外し、ビルド ディレクトリを `/symbolpaths` で渡します。                           |
| Store 関連付け起動がハンドシェイク中に失敗するように見える                   | タイトルがまだ起動中である可能性、または診断が不完全                       | `/WaitToExit`、`/show:all`、`/LogModuleLoads` を付けて起動し、パッケージ状態を照会します。           |

## 関連項目

* [新しい GDK タイトルを開発する](/home/build-first-title/developing-new-titles)
* [GDK ツールチェーンをインストール](/home/setup-install/download-install)
* [MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-Overview)
* [Packaging](/build/core-features/common/packaging/overviews/packaging)
* [Series X|S 向けにビルドする](/paths/series-xs/overview)
* [Cross-gen](/build/console-features/cross-gen/cross-gen-overview)


## Related topics

- [新しい GDK タイトルを開発する](/ja-jp/home/build-first-title/developing-new-titles.md)
- [GDK のセットアップとインストール](/ja-jp/home/setup-install/get-started.md)
- [XBOX Series X|S 概要](/ja-jp/paths/series-xs/overview.md)
- [Linux 向け C++ クイックスタート](/ja-jp/services/playfab/sdks/playfab-cpp/quickstart-linux.md)
- [XBOX Manager: コンソールの更新](/ja-jp/tools/tools-console/xbom/manager-tool-updating-console.md)