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.
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 -fThe 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"] }
}]
}
}| 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:
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
- Detect. The user opens a folder; the scan matches your markers and lists the project with your icon and name.
- Activate. The app fires
onGameEngine:<id>and waits up to 30 seconds forregisterEngine. - Launch. Play calls
editor.launchwith anoperationId. Report lines withhost.progress({ operationId, message })(a message like"Building 40%"draws a bar) and checkawait host.cancelled(operationId)between steps. A call ends after 15 minutes without progress, or 3 hours in all. - Show. With
gameView: "browser"the game panel loads the URLeditor.gameViewreturns. - Connect. In a chat, the agent's connect lists
tools.listas the project's tools; each call goes totools.call. A tool name is 1 to 64 ofA-Z a-z 0-9 _ -; give each aninputSchema. - Stop.
editor.stopends whatlaunchstarted, 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. contractVersionnames the engine contract you implement (only1today). Additions keep the version; an incompatible change would ship as version 2 beside 1.
Related pages
- Projects and engines for how users work with engine projects.
- Package API for the rest of
ctx.aigd. - Publishing packages to share your engine.