本頁面由英文機器翻譯而成。閱讀英文原文。

遊戲引擎套件

用套件讓 AI Game Dev 認識一整套遊戲引擎:專案偵測、建立對話框、Play、遊戲檢視與即時 agent 工具,逐步說明。

更新於 2026年11月19日 以 Markdown 檢視

遊戲引擎套件能讓 AI Game Dev 認識一整套引擎:哪些資料夾是它的專案、如何建立專案、如何執行、如何顯示執行中的遊戲,以及遊戲執行時 agent 能取得哪些即時工具。應用程式內建的引擎(Unity、Godot、Unreal Engine、BRUTAL、Bevy、Web)是在應用程式內部實作同一份契約;套件則是從 Extension Host 實作。引擎套件需要 AI Game Dev 0.32.0 或更新版本,並和其他套件一樣發佈到社群 registry。

從範本開始

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。

{
  "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> 上執行,並註冊實作:

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 並存的形式發布。