LuawardDocs

API de scripts

Liste, crie, altere, envie código e exclua scripts, e acompanhe os builds.

Um script pertence a um projeto. Estas rotas listam, criam, alteram e excluem scripts, enviam código novo e acompanham o build que transforma o código no script protegido que os jogadores carregam. O que altera um script exige uma chave com o escopo scripts:write (Acesso total o tem); ler não exige escopo.

A leitura ainda exige uma chave de API de desenvolvedor ativa, mas não o scope scripts:write.

Ler scripts

GET /v3/projects/:id/scripts

Retorna scripts, do mais antigo ao mais novo. GET /v3/projects/:id/scripts/:script_id retorna um script. Um script que não está neste projeto, foi excluído ou não existe responde 404 SCRIPT_NOT_FOUND.

Um script tem script_id, script_name, project_id, enabled (kill switch), paused_reason (null, ou por que o Luaward o desligou: plan, owner, ban), version, as configurações ffa, silent, heartbeat, lightning, preset (max, balanced ou fast) e auto_rebuild, loader_url e loadstring (o que o jogador cola no runtime), current_build (build_id, version, status), stable_build_id, created_at e updated_at.

Criar um script

POST /v3/projects/:id/scripts

CampoRegra
nameObrigatório. De 1 a 60 caracteres.
scriptObrigatório (source também serve). O código, até 2.000.000 de caracteres.
ffa, silent, heartbeat, lightning, auto_rebuildOpcional, true ou false. ffa deixa o script sem chave.
presetOpcional: max, balanced (padrão) ou 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"}'

A resposta é 202 com script_id, build_id, version (1), status queued e o script: o código é guardado selado e o build entra na fila, ainda não terminou. Acompanhe com as rotas de build abaixo. Recusas: 403 PLAN_LIMIT no limite de scripts do plano, 404 PROJECT_NOT_FOUND, 429 TOO_MANY_BUILDS quando o workspace já tem vários builds esperando, 503 UNAVAILABLE onde a API não alcança o serviço de build. O corpo destas duas rotas de código pode ter até 4 MiB. O padrão é 16 KiB; rotas de chaves em lote permitem 512 KiB.

Enviar código novo

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

Envie script (ou source) e, se quiser, qualquer configuração. A versão sobe uma e um novo build entra na fila; os jogadores continuam no build antigo até o novo ficar pronto. As configurações enviadas com o código valem para esse mesmo build. Dois envios ao mesmo tempo geram duas versões. A resposta é 202 com script_id, build_id, version e status queued.

Acompanhar um build

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

Retorna builds, do mais novo ao mais antigo (limit de 1 a 50, padrão 20). GET …/builds/:build_id retorna um build: build_id, version, status (queued, building, ready ou failed), error (a mensagem do compilador quando falhou), size_bytes, is_stable, current (os jogadores recebem este), created_at e finished_at. Um build leva de segundos a minutos; consulte a cada poucos segundos:

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

Alterar um script

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

Qualquer um de name, enabled (kill switch) e as configurações; pelo menos um. Ligar um script exige espaço no plano (403 PLAN_LIMIT). Um script que o próprio Luaward desligou (paused_reason owner ou ban) não pode ser ligado aqui (403 SCRIPT_LOCKED). Mudar preset ou lightning muda a saída protegida, então um novo build entra na fila: a resposta traz rebuilding true com seu build_id; as outras configurações valem na hora.

Um script desligado recusa novas autorizações e payloads. Sessões com chave e heartbeat ativado param na próxima verificação. Não é possível garantir a interrupção remota de código já carregado sem heartbeat.

Reverter

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

{ "build_id": "0123456789abcdef0123456789abcdef" }

Volta a servir um build ready anterior. Um build que não terminou responde 400 BUILD_NOT_READY; um que não é deste script, 404 BUILD_NOT_FOUND.

Excluir e restaurar

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

É uma exclusão lógica: novas chamadas do loader são recusadas e o registro do script permanece. POST …/:script_id/restore restaura se o projeto existir e houver espaço no plano (403 PLAN_LIMIT caso contrário). Não há promessa de apagar automaticamente após 30 dias; veja exclusão de conta. As duas operações são auditadas.