# ゲームエンジンパッケージ — AI Game DevアプリとCLI · AI Game Developer Wiki

パッケージでゲームエンジン全体を AI Game Dev に教え込みます。プロジェクト検出、作成ダイアログ、Play、ゲームビュー、エージェントのライブツールを順を追って解説します。

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/app/game-engine-packages)。

ゲームエンジンパッケージは、AI Game Dev にエンジン全体を教え込みます。どのフォルダーがそのプロジェクトなのか、プロジェクトの作成方法、実行方法、実行中のゲームの表示方法、そして実行中にエージェントが使えるライブツールはどれか、といった内容です。アプリ内蔵のエンジン（Unity、Godot、Unreal Engine、BRUTAL、Bevy、Web）はアプリ内で同じ契約を実装していますが、パッケージは Extension Host からそれを実装します。エンジンパッケージには AI Game Dev 0.32.0 以降が必要で、他のパッケージと同様にコミュニティレジストリへ公開します。

## テンプレートから始める

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

テンプレートはサンプルエンジン `samples.toy-engine` です。`toy-engine.json` を含むフォルダーを検出し、2 つのスターターからプロジェクトを作成し、ゲームを `127.0.0.1` 上の小さな Node.js サーバーとして実行してゲームパネルに表示し、エージェントに 2 つのライブツールを提供し、ゲームを停止します。ネイティブバイナリは不要です。

## 宣言型の部分: contributes.gameEngines

アプリはあなたのコードを実行せずにこれを読み取るため、パッケージが起動する前にプロジェクトの検出・一覧表示・描画・作成ダイアログでの提示が行われます。1 パッケージにつき 1 エンジンで、その `id` はパッケージ 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"] }
    }]
  }
}
```

| フィールド | 内容 |
| --- | --- |
| `detect` | いずれかのルールに一致すると、そのフォルダーがプロジェクトとしてマークされます: `exists`（相対パス、最大 3 セグメント）、`glob`（フォルダー内のファイル名パターン）、`contains`（一致したファイルの先頭 64 KB 内のリテラル）、`allOf`（2〜4 個のマーカー）。各エンジンのスキャンは 2 秒なので、マーカーは軽量に保ってください。 |
| `editor` | エンジンに起動するエディターアプリがある場合は `"app"`、なければ `"none"` |
| `connection` | `"package"`: パッケージがエージェントのライブツールを提供します。`"none"`: ツールなし |
| `gameView` | `"browser"`: 実行中のゲームはゲームパネルに表示される Web ページです |
| `starters` | 作成ダイアログ用のスターターを 1〜8 個。`recommended` は最大 1 個。`preview` は横長画像（約 16:7、例えば 640×280）。`blank` と `game` はスターターの種類をダイアログに伝えます（これらを拒否するアプリ 0.32.0-beta.1 以前に対応するには省略してください） |
| `showcase` | 作成ダイアログでのエンジンの見せ方: `accent` と `accent2` の色（`#rrggbb`）、`pitch`（80 文字）、`summary`、`languages`、最大 5 個の `tags`、`shortName` |
| `editorInstall` | `{url, label}`: プロジェクトを開くのに必要なものを入手できる場所 |
| `skills` | `<skill>/SKILL.md` を含むパッケージフォルダーで、エージェントがこのエンジンのプロジェクト向けに読み込みます |

パッケージが Unity、Godot、Unreal、BRUTAL のプロジェクトのラベルを付け替えることはありません。無効なフィールドがあるとエンジンエントリ全体が破棄されます。`gamedev pkg validate` がそのフィールドを指摘します。

## コード側の部分: registerEngine

`activate` は、アプリが初めてそのエンジンを必要としたときに `onGameEngine:<id>` で実行され、実装を登録します:

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

アプリがあなたのメソッドを呼び出します。すべてのメソッドは非同期で、プレーンな JSON を受け取って返し、**決してスローしません**: 失敗は `{ success: false, errorMessage }` のような結果として返されます。

| メソッド | アプリが呼び出すタイミング |
| --- | --- |
| `project.validate(path)` | 検出されたフォルダーがプロジェクトであることを確認するため |
| `project.create({ projectPath, name, starter?, force? })` | 作成ダイアログから |
| `plugin.status`、`install`、`update(projectPath)` | プロジェクト内で必要なものをセットアップするため |
| `editor.availability()` | 起動前: このコンピューターでエンジンを実行できるか |
| `editor.launch(projectPath, { operationId? })` | Play 時、およびエージェントが接続したとき |
| `editor.diagnose(projectPath)` | Projects パネルのステータス用 |
| `editor.health?`、`editor.stop?`、`editor.gameView?`、`editor.runIdentity?`、`editor.prepare?` | 任意: 失敗の説明、ゲームの停止、ゲームビューの URL、実行の識別、オンデマンドの準備 |
| `tools.list(projectPath)`、`tools.call(projectPath, call)` | エージェントのライブツール（`connection: "package"`） |

省略した任意のメソッドには中立的な応答が返ります: 停止なし、ゲームビューなし、ツールなし。

## 1 回の実行を順を追って

1. **検出。** ユーザーがフォルダーを開くと、スキャンがあなたのマーカーに一致し、プロジェクトがあなたのアイコンと名前で一覧表示されます。
2. **アクティベート。** アプリが `onGameEngine:<id>` を発火し、`registerEngine` を最大 30 秒待ちます。
3. **起動。** Play は `operationId` 付きで `editor.launch` を呼び出します。`host.progress({ operationId, message })` で行を報告し（`"Building 40%"` のようなメッセージはバーを描画します）、各ステップの間で `await host.cancelled(operationId)` を確認します。呼び出しは進捗なしで 15 分、合計で 3 時間で終了します。
4. **表示。** `gameView: "browser"` の場合、ゲームパネルが `editor.gameView` の返す URL を読み込みます。
5. **接続。** チャットで、エージェントの接続は `tools.list` をプロジェクトのツールとして一覧表示し、各呼び出しは `tools.call` に送られます。ツール名は `A-Z a-z 0-9 _ -` の 1〜64 文字です。それぞれに `inputSchema` を指定してください。
6. **停止。** `editor.stop` は `launch` が開始したものを終了させ、それだけを行います。

ホストサービスは `logger(scope)`、`progress`、`cancelled`、`compareVersions(a, b)`、および自分のストレージフォルダー内のパスに対するファイルロックと macOS の検疫解除です。1 回の呼び出しを超えて存続する状態（実行記録、ダウンロードしたランタイム）は `ctx.globalStoragePath` または `ctx.projectStoragePath` に保存してください。

## テストする

- `gamedev pkg validate`: マニフェストと、それが指定するファイル。
- 一時フォルダーにリンクし、ダイアログからプロジェクトを作成し、Play を押し、チャットで接続し、各ツールを呼び出し、停止します。その後、`gamedev pkg logs <id>` で実行全体を確認します。
- `contractVersion` は実装するエンジンコントラクトを示します（現在は `1` のみ）。追加はバージョンを維持し、互換性のない変更は 1 と並べてバージョン 2 として提供されます。

## 関連ページ

- [Projects and engines](https://ai-game.dev/ja/docs/wiki/app/projects-and-engines) では、ユーザーがエンジンプロジェクトをどのように扱うかを説明しています。
- [Package API](https://ai-game.dev/ja/docs/wiki/app/package-api) では、`ctx.aigd` の残りの部分を説明しています。
- [Publishing packages](https://ai-game.dev/ja/docs/wiki/app/publishing-packages) では、自分のエンジンを共有する方法を説明しています。

---

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

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