LuawardDocs

API de scripts

Lista, crea, cambia, sube código y elimina scripts, y sigue sus builds.

Un script pertenece a un proyecto. Estas rutas listan, crean, cambian y eliminan scripts, suben código nuevo y siguen el build que convierte el código en el script protegido que cargan los jugadores. Lo que cambia un script exige una clave con el scope scripts:write (Acceso total lo tiene); leer no exige scope.

Leer sigue requiriendo una clave de API de desarrollador activa, pero no el scope scripts:write.

Leer scripts

GET /v3/projects/:id/scripts

Devuelve scripts, del más antiguo al más nuevo. GET /v3/projects/:id/scripts/:script_id devuelve un script. Un script que no está en este proyecto, fue eliminado o no existe responde 404 SCRIPT_NOT_FOUND.

Un script tiene script_id, script_name, project_id, enabled (kill switch), paused_reason (null, o por qué Luaward lo apagó: plan, owner, ban), version, los ajustes ffa, silent, heartbeat, lightning, preset (max, balanced o fast) y auto_rebuild, loader_url y loadstring (lo que el jugador pega en el runtime), current_build (build_id, version, status), stable_build_id, created_at y updated_at.

Crear un script

POST /v3/projects/:id/scripts

CampoRegla
nameObligatorio. De 1 a 60 caracteres.
scriptObligatorio (source también sirve). El código, hasta 2.000.000 de caracteres.
ffa, silent, heartbeat, lightning, auto_rebuildOpcional, true o false. ffa deja el script sin clave.
presetOpcional: max, balanced (por defecto) o 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"}'

La respuesta es 202 con script_id, build_id, version (1), status queued y el script: el código se guarda sellado y el build entra en la cola, aún no ha terminado. Síguelo con las rutas de build de abajo. Rechazos: 403 PLAN_LIMIT en el límite de scripts del plan, 404 PROJECT_NOT_FOUND, 429 TOO_MANY_BUILDS cuando el workspace ya tiene varios builds esperando, 503 UNAVAILABLE donde la API no llega al servicio de build. El cuerpo de estas dos rutas de código puede ser de hasta 4 MiB. El valor predeterminado es 16 KiB; las rutas de claves en lote permiten 512 KiB.

Subir código nuevo

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

Envía script (o source) y, si quieres, cualquier ajuste. La versión sube una y se encola un build nuevo; los jugadores siguen con el build anterior hasta que el nuevo esté listo. Los ajustes enviados con el código se aplican a ese mismo build. Dos subidas a la vez dan dos versiones. La respuesta es 202 con script_id, build_id, version y status queued.

Seguir un build

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

Devuelve builds, del más nuevo al más antiguo (limit de 1 a 50, por defecto 20). GET …/builds/:build_id devuelve un build: build_id, version, status (queued, building, ready o failed), error (el mensaje del compilador si falló), size_bytes, is_stable, current (los jugadores reciben este), created_at y finished_at. Un build tarda de segundos a minutos; consúltalo cada pocos 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

Cambiar un script

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

Cualquiera de name, enabled (kill switch) y los ajustes; al menos uno. Encender un script exige espacio en el plan (403 PLAN_LIMIT). Un script que el propio Luaward apagó (paused_reason owner o ban) no se puede encender aquí (403 SCRIPT_LOCKED). Cambiar preset o lightning cambia la salida protegida, así que se encola un build nuevo: la respuesta trae rebuilding true con su build_id; los demás ajustes valen al instante.

Un script desactivado rechaza nuevas autorizaciones y payloads. Las sesiones con clave y heartbeat activado se detienen en su próxima comprobación. No se garantiza detener a distancia código ya cargado sin heartbeat.

Revertir

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

{ "build_id": "0123456789abcdef0123456789abcdef" }

Vuelve a servir un build ready anterior. Un build que no ha terminado responde 400 BUILD_NOT_READY; uno que no es de este script, 404 BUILD_NOT_FOUND.

Eliminar y restaurar

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

Es una eliminación lógica: se rechazan nuevas solicitudes del loader y se conserva el registro del script. POST …/:script_id/restore restaura si el proyecto existe y hay espacio en el plan (403 PLAN_LIMIT en caso contrario). No promete borrar automáticamente los datos a los 30 días; consulta eliminación de cuenta. Ambas operaciones se auditan.