> ## 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 建置、部署到 dev kit,並產生可安裝的 XVC。

本逐步解說記錄了建立一個小型 `sample-game` 遊戲並為 XBOX Series X|S 主機建置的端對端流程。接著你會將完整的遊戲部署到 XBOX dev kit、診斷啟動失敗,並建立可安裝的 XVC。

完成的範例使用 C++、Direct3D 12,以及含 XBOX Extensions 的 GDK(GDKX)。它也使用 [DirectXTK12](https://github.com/microsoft/DirectXTK12) 作為選用的轉譯輔助工具。兩個球拍都由電腦控制,因此當你反覆調整圖形、遊戲玩法與特效時,遊戲可以在無人操作的情況下持續執行。

<Warning>
  透過 GitHub 或 WinGet 取得的公開版 GDK 僅支援 Windows PC 遊戲開發。若要編譯並部署 XBOX 主機可執行檔,請從 XBOX Secure Downloads 安裝含 XBOX Extensions 的 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 dev kit 上執行的完整鬆散檔案(loose-file)部署。
* 一個選用的、已與 Store 關聯的 XVC,可在 dev kit 上安裝與測試。

## 開始之前

本逐步解說使用以下環境驗證:

* 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 認可(commit)`e656d54637b2830fc6eb5ecd9b329a9c72cb87d4`。

如果你使用其他版本進行本逐步解說,請使用開發 PC 上安裝的 GDK 版本,而非 `260402`。

## 步驟 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 範本可用,那麼很可能安裝的是公開版 PC GDK,而不是 GDKX。

## 步驟 3:建立原生 XBOX 專案

<Steps>
  <Step title="開啟 Visual Studio 2022 並選擇 Create a new project">
    將 **Language** 設為 **C++**、**Platform** 設為 **XBOX**、**Project type** 設為 **Games**。
  </Step>

  <Step title="選擇 Direct3D 12 XBOX Game">
    將專案名稱設為 `sample-game`,位置設為 `D:\repos\sample-game`。
  </Step>

  <Step title="保持 Place solution and project in the same directory 為未勾選">
    這樣方案會位於根目錄,而專案位於 `D:\repos\sample-game\sample-game`。
  </Step>

  <Step title="建立專案" />
</Steps>

支援的工作流程是透過 Visual Studio 建立專案。手動複製 `d3d12game_gx` 範本檔案是一種復原技巧,不是建議的新專案工作流程。

### 確認專案不是 UWP

在加入遊戲程式碼之前,請確認專案:

* 包含 `MicrosoftGameConfig.mgc`。
* 使用 `Gaming.XBOX.*.x64` 專案平台。
* 連結到 XBOX GDK 平台程式庫。
* 不使用 `Package.appxmanifest` 作為其遊戲設定。
* 是從 **Direct3D 12 XBOX Game** 建立的,而非通用 Windows 範本。

如果專案是 UWP,請刪除它並從 XBOX GDK 範本建立新專案。轉換產生的 UWP 專案比使用正確的範本重新開始更容易出錯。

## 步驟 4:固定 GDK 版本並設定主機目標

固定 GDK 版本可防止之後安裝的 GDK 無聲無息地變更專案使用的工具鏈。

在 `sample-game.vcxproj` 的主要屬性群組中,設定:

```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 系列主機的組態。若要讓同一款遊戲跨世代推出,請參閱[跨世代](/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 作為選用輔助工具

建立 GDK 遊戲並不需要 DirectXTK12。XBOX GDK 範本已提供直接以 Direct3D 12 建置遊戲所需的 Direct3D 12 裝置、命令佇列、交換鏈與遊戲迴圈。

本範例使用獨立的 Microsoft 開放原始碼程式庫 DirectXTK12。該程式庫可減少 sprite 轉譯、描述元管理、貼圖載入、資源上傳與圖形記憶體管理所需的低階轉譯公用程式碼。遊戲可以用自己的引擎或直接的 D3D12 實作取代這些輔助工具。

將 DirectXTK12 複製(clone)到專案中:

```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` 加入 include 目錄。
4. 以相同的 XBOX 平台與組態建置這兩個專案。

`sample-game` 專案使用以下屬性:

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

接著加入 include 路徑與專案參考:

```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` 與五個外殼視覺 PNG 檔案。將以下範例專屬檔案加入專案:

| 檔案                             | 用途                          |
| ------------------------------ | --------------------------- |
| `GameTuning.h`                 | 場地、球拍、冰球、AI、軌跡與粒子的常數。       |
| `sample-gameSimulation.h/.cpp` | 冰球移動、球拍移動、碰撞、計分、發球與 AI。     |
| `ParticleSystem.h/.cpp`        | 固定大小的粒子集區與撞擊發射器。            |
| `Game.h/.cpp`                  | DirectXTK12 資源、遊戲更新與轉譯。     |
| `tools\BuildAssets.ps1`        | 可重現的白色 sprite 與冰球 DDS 產生流程。 |

### 使用固定的模擬時步

本專案使用範本的 `StepTimer`,並採用 **120 Hz 固定更新**。當畫格時間變動時,固定的時步可以讓碰撞回應與 AI 行為保持穩定。

模擬包含:

* 兩個球拍的狀態。
* 一個圓形冰球的狀態。
* 左右兩側的分數。
* 發球延遲與交替的發球方向。
* 球拍、牆面與進球碰撞的撞擊事件。

### 實作圓形冰球碰撞

將每個球拍視為軸對齊矩形,將冰球視為圓形:

1. 找出球拍矩形上最接近冰球中心的點。
2. 計算該點到冰球中心的距離平方。
3. 如果該距離不大於冰球半徑的平方,即發生碰撞。
4. 將冰球移到球拍之外,以防止重複重疊。
5. 根據命中偏移量與球拍速度計算出射角度。
6. 稍微增加冰球速度,但不超過上限。

即使冰球是以方形貼圖繪製,這樣仍可讓物理維持圓形。

### 加入預測式自動遊玩

每個球拍會:

* 預測冰球將在其水平位置的哪個點相交。
* 將預測座標沿場地上下牆面反射。
* 以固定的反應間隔更新其目標。
* 使用加速度與最高速度限制,而不是瞬間移動。
* 加入少量確定性的瞄準誤差。

為了讓比賽能夠得分,每一側會偶爾進入短暫的失誤時段,刻意偏離預測的攔截點。請錯開初始失誤計時器,讓兩個球拍不會同時漏接。

### 使用 DirectXTK12 轉譯場景

建立:

* `GraphicsMemory`。
* 一個包含白色貼圖與冰球貼圖的描述元堆積。
* 一個一般 alpha 的 `SpriteBatch`。
* 一個用於粒子的加色(additive)`SpriteBatch`。
* 透過 `ResourceUploadBatch` 與 `CreateDDSTextureFromFile` 建立的 DDS 貼圖。

使用 `SpriteBatch` 繪製場地、中線、球拍、分數、冰球軌跡與冰球。在加色階段繪製粒子。

完成的範例會在 1920 x 1080 的虛擬座標系統中轉譯,並將該場景縮放到輸出檢視區。

### 讓特效保持節制

最終調校使用:

* 短暫、以指數衰減的螢幕震動。
* 較小的條紋狀撞擊粒子。
* 球拍命中時的粒子多於牆面命中。
* 進球時較強烈的爆發效果。
* 低 alpha 的冰球軌跡。
* 短暫的綠色撞擊閃光。

這些調整保留了撞擊回饋,同時避免遊戲看起來像卡通,或讓球拍碰撞在視覺上過於突兀。

## 步驟 8:建立並部署貼圖素材

本範例需要:

* `Assets\white.dds`:1 x 1 的白色 RGBA 貼圖,用於繪製矩形與粒子。
* `Assets\xbox_logo.dds`:256 x 256 的 RGBA 貼圖,用於冰球。

素材指令碼會:

1. 載入來源標誌。
2. 將其調整為 256 x 256。
3. 套用羽化的圓形 alpha 遮罩。
4. 寫出帶有 DX10 標頭的 RGBA8 DDS。
5. 建立 1 x 1 的白色 DDS。

從 PowerShell 執行:

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

在 `sample-game.vcxproj` 中將兩個 DDS 檔案註冊為部署內容:

```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` 檔案。請參閱[遊戲設定](/build/core-features/common/game-config/MicrosoftGameConfig-Overview)。

## 步驟 10:連線到 XBOX dev kit

使用其 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)
```

此時,自動遊玩的對戰畫面應該會出現在 dev kit 上。

## 步驟 13:診斷立即啟動失敗

如果遊戲立即結束,請不要因為可執行檔已被複製就假設部署成功。

### 取得最後一次遊戲結果

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

### 監視偵錯輸出

在一個命令提示字元中啟動偵錯輸出監視器:

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

從另一個命令提示字元啟動遊戲:

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

本範例在以下位置加入了 `OutputDebugStringA` 訊息:

* 遊戲初始化。
* DirectXTK12 資源建立。
* 每次貼圖載入。
* Sprite 管線建立。
* 貼圖上傳完成。
* 畫格例外狀況。

最初的開發過程將啟動失敗定位在載入 `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。完整的封裝參考請參閱[封裝](/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"
```

對於這個小型範例,產生的配置只包含一個啟動區塊:

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

### 建立 dev kit 測試套件

預設的測試加密適合用於本機 dev kit 安裝:

```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 套件使用提交加密

請先以 dev kit 測試加密產生 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 範本可用                     | 安裝了公開版 PC GDK,沒有 XBOX Extensions       | 從 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`。 |
| 產品身分識別在多處提供                         | 即使 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)
* [封裝](/build/core-features/common/packaging/overviews/packaging)
* [為 Series X|S 建置](/paths/series-xs/overview)
* [跨世代](/build/console-features/cross-gen/cross-gen-overview)


## Related topics

- [開發新的 GDK 遊戲](/zh-TW/home/build-first-title/developing-new-titles.md)
- [設定並安裝 GDK](/zh-TW/home/setup-install/get-started.md)
- [GDK 範例](/zh-TW/home/setup-install/samples.md)
- [XBOX 遊戲開發文件](/zh-TW/index.md)
- [XBOX Series X|S 總覽](/zh-TW/paths/series-xs/overview.md)