Game-Engine-Pakete
Ein Paket lehrt AI Game Dev eine ganze Engine: Projekterkennung, Erstellen-Dialog, Play, Spielansicht und Live-Tools für den Agenten.
Ein Game-Engine-Paket bringt AI Game Dev eine ganze Engine bei: welche Ordner ihre Projekte sind, wie man eines erstellt, wie man sie startet, wie man das laufende Spiel anzeigt und welche Live-Tools der Agent während des Laufs bekommt. Die eigenen Engines der App (Unity, Godot, Unreal Engine, BRUTAL, Bevy, Web) implementieren denselben Vertrag innerhalb der App; ein Paket implementiert ihn aus dem Extension Host heraus. Engine-Pakete benötigen AI Game Dev 0.32.0 oder neuer und werden wie jedes andere Paket in der Community-Registry veröffentlicht.
Mit der Vorlage starten
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 -fDie Vorlage ist die Beispiel-Engine samples.toy-engine: Sie erkennt Ordner mit einer toy-engine.json, erstellt Projekte aus zwei Startern, startet das Spiel als kleinen Node.js-Server auf 127.0.0.1, den das Spiel-Panel anzeigt, gibt dem Agenten zwei Live-Tools und stoppt das Spiel. Sie benötigt keine nativen Binärdateien.
Die deklarative Hälfte: contributes.gameEngines
Die App liest dies, ohne deinen Code auszuführen, sodass ein Projekt erkannt, gelistet, gezeichnet und im Erstellen-Dialog angeboten wird, bevor dein Paket startet. Eine Engine pro Paket; ihre id ist die Paket-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"] }
}]
}
}| Feld | Was es bewirkt |
|---|---|
detect | Jede passende Regel markiert einen Ordner als Projekt: exists (ein relativer Pfad, bis zu 3 Segmente), glob (ein Dateinamenmuster im Ordner), contains (ein Literal in den ersten 64 KB der getroffenen Datei), allOf (2 bis 4 Marker). Jede Engine hat 2 Sekunden pro Scan, halte die Marker also günstig. |
editor | "app", wenn die Engine eine Editor-Anwendung zum Starten hat, sonst "none" |
connection | "package": dein Paket stellt die Live-Tools des Agenten bereit; "none": keine Tools |
gameView | "browser": das laufende Spiel ist eine Webseite, die das Spiel-Panel anzeigt |
starters | 1 bis 8 Starter für den Erstellen-Dialog; höchstens ein recommended; preview ist ein breites Bild (etwa 16:7, zum Beispiel 640×280); blank und game sagen dem Dialog, wie ein Starter aussieht (lass sie weg, um App 0.32.0-beta.1 und älter zu unterstützen, die sie ablehnen) |
showcase | Wie der Erstellen-Dialog die Engine präsentiert: Farben accent und accent2 (#rrggbb), pitch (80 Zeichen), summary, languages, bis zu 5 tags, shortName |
editorInstall | {url, label}: wo man bekommt, was zum Öffnen eines Projekts nötig ist |
skills | Ein Paketordner mit <skill>/SKILL.md, den der Agent für die Projekte dieser Engine lädt |
Ein Paket etikettiert niemals ein Unity-, Godot-, Unreal- oder BRUTAL-Projekt um. Ein ungültiges Feld verwirft den gesamten Engine-Eintrag; gamedev pkg validate nennt es.
Die Code-Hälfte: registerEngine
activate läuft bei onGameEngine:<id>, wenn die App die Engine zum ersten Mal braucht, und registriert die Implementierung:
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));
}Die App ruft deine Methoden auf; jede Methode ist async, nimmt und liefert reines JSON und wirft nie: Ein Fehler ist ein Ergebnis, etwa { success: false, errorMessage }.
| Methode | Wann die App sie aufruft |
|---|---|
project.validate(path) | Um zu bestätigen, dass ein erkannter Ordner ein Projekt ist |
project.create({ projectPath, name, starter?, force? }) | Aus dem Erstellen-Dialog |
plugin.status, install, update(projectPath) | Um einzurichten, was ein Projekt intern braucht |
editor.availability() | Vor einem Start: Kann die Engine auf diesem Computer laufen |
editor.launch(projectPath, { operationId? }) | Bei Play und wenn der Agent sich verbindet |
editor.diagnose(projectPath) | Für den Status im Projekte-Panel |
editor.health?, editor.stop?, editor.gameView?, editor.runIdentity?, editor.prepare? | Optional: einen Fehler erklären, das Spiel stoppen, die URL der Spielansicht, Läufe unterscheiden, bei Bedarf vorbereiten |
tools.list(projectPath), tools.call(projectPath, call) | Die Live-Tools des Agenten (connection: "package") |
Optionale Methoden, die du weglässt, erhalten eine neutrale Antwort: kein Stopp, keine Spielansicht, keine Tools.
Ein Durchlauf, Schritt für Schritt
- Erkennen. Der Nutzer öffnet einen Ordner; der Scan trifft deine Marker und listet das Projekt mit deinem Icon und Namen auf.
- Aktivieren. Die App löst
onGameEngine:<id>aus und wartet bis zu 30 Sekunden aufregisterEngine. - Starten. Play ruft
editor.launchmit eineroperationIdauf. Melde Zeilen mithost.progress({ operationId, message })(eine Meldung wie"Building 40%"zeichnet einen Balken) und prüfe zwischen den Schrittenawait host.cancelled(operationId). Ein Aufruf endet nach 15 Minuten ohne Fortschritt oder nach insgesamt 3 Stunden. - Anzeigen. Mit
gameView: "browser"lädt das Spiel-Panel die URL, dieeditor.gameViewzurückgibt. - Verbinden. In einem Chat listet der Connect des Agenten
tools.listals die Tools des Projekts auf; jeder Aufruf geht antools.call. Ein Tool-Name besteht aus 1 bis 64 Zeichen ausA-Z a-z 0-9 _ -; gib jedem eininputSchema. - Stopp.
editor.stopbeendet, waslaunchgestartet hat – und nur das.
Die Host-Dienste sind logger(scope), progress, cancelled, compareVersions(a, b) sowie Dateisperren und das Entfernen der macOS-Quarantäne für Pfade innerhalb deiner eigenen Speicherordner. Zustand, der einen Aufruf überdauert (ein Run-Datensatz, eine heruntergeladene Runtime), gehört in ctx.globalStoragePath oder ctx.projectStoragePath.
Testen
gamedev pkg validate: das Manifest und die darin genannten Dateien.- Verknüpfe es in einem Testordner, erstelle ein Projekt über den Dialog, drücke Play, verbinde dich in einem Chat, rufe jedes Tool auf, stoppe; lies dann
gamedev pkg logs <id>für den gesamten Lauf. contractVersionbenennt den Engine-Vertrag, den du implementierst (heute nur1). Ergänzungen behalten die Version; eine inkompatible Änderung würde als Version 2 neben 1 erscheinen.
Verwandte Seiten
- Projekte und Engines für den Umgang von Nutzern mit Engine-Projekten.
- Package API für den Rest von
ctx.aigd. - Pakete veröffentlichen, um deine Engine zu teilen.