Defold エディターの自動化

Defold エディターは、自動操作のための専用サーバーを起動します。HTTP API は、開いているプロジェクトを操作します。エディターコマンド、ビルド、プロジェクトのリソース（resource）、プレビュー、環境設定、コンソール出力、ドキュメント検索、エディタースクリプト（editor script）との連携に利用できます。実行中のゲームを調べたり操作したりする場合は、エンジンサービス（engine service）またはランタイム自動化 API を使用してください。

外部ツールからのエディターの起動

外部ツールには、エディターの実行ファイルと、プロジェクトの game.project ファイルへの絶対パスが必要です。

インストール済みの Defold の各バージョンは、エディターマニュアル で説明されている installations.json を使って見つけることができます。その launcherPath フィールドには、起動する実行ファイルが格納されています。game.project のパスを最初の位置引数として渡すと、そのプロジェクトを直接開くことができます。

省略可能な引数 --port または -p は、エディターサーバーのポートを指定します。省略すると Defold が利用可能なポートを選択します。複数のプロジェクトを開く可能性がある場合は、通常、省略することをお勧めします。

# Linux
/path/to/Defold/Defold --port 8181 /absolute/path/to/project/game.project

# macOS
/path/to/Defold.app/Contents/MacOS/Defold --port 8181 /absolute/path/to/project/game.project

# Windows
C:\path\to\Defold\Defold.exe --port 8181 C:\absolute\path\to\project\game.project

エディターはグラフィカルなデスクトップアプリケーションです。ディスプレイにアクセスできる対話型ユーザーセッションで起動してください。画面表示を伴わずに実行するヘッドレス（headless）CI など、グラフィカルなセッションが利用できない場合や、コンパイルのみの自動化、スタンドアロンのバンドル（bundle）の作成には、Bob を使用してください。

エディターを起動したら、プロジェクトが開き、.internal/editor.port が作成されるまで待ちます。その後、有効なドキュメントが返されるまで /openapi.json をポーリングします。プロセスが作成されたからといって、プロジェクトの準備ができたと判断しないでください。

エディターサーバーの検出

エディターは、プロジェクトを開いている間、ローカル HTTP サーバーを起動します。Help ▸ Open Editor Server を選択すると、既定のブラウザーでホームページが開きます。

選択されたポートは、プロジェクト内の次のファイルに書き込まれます。

.internal/editor.port

このマニュアルの以降の例とコマンドでは、次のシェル変数を使用します。

PORT="$(cat .internal/editor.port)"
BASE_URL="http://127.0.0.1:$PORT"

ポートファイルは、現在のエディターセッションに対応しています。エディターを再起動したら、読み直してください。

OpenAPI による操作の検出

外部ツールが処理を開始するために必要な Defold 固有の情報は、エディターのポートと OpenAPI ドキュメントだけです。

curl -sS "http://127.0.0.1:$(cat .internal/editor.port)/openapi.json"

返される OpenAPI 3.0.3 ドキュメントには、実行中のエディターバージョンがサポートする操作が記述されています。パス、メソッド、パラメーター、コマンド名、リクエスト形式、レスポンス、ステータスコード、認証要件が含まれます。

ドキュメントに記載されているパスを一覧表示します。

curl -sS "$BASE_URL/openapi.json" |
  jq -r '.paths | keys[]'

利用可能なエディターコマンドを一覧表示します。

curl -sS "$BASE_URL/openapi.json" |
  jq -r '
    .paths["/command/{command}"].post.parameters[]
    | select(.name == "command")
    | .schema.enum[]
  '

バージョンの違いに対応する連携では、必要な各操作を確認し、返されたスキーマに基づいてリクエストを設定することをお勧めします。エンドポイント名やコマンド名を網羅していると想定した一覧を別に管理することは、内容が古くなる可能性があるため推奨しません。

プロジェクトで定義したルートも、そのエディタースクリプトが OpenAPI の操作の記述を提供していれば、/openapi.json に表示されます。

エディターコマンドの実行

エディターコマンドは、次の方法で呼び出します。

POST /command/{command}

たとえば、現在の build コマンドは、プロジェクトをコンパイルして実行します。

curl -sS \
  -X POST \
  "$BASE_URL/command/build" |
  jq

ビルドが成功すると、構造化された結果が返されます。

{
  "success": true,
  "issues": []
}

ビルドが失敗すると、HTTP ステータス 422 とともに、次のような問題の情報が返されます。

{
  "success": false,
  "issues": [
    {
      "message": "Example compiler message",
      "severity": "error",
      "resource": "/main/player.script",
      "range": {
        "start": {
          "line": 12,
          "character": 4
        },
        "end": {
          "line": 12,
          "character": 17
        }
      }
    }
  ]
}

利用可能なフィールドはエラーによって異なります。リソースパスとソース内の範囲がある場合はそれらを利用しつつ、メッセージのみを含む問題にも対応してください。

実行中のエディターの一覧に含まれていれば、次のようなコマンドがよく役立ちます。

build

プロジェクトをコンパイルして実行します。

clean-build

ビルドキャッシュを消去してから、コンパイルして実行します。通常のビルドの動作に一貫性がない場合や、変更が反映されていないように見える場合にのみ使用してください。

build-html5

プロジェクトを HTML5 向けにビルドし、エディターサーバーを通じて出力を利用できるようにします。

fetch-libraries

プロジェクトの依存関係をダウンロードして再読み込みします。

hot-reload

変更されたリソースを実行中のゲームに再読み込みします。

reload-extensions

エディタースクリプトを再読み込みします。

debugger-start、debugger-stop、およびデバッガーのステップ実行コマンド

デバッグセッションと実行中のプロジェクトを操作します。

正確な名前と利用可否は、エディターのバージョンと現在の状態によって異なります。/openapi.json から確認してください。

プロジェクトのリソースを操作するコマンドは、実行前に外部でのファイル変更を同期します。

コマンドのレスポンスと非同期処理

コマンド操作のレスポンスコードは、現在の OpenAPI スキーマに記載されています。

HTTP 202 レスポンスは、要求した結果が存在する証拠にはなりません。関連する出力、リソース、コンソールのマーカー、または配信 URL を待ち、タイムアウトを設けてください。

HTML5 のビルド

現在の OpenAPI ドキュメントに build-html5 が記載されている場合は、コマンド操作を通じて呼び出します。

curl -sS \
  -X POST \
  "$BASE_URL/command/build-html5"

このコマンドは非同期で実行され、通常は HTTP 202 を返します。ビルドが完了すると、エディターは次の URL でビルド成果物を配信します。

http://127.0.0.1:<editor-port>/html5/

ブラウザーテストを開始する前に、この URL が利用可能になるまで待ってください。詳細は、HTML5 のブラウザーテスト を参照してください。

API ドキュメントの検索

/openapi.json に /ref 操作がある場合、この操作で、実行中のエディターバージョンに含まれる API ドキュメントを検索できます。そのバージョンに対応する名前とシグネチャを取得できます。

たとえば、関数を検索するには次のようにします。

curl -sS \
  --get \
  --data-urlencode "q=go.animate" \
  "$BASE_URL/ref" |
  jq

環境と言語で絞り込みます。

curl -sS \
  --get \
  --data-urlencode "environment=runtime" \
  --data-urlencode "language=Lua" \
  --data-urlencode "q=collision message|raycast" \
  "$BASE_URL/ref" |
  jq

検索パラメーターは次のとおりです。

environment

editor、runtime、またはカンマ区切りの値です。

language

Lua、C、C++、またはカンマ区切りの値です。

q

大文字と小文字を区別しない式です。空白は AND、| は OR を表します。

ドキュメントをまとめたリソースもあります。LLM ドキュメントの索引 には、公式マニュアル、API 名前空間、サンプルへのリンクがあり、LLM 向けドキュメント全文 には、オフライン検索とローカルでの索引作成に利用できる完全なドキュメントが掲載されています。

AI エージェントには、API やメッセージが1つだけ必要な場合、リファレンス全体を取得するよりも、対象を絞った検索を優先することをお勧めします。これにより、トークンを節約し、対象タスクに適した整理されたコンテキストを用意できます。

コンソール出力の読み取り

エディターのコンソールを JSON として読み取ります。

curl -sS "$BASE_URL/console" | jq

レスポンスの lines にはコンソールのテキストが、regions には意味に基づいて区分された領域が含まれます。この領域には、エラー、評価結果、リソース参照などが含まれます。

コンソール出力を継続的に取得するには、次のようにします。

curl -N "$BASE_URL/console/stream"

ストリームには既存のコンソール行が含まれ、その後も新しい出力を受け取るために接続を維持します。完了マーカーまたはエラーを受け取ったとき、プロセスの終了を検出したとき、あるいはタイムアウトまたは行数の上限に達したときに閉じてください。

テスト結果の区切り方と失敗の分類については、自動テストと検証 を参照してください。

シーンプレビューのレンダリング

Defold エディター（1.13.1 以降）では、コマンド /preview/{path} を通じて、対応するシーンリソースの「スクリーンショット」を PNG にレンダリングできます。

mkdir -p build/automation

curl -sS \
  "$BASE_URL/preview/main/main.collection?width=1280&height=720" \
  --output build/automation/main-preview.png

これは、開いている Basic 3D テンプレートプロジェクトのメインコレクション（main collection）を、既定の初期ビューでレンダリングします。

ビジュアルシーンエディターを使うリソースのプレビューを、レンダリングで取得できます。たとえば、モデルコンポーネント（model component）も同じ方法でレンダリングでき、見た目やシェーダーの正しさなどを検証できます。

curl -sS \
  "$BASE_URL/preview/assets/models/cube.model?width=1280&height=720" \
  --output build/automation/cube-preview.png

/preview/ に続くパスには、先頭のスラッシュを含めません。省略可能な寸法の既定値はプロジェクトの表示サイズで、1 から 4096 の範囲である必要があります。

プレビューは、レベルのレイアウト、GUI のレイアウト、シェーダーとライティングの設定、見た目の回帰の確認など、プロジェクトの視覚的な分析や、ドキュメントのサムネイル作成に非常に役立つ可能性があります。

エディター Lua の実行

認証が必要な POST /eval 操作は、エディター拡張環境で Lua を実行します。セッションごとの Bearer トークンは、次のファイルに保存されます。

.internal/editor.token

トークンを読み取り、コードを実行します。

TOKEN="$(cat .internal/editor.token)"

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary 'print(editor.version) return editor.platform' \
  "$BASE_URL/eval"

出力された内容と戻り値は、テキストとして返されます。一般的なレスポンスは次のとおりです。

クライアントは 503 の後に再試行してもかまいませんが、試行回数には上限を設けることをお勧めします。422 が返されたリクエストを再度送信する前に、コードを修正してください。

評価するコードでは、エディター API とエディタースクリプト環境を利用できます。go.* などのゲームのランタイム API を使って、実行中のゲームを操作することはできません。ゲームプレイには、ランタイムテスト、デバッガー、ブラウザーテスト、または ランタイム自動化 API を使用してください。

リソースとファイルの変更

Defold のソースリソースの多くはテキスト形式を使用しており、任意のテキスト編集ツールで編集できます。Defold プロジェクトの構造化されたリソースを変更する場合は、エディターのトランザクション（editor transaction）を優先してください。

リソースを変更する前に、その内容を調べます。

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary '
    local path = "/game.project"
    pprint(editor.properties(path))
    return editor.get(path, "path")
  ' \
  "$BASE_URL/eval"

トランザクションを実行する前に、editor.can_get()、editor.can_set()、その他の editor.can_*() 関数で確認してください。

エディター Lua で editor.execute() を使うと、フォーマッター、バリデーター、ジェネレーターを実行できます。

local output = editor.execute(
  "python3",
  "scripts/generate_levels.py",
  {
    out = "capture"
  }
)

print(output)

コマンドがプロジェクトのリソースを変更しない場合は、reload_resources = false を設定して不要な再読み込みを避けてください。

環境設定

エディターの環境設定は、OpenAPI に記載されているパス（現在は /prefs/{path}）を通じて読み書きできます。

たとえば、設定されているコードのフォントサイズを読み取ることができます。

curl -sS "$BASE_URL/prefs/code/font/size" | jq

また、たとえば 16 に設定することもできます。

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  --data '16' \
  "$BASE_URL/prefs/code/font/size"

エディターは、環境設定のスキーマに照らして値を検証します。パスまたは値が無効な場合は、HTTP 400 が返されます。

環境設定は、ユーザー単位、またはプロジェクトごとのユーザー単位で永続的に保存される設定であり、game.project に保存されるプロジェクト設定ではありません。自動化で環境設定を一時的に変更する必要がある場合は、以前の値を保存し、処理後に復元してください。

プロジェクトで定義するルート

エディタースクリプトでは、get_http_server_routes() を使ってルートを追加できます。省略可能な OpenAPI 操作テーブルを指定すると、組み込み操作と同じ /openapi.json ドキュメントにルートが公開されます。

プロジェクトで定義したルートでは、コンテンツ生成、検証、レポート、ローカライズのチェック、リソース分析、プロジェクト固有のテスト、IDE や外部コントローラー向けのより小さなインターフェースなどを提供できます。

適切なルートにするには、明確な名前の付いた1つの操作を実行し、入力を検証し、構造化された結果を返し、可能な限り冪等にし、負荷の高い処理を制限することをお勧めします。

プロジェクトで定義したルートは、/eval のトークンでは自動的に保護されません。機密性の高い操作を実行するルートには、プロジェクト固有の認証と安全性のチェックを追加してください。

ライフサイクルフック

フック（hook）は、ビルドの前後、バンドル作成の前後、ゲームプロセスの開始時または終了時に実行できる関数です。プロジェクトのルートには、hooks.editor_script ファイルを1つ配置できます。ルートのフックファイルだけがこれらのイベントを受け取るため、プロジェクト内の1か所で実行順序を定義できます。

local M = {}

local function validate_project()
  print(editor.execute(
    "python3",
    "scripts/validate_project.py",
    {
      out = "capture",
      reload_resources = false
    }
  ))
end

function M.on_build_started(opts)
  validate_project()
end

function M.on_build_finished(opts)
  print("Build successful:", opts.success)
end

return M

on_build_started() でエラーが発生すると、エディターのビルドは停止します。ライフサイクルフックはエディター内でのみ実行されます。共通の検証と生成のロジックは、CI からも呼び出せるスタンドアロンのスクリプトに配置してください。

セキュリティと互換性

エディターサーバー全体を、信頼できるローカルのインターフェースとして扱ってください。

• ポートへのアクセスを外部に公開しないでください。
• .internal/editor.token を保護してください。このファイルは、現在のセッションで /eval の使用を認可します。
• 外部に無制限の /eval アクセスを与えないでください。
• トークンは、プロンプト、レポート、ログではなく、ローカルの連携レイヤーに保持してください。
• プロジェクトで定義したルートは、/eval の認証を継承しないことに注意してください。
• 最新の /openapi.json を使用してください。
• 非同期の自動コマンドとエディターの起動を待つ際は、待機時間に上限を設けてください。

エンジンサーバー

エディターサーバーは、エディタープロセスに属します。実行中のゲームは別のポートを使用し、役割も異なります。詳細は、エンジンサービスとランタイム HTTP API のマニュアル を参照してください。