このページは英語から機械翻訳されています。英語の原文を読む。

ゲームエンジンパッケージ

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

2026年11月19日に更新 Markdownで表示

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

テンプレートから始める

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 です。

{
  "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> で実行され、実装を登録します:

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 では、ユーザーがエンジンプロジェクトをどのように扱うかを説明しています。
  • Package API では、ctx.aigd の残りの部分を説明しています。
  • Publishing packages では、自分のエンジンを共有する方法を説明しています。