本页由英文机器翻译而成。阅读英文原文。

游戏引擎包

用一个包让 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 的文件夹,从两个起始模板创建项目,把游戏作为一个小型 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")

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

一次运行,逐步说明

  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 并存发布。