# Package-API — AI Game Dev App & CLI · AI Game Developer Wiki

Die ctx.aigd-API der AI Game Developer-Pakete: Namespaces, stabile vs. vorgeschlagene Member, Desktop-Aufrufe und Beispiele für Tools, UI und State.

Diese Seite wurde maschinell aus dem Englischen übersetzt. [Englisches Original lesen](https://ai-game.dev/docs/wiki/app/package-api).

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:

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

```javascript
/** @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:

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

**Warnung**

Die Community-Registry lehnt jedes Paket ab, das einen Proposal deklariert. Ein Paket, das einen braucht, kann trotzdem von GitHub, npm oder einem Ordner aus geteilt werden; siehe [Pakete veröffentlichen](https://ai-game.dev/de/docs/wiki/app/publishing-packages#other-sources).

## Befehle und Slash-Befehle

```typescript
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:

```json
{
  "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):

```typescript
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:

```json
{
  "contributes": {
    "capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
    "agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
  }
}
```

```typescript
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:

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

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

```typescript
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:

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

```javascript
// 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" }` unter `contributes.views.right` und registriere `aigd.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, kein `eval`.
- **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()` liefert `postMessage`, `getState`, `setState`, `executeCommand` (deine eigenen Befehle und App-Befehle), `getContext()` und `close()`.

## Tree-Ansichten

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

```json
{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }
```

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

```json
{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }
```

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

```typescript
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](https://ai-game.dev/de/docs/wiki/app/package-manifest) für die Deklarationen, mit denen diese Aufrufe zusammengehören.
- [Lebenszyklus, Hosts und Berechtigungen](https://ai-game.dev/de/docs/wiki/app/package-lifecycle) dazu, wann dein Code ausgeführt wird und was er tun darf.
- [Pakete für Spiel-Engines](https://ai-game.dev/de/docs/wiki/app/game-engine-packages) für `aigd.gameEngines`.

---

Source (HTML): https://ai-game.dev/de/docs/wiki/app/package-api

Machine-translated (de) from the English page: https://ai-game.dev/docs/wiki/app/package-api
