开始之前
- 安装 GDK。示例使用 2026 年 10 月 GDK(版本
261000)。请将261000替换为游戏生成时所用的版本。 - 使用能够连接到 Model Context Protocol (MCP) 服务器、读取计算机上的文件或运行命令的智能体。大多数编码智能体这三项都能做到。
- 了解你的组织批准哪些 AI 工具可用于处理机密内容。GDKX 文档、头文件和工具均属机密。
选择要提供给智能体的 GDK 上下文
在线来源描述的是当前 GDK。使用较早的 GDK 进行生成时,还应向智能体提供已安装的头文件和脱机文档,以免它使用你的 GDK 中没有的 API。
连接 XBOX 文档 MCP 服务器
位于https://docs.xbox.com/mcp 的 XBOX 文档 MCP 服务器使智能体能够搜索和引用已发布的文档。它不需要 API 密钥,也无需登录。例如,在 Visual Studio Code 中,将该服务器添加到项目中的 .vscode/mcp.json 文件:
.vscode/mcp.json
https://docs.xbox.com/llms.txt列出所有页面及其简短说明。https://docs.xbox.com/llms-full.txt在一个文件中包含文档全文。- 在任何页面 URL 的末尾添加
.md,即可获取该页面的 Markdown 版本。
向智能体提供脱机文档
GDKX 会将 GDK 文档以 Markdown 文件的形式安装在 GDK 版本的xbox\documentation 文件夹中的 GDKDocumentationMarkdown.zip 内。由于这些文件与你安装的 GDK 匹配,因此它们是该版本最准确的文档来源。
每个页面都以 YAML frontmatter 开头。permissioned-type 值指明页面的访问分类:public、private 或 secret。存档根目录下的 site-map.md 文件列出了所有页面。
-
将存档解压到源存储库之外的文件夹中。在 PowerShell 中运行以下命令。
-
如果你的 AI 工具未获批准处理机密内容,请仅保留公开页面。以下命令会删除
permissioned-type不是public的所有 Markdown 文件,包括没有该字段的文件。 - 向智能体授予该文件夹的访问权限。例如,将其添加到编辑器的工作区,或在项目说明文件中指明该文件夹。
让智能体使用已安装的头文件和工具
GDK 安装程序会设置环境变量,向智能体提供已安装 GDK 的位置:GameDK是 GDK 根文件夹。它包含存放命令行工具的bin文件夹,以及每个已安装版本的文件夹,例如%GameDK%261000\。GameDKCoreLatest和GameDKXboxLatest指向最新安装的版本。
%GameDK%261000\),而不是这些变量。
有关每个版本下的文件夹,请参阅 GDK 头文件和库目录结构。告诉智能体在使用某个 API 之前,先在该版本的 windows\include 文件夹(适用于 PC)或 xbox\include 文件夹(适用于 XBOX 主机)下的头文件中检查声明。某些头文件(例如 XBOX 服务 API (XSAPI)、libHttpClient 和 PlayFab 头文件)还包含描述每个 API 的文档注释。
%GameDK%bin 中的命令行工具在使用 /? 运行时会输出其用法。智能体可以在使用工具之前运行该工具的 /?,而不是猜测其选项。要将 HRESULT 转换为说明,请使用 xberror.exe:
向智能体提供与版本匹配的示例代码
使用 XBOX GDK 示例列表查找你正在实现的功能的示例。查看存储库和示例的 README,了解 GDK 版本、目录布局和平台要求。如果 main 分支与你的项目不匹配,请选择兼容的示例发布版本。 克隆或下载兼容的发布版本,并向智能体提供相关示例的源代码和 README 的本地路径。要求它遵循示例的初始化、错误处理、异步生存期和清理模式。让智能体根据你已安装的头文件验证 API,而不是从不同的 GDK 布局中复制项目设置。让智能体从命令行生成
要进行生成,智能体需要与 Gaming Command Prompt 相同的环境。使用“开始”菜单快捷方式所用的参数运行GamingDesktopVars.cmd,然后在同一 cmd 进程中运行生成:
GamingDesktopVS2022。环境不会在单独的命令之间延续,因此智能体必须一起运行该脚本和生成。
添加项目说明文件
大多数编码智能体会读取存储库根目录下的项目说明文件,例如AGENTS.md 或 .github/copilot-instructions.md。使用该文件为每个智能体会话提供相同的 GDK 上下文。从以下示例开始,并替换尖括号中的值。
AGENTS.md
