# 遊戲引擎套件 — 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` 的資料夾、從兩個起始範本建立專案、以 `127.0.0.1` 上的小型 Node.js 伺服器執行遊戲並由遊戲面板顯示、提供 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` 告訴對話框這個起始範本是什麼樣子（若要支援 app 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));
}
```

應用程式會呼叫你的方法；每個方法都是非同步、接收並回傳純 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`：檢查 manifest 以及它所列出的檔案。
- 把它連結到一個暫存資料夾，從對話框建立專案、按下 Play、在聊天中連線、逐一呼叫每個工具、停止；然後讀取 `gamedev pkg logs <id>` 查看整段執行過程。
- `contractVersion` 指出你所實作的引擎契約（目前只有 `1`）。新增功能會沿用同一版本；若有不相容的變更，則會以版本 2 與 1 並存的形式發布。

## 相關頁面

- [專案與引擎](https://ai-game.dev/zh-hant/docs/wiki/app/projects-and-engines)：使用者如何操作引擎專案。
- [套件 API](https://ai-game.dev/zh-hant/docs/wiki/app/package-api)：`ctx.aigd` 的其他部分。
- [發布套件](https://ai-game.dev/zh-hant/docs/wiki/app/publishing-packages)：分享你的引擎。

---

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

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