Package-API
Die ctx.aigd-API der AI Game Developer-Pakete: Namespaces, stabile vs. vorgeschlagene Member, Desktop-Aufrufe und Beispiele für Tools, UI und State.
Der Code deines Pakets erreicht die App über ein einziges Objekt, ctx.aigd, das an activate(ctx) übergeben wird. Diese Seite listet seine Namespaces auf, nennt, welche Member stabil und welche vorgeschlagen sind, und zeigt funktionierende Beispiele für die Aufrufe, die die meisten Pakete machen: Befehle, Slash-Befehle, Agent-Tools, Einstellungen, Nachrichten, Webviews, Tree Views, Custom Editoren, Tutorials und gespeicherten State. Die Package-API hat Version 0.4.0.
Typen
gamedev pkg init schreibt die gesamte API als eine in sich geschlossene Datei, src/types/aigd.d.ts, die aus dem eigenen Vertrag der App generiert wird und zu der App-Version passt, die sie geschrieben hat. TypeScript importiert sie; JavaScript nutzt sie aus JSDoc:
import type { PackageContext } from "./types/aigd";
export async function activate(ctx: PackageContext): Promise<void> {
ctx.subscriptions.push(ctx.aigd.commands.registerCommand("acme.level-tools.hello", () => "hi"));
}
export function deactivate(): void {}/** @param {import("./types/aigd").PackageContext} ctx */
exports.activate = function activate(ctx) { /* … */ };Ein neueres gamedev pkg init in einem Wegwerfordner liefert dir eine neuere Kopie der Typen. Ein npm-Typenpaket (@ai-game-dev/package-api) ist vorbereitet, aber noch nicht veröffentlicht.
Jeder Aufruf überschreitet eine Prozessgrenze (dein Code läuft im Extension Host der App), daher müssen Argumente und Ergebnisse JSON-Werte sein, und jede Methode, die mit der App spricht, ist async. Die wenigen synchronen Member (env, project.path, settings.get) lesen State, den die App beim Start des Pakets gepusht hat.
Der Kontext
| Member | Was es ist |
|---|---|
ctx.aigd | Die API (unten) |
ctx.package | Dieses Paket: id, publisher, name, version, displayName, dir, manifest |
ctx.subscriptions | Alle Disposable hier pushen; die App disposed sie, wenn das Paket stoppt |
ctx.globalState, ctx.projectState | Kleine Key-Value-Stores für diesen Computer und für dieses Projekt auf diesem Computer |
ctx.globalStoragePath, ctx.projectStoragePath | Ordner, in die dein Paket schreiben darf |
ctx.log | debug, info, warn, error: Zeilen mit Tag pkg:<id> im App-Log |
ctx.asAbsolutePath(rel) | Ein Pfad innerhalb des Paketordners |
ctx.reportError(err, subject?) | Einen Fehler in der Errors-Liste des Packages-Fensters erfassen |
Namespaces
| Namespace | Was es tut | Status |
|---|---|---|
env | Host (desktop oder cli), App-Version, Plattform, nodeCommand, fetch über den System-Proxy, openExternal, Zwischenablage (Desktop) | Stabil |
commands | Befehle und Slash-Befehle registrieren und ausführen, when-Kontextschlüssel setzen | Stabil |
capabilities | Status, Aktivierung und Anhängen deiner Tools-Schalter pro Chat | Stabil |
mcp | MCP-Server für dieses Projekt registrieren | Stabil |
agent | Agent-Tools im Speicher bereitstellen (registerProvider) | Stabil |
gameEngines | Eine Game Engine implementieren (registerEngine, host) | Stabil seit 0.4.0 |
settings | Einstellungen lesen und schreiben, Änderungen beobachten | Stabil |
project | Der Projektpfad und getInfo() (Engine, Engine-Version, die Engine-Projekte im Ordner) | Stabil |
packages | Andere Pakete und ihre Exporte (all, get, getExports) | Stabil |
claude | Einen Claude Code-Plugin-Ordner zu den Chats dieses Projekts hinzufügen (registerPlugin) | Stabil |
editor | Die Tools des verbundenen Engine-Editors, für Chats, an die dein Provider angehängt ist | Stabil |
account | Der Capability-Katalog des angemeldeten Kontos (getSnapshot) | Stabil |
media | Einen lokalen Media-Generator registrieren, der in contributes.mediaProviders deklariert ist (registerProvider) | Stabil |
window | Nachrichten, Quick Picks, Eingabefelder, Fortschritt, Statusleiste, Webviews, Tree Views, Custom Editoren | Stabil, Desktop |
tutorials | In-App-Tipps anfordern und verfolgen | Stabil, Desktop |
sessions | list(), active() und Live-Events sind stabil; Transkripte, Prompts und Konfiguration pro Chat sind vorgeschlagen | Gemischt |
storage, downloads, hardware | Der Blob-Store der App, verifizierte Downloads und Hardware-Probe | Vorgeschlagen |
tasks, subscriptions, work | Beobachtung von Hintergrundtasks, langlaufende Arbeit, Work Holds | Vorgeschlagen |
Member, die in aigd.d.ts mit @desktop markiert sind, tun in der CLI nichts: Sie lösen zu undefined auf oder geben ein inertes Objekt zurück, und der Host loggt eine Zeile. Prüfe aigd.env.host, wenn sich dein Paket im Terminal anders verhalten soll.
Stabile und vorgeschlagene API
Ein stabiles Member behält seine Bedeutung in jeder App-Version. Änderungen sind nur Ergänzungen; ein stabiles Member wird erst entfernt, nachdem mindestens zwei Minor-App-Releases lang Deprecation-Warnungen erschienen sind (eine Zeile pro Paket und Session in gamedev pkg logs), zusammen mit einer Anhebung der ältesten engines.aigd, die die App lädt.
Ein vorgeschlagenes Member kann sich in jeder Version ändern oder verschwinden. Um eines aufzurufen, deklariere sein Proposal; ein Aufruf ohne die Deklaration schlägt mit einer Meldung fehl, die das Proposal nennt:
{ "enabledApiProposals": ["forms"] }| Proposal | Member |
|---|---|
forms | window.showForm |
alerts | window.showAlert |
sessions | sessions.getTranscript, sendPrompt, create, focusComposer |
sessionConfiguration | paketweise Konfiguration pro Chat und Tools-Module (sessions.getConfiguration, updateConfiguration, registerToolStateProvider, …) |
appFocus | window.keepInFront |
storage, downloads, hardware | der Blob-Store, der Download-Manager, die Hardware-Probe |
backgroundTasks, subscriptions, workHolds | tasks.*, subscriptions.open, work.hold |
paidOperations, mockJobs | bezahlte Server-Jobs (nur die eigenen Provider-Pakete von AI Game Dev) und ihre Entwicklungs-Simulation |
Befehle und Slash-Befehle
const ID = "acme.level-tools";
ctx.subscriptions.push(
aigd.commands.registerCommand(`${ID}.count`, async (...args) => {
const n = await countCollectibles();
await aigd.window.showInformationMessage(`${n} collectibles in this level`);
return n;
}),
aigd.commands.registerSlashCommand("/collectibles", async (inv) => {
inv.say("Counting…"); // a system line in the chat, live
const n = await countCollectibles(inv.args.trim());
inv.say(`${n} collectibles.`);
}),
);
await aigd.commands.setContext(`${ID}.hasLevel`, true); // usable in when clauses
await aigd.commands.executeCommand("aigd.packages.open", { packageId: ID });Ein Slash-Befehl erhält den Text nach seinem Namen (inv.args), den Chat, in dem er eingegeben wurde (inv.sessionId), say() für Live-Zeilen und cancelled, ein Promise, das sich auflöst, wenn der Benutzer Esc oder Stop drückt. Slash-Befehle funktionieren im Desktop-Chat und in der CLI gleich. App-Befehle, die dein Paket ausführen darf, sind unter anderem aigd.packages.open, aigd.packages.reload, aigd.packages.checkForUpdates, aigd.session.focus, aigd.settings.open und aigd.tutorials.show.
Dem Agenten Werkzeuge geben
Ein MCP-Server, deklariert. Der einfachste Weg: Deklariere den Server und eine Capability, die ihn pro Chat einschaltet. Kein Code nötig; der Server ist dein eigenes Skript, das mit dem Node der App gestartet wird:
{
"contributes": {
"capabilities": [
{ "id": "acme.level-tools", "label": "Level tools", "description": "Counts collectibles in level files.", "mcpServer": "acme--level-tools" }
],
"mcpServers": {
"acme--level-tools": { "command": "${node}", "args": ["${packageDir}/server.js"] }
}
}
}Ein MCP-Server, zur Laufzeit registriert. Für einen Server, dessen Adresse du erst kennst, wenn etwas gestartet ist (der Port einer externen App):
await aigd.mcp.registerServer("acme--level-tools", { type: "http", url: `http://127.0.0.1:${port}/mcp` });Tools direkt aus deinem Code. Ein Agent-Provider hält die Tools in deinem Paket, ohne Serverprozess. Deklariere ihn mit seiner Capability und registriere ihn dann:
{
"contributes": {
"capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
"agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
}
}ctx.subscriptions.push(await aigd.agent.registerProvider("acme.helper.agent", {
getTools: () => [{
name: "status",
description: "Read the helper's status",
inputSchema: { type: "object", properties: {}, additionalProperties: false },
}],
getInstructions: () => "Use the helper's status tool when working in this project.",
invokeTool: async (name, args, context) => ({ content: [{ type: "text", text: context.project.path }] }),
}));Das Eingabe-Schema eines Tools muss eine Objekt-Wurzel haben, ohne oneOf, anyOf oder allOf auf oberster Ebene. Ergebnisse können Text und Bilder tragen ({ type: "image", data, mimeType }, PNG, JPEG oder WebP); ein Bild, das die Prüfungen der App nicht besteht, wird durch einen Hinweis ersetzt, nie durch einen Fehler. Die Standard-Frist für Tools ist 60 Sekunden (executionTimeoutMs, bis zu einer Stunde).
Eine Capability mit Status. Setze statusful: true auf der Capability, wenn das Einschalten Aufwand bedeutet (Start einer externen App). Die App zeigt dann deinen Status am Schalter an und ruft deinen Activation-Handler auf:
ctx.subscriptions.push(
aigd.capabilities.registerStatusProvider("acme.level-tools", async () =>
(await isRunning()) ? { phase: "connected", detail: "Editor 4.2" } : { phase: "idle" }),
aigd.capabilities.registerActivationHandler("acme.level-tools", async (req) => {
req.progress("Starting the level server…");
try { await start(); return { ok: true }; }
catch (e) { return { ok: false, failure: { code: "start-failed", text: String(e) } }; }
}),
);Einstellungen
const quality = aigd.settings.get<string>("quality") ?? "draft";
await aigd.settings.update("quality", "final", "project"); // user, project or local
ctx.subscriptions.push(aigd.settings.onDidChange((e) => ctx.log.info(`${e.key} is now ${String(e.value)}`)));Die Schlüssel gehören dir (ohne das Paket-Präfix) und müssen in contributes.settings deklariert werden. Jeder Schreibvorgang wird gegen die Deklaration validiert.
Meldungen, Auswahldialoge und Fortschritt
const choice = await aigd.window.showWarningMessage("Overwrite the export?", { modal: true }, "Overwrite", "Keep");
const level = await aigd.window.showQuickPick(["forest", "cave", "castle"], { title: "Export which level?" });
const name = await aigd.window.showInputBox({ prompt: "File name", value: "level-1" });
await aigd.window.withProgress({ title: "Exporting", cancellable: true }, async (progress, cancelled) => {
progress.report({ message: "Meshes", increment: 50 });
progress.report({ message: "Textures", increment: 50 });
});
const item = aigd.window.createStatusBarItem("acme.level-tools.status", { alignment: "left" });
item.text = "3 levels";
item.command = "acme.level-tools.count";
item.show();
ctx.subscriptions.push(item);In der CLI werden Meldungen als Systemzeilen ausgegeben; eine modale Meldung, ein Quick Pick oder eine Eingabebox wird zu einer Terminal-Abfrage, während dein Slash-Befehl läuft. Außerhalb eines Slash-Befehls lehnt die CLI Abfragen mit einem PromptRefusedError ab (Code prompt_refused); ein Paket, das Fragen stellt, sollte sie daher aus einem Slash-Befehl heraus stellen oder aigd.env.host prüfen.
Webviews: Panels, Seitenansichten und Fenster
Eine Webview ist deine eigene HTML-Seite innerhalb der App (Desktop). Dieselbe Seite funktioniert in einem Bereich, einem Tab im Seitenpanel oder in einem eigenen Fenster:
const panel = aigd.window.createWebviewPanel("acme.level-tools.map", "Level map");
const script = panel.webview.asWebviewUri(ctx.asAbsolutePath("dist/map.js"));
panel.webview.html = `<!doctype html><html><body><canvas id="map"></canvas>
<script type="module" src="${script}"></script></body></html>`;
panel.webview.onDidReceiveMessage((msg) => ctx.log.info(`page says ${JSON.stringify(msg)}`));
await panel.webview.postMessage({ type: "level", tiles });// dist/map.js, inside the page
const api = acquireAigdApi();
api.postMessage({ type: "ready" });
window.addEventListener("message", (e) => draw(e.data));
api.setState({ zoom: 2 }); // restored with the pane after a relaunch- Tab im Seitenpanel: Deklariere
{ "id": "acme.level-tools.side", "name": "Levels", "type": "webview" }untercontributes.views.rightund registriereaigd.window.registerWebviewViewProvider("acme.level-tools.side", { resolveWebviewView(view) { view.webview.html = page(); } }). Mit"titleBar": "hidden"kann deine Seite ihre eigene Kopfzeile zeichnen. - Eigenes Fenster:
aigd.window.createWebviewWindow(viewType, title)öffnet ein größenveränderbares natives Fenster, eines pro View-Typ pro Projekt. Seine Seite läuft unter einer strikten Content Security Policy: nur die eigenen Dateien des Pakets, kein Netzwerk, keineval. - Theme: Die Seite erhält
<html data-theme="light|dark">und die Palette der App als CSS-Variablen--aigd-*(--aigd-bg,--aigd-surface,--aigd-text,--aigd-primary, …), die bei jedem Theme-Wechsel neu gesendet werden. - Page-API:
acquireAigdApi()liefertpostMessage,getState,setState,executeCommand(deine eigenen Befehle und App-Befehle),getContext()undclose().
Tree-Ansichten
const tree = aigd.window.createTreeView("acme.level-tools.levels", {
treeDataProvider: {
getChildren: async (parent) => parent
? listObjects(parent.id).map((o) => ({ id: o.id, label: o.name, icon: "$(box)" }))
: listLevels().map((l) => ({ id: l.id, label: l.name, collapsible: "collapsed", contextValue: "level" })),
},
});
tree.message = "3 levels";
ctx.subscriptions.push(tree);Die Ansicht wird mit "type": "tree" in contributes.views deklariert. contextValue wird für view/item/context-Menüs zu viewItem; Einträge können Checkboxen, Badges und einen Klick-Befehl tragen.
Benutzerdefinierte Editoren
{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }ctx.subscriptions.push(aigd.window.registerCustomEditorProvider("acme.level-tools.level", {
resolveCustomEditor(document, panel) {
panel.webview.html = renderLevel(fs.readFileSync(document.path, "utf8"));
},
}));Ein default-Editor ersetzt die eigene Vorschau der App für passende Dateien; ein option-Editor erscheint unter Open With. Dokumente sind von der App-Seite aus schreibgeschützt: Dein Paket schreibt Dateien selbst, und der Bereich lädt neu, wenn sich die Datei auf der Festplatte ändert. aigd.window.openPreview(path) zeigt eine Projektdatei in der Vorschau, wie es ein Klick im Explorer tut.
Tutorials
{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }ctx.subscriptions.push(aigd.tutorials.request("acme.level-tools.intro"));Ein Tipp wird jedem Nutzer einmal angezeigt, in einem ruhigen Moment, und zeigt auf seinen Anker: capability:, statusBar:, view:, slashCommand:, command: oder menu: gefolgt von einer id, composer oder none. markdown mit bis zu 8 media-Dateien oder eine webview-Seite für umfangreiche Inhalte. request(id, { force: true }) zeigt ihn erneut an; isSeen und setSeen lesen und setzen den Gesehen-Status.
Gespeicherter Zustand
const DATA = 2;
if ((ctx.globalState.dataVersion ?? 0) < DATA) {
await migrate(ctx.globalState);
await ctx.globalState.setDataVersion(DATA);
}
await ctx.projectState.update("lastExport", new Date().toISOString());
const last = ctx.projectState.get<string>("lastExport");globalState wird von jedem Projekt auf diesem Computer geteilt; projectState gehört zu diesem Projekt auf diesem Computer. Beide überleben Updates und das Entfernen (beim erneuten Hinzufügen des Pakets werden sie wiederhergestellt); Remove data im Fenster Packages löscht sie. Die App migriert deine Daten nie: dataVersion liegt bei dir, um sie zu vergleichen und zu erhöhen.
Verwandte Seiten
- Referenz zum Paketmanifest für die Deklarationen, mit denen diese Aufrufe zusammengehören.
- Lebenszyklus, Hosts und Berechtigungen dazu, wann dein Code ausgeführt wird und was er tun darf.
- Pakete für Spiel-Engines für
aigd.gameEngines.