sample-game タイトルの作成、XBOX Series X|S コンソール向けのビルド、ゲーム一式の XBOX 開発機へのデプロイ、起動失敗の診断、インストール可能な XVC の作成までの、エンドツーエンドのプロセスをドキュメント化したものです。
完成したサンプルは C++、Direct3D 12、および XBOX 拡張を伴う GDK (GDKX) を使用しています。また、オプションのレンダリング ヘルパーとして DirectXTK12 も使用しています。両方のパドルはコンピューター制御なので、グラフィックス、ゲームプレイ、エフェクトを反復しながらゲームを無人で実行できます。
何を作るか
このウォークスルーの最後には、以下が得られます:- ネイティブ 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 を開いて、空のルート フォルダーを作成します。DeviceResources.*、Main.cpp、pch.*、StepTimer.h、シェル ビジュアルの PNG ファイルを生成します。サンプル固有のソースを追加する際も、これらの生成ファイルは残してください。
ステップ 2: XBOX GDK のインストールを検証する
GDKX と共にインストールされる XBOX Series X|S VS 2022 Gaming Command Prompt を開きます。ショートカットは通常、スタート メニューの Microsoft GDK の下にあります。 環境は通常のコマンド プロンプトから初期化することもできます:GXDKEDITIONが空である。- XBOX コマンド プロンプトのショートカットがない。
- Visual Studio に XBOX プロジェクト テンプレートが表示されない。
Gaming.XBOX.Scarlett.x64MSBuild プラットフォームが利用できない。xbconnectやxbappが見つからない。
ステップ 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
プロジェクトを作成します
d3d12game_gx テンプレート ファイルをコピーする方法は復旧手段であり、推奨される新規プロジェクト ワークフローではありません。
プロジェクトが UWP でないことを確認する
ゲーム コードを追加する前に、プロジェクトが以下を満たすことを確認します:MicrosoftGameConfig.mgcを含む。Gaming.XBOX.*.x64プロジェクト プラットフォームを使用する。- XBOX GDK プラットフォーム ライブラリをリンクする。
Package.appxmanifestをタイトル構成として使用しない。- Universal Windows テンプレートではなく Direct3D 12 XBOX Game から作成された。
ステップ 4: GDK エディションをピン留めし、コンソール ターゲットを構成する
GDK エディションをピン留めすることで、将来の GDK インストールがプロジェクトで使用されるツールチェーンを気づかないうちに変更することを防げます。sample-game.vcxproj の main プロパティ グループに次を設定します:
タイトルが XBOX Series X|S コンソールのみをサポートする場合は、XBOX One ファミリー コンソールの構成を省略できます。同じタイトルを世代間で出荷する方法については、Cross-gen を参照してください。
ステップ 5: 未変更のテンプレートをビルドする
依存関係やゲーム コードを追加する前に、生成されたテンプレートをビルドします。これにより、ツールチェーンの問題とサンプルによって混入した問題を分離できます。 XBOX Series X|S VS 2022 Gaming Command Prompt から:ステップ 6: DirectXTK12 をオプション ヘルパーとして追加する
DirectXTK12 は GDK タイトルの作成に必須ではありません。XBOX GDK テンプレートは、Direct3D 12 に対して直接ゲームをビルドするために必要な Direct3D 12 デバイス、コマンド キュー、スワップ チェーン、ゲーム ループを既に提供しています。 このサンプルでは、スプライト レンダリング、ディスクリプタ管理、テクスチャ ローディング、リソース アップロード、グラフィックス メモリ管理に必要な低レベル レンダリング ユーティリティ コードの量を減らすため、独立した Microsoft オープン ソース ライブラリの DirectXTK12 を使用します。タイトル側は、これらのヘルパーを独自のエンジンや直接の D3D12 実装に置き換えても構いません。 DirectXTK12 をプロジェクトにクローンします:external\DirectXTK12\DirectXTK_GDKX_2022.vcxprojをソリューションに追加します。sample-gameから DirectXTK12 をプロジェクト参照として追加します。$(SolutionDir)external\DirectXTK12\Incをインクルード ディレクトリに追加します。- 両方のプロジェクトを同じ XBOX プラットフォームと構成でビルドします。
sample-game プロジェクトは次のプロパティを使用します:
CompileShaders.cmd を明示的なプロジェクト相対パスで呼び出すようにしました:
ステップ 7: ゲーム コードを追加する
サンプルはゲームプレイの状態とレンダリングを分離しているため、Direct3D コードを変更せずにシミュレーションを調整できます。DeviceResources.*、Main.cpp、pch.*、StepTimer.h、および 5 つのシェル ビジュアル PNG ファイルなど、テンプレートで生成されたファイルはそのまま残してください。以下のサンプル固有のファイルをプロジェクトに追加します:
固定ステップ シミュレーションを使用する
このプロジェクトは、テンプレートのStepTimer を 120 Hz 固定更新 で使用します。固定ステップは、フレーム時間が変動しても衝突応答と AI 挙動を安定させます。
シミュレーションは以下を含みます:
- 2 つのパドル状態。
- 1 つの円形パック状態。
- 左右のサイドのスコア。
- サーブ遅延とサーブ方向の交代。
- パドル、壁、ゴール衝突の衝突イベント。
円形パックの衝突を実装する
各パドルを軸整列の矩形として、パックを円として扱います:- パドル矩形上でパック中心に最も近い点を見つけます。
- その点からパック中心までの二乗距離を計算します。
- 距離がパック半径の二乗以下の場合、衝突が発生しています。
- 重複を繰り返さないよう、パックをパドルの外側に移動します。
- 衝突オフセットとパドル速度から出射角を計算します。
- パックの速度を最大値まで少しずつ上げます。
予測的なオートプレイを追加する
各パドルは:- パックがその水平位置と交差する場所を予測します。
- 予測座標をアリーナの上下の壁で反射します。
- 一定の反応間隔でターゲットを更新します。
- スナップではなく、加速度と最大速度の制限を使用します。
- 決定的な小さなターゲティング誤差を加えます。
DirectXTK12 でシーンをレンダリングする
以下を作成します:GraphicsMemory。- 白テクスチャとパック テクスチャを含むディスクリプタ ヒープ。
- 通常アルファの
SpriteBatch。 - パーティクル用の加算
SpriteBatch。 ResourceUploadBatchとCreateDDSTextureFromFileによる DDS テクスチャ。
SpriteBatch を使ってアリーナ、センター ライン、パドル、スコア、パック トレイル、パックを描画します。パーティクルは加算パスで描画します。
完成したサンプルは 1920 × 1080 の仮想座標系でレンダリングし、そのシーンを出力ビューポートにスケールします。
エフェクトを控えめに保つ
最終的なチューニングでは以下を使用しました:- 短く指数的に減衰する画面揺れ。
- より小さな筋状の衝突パーティクル。
- 壁の衝突よりもパドルの衝突で多くのパーティクル。
- ゴール時のより強いバースト。
- 低アルファのパック トレイル。
- 短時間の緑色の衝突フラッシュ。
ステップ 8: テクスチャ アセットを作成してデプロイする
サンプルには以下が必要です:Assets\white.dds: 矩形とパーティクルの描画に使用する 1 × 1 の白 RGBA テクスチャ。Assets\xbox_logo.dds: パックに使用する 256 × 256 の RGBA テクスチャ。
- ソースのロゴを読み込みます。
- 256 × 256 にリサイズします。
- フェザリングされた円形のアルファ マスクを適用します。
- DX10 ヘッダー付きの RGBA8 DDS を書き出します。
- 1 × 1 の白 DDS を作成します。
sample-game.vcxproj のデプロイ コンテンツとして登録します:
標準ヘッダーに DX10 拡張を加えた DDS ファイルは、ピクセル データの前に 148 バイト あります。当初のセッションでは、独自の DDS ライターが 152 バイトを出力し、タイトルはテクスチャの読み込み中に
0x8007000D で失敗しました。独自の DDS ライターを使用する場合は、デプロイ前にヘッダー レイアウトを検証してください。ステップ 9: ゲームをビルドする
XBOX Series X|S VS 2022 Gaming Command Prompt から:sample-game.exeMicrosoftGame.config- シェル ビジュアルの PNG ファイル
Assets\white.ddsAssets\xbox_logo.dds- 必要なランタイム DLL
- ビルドで生成される Game OS イメージまたはその他のデプロイ メタデータ
MicrosoftGameConfig.mgc という名前です。GDK の MGCCompile ビルド項目がこれを検証して、ビルド出力に MicrosoftGame.config を出力します。デプロイとパッケージングはどちらも生成された .config ファイルを使用します。Game config を参照してください。
ステップ 10: XBOX 開発機に接続する
Tools IP アドレスまたはホスト名を使って既定のコンソールを設定します:ステップ 11: ゲーム全体をデプロイする
ビルド出力フォルダー全体をデプロイします:xbapp list を使って、登録されたパッケージのフル名とアプリケーション ユーザー モデル ID (AUMID) を確認します。AUMID の末尾は !Game です。
ステップ 12: ゲームを起動して検証する
xbapp list が報告した AUMID を厳密に指定して起動します:
ステップ 13: 起動直後の失敗を診断する
ゲームが即座に終了した場合、実行ファイルがコピーされたというだけでデプロイが成功したと決めつけないでください。直近のタイトル実行結果を取得する
デバッグ出力を監視する
あるコマンド プロンプトでデバッグ出力モニターを起動します:OutputDebugStringA メッセージを追加しました:
- ゲームの初期化。
- DirectXTK12 のリソース作成。
- 各テクスチャの読み込み。
- スプライト パイプラインの作成。
- テクスチャ アップロードの完了。
- フレーム内の例外。
white.dds の読み込みに切り分けられました。ローダーは 0x8007000D を返し、これは不正な DDS データを示します。DDS ヘッダーを修正し、クリーンに完全デプロイし直すことで起動が修正されました。
より詳しい起動診断には、失敗を再現しながら xbWatson を実行してください。エラー ハンドリング も参照してください。
ステップ 14: 安全に反復する
コードのみの変更の場合はほとんど:- Debug をビルドします。
- 実行中のパッケージを終了します。
- 出力フォルダー全体をデプロイします。
- 登録済みの AUMID を起動します。
- パッケージの状態を照会します。
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。
TargetDeviceFamily="Scarlett" が必要です。XBOX One ファミリー コンソール用パッケージには別の構成を使用してください。
Release 構成をビルドする
パッケージ コンテンツをステージングする
Release 出力をステージング ディレクトリにコピーしますが、gameos.xvd はコンテンツ マップの外側に置き、PDB ファイルは通常のパッケージ コンテンツとしては含めません。
レイアウトを生成する
開発機向けのテスト パッケージを作成する
既定のテスト暗号化は開発機へのローカル インストールに便利です:Partner Center パッケージには提出用暗号化を使用する
sample-game パッケージは、インストールと起動を検証できるよう、最初は開発機向けのテスト暗号化で作成されました。提出予定のパッケージについては、現行のパッケージング ポリシーに従い、/lk または /l を使用してください。
推奨される再現可能な /lk ワークフローは以下です:
