Автоматизация редактора Defold

Редактор Defold запускает специальный сервер для автоматизированных действий. HTTP API управляет открытым проектом. Используйте его для команд редактора, сборок, ресурсов проекта, предпросмотров, настроек, вывода консоли, поиска по документации или интеграций со скриптами редактора. Чтобы исследовать запущенную игру или управлять ею, используйте сервис движка или 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, либо для автоматизации только компиляции и создания автономных бандлов, используйте 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.json, когда их скрипты редактора предоставляют описание операции OpenAPI.

Выполнение команд редактора

Команды редактора вызываются через:

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. После завершения сборки редактор предоставляет её по адресу:

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 содержит всю документацию для офлайн-поиска и локального индексирования.

Чтобы экономить токены и получать более подготовленный и чистый контекст для конкретной задачи, ИИ-агентам следует предпочитать точечный поиск, а не получение всего справочника, когда требуется только один API или одно сообщение.

Чтение вывода консоли

Прочитайте консоль редактора в формате 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 в стандартном начальном представлении:

Рендеринг можно использовать для предпросмотра ресурсов, использующих визуальный редактор сцен. Например, таким же способом можно отрисовать компонент модели, чтобы проверить его внешний вид или, например, правильность шейдера:

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.

Вычисляемый код может использовать Editor API и окружение скриптов редактора. Он не может использовать API среды выполнения игры, например go.*, для управления запущенной игрой. Для игрового процесса используйте тест среды выполнения, отладчик, браузерный тест или API автоматизации среды выполнения.

Изменение ресурсов и файлов

Многие исходные ресурсы Defold используют текстовые форматы, и их можно редактировать любым текстовым редактором. Для изменения структурированных ресурсов проекта Defold предпочтительны транзакции редактора.

Исследуйте ресурс перед изменением:

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_*().

Используйте editor.execute() в Lua редактора для запуска форматтера, валидатора или генератора:

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 либо внешнего контроллера.

Хороший маршрут должен выполнять одну чётко названную операцию, проверять входные данные, возвращать структурированный результат, по возможности быть идемпотентным и ограничивать дорогостоящую работу.

Маршруты, определяемые проектом, не защищаются токеном /eval автоматически. Добавьте специфичные для проекта аутентификацию и проверки безопасности, если маршрут выполняет чувствительные операции.

Хуки жизненного цикла

Хуки — это функции, которые можно запускать до и после сборок, до и после создания бандла, а также при запуске или завершении игрового процесса. Проект может содержать один файл hooks.editor_script в корне. Только корневой файл хуков получает эти события, предоставляя проекту единое место для определения их порядка.

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 среды выполнения.