# Game-Engine-Pakete — AI Game Dev App & CLI · AI Game Developer Wiki

Ein Paket lehrt AI Game Dev eine ganze Engine: Projekterkennung, Erstellen-Dialog, Play, Spielansicht und Live-Tools für den Agenten.

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

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

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

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

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

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

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

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

1. **Erkennen.** Der Nutzer öffnet einen Ordner; der Scan trifft deine Marker und listet das Projekt mit deinem Icon und Namen auf.
2. **Aktivieren.** Die App löst `onGameEngine:<id>` aus und wartet bis zu 30 Sekunden auf `registerEngine`.
3. **Starten.** Play ruft `editor.launch` mit einer `operationId` auf. Melde Zeilen mit `host.progress({ operationId, message })` (eine Meldung wie `"Building 40%"` zeichnet einen Balken) und prüfe zwischen den Schritten `await host.cancelled(operationId)`. Ein Aufruf endet nach 15 Minuten ohne Fortschritt oder nach insgesamt 3 Stunden.
4. **Anzeigen.** Mit `gameView: "browser"` lädt das Spiel-Panel die URL, die `editor.gameView` zurückgibt.
5. **Verbinden.** In einem Chat listet der Connect des Agenten `tools.list` als die Tools des Projekts auf; jeder Aufruf geht an `tools.call`. Ein Tool-Name besteht aus 1 bis 64 Zeichen aus `A-Z a-z 0-9 _ -`; gib jedem ein `inputSchema`.
6. **Stopp.** `editor.stop` beendet, was `launch` gestartet 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.
- `contractVersion` benennt den Engine-Vertrag, den du implementierst (heute nur `1`). Ergänzungen behalten die Version; eine inkompatible Änderung würde als Version 2 neben 1 erscheinen.

## Verwandte Seiten

- [Projekte und Engines](https://ai-game.dev/de/docs/wiki/app/projects-and-engines) für den Umgang von Nutzern mit Engine-Projekten.
- [Package API](https://ai-game.dev/de/docs/wiki/app/package-api) für den Rest von `ctx.aigd`.
- [Pakete veröffentlichen](https://ai-game.dev/de/docs/wiki/app/publishing-packages), um deine Engine zu teilen.

---

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

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