遊戲引擎套件
用套件讓 AI Game Dev 認識一整套遊戲引擎:專案偵測、建立對話框、Play、遊戲檢視與即時 agent 工具,逐步說明。
遊戲引擎套件能讓 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") |
省略的選用方法會得到中性的回應:不停止、沒有遊戲檢視、沒有工具。
一次執行的逐步流程
- 偵測。 使用者開啟資料夾;掃描比對到你的標記後,便以你的圖示與名稱列出該專案。
- 啟用。 應用程式發出
onGameEngine:<id>,並最多等待 30 秒讓registerEngine完成。 - 啟動。 Play 會帶著
operationId呼叫editor.launch。用host.progress({ operationId, message })回報每一行訊息(像"Building 40%"這樣的訊息會畫出進度條),並在步驟之間檢查await host.cancelled(operationId)。呼叫若 15 分鐘沒有進度,或總計 3 小時後就會結束。 - 顯示。 當
gameView: "browser"時,遊戲面板會載入editor.gameView回傳的 URL。 - 連線。 在對話中,agent 連線時會把
tools.list列為專案的工具;每次呼叫都會送到tools.call。工具名稱長度為 1 到 64 個字元,可用A-Z a-z 0-9 _ -;請為每個工具提供inputSchema。 - 停止。
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 並存的形式發布。