Game engine packages

Teach AI Game Dev a whole game engine with a package: project detection, the create dialog, Play, the game view and live agent tools, step by step.

Updated November 19, 2026 View as Markdown

A game engine package teaches AI Game Dev a whole engine: which folders are its projects, how to create one, how to run it, how to show the running game, and which live tools the agent gets while it runs. The app's own engines (Unity, Godot, Unreal Engine, BRUTAL, Bevy, Web) implement the same contract inside the app; a package implements it from the Extension Host. Engine packages need AI Game Dev 0.32.0 or newer and publish to the community registry like any other package.

Start from the template

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

The template is the example engine samples.toy-engine: it detects folders holding toy-engine.json, creates projects from two starters, runs the game as a small Node.js server on 127.0.0.1 that the game panel shows, gives the agent two live tools and stops the game. It needs no native binaries.

The declarative half: contributes.gameEngines

The app reads this without running your code, so a project is detected, listed, drawn and offered in the create dialog before your package starts. One engine per package; its id is the package 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"] }
    }]
  }
}
FieldWhat it does
detectAny rule matching marks a folder as a project: exists (a relative path, up to 3 segments), glob (a file name pattern in the folder), contains (a literal in the first 64 KB of the matched file), allOf (2 to 4 markers). Each engine has 2 seconds per scan, so keep markers cheap.
editor"app" when the engine has an editor application to launch, else "none"
connection"package": your package serves the agent's live tools; "none": no tools
gameView"browser": the running game is a web page the game panel shows
starters1 to 8 starters for the create dialog; at most one recommended; preview is a wide image (about 16:7, for example 640×280); blank and game tell the dialog what a starter looks like (leave them out to support app 0.32.0-beta.1 and older, which refuse them)
showcaseHow the create dialog presents the engine: accent and accent2 colours (#rrggbb), pitch (80 characters), summary, languages, up to 5 tags, shortName
editorInstall{url, label}: where to get what opening a project needs
skillsA package folder of <skill>/SKILL.md the agent loads for this engine's projects

A package never re-labels a Unity, Godot, Unreal or BRUTAL project. An invalid field drops the whole engine entry; gamedev pkg validate names it.

The code half: registerEngine

activate runs on onGameEngine:<id>, the first time the app needs the engine, and registers the implementation:

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));
}

The app calls your methods; every method is async, takes and returns plain JSON, and never throws: a failure is a result, such as { success: false, errorMessage }.

MethodThe app calls it
project.validate(path)To confirm a detected folder is a project
project.create({ projectPath, name, starter?, force? })From the create dialog
plugin.status, install, update(projectPath)To set up what a project needs inside it
editor.availability()Before a launch: can the engine run on this computer
editor.launch(projectPath, { operationId? })On Play, and when the agent connects
editor.diagnose(projectPath)For the Projects panel's status
editor.health?, editor.stop?, editor.gameView?, editor.runIdentity?, editor.prepare?Optional: explain a failure, stop the game, the game view's URL, tell runs apart, prepare on demand
tools.list(projectPath), tools.call(projectPath, call)The agent's live tools (connection: "package")

Optional methods you leave out get a neutral answer: no stop, no game view, no tools.

A run, step by step

  1. Detect. The user opens a folder; the scan matches your markers and lists the project with your icon and name.
  2. Activate. The app fires onGameEngine:<id> and waits up to 30 seconds for registerEngine.
  3. Launch. Play calls editor.launch with an operationId. Report lines with host.progress({ operationId, message }) (a message like "Building 40%" draws a bar) and check await host.cancelled(operationId) between steps. A call ends after 15 minutes without progress, or 3 hours in all.
  4. Show. With gameView: "browser" the game panel loads the URL editor.gameView returns.
  5. Connect. In a chat, the agent's connect lists tools.list as the project's tools; each call goes to tools.call. A tool name is 1 to 64 of A-Z a-z 0-9 _ -; give each an inputSchema.
  6. Stop. editor.stop ends what launch started, and only that.

The host services are logger(scope), progress, cancelled, compareVersions(a, b), and file locks and macOS quarantine removal for paths inside your own storage folders. Keep state that outlives one call (a run record, a downloaded runtime) in ctx.globalStoragePath or ctx.projectStoragePath.

Test it

  • gamedev pkg validate: the manifest and the files it names.
  • Link it into a scratch folder, create a project from the dialog, press Play, connect in a chat, call each tool, stop; then read gamedev pkg logs <id> for the whole run.
  • contractVersion names the engine contract you implement (only 1 today). Additions keep the version; an incompatible change would ship as version 2 beside 1.