ゲームエンジンパッケージ
パッケージでゲームエンジン全体を AI Game Dev に教え込みます。プロジェクト検出、作成ダイアログ、Play、ゲームビュー、エージェントのライブツールを順を追って解説します。
ゲームエンジンパッケージは、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 回の実行を順を追って
- 検出。 ユーザーがフォルダーを開くと、スキャンがあなたのマーカーに一致し、プロジェクトがあなたのアイコンと名前で一覧表示されます。
- アクティベート。 アプリが
onGameEngine:<id>を発火し、registerEngineを最大 30 秒待ちます。 - 起動。 Play は
operationId付きでeditor.launchを呼び出します。host.progress({ operationId, message })で行を報告し("Building 40%"のようなメッセージはバーを描画します)、各ステップの間でawait host.cancelled(operationId)を確認します。呼び出しは進捗なしで 15 分、合計で 3 時間で終了します。 - 表示。
gameView: "browser"の場合、ゲームパネルがeditor.gameViewの返す URL を読み込みます。 - 接続。 チャットで、エージェントの接続は
tools.listをプロジェクトのツールとして一覧表示し、各呼び出しはtools.callに送られます。ツール名はA-Z a-z 0-9 _ -の 1〜64 文字です。それぞれにinputSchemaを指定してください。 - 停止。
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 では、自分のエンジンを共有する方法を説明しています。