# 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.

_Last updated: 2026-11-19_

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

```bash
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.

```json
{
  "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"] }
    }]
  }
}
```

| Field | What it does |
| --- | --- |
| `detect` | Any 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 |
| `starters` | 1 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) |
| `showcase` | How 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 |
| `skills` | A 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:

```typescript
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 }`.

| Method | The 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.

## Related pages

- [Projects and engines](https://ai-game.dev/docs/wiki/app/projects-and-engines) for how users work with engine projects.
- [Package API](https://ai-game.dev/docs/wiki/app/package-api) for the rest of `ctx.aigd`.
- [Publishing packages](https://ai-game.dev/docs/wiki/app/publishing-packages) to share your engine.

---

Source (HTML): https://ai-game.dev/docs/wiki/app/game-engine-packages
