Skip to main content
このウォークスルーは、小規模な sample-game タイトルの作成、XBOX Series X|S コンソール向けのビルド、ゲーム一式の XBOX 開発機へのデプロイ、起動失敗の診断、インストール可能な XVC の作成までの、エンドツーエンドのプロセスをドキュメント化したものです。 完成したサンプルは C++、Direct3D 12、および XBOX 拡張を伴う GDK (GDKX) を使用しています。また、オプションのレンダリング ヘルパーとして DirectXTK12 も使用しています。両方のパドルはコンピューター制御なので、グラフィックス、ゲームプレイ、エフェクトを反復しながらゲームを無人で実行できます。
GitHub や WinGet 経由で入手できる公開版 GDK は、Windows PC のゲーム開発のみをサポートします。XBOX コンソールの実行ファイルをコンパイルしてデプロイするには、XBOX Secure Downloads から XBOX 拡張を伴う GDK (GDKX) をインストールしてください。アクセスには承認済みの XBOX 開発者アカウントが必要です。ID@XBOX オンボーディングGDK のリソースとダウンロードにアクセスする を参照してください。

何を作るか

このウォークスルーの最後には、以下が得られます:
  • ネイティブ 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 を開いて、空のルート フォルダーを作成します。
このウォークスルーで使用する最終的なプロジェクト レイアウトは以下のとおりです:
Visual Studio は Direct3D 12 XBOX Game テンプレートから DeviceResources.*Main.cpppch.*StepTimer.h、シェル ビジュアルの PNG ファイルを生成します。サンプル固有のソースを追加する際も、これらの生成ファイルは残してください。

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

GDKX と共にインストールされる XBOX Series X|S VS 2022 Gaming Command Prompt を開きます。ショートカットは通常、スタート メニューの Microsoft GDK の下にあります。 環境は通常のコマンド プロンプトから初期化することもできます:
XBOX のビルドおよびデプロイ ツールが利用できることを確認します:
以下の場合、GDK のインストールはコンソール開発の準備が整っていません:
  • GXDKEDITION が空である。
  • XBOX コマンド プロンプトのショートカットがない。
  • Visual Studio に XBOX プロジェクト テンプレートが表示されない。
  • Gaming.XBOX.Scarlett.x64 MSBuild プラットフォームが利用できない。
  • xbconnectxbapp が見つからない。
Desktop GDK のコマンド プロンプトと Desktop テンプレートのみが利用可能な場合、GDKX ではなく公開版の PC GDK がインストールされている可能性があります。

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

1

Visual Studio 2022 を開いて [新しいプロジェクトの作成] を選択します

[言語]C++[プラットフォーム]XBOX[プロジェクトの種類]Games に設定します。
2

Direct3D 12 XBOX Game を選択します

プロジェクト名を sample-game、場所を D:\repos\sample-game に設定します。
3

[ソリューションとプロジェクトを同じディレクトリに配置する] のチェックは外したままにします

ソリューションがルートに、プロジェクトが D:\repos\sample-game\sample-game に配置されるようにします。
4

プロジェクトを作成します

サポートされているワークフローは、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 プロパティ グループに次を設定します:
Visual Studio Configuration Manager を使って、以下のソリューション構成を確認します: タイトルが XBOX Series X|S コンソールのみをサポートする場合は、XBOX One ファミリー コンソールの構成を省略できます。同じタイトルを世代間で出荷する方法については、Cross-gen を参照してください。

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

依存関係やゲーム コードを追加する前に、生成されたテンプレートをビルドします。これにより、ツールチェーンの問題とサンプルによって混入した問題を分離できます。 XBOX Series X|S VS 2022 Gaming Command Prompt から:
XBOX One ファミリー コンソール向けには、XBOX One コマンド環境を初期化して XBOX One プラットフォームをビルドします:
素の XBOX テンプレートが正常にビルドされるまでは、続行しないでください。

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

DirectXTK12 は GDK タイトルの作成に必須ではありません。XBOX GDK テンプレートは、Direct3D 12 に対して直接ゲームをビルドするために必要な Direct3D 12 デバイス、コマンド キュー、スワップ チェーン、ゲーム ループを既に提供しています。 このサンプルでは、スプライト レンダリング、ディスクリプタ管理、テクスチャ ローディング、リソース アップロード、グラフィックス メモリ管理に必要な低レベル レンダリング ユーティリティ コードの量を減らすため、独立した Microsoft オープン ソース ライブラリの DirectXTK12 を使用します。タイトル側は、これらのヘルパーを独自のエンジンや直接の D3D12 実装に置き換えても構いません。 DirectXTK12 をプロジェクトにクローンします:
Visual Studio で:
  1. external\DirectXTK12\DirectXTK_GDKX_2022.vcxproj をソリューションに追加します。
  2. sample-game から DirectXTK12 をプロジェクト参照として追加します。
  3. $(SolutionDir)external\DirectXTK12\Inc をインクルード ディレクトリに追加します。
  4. 両方のプロジェクトを同じ XBOX プラットフォームと構成でビルドします。
sample-game プロジェクトは次のプロパティを使用します:
そして、インクルード パスとプロジェクト参照を追加します:
このプロジェクトでは、DirectXTK12 のシェーダー ビルド コマンドを変更し、CompileShaders.cmd を明示的なプロジェクト相対パスで呼び出すようにしました:
これにより、MSBuild がシェーダー コンパイラを呼び出す際に、現在のコマンド ディレクトリに依存することを避けられます。

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

サンプルはゲームプレイの状態とレンダリングを分離しているため、Direct3D コードを変更せずにシミュレーションを調整できます。 DeviceResources.*Main.cpppch.*StepTimer.h、および 5 つのシェル ビジュアル PNG ファイルなど、テンプレートで生成されたファイルはそのまま残してください。以下のサンプル固有のファイルをプロジェクトに追加します:

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

このプロジェクトは、テンプレートの StepTimer120 Hz 固定更新 で使用します。固定ステップは、フレーム時間が変動しても衝突応答と AI 挙動を安定させます。 シミュレーションは以下を含みます:
  • 2 つのパドル状態。
  • 1 つの円形パック状態。
  • 左右のサイドのスコア。
  • サーブ遅延とサーブ方向の交代。
  • パドル、壁、ゴール衝突の衝突イベント。

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

各パドルを軸整列の矩形として、パックを円として扱います:
  1. パドル矩形上でパック中心に最も近い点を見つけます。
  2. その点からパック中心までの二乗距離を計算します。
  3. 距離がパック半径の二乗以下の場合、衝突が発生しています。
  4. 重複を繰り返さないよう、パックをパドルの外側に移動します。
  5. 衝突オフセットとパドル速度から出射角を計算します。
  6. パックの速度を最大値まで少しずつ上げます。
これにより、パックが正方形のテクスチャから描画されていても、物理演算は円形のままに保たれます。

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

各パドルは:
  • パックがその水平位置と交差する場所を予測します。
  • 予測座標をアリーナの上下の壁で反射します。
  • 一定の反応間隔でターゲットを更新します。
  • スナップではなく、加速度と最大速度の制限を使用します。
  • 決定的な小さなターゲティング誤差を加えます。
ゲームで得点が入るようにするため、各サイドは時折、短いミス ウィンドウに入り、予測した迎撃点から意図的に離れます。両方のパドルが同時に外さないよう、最初のミス タイマーはずらしてください。

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

以下を作成します:
  • GraphicsMemory
  • 白テクスチャとパック テクスチャを含むディスクリプタ ヒープ。
  • 通常アルファの SpriteBatch
  • パーティクル用の加算 SpriteBatch
  • ResourceUploadBatchCreateDDSTextureFromFile による 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 から実行します:
両方の DDS ファイルを sample-game.vcxproj のデプロイ コンテンツとして登録します:
標準ヘッダーに DX10 拡張を加えた DDS ファイルは、ピクセル データの前に 148 バイト あります。当初のセッションでは、独自の DDS ライターが 152 バイトを出力し、タイトルはテクスチャの読み込み中に 0x8007000D で失敗しました。独自の DDS ライターを使用する場合は、デプロイ前にヘッダー レイアウトを検証してください。

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

XBOX Series X|S VS 2022 Gaming Command Prompt から:
ルーズ ビルドの出力先は以下です:
出力に以下が含まれていることを確認します:
  • 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 を参照してください。

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

Tools IP アドレスまたはホスト名を使って既定のコンソールを設定します:
保存されているコンソールを確認します:
接続の診断を実行します:
タイトルが Partner Center のサンドボックスを使用する場合は、大文字と小文字を区別するサンドボックス ID を設定してコンソールを再起動します:
現在のサンドボックスを表示します:

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

ビルド出力フォルダー全体をデプロイします:
sample-game.exe だけをコピーしないでください。タイトルには MicrosoftGame.config、アセット、ランタイム依存関係、シェル イメージ、デプロイ メタデータも必要です。実行ファイルだけをコピーしたものは、有効な完全デプロイではありません。
アセットや構成を変更した後にクリーンに再デプロイする場合は:
デプロイ後は xbapp list を使って、登録されたパッケージのフル名とアプリケーション ユーザー モデル ID (AUMID) を確認します。AUMID の末尾は !Game です。

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

xbapp list が報告した AUMID を厳密に指定して起動します:
タイトル プロセスを待機します:
パッケージが実行中であることを確認します:
期待される結果は以下です:
この時点で、オートプレイの試合が開発機に表示されているはずです。

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

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

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

デバッグ出力を監視する

あるコマンド プロンプトでデバッグ出力モニターを起動します:
別のコマンド プロンプトからゲームを起動します:
サンプルでは以下の周辺に OutputDebugStringA メッセージを追加しました:
  • ゲームの初期化。
  • DirectXTK12 のリソース作成。
  • 各テクスチャの読み込み。
  • スプライト パイプラインの作成。
  • テクスチャ アップロードの完了。
  • フレーム内の例外。
当初のセッションでの起動失敗は、white.dds の読み込みに切り分けられました。ローダーは 0x8007000D を返し、これは不正な DDS データを示します。DDS ヘッダーを修正し、クリーンに完全デプロイし直すことで起動が修正されました。 より詳しい起動診断には、失敗を再現しながら xbWatson を実行してください。エラー ハンドリング も参照してください。

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

コードのみの変更の場合はほとんど:
  1. Debug をビルドします。
  2. 実行中のパッケージを終了します。
  3. 出力フォルダー全体をデプロイします。
  4. 登録済みの AUMID を起動します。
  5. パッケージの状態を照会します。
MicrosoftGameConfig.mgc、アセット、デプロイ メタデータへの変更については、再デプロイ前に古いルーズ デプロイをアンインストールしてください。これにより、古いファイルや登録データが修正を隠してしまうことを防ぎます。

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

ルーズ デプロイは最速の開発ループです。製品版に近いインストールをテストしたり、Partner Center 用にパッケージを準備したりする必要があるときに XVC を作成します。完全なパッケージング リファレンスについては 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 コンソールの場合、重要な構造は以下です:
XBOX Series X|S コンソールのパッケージには TargetDeviceFamily="Scarlett" が必要です。XBOX One ファミリー コンソール用パッケージには別の構成を使用してください。

Release 構成をビルドする

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

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

レイアウトを生成する

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

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

既定のテスト暗号化は開発機へのローカル インストールに便利です:
MicrosoftGame.configStoreId が含まれている場合、通常の Store 提出には /productid は不要です。ドキュメント化されたオフラインまたはディスク シナリオが特に要求する場合を除き、省略してください。

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

sample-game パッケージは、インストールと起動を検証できるよう、最初は開発機向けのテスト暗号化で作成されました。提出予定のパッケージについては、現行のパッケージング ポリシーに従い、/lk または /l を使用してください。 推奨される再現可能な /lk ワークフローは以下です:
LEKB を安全に保管してください。ソース管理にコミットしないでください。

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

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

よくある問題と修正

関連項目

最終更新日 2026年8月24日