游戏引擎包
用一个包让 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 的文件夹,从两个起始模板创建项目,把游戏作为一个小型 Node.js 服务器运行在 127.0.0.1 上并由游戏面板显示,为 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 告诉对话框某个起始模板是什么样子(省略它们可兼容 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));
}应用会调用你的方法;每个方法都是 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") |
省略不写的可选方法会得到中性的答复:不停止、没有游戏视图、没有工具。
一次运行,逐步说明
- 检测。 用户打开一个文件夹;扫描匹配你的标记,并用你的图标和名称列出该项目。
- 激活。 应用触发
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:验证清单及其列出的文件。- 将其链接到一个临时文件夹,从对话框创建项目,点击 Play,在聊天中连接,调用每个工具,停止;然后读取
gamedev pkg logs <id>查看整个运行记录。 contractVersion指定你实现的引擎契约(目前只有1)。新增内容保持版本不变;不兼容的变更会作为版本 2 与 1 并存发布。