LuawardDocs

API скриптов

Список, создание, изменение, загрузка кода и удаление скриптов, а также слежение за сборками.

Скрипт принадлежит проекту. Эти маршруты показывают, создают, меняют и удаляют скрипты, загружают новый код и следят за сборкой, которая превращает код в защищённый скрипт, загружаемый игроками. Всё, что меняет скрипт, требует ключа со scope scripts:write (Полный доступ его включает); чтение scope не требует.

Для чтения тоже нужен действующий ключ API разработчика, но scope scripts:write не требуется.

Чтение скриптов

GET /v3/projects/:id/scripts

Возвращает scripts от старых к новым. GET /v3/projects/:id/scripts/:script_id возвращает один script. Скрипт, которого нет в этом проекте, удалённый или несуществующий отвечает 404 SCRIPT_NOT_FOUND.

У скрипта есть script_id, script_name, project_id, enabled (kill switch), paused_reason (null или причина, по которой Luaward его выключил: plan, owner, ban), version, настройки ffa, silent, heartbeat, lightning, preset (max, balanced или fast) и auto_rebuild, loader_url и loadstring (что игрок вставляет в runtime), current_build (build_id, version, status), stable_build_id, created_at и updated_at.

Создание скрипта

POST /v3/projects/:id/scripts

ПолеПравило
nameОбязательно. От 1 до 60 символов.
scriptОбязательно (подойдёт и source). Код, до 2 000 000 символов.
ffa, silent, heartbeat, lightning, auto_rebuildНеобязательно, true или false. ffa делает скрипт безключевым.
presetНеобязательно: max, balanced (по умолчанию) или fast.
curl -X POST "https://api.luaward.com/v3/projects/PROJECT_ID/scripts" \
  -H "Authorization: Bearer YOUR_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Arena","script":"print(\"hello\")","ffa":false,"preset":"balanced"}'

Ответ — 202 с script_id, build_id, version (1), status queued и script: код сохранён в зашифрованном виде, сборка поставлена в очередь, но не завершена. Следите за ней маршрутами сборок ниже. Отказы: 403 PLAN_LIMIT на лимите скриптов плана, 404 PROJECT_NOT_FOUND, 429 TOO_MANY_BUILDS, когда в воркспейсе уже несколько сборок в очереди, 503 UNAVAILABLE, если API не может связаться со службой сборки. Тело этих двух маршрутов с кодом может быть до 4 MiB. Обычный лимит — 16 KiB; пакетные маршруты ключей допускают 512 KiB.

Загрузка нового кода

PUT /v3/projects/:id/scripts/:script_id

Отправьте script (или source) и при желании любые настройки. Версия растёт на единицу, новая сборка ставится в очередь; игроки работают на старой сборке, пока новая не готова. Настройки, присланные с кодом, применяются к этой же сборке. Две загрузки одновременно получают две версии. Ответ — 202 с script_id, build_id, version и status queued.

Слежение за сборкой

GET /v3/projects/:id/scripts/:script_id/builds

Возвращает builds от новых к старым (limit от 1 до 50, по умолчанию 20). GET …/builds/:build_id возвращает один build: build_id, version, status (queued, building, ready или failed), error (сообщение компилятора при сбое), size_bytes, is_stable, current (игроки получают эту), created_at и finished_at. Сборка занимает от секунд до минут; опрашивайте раз в несколько секунд:

build_id=BUILD_ID
build_deadline=$((SECONDS + 180))
build_status=""
while (( SECONDS < build_deadline )); do
  build_remaining=$((build_deadline - SECONDS))
  (( build_remaining > 15 )) && build_remaining=15
  build_response=$(curl --fail-with-body --silent --show-error --connect-timeout 5 --max-time "$build_remaining" \
    -H "Authorization: Bearer $LUAWARD_API_KEY" \
    "https://api.luaward.com/v3/projects/PROJECT_ID/scripts/SCRIPT_ID/builds/$build_id") || exit 1
  build_status=$(printf '%s' "$build_response" | jq -er '.build.status') || exit 1
  case "$build_status" in
    ready) printf '%s\n' "$build_response"; break ;;
    failed) printf '%s\n' "$build_response" | jq -r '.build.error // "Build failed"' >&2; exit 1 ;;
    queued|building)
      build_remaining=$((build_deadline - SECONDS))
      (( build_remaining > 0 )) || break
      (( build_remaining > 3 )) && build_remaining=3
      sleep "$build_remaining" ;;
    *) printf 'Unexpected build status: %s\n' "$build_status" >&2; exit 1 ;;
  esac
done
if [[ "$build_status" != ready ]]; then
  printf 'Build did not finish within 180 seconds\n' >&2
  exit 1
fi

Изменение скрипта

PATCH /v3/projects/:id/scripts/:script_id

Любое из name, enabled (kill switch) и настроек; хотя бы одно. Для включения скрипта нужно место в плане (403 PLAN_LIMIT). Скрипт, выключенный самим Luaward (paused_reason owner или ban), здесь не включить (403 SCRIPT_LOCKED). Смена preset или lightning меняет защищённый результат, поэтому в очередь ставится новая сборка: в ответе rebuilding true и её build_id; остальные настройки действуют сразу.

Выключенный скрипт отклоняет новую авторизацию и payload. Сессии с ключом и включённым heartbeat останавливаются при следующей проверке. Остановка уже загруженного кода без heartbeat удалённо не гарантируется.

Откат

POST /v3/projects/:id/scripts/:script_id/rollback

{ "build_id": "0123456789abcdef0123456789abcdef" }

Снова отдаёт игрокам одну из прежних ready-сборок. Незавершённая сборка отвечает 400 BUILD_NOT_READY, чужая для этого скрипта — 404 BUILD_NOT_FOUND.

Удаление и восстановление

DELETE /v3/projects/:id/scripts/:script_id

Это мягкое удаление: новые запросы загрузчика отклоняются, запись скрипта сохраняется. POST …/:script_id/restore восстанавливает её, если проект существует и в тарифе есть место (иначе 403 PLAN_LIMIT). Автоматическое стирание через 30 дней не обещается; см. удаление аккаунта. Обе операции записываются в аудит.