This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
エンジンサービスとランタイム HTTP API
Debug モードでプロジェクトを実行すると、ゲームと特別なエンジンサービス（engine service）を含む、特定のエンジンのランタイムインスタンス用のプロセスが作成されます。このサービスにアクセスすると、開発とプロファイリングの基盤、実行時のロジックとメッセージ、エンジンの状態、拡張機能を扱えます。
エンジンサービスは、実行中のデバッグエンジン（dmengine）が管理する開発用 HTTP サービスです。
Defold エディターに属し、開いているプロジェクトを制御するエディターサーバー（editor server）とは別のサービスです。
2つのサービスは異なるポートを使います。エディターのポートに接続するツールは、そのポートでランタイム拡張のルートを呼び出せません。逆も同様で、エンジンサービスに接続するツールはエディターの操作を呼び出せません。
エンジンサービスは、デバッグ、開発、プロファイリングの基盤の一部です。リリースエンジンのインスタンスは、このサービスを作成しません。
利用条件とポートの検出
エディターがデバッグエンジンを起動するとき、動的に割り当てられるサービスポートを要求します。エンジンは、選択されたポートを Console に表示します（`CLI から実行した場合はログにも表示します）:
INFO:ENGINE: Engine service started on port <port>
ゲームをエディターから起動した場合、この行はエディターのコンソールに表示されます。簡単なローカルコントローラーであれば、この行を解析できます。ただし、再利用可能な連携機能では、エディターまたはそのラッパーにエンジンのインスタンスと登録済みポートを追跡させることをお勧めします。これにより、古いポートを、新しく起動されたプロセスや再利用されたプロセスのポートと取り違えずに済みます。
エンジンは、対応するプラットフォームではサービス検出を通じて開発ターゲットの存在も通知します。この仕組みは主に Defold のツールが使用するもので、常に固定のポートをハードコードする方法で置き換えることは推奨しません。
サーバーには、localhost（127.0.0.1）の指定されたポートでアクセスできます:
組み込みエンドポイント
現在のデバッグエンジンは、少数の基本ルートを登録します。
| エンドポイント | 用途 |
|---|---|
GET /ping |
エンジンサービスが応答することを確認します。 |
GET /info |
エンジンのバージョン、プラットフォーム、ビルド識別子、ログサービスの情報を読み取ります。 |
GET /state |
Defold のツールが使用する開発用の接続状態を読み取ります。 |
POST /post/<socket>/<message-type> |
Protobuf でエンコードした Defold メッセージを、エンジンの名前付きソケット（socket）に送信します。 |
例:
curl -sS "$ENGINE_URL/ping"
curl -sS "$ENGINE_URL/info" | jq
curl -sS "$ENGINE_URL/state" | jq
/post ルートは、ホットリロード（hot reload）、再起動、サイズ変更、プロセス制御などの開発操作で使用されます。リクエスト本文は、ルートで指定された型のバイナリ Protobuf メッセージです。JSON メッセージ API ではありません。Protobuf メッセージは、シリアライズ後のサイズが 1024 バイト以下である必要があります。これを超えると、400 Too large message が返されます。
これらのルートは開発の基盤であり、エンジンの実装にはプロファイラーやリソースの調査用のルートもあります。
拡張機能で定義するランタイムルート
デバッグビルドでは、ネイティブ拡張（native extension）SDK からエンジンの Web サーバーにアクセスできます。拡張機能は、そのサーバーにルートプレフィックスを登録し、ランタイムデータに依存する操作を公開できます。
拡張機能は別の HTTP サーバーを開かずに既存のエンジンサービスを共有できるため、開発ツールに役立ちます。
拡張機能で定義するランタイム自動化 API には、次を推奨します:
- 他と区別できる、バージョン付きのルートプレフィックスを使用します。
- サポートする機能を公開します。
- 構造化されたエラーを返します。
- プラットフォームの機能やエンジンの機能が利用できない場合を明示的に処理します。
- 操作を開発とテストのローカル環境に限定します。
- リリースビルドから除外されるかどうかを明記します。
Automation Bridge 拡張
Defold 公式の Automation Bridge は、エンジンサービスを基盤とした、デバッグビルド専用のネイティブ拡張です。次の URL 以下に、バージョン付きのランタイム自動化 API を登録します:
http://127.0.0.1:<engine-service-port>/automation-bridge/v1
ランタイム API は、シーンやノードの調査、入力、画面情報、スクリーンショット、録画、ライフサイクル情報、オプションのアプリケーション定義の同期などの機能を提供します。操作の例を次に示します:
| 操作 | 動作 |
|---|---|
GET /automation-bridge/v1/health |
動作状況のレポート、API の機能と互換性 |
POST /automation-bridge/v1/input/click |
実行時の入力操作 |
GET /automation-bridge/v1/screenshot |
実行時のスクリーンショット |
プロジェクトにインストールされているバージョンに対応した、拡張機能のネイティブ API ドキュメントと Python ヘルパーのドキュメントを使用してください。
Automation Bridge は、リリースビルドでは HTTP API も Lua モジュールも公開しません。
エディターとランタイムのクライアント
Automation Bridge の Python ヘルパーは、2つのクライアントからなる構成を示しています。関数 editor.open_project() はエディターのプロジェクトクライアントを返し、project.build_and_run() は別のエンジンクライアントを返します。
| クライアント | 用途 |
|---|---|
| プロジェクト | エディター HTTP API、コマンド、デバッガー、コンソール、環境設定、リファレンス、プレビュー、ビルド、ポートの検出 |
| ゲーム - エンジンサービス | シーン、入力、スクリーンショット、実行時の状態、同期 |
project と game を分けることで、プロセスの境界が明確になります。エディターの操作はエディターサーバーで行い、実行中のゲームの観察や操作はエンジンサービスで行います。
from automation_bridge import editor
project = editor.open_project(".")
game = project.build_and_run()
制限事項とセキュリティ
エンジンサービスと拡張機能で定義するルートは開発ツールであり、そのように扱うことをお勧めします。
現在、エンジンサービスは OpenAPI ドキュメントを公開していません。連携機能は、ドキュメントに記載された動作、または拡張機能のバージョン付き API に限定することをお勧めします。
実行時のスクリプト、物理演算、入力、動的に作成されたオブジェクト、プラットフォームのレンダリングには、実行中のエンジンが必要です。これらはランタイムの自動テストで検証することをお勧めします。
- ルーター、公開インターフェース、信頼できないトンネルを介してサービスを公開しないでください。
- エンジンサービスのルートが認証を必要とするものと想定しないでください。
- ランタイムルートは、拡張機能のバージョン、プラットフォーム、グラフィックスバックエンド、エンジンの機能によって異なることがあります。
- 拡張機能で定義する最新の API には、バージョンまたは機能のネゴシエーションを使用してください。