# 游戏引擎包 — AI Game Dev 应用与 CLI · AI Game Developer Wiki

用一个包让 AI Game Dev 掌握整个游戏引擎：项目检测、创建对话框、Play、游戏视图和实时 agent 工具，逐步讲解。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/app/game-engine-packages)。

游戏引擎包能让 AI Game Dev 掌握整个引擎：哪些文件夹属于它的项目、如何创建项目、如何运行项目、如何展示运行中的游戏，以及游戏运行时 agent 可以使用哪些实时工具。应用自带的引擎（Unity、Godot、Unreal Engine、BRUTAL、Bevy、Web）在应用内部实现同一套约定；而包则在 Extension Host 中实现它。引擎包需要 AI Game Dev 0.32.0 或更高版本，并像其他包一样发布到社区 registry。

## 从模板开始

```bash
gamedev pkg init forge --engine --id acme.forge
cd ~/projects && gamedev pkg dev ~/src/forge      # then open a folder, or create a Forge project
gamedev pkg logs acme.forge -f
```

模板就是示例引擎 `samples.toy-engine`：它会检测包含 `toy-engine.json` 的文件夹，从两个起始模板创建项目，把游戏作为一个小型 Node.js 服务器运行在 `127.0.0.1` 上并由游戏面板显示，为 agent 提供两个实时工具，并能停止游戏。它不需要任何原生二进制文件。

## 声明式部分：contributes.gameEngines

应用无需运行你的代码就能读取这些信息，因此在你的包启动之前，项目就已被检测、列出、绘制，并在创建对话框中提供。每个包只能有一个引擎；其 `id` 就是包 id。

```json
{
  "engines": { "aigd": ">=0.32.0" },
  "contributes": {
    "gameEngines": [{
      "id": "acme.forge",
      "contractVersion": 1,
      "displayName": "Forge",
      "icon": "media/forge.svg",
      "explorerIcons": { "folder": "media/forge.svg", "folderOpen": "media/forge.svg" },
      "detect": [{ "exists": "forge.json", "type": "file" }],
      "ignoreDirs": [".forge"],
      "editor": "none",
      "connection": "package",
      "gameView": "browser",
      "starters": [
        { "id": "empty", "label": "Empty", "description": "A blank canvas", "preview": "media/starter-empty.webp", "blank": true },
        { "id": "platformer", "label": "Platformer", "description": "A small playable level", "preview": "media/starter-platformer.webp", "recommended": true, "game": true }
      ],
      "defaultProjectName": "forgegame",
      "showcase": { "accent": "#ff8a3d", "pitch": "A tiny canvas engine, run by a package", "languages": "JavaScript", "tags": ["JavaScript", "Canvas"] }
    }]
  }
}
```

| 字段 | 作用 |
| --- | --- |
| `detect` | 任一规则匹配即把该文件夹标记为项目：`exists`（一个相对路径，最多 3 段）、`glob`（文件夹中的文件名模式）、`contains`（匹配文件前 64 KB 中的字面量）、`allOf`（2 到 4 个标记）。每个引擎每次扫描只有 2 秒，所以标记要尽量轻量。 |
| `editor` | 当该引擎有可启动的编辑器应用时为 `"app"`，否则为 `"none"` |
| `connection` | `"package"`：由你的包提供 agent 的实时工具；`"none"`：没有工具 |
| `gameView` | `"browser"`：运行中的游戏是一个网页，由游戏面板显示 |
| `starters` | 创建对话框的 1 到 8 个起始模板；最多一个 `recommended`；`preview` 是一张宽图（约 16:7，例如 640×280）；`blank` 和 `game` 告诉对话框某个起始模板是什么样子（省略它们可兼容 0.32.0-beta.1 及更早版本的应用，这些版本会拒绝它们） |
| `showcase` | 创建对话框如何呈现该引擎：`accent` 和 `accent2` 颜色（`#rrggbb`）、`pitch`（80 个字符）、`summary`、`languages`、最多 5 个 `tags`、`shortName` |
| `editorInstall` | `{url, label}`：从哪里获取打开项目所需的内容 |
| `skills` | 一个包含 `<skill>/SKILL.md` 的包文件夹，agent 会为使用该引擎的项目加载它 |

包永远不能重新标记 Unity、Godot、Unreal 或 BRUTAL 项目。任何一个无效字段都会导致整个引擎条目被丢弃；`gamedev pkg validate` 会指出是哪一个。

## 代码部分：registerEngine

`activate` 在 `onGameEngine:<id>` 上运行，时机是应用首次需要该引擎时，并注册实现：

```typescript
import type { PackageContext, GameEngineImplementation } from "./types/aigd";

export async function activate(ctx: PackageContext): Promise<void> {
  if (!ctx.aigd.gameEngines) return;                 // an app older than 0.32.0
  const host = ctx.aigd.gameEngines.host;            // the app's services, scoped to this package
  const engine: GameEngineImplementation = { project: { /* … */ }, plugin: { /* … */ }, editor: { /* … */ }, tools: { /* … */ } };
  ctx.subscriptions.push(await ctx.aigd.gameEngines.registerEngine("acme.forge", engine));
}
```

应用会调用你的方法；每个方法都是 async 的，接收并返回纯 JSON，而且**绝不抛出异常**：失败也是一种结果，例如 `{ success: false, errorMessage }`。

| 方法 | 应用调用它的时机 |
| --- | --- |
| `project.validate(path)` | 用于确认检测到的文件夹确实是一个项目 |
| `project.create({ projectPath, name, starter?, force? })` | 来自创建对话框 |
| `plugin.status`、`install`、`update(projectPath)` | 用于在项目内部准备好项目所需的内容 |
| `editor.availability()` | 启动之前：该引擎能否在这台电脑上运行 |
| `editor.launch(projectPath, { operationId? })` | 在 Play 时，以及 agent 连接时 |
| `editor.diagnose(projectPath)` | 用于 Projects 面板的状态显示 |
| `editor.health?`、`editor.stop?`、`editor.gameView?`、`editor.runIdentity?`、`editor.prepare?` | 可选：解释失败原因、停止游戏、提供游戏视图的 URL、区分不同的运行、按需准备 |
| `tools.list(projectPath)`、`tools.call(projectPath, call)` | agent 的实时工具（`connection: "package"`） |

省略不写的可选方法会得到中性的答复：不停止、没有游戏视图、没有工具。

## 一次运行，逐步说明

1. **检测。** 用户打开一个文件夹；扫描匹配你的标记，并用你的图标和名称列出该项目。
2. **激活。** 应用触发 `onGameEngine:<id>`，并最多等待 30 秒让 `registerEngine` 完成。
3. **启动。** Play 会带着 `operationId` 调用 `editor.launch`。用 `host.progress({ operationId, message })` 报告进度行（像 `"Building 40%"` 这样的消息会画出一个进度条），并在各步骤之间检查 `await host.cancelled(operationId)`。如果 15 分钟没有进度，或总计 3 小时，调用就会结束。
4. **显示。** 当 `gameView: "browser"` 时，游戏面板会加载 `editor.gameView` 返回的 URL。
5. **连接。** 在聊天中，agent 连接时会把 `tools.list` 列为该项目的工具；每次调用都会发往 `tools.call`。工具名长度为 1 到 64 个字符，可用的字符为 `A-Z a-z 0-9 _ -`；请为每个工具提供一个 `inputSchema`。
6. **停止。** `editor.stop` 只结束由 `launch` 启动的内容，且仅此而已。

宿主服务包括 `logger(scope)`、`progress`、`cancelled`、`compareVersions(a, b)`，以及针对你自己存储文件夹内路径的文件锁和 macOS 隔离标记移除。将跨越单次调用而保留的状态（运行记录、已下载的运行时）保存在 `ctx.globalStoragePath` 或 `ctx.projectStoragePath` 中。

## 测试

- `gamedev pkg validate`：验证清单及其列出的文件。
- 将其链接到一个临时文件夹，从对话框创建项目，点击 Play，在聊天中连接，调用每个工具，停止；然后读取 `gamedev pkg logs <id>` 查看整个运行记录。
- `contractVersion` 指定你实现的引擎契约（目前只有 `1`）。新增内容保持版本不变；不兼容的变更会作为版本 2 与 1 并存发布。

## 相关页面

- [项目和引擎](https://ai-game.dev/zh-hans/docs/wiki/app/projects-and-engines) 介绍用户如何使用引擎项目。
- [包 API](https://ai-game.dev/zh-hans/docs/wiki/app/package-api) 介绍 `ctx.aigd` 的其余部分。
- [发布包](https://ai-game.dev/zh-hans/docs/wiki/app/publishing-packages) 以分享你的引擎。

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/app/game-engine-packages

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/app/game-engine-packages
