> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 游戏

> 列出卖家的 Partner Center 游戏、查找游戏、创建游戏,以及检查其创建作业。

`game` 命令可列出卖家的 Partner Center 游戏、按 Store ID、XBOX 游戏 ID 或名称查找游戏、创建游戏,以及检查其创建作业。

每个命令都作用于一个卖家,该卖家来自 `--seller-id` 或你已保存的卖家;请参阅
[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。如果你属于多个卖家,请参阅
[此已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md#xbox-game-commands-ignore---seller-id):这些命令可能会使用其他卖家。

## 命令

| 命令 | 说明 |
| - | - |
| `game list` | 列出卖家的每个游戏。 |
| `game get` | 按 Store ID、XBOX 游戏 ID 或名称关键字获取游戏。 |
| `game create` | 创建游戏,然后等待其创建作业。 |
| `game job get` | 读取游戏创建作业的当前状态。 |

## 参数

| 参数 | 命令 | 说明 |
| - | - | - |
| `[title-id]` | `get` | XBOX 游戏 ID:一到八个十六进制数字,可带可选的 `0x` 前缀,例如 `1234ABCD`。`42` 表示 `0x00000042`。 |
| `<job-id>` | `job get` | `game create` 输出的创建作业 ID。 |

## 选项

| 选项 | 命令 | 说明 |
| - | - | - |
| `--seller-id <id>` | 全部 | Partner Center 卖家 ID。 |
| `--base-url <url>` | 全部 | 请求的基 URL,覆盖 `XboxPartner:BaseUrl` 配置键。 |
| `--store-id <id>` | `get` | 游戏的 Microsoft Store ID,例如 `9N0000000000`。可以与 `title-id` 结合使用以缩小结果范围。 |
| `--keyword <text>` | `get` | 查找名称包含此文本的游戏,不区分大小写。不能与 `title-id` 或 `--store-id` 结合使用。 |
| `-d`, `--details` | `list`、`get` | 为每个游戏显示一个文本块。不能与 `--output` 结合使用。 |
| `--name <name>` | `create` | 必需。游戏的名称。 |
| `--supported-device <device>` | `create` | 必需。`xbox` 或 `desktop`;若要同时支持两者,请重复此选项。 |
| `--sandbox-id <id>` | `create` | 游戏的开发沙盒。它必须是现有的共享沙盒;[`sandbox get`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/sandbox) 会显示沙盒的类型。 |
| `--confirm`, `--yes`, `-y` | `create` | 创建游戏,不显示确认提示。 |
| `--output <format>` | 全部 | `json`(默认)或 `json-compact`;`table` 仅适用于 `list` 和 `get`。 |

`game get` 至少需要 `title-id`、`--store-id` 或 `--keyword` 中的一个。位置值始终是 XBOX 游戏 ID;如果它看起来像 Store ID,错误会建议改用带有
`--store-id` 的相同命令:

```text theme={null}
title-id must be one to eight hexadecimal digits, with an optional 0x prefix. 9N0000000000 looks like a Store ID. Did you mean:
  xbox game get --store-id 9N0000000000 --seller-id 1234567
```

## 列出和查找

```bash theme={null}
xbox game list --output table
xbox game get --store-id 9N0000000000
xbox game get 1234ABCD --details
xbox game get --keyword "nod arena" --output table
```

`game list` 返回卖家的整个目录,带有 `--keyword` 的 `game get` 会搜索整个目录。读取大型目录可能需要几分钟时间,该命令会在 stderr 上显示其
[进度](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands.md#progress)。没有分页选项;请使用
`less` 或 `more` 对输出进行分页。如果请求失败,该命令不会输出部分结果,并会将关联 ID 写入 stderr。每个请求在两分钟后超时;若要更改此值,请设置
`XboxPartner:TimeoutSeconds`(请参阅[配置](https://docs.xbox.com/zh-CN/tools/xbox-cli/configuration.md))。

## 输出

JSON 输出是一个 `games` 数组。每个游戏都有以下字段:

| 字段 | 说明 |
| - | - |
| `productId` | Partner Center 产品 ID。 |
| `storeId` | Microsoft Store ID。 |
| `xboxTitleId` | XBOX 游戏 ID:八个大写十六进制数字,不带 `0x`,例如 `"1234ABCD"`。如果游戏没有有效的游戏 ID,则为 `null`。 |
| `SCID` | 服务配置标识符 (SCID),例如 `"00000000-0000-0000-0000-00001234ABCD"`。键为大写。当 `xboxTitleId` 为 `null` 时为 `null`。 |
| `name` | 游戏的名称。 |
| `primaryDevelopmentSandbox` | 游戏的开发沙盒,或 `null`。 |
| `deviceFamilies` | 支持的设备,例如 `["xbox", "desktop"]`。未列出任何设备时为 `null` 或 `[]`。 |
| `packageIdentityName`, `packageIdentityPublisher`, `packageFamilyName` | 游戏的程序包标识。 |
| `msaAppId` | Microsoft 帐户 (MSA) 应用 ID。 |

`game create` 和 `game job get` 写入创建作业。游戏存在后,作业中会出现具有相同字段的 `game` 字段。

### 表格输出

`list` 和 `get` 接受 `--output table`,每个 XBOX 游戏 ID 一行,包含以下列:
`TITLE ID`、`STORE IDS`、`PRODUCT NAME`、`MSA APP ID` 和 `PACKAGE FAMILY NAME`。游戏的 Store ID 和其他值共享该游戏的行,过长的值会被截断。`create` 和 `job get`
拒绝 `--output table`。

### 详细信息视图

`--details` 为每个游戏 ID 输出一个块,其中包含该 ID 下的每个游戏及其所有标识符(包括 SCID 和开发沙盒),且不会截断。缺少的值显示为 `-`。使用
`--details` 或 `--output table` 时,结果计数和持续时间会输出到 stderr。

## 创建游戏

```bash theme={null}
xbox game create --name "Nod Arena" \
  --supported-device xbox --supported-device desktop \
  --sandbox-id TESTSB.42 --seller-id 1234567 --confirm
```

`game create` 会在创建游戏之前进行询问;如果没有终端,则需要 `--confirm`。CLI
无法删除游戏。如果你属于多个卖家,请先查看
[该已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md#xbox-game-commands-ignore---seller-id):游戏可能会在其他卖家中创建。

该命令只发送一次请求,最多等待两分钟以完成创建作业,然后将作业写入 stdout。作业 ID、关联 ID 以及用于检查作业的命令会输出到 stderr。如果等待先结束,作业会继续运行:请使用 `game job get` 检查它,不要再次创建游戏。

如果请求失败,stderr 会说明是否可能已创建游戏:

* 当请求未发送或服务拒绝了请求(例如对于游戏无法使用的沙盒返回
  `400`)时,**未创建任何游戏**。请解决问题,然后再次运行该命令。
* 在出现服务器错误、超时或连接丢失后,**结果未知**。在重试之前,请使用 stderr 上输出的命令检查
  `game list`。

## 检查创建作业

```bash theme={null}
xbox game job get 11111111-2222-3333-4444-555555555555 --output json-compact
```

`job get` 只执行读取,因此你可以根据需要随时运行它。已成功的作业仍可能在其 `errors` 字段中报告问题。

## 退出代码

| 退出代码 | 含义 |
| - | - |
| `0` | 作业已成功或仍在运行。`create` 在其等待结束时也会以 `0` 退出,因此 `0` 并不保证游戏已存在。 |
| `1` | 命令失败。对于 `create`,stderr 会说明是否可能已创建游戏。 |
| `2` | 作业已结束,但未创建游戏。请查看其 `errors` 字段。 |
| `130` | 在命令读取时,或在 `create` 等待其请求的响应时,你按下了 Ctrl+C。对于 `create`,stderr 会说明结果未知。 |

不要根据退出代码来决定是否再次运行 `create`。如果 stderr 说明未创建任何游戏,请解决错误并再次运行;否则,请使用其输出的 `game job get` 或 `game list`
命令进行检查。

## 端到端示例

保存一次卖家,然后创建游戏,该命令会使用此卖家:

```bash theme={null}
xbox context set seller-id 1234567

xbox game create --name "Nod Arena" \
  --supported-device xbox --supported-device desktop \
  --sandbox-id TESTSB.42 --confirm
```

如果等待在作业完成之前结束,请检查作业,而不是再次创建游戏。请使用 `game create` 在 stderr 上输出的作业 ID:

```bash theme={null}
xbox game job get 11111111-2222-3333-4444-555555555555 --output json-compact
```

作业成功后,查找该游戏:

```bash theme={null}
xbox game get --keyword "Nod Arena" --output table
```


## Related topics

- [游戏存档](https://docs.xbox.com/zh-CN/build/core-features/common/game-save/index.md)
- [游戏存储](https://docs.xbox.com/zh-CN/services/xbox-services/storage/title-storage/index.md)
- [游戏设置](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/game-setup-overview.md)
- [认证游戏](https://docs.xbox.com/zh-CN/publishing/game-publishing/tutorial-xbox-managed/how-to-certify-a-game.md)
- [游戏数据](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/game-configuration/titledata/index.md)
