> ## 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。
* 2026 年 4 月 Update 2 GDKX,版本号 `260402`。
* 面向 XBOX Series X|S 主机的 `Gaming.XBOX.Scarlett.x64`。
* 面向 XBOX One 系列主机的 `Gaming.XBOX.XboxOne.x64`。
* DirectXTK12 提交 `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 | Platform                   |
| ------------- | -------------------------- |
| 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 作为可选辅助库添加

DirectXTK12 并非创建 GDK 游戏的必需项。XBOX GDK 模板已经提供了直接基于 Direct3D 12 构建游戏所需的 D3D12 设备、命令队列、交换链与游戏循环。

本示例使用另外的 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` 以及五个外壳视觉 PNG 文件。将下列示例特有文件添加到项目中:

| 文件                             | 用途                      |
| ------------------------------ | ----------------------- |
| `GameTuning.h`                 | 场地、球拍、冰球、AI、尾迹与粒子常量。    |
| `sample-gameSimulation.h/.cpp` | 冰球运动、球拍移动、碰撞、计分、发球与 AI。 |
| `ParticleSystem.h/.cpp`        | 固定大小的粒子池与撞击发射器。         |
| `Game.h/.cpp`                  | DirectXTK12 资源、游戏更新与渲染。 |
| `tools\BuildAssets.ps1`        | 可复现地生成白色精灵与冰球的 DDS。     |

### 使用固定的仿真步长

项目使用模板自带的 `StepTimer`,以 **120 Hz 固定更新**运行。固定步长可在帧时波动时保持碰撞响应与 AI 行为稳定。

仿真包含:

* 两个球拍状态。
* 一个圆形冰球状态。
* 左右两侧的比分。
* 发球延迟与交替的发球方向。
* 用于球拍、墙壁与球门碰撞的撞击事件。

### 实现圆形冰球碰撞

将每个球拍视为轴对齐矩形,将冰球视为圆:

1. 找到球拍矩形上距离冰球中心最近的点。
2. 计算该点到冰球中心的距离平方。
3. 若距离不大于冰球半径的平方,则发生碰撞。
4. 将冰球移出球拍范围以避免反复重叠。
5. 根据撞击偏移与球拍速度计算出射角度。
6. 略微增加冰球速度,直至上限。

即便冰球是用正方形纹理绘制的,这种方式也能保持物理表现为圆形。

### 添加预测式自动操作

每个球拍会:

* 预测冰球何时抵达其水平位置。
* 将预测坐标在场地上下墙之间反射。
* 以固定的反应间隔更新目标。
* 使用加速度与最高速度限制,而不是瞬移。
* 加入一个小的确定性瞄准误差。

为了让比赛能够得分,每一侧偶尔会进入短暂的"失误窗口",故意偏离预测的拦截点。让两侧的初始失误计时器错开,以免同时失误。

### 使用 DirectXTK12 渲染场景

创建:

* `GraphicsMemory`。
* 一个包含白色纹理和冰球纹理的描述符堆。
* 一个正常 Alpha 混合的 `SpriteBatch`。
* 一个用于粒子的加性混合 `SpriteBatch`。
* 通过 `ResourceUploadBatch` 与 `CreateDDSTextureFromFile` 加载的 DDS 纹理。

使用 `SpriteBatch` 绘制场地、中线、球拍、比分、冰球尾迹与冰球。在加性通道中绘制粒子。

完成后的示例在 1920 × 1080 的虚拟坐标系中渲染,并将该场景缩放至输出视口。

### 保持特效克制

最终调整参数为:

* 短暂、指数衰减的画面震动。
* 更小的条状撞击粒子。
* 球拍撞击时的粒子数多于墙壁撞击。
* 进球时爆发更强。
* 低透明度的冰球尾迹。
* 短暂的绿色撞击闪光。

这些调整保留了撞击反馈,同时避免让游戏显得卡通化,或让球拍碰撞在视觉上过于突兀。

## 第 8 步:创建并部署纹理资源

示例需要:

* `Assets\white.dds`:一张 1×1 的白色 RGBA 纹理,用于绘制矩形与粒子。
* `Assets\xbox_logo.dds`:一张 256×256 的 RGBA 纹理,用于冰球。

资源脚本会:

1. 加载源 logo。
2. 缩放为 256×256。
3. 应用羽化圆形 Alpha 遮罩。
4. 写出带 DX10 头的 RGBA8 DDS。
5. 创建 1×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 开发套件

使用开发套件的 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` 查找已注册的 package full name 与应用用户模型 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。完整的打包参考请参阅[打包](/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>
```

### 创建开发套件测试包

默认的测试加密方式适用于本地开发套件安装:

```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 模板                     | 已安装公开的 PC GDK,但没有 XBOX 扩展          | 从 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 字节加 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-CN/home/build-first-title/developing-new-titles.md)
- [设置并安装 GDK](/zh-CN/home/setup-install/get-started.md)
- [GDK 示例](/zh-CN/home/setup-install/samples.md)
- [Android 推送通知](/zh-CN/services/playfab/live-service-management/game-configuration/title-communications/push-notifications/push-notifications-for-android.md)
- [XBOX Series X|S 概览](/zh-CN/paths/series-xs/overview.md)