Автоматизація редактора 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

Редактор є графічним настільним застосунком. Запускайте його в інтерактивному сеансі користувача з доступом до дисплея. Використовуйте Bob, коли графічний сеанс недоступний, наприклад у CI без графічного інтерфейсу, або для створення автономних пакетів. Відкритий редактор також підтримує автоматизацію лише компіляції через /command/compile.

Після запуску редактора зачекайте, доки проєкт відкриється і з’явиться .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 | keys[] | select(startswith("/command/"))'

У Defold 1.13.2 і новіших версіях кожна команда має власний шлях у документі OpenAPI. У попередніх версіях команди описано через шлях /command/{command} і перелік назв команд.

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

Визначені проєктом маршрути також з’являються в /openapi.json, коли їхні скрипти редактора надають опис операції OpenAPI.

Виконання команд редактора

Викликайте команди редактора, надсилаючи запит POST за задокументованим шляхом команди, наприклад:

POST /command/compile
POST /command/run

Щоб скомпілювати проєкт без запуску:

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

Щоб скомпілювати й запустити проєкт:

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

Ці конвеєри відображають тіло відповіді. У скриптах автоматизації також перевіряйте статус HTTP і success за зразком із розділу Збирання HTML5.

Успішна компіляція повертає статус HTTP 200 зі структурованим результатом:

{
  "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
        }
      }
    }
  ]
}

Доступні поля залежать від помилки. Використовуйте шлях ресурсу й діапазон у вихідному коді, коли вони присутні, але також обробляйте проблеми, що містять лише повідомлення.

До поширених корисних команд, якщо їх перелічує запущений редактор, належать:

compile

Скомпілюйте проєкт без запуску.

run

Скомпілюйте й запустіть проєкт.

clean-build

Очистіть кеш збирання, а потім скомпілюйте й запустіть проєкт. Використовуйте цю команду лише тоді, коли звичайне збирання поводиться непослідовно або начебто не враховує зміни.

build-html5

Зберіть проєкт для HTML5 і зробіть результат доступним через сервер редактора.

fetch-libraries

Завантажте й перезавантажте залежності проєкту.

hot-reload

Повторно завантажте змінені ресурси в запущену гру.

reload-extensions

Повторно завантажте скрипти редактора.

debugger-start, debugger-stop і команди покрокового виконання налагоджувача

Керуйте налагоджувальним сеансом і запущеним проєктом.

Точні назви й доступність залежать від версії редактора та його поточного стану; виявляйте їх із /openapi.json.

Команди, що працюють із ресурсами проєкту, синхронізують зовнішні зміни файлів перед виконанням.

Відповіді команд і асинхронна робота

Відповіді залежать від команди. У Defold 1.13.2 і новіших версіях compile, run, clean-build, build-html5, debugger-start і hot-reload очікують завершення команди й повертають структурований результат із success та issues, як показано вище. Успішний результат повертає HTTP 200; невдале збирання або перевірка — 422.

Інші команди, наприклад debugger-break, і далі можуть повертати 202. Перегляньте операцію в поточній схемі OpenAPI й обробляйте фактичний статус відповіді HTTP:

Відповідь HTTP 202 не є доказом існування запитаного результату. Зачекайте на відповідне виведення, ресурс, маркер консолі або обслуговувану URL-адресу й установіть тайм-аут.

Збирання HTML5

Якщо поточний документ OpenAPI містить /command/build-html5, викличте команду за цим шляхом. У скрипті оболонки зберігайте статус HTTP окремо від тіла відповіді й зупиняйте виконання, якщо запит або збирання завершилися невдало:

build_response_file="$(mktemp)" || exit 1
if ! build_http_status="$(curl -sS \
  -X POST \
  -o "$build_response_file" \
  -w '%{http_code}' \
  "$BASE_URL/command/build-html5")"; then
  cat "$build_response_file"
  rm -f "$build_response_file"
  exit 1
fi

cat "$build_response_file"
if [ "$build_http_status" != "200" ] ||
   ! jq -e '.success == true' "$build_response_file" > /dev/null; then
  rm -f "$build_response_file"
  exit 1
fi
rm -f "$build_response_file"

У Defold 1.13.2 і новіших версіях цей запит очікує завершення збирання й повертає структурований результат. Приклад виводить тіло відповіді, зокрема всі проблеми збирання, і продовжує виконання лише за HTTP 200 із success: true. Після успішного збирання редактор відкриває гру в браузері й обслуговує її за адресою:

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

Завершене збирання не означає, що гра вже завантажилася в браузері. Зачекайте на готовність полотна й застосунку, перш ніж надсилати введення або перевіряти ігровий процес. Докладніше дивіться в розділі Браузерні тести для 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) може відрендерити «знімок екрана» підтримуваного ресурсу сцени у форматі PNG за допомогою команди /preview/{path}:

mkdir -p build/automation

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

Це рендерить головну колекцію (collection) з відкритого проєкту шаблону Basic 3D у стандартному початковому вигляді:

Рендеринг можна використовувати для отримання попередніх переглядів ресурсів, які використовують візуальний редактор сцен. Наприклад, у такий самий спосіб можна відрендерити компонент (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 в середовищі розширень редактора. Токен-носій для окремого сеансу зберігається у файлі:

.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 редактора й середовище скриптів редактора. Він не може використовувати 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 середовища виконання.