Automatizzare l’editor Defold

L’editor Defold avvia un server dedicato alle azioni automatizzate. L’API HTTP controlla il progetto aperto. Utilizzala per comandi dell’editor, build, risorse del progetto, anteprime, preferenze, output della console, ricerca nella documentazione o integrazioni con script dell’editor. Per ispezionare o controllare invece il gioco in esecuzione, utilizza il servizio del motore o un’API di automazione a runtime.

Avviare l’editor da uno strumento esterno

Uno strumento esterno necessita dell’eseguibile dell’editor e del percorso assoluto del file game.project del progetto.

Le versioni di Defold installate possono essere individuate tramite installations.json, come descritto nel manuale dell’editor. Il relativo campo launcherPath contiene l’eseguibile da avviare. Passa il percorso di game.project come primo argomento posizionale per aprire direttamente il progetto.

L’argomento facoltativo --port o -p seleziona la porta del server dell’editor. Se viene omesso, Defold sceglie una porta disponibile; questa soluzione è solitamente preferibile quando possono essere aperti più progetti.

# 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

L’editor è un’applicazione desktop grafica. Avvialo in una sessione utente interattiva con accesso allo schermo. Utilizza Bob quando non è disponibile una sessione grafica, ad esempio nella CI headless, oppure per creare bundle autonomi. Un editor aperto supporta anche l’automazione della sola compilazione tramite /command/compile.

Dopo avere avviato l’editor, attendi che il progetto sia aperto e che esista .internal/editor.port. Quindi interroga ripetutamente /openapi.json finché non restituisce un documento valido. Non presupporre che la creazione del processo significhi che il progetto sia pronto.

Individuare il server dell’editor

L’editor avvia un server HTTP locale mentre è aperto un progetto. Seleziona Help ▸ Open Editor Server per aprirne la pagina iniziale nel browser predefinito:

La porta selezionata viene scritta all’interno del progetto in:

.internal/editor.port

D’ora in poi, gli esempi e i comandi di questo manuale faranno riferimento alle seguenti variabili della shell:

PORT="$(cat .internal/editor.port)"
BASE_URL="http://127.0.0.1:$PORT"

Il file della porta appartiene alla sessione corrente dell’editor. Leggilo nuovamente dopo avere riavviato l’editor.

Individuare le operazioni tramite OpenAPI

Le uniche informazioni iniziali specifiche di Defold necessarie a uno strumento esterno sono la porta dell’editor e il documento OpenAPI:

curl -sS "http://127.0.0.1:$(cat .internal/editor.port)/openapi.json"

Il documento OpenAPI 3.0.3 restituito descrive le operazioni supportate dalla versione dell’editor in esecuzione, inclusi percorsi, metodi, parametri, nomi dei comandi, formati delle richieste, risposte, codici di stato e requisiti di autenticazione.

Elenca i percorsi documentati:

curl -sS "$BASE_URL/openapi.json" |
  jq -r '.paths | keys[]'

Elenca i percorsi documentati dei comandi dell’editor:

curl -sS "$BASE_URL/openapi.json" |
  jq -r '.paths | keys[] | select(startswith("/command/"))'

Da Defold 1.13.2, ogni comando ha un proprio percorso nel documento OpenAPI. Le versioni precedenti descrivono i comandi tramite il percorso /command/{command} e un’enumerazione dei nomi dei comandi.

Un’integrazione che tiene conto della versione dovrebbe verificare ogni operazione richiesta e configurare le richieste in base allo schema restituito. Sconsigliamo di mantenere una copia che si presume esaustiva dei nomi degli endpoint o dei comandi, poiché può diventare obsoleta.

Anche le route definite dal progetto compaiono in /openapi.json quando i relativi script dell’editor forniscono una descrizione dell’operazione OpenAPI.

Eseguire i comandi dell’editor

Richiama i comandi dell’editor inviando una richiesta POST al percorso documentato del comando, per esempio:

POST /command/compile
POST /command/run

Per compilare il progetto senza eseguirlo:

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

Per compilare ed eseguire il progetto:

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

Queste pipeline mostrano il corpo della risposta. Negli script di automazione, controlla anche lo stato HTTP e success, seguendo lo schema descritto in Creare una build HTML5.

Una compilazione riuscita restituisce lo stato HTTP 200 con un risultato strutturato:

{
  "success": true,
  "issues": []
}

Una build non riuscita restituisce lo stato HTTP 422 con problemi come:

{
  "success": false,
  "issues": [
    {
      "message": "Example compiler message",
      "severity": "error",
      "resource": "/main/player.script",
      "range": {
        "start": {
          "line": 12,
          "character": 4
        },
        "end": {
          "line": 12,
          "character": 17
        }
      }
    }
  ]
}

I campi disponibili dipendono dall’errore. Utilizza il percorso della risorsa e l’intervallo nel codice sorgente quando sono presenti, ma gestisci anche i problemi che contengono soltanto un messaggio.

Tra i comandi comunemente utili, quando sono elencati dall’editor in esecuzione, figurano:

compile

Compila il progetto senza eseguirlo.

run

Compila ed esegue il progetto.

clean-build

Svuota la cache di build, quindi compila ed esegue il progetto. Utilizzalo soltanto quando una build normale si comporta in modo incoerente o sembra non rilevare le modifiche.

build-html5

Crea la build HTML5 del progetto e rende l’output disponibile tramite il server dell’editor.

fetch-libraries

Scarica e ricarica le dipendenze del progetto.

hot-reload

Ricarica le risorse modificate in un gioco in esecuzione.

reload-extensions

Ricarica gli script dell’editor.

debugger-start, debugger-stop e i comandi di avanzamento del debugger

Controllano una sessione di debug e il progetto in esecuzione.

I nomi esatti e la disponibilità dipendono dalla versione dell’editor e dal suo stato corrente; ricavali da /openapi.json.

I comandi che operano sulle risorse del progetto sincronizzano le modifiche esterne ai file prima dell’esecuzione.

Risposte dei comandi e attività asincrone

Le risposte dipendono dal comando. Da Defold 1.13.2, compile, run, clean-build, build-html5, debugger-start e hot-reload attendono il completamento del comando e restituiscono un risultato strutturato con success e issues, come mostrato sopra. Un risultato positivo restituisce HTTP 200; un errore di build o di convalida restituisce 422.

Altri comandi possono ancora restituire 202, per esempio debugger-break. Esamina l’operazione nello schema OpenAPI corrente e gestisci il codice di stato HTTP effettivo della risposta:

Una risposta HTTP 202 non dimostra che il risultato richiesto esista. Attendi l’output, la risorsa, l’indicatore nella console o l’URL servito pertinente e imponi un timeout.

Creare una build HTML5

Se il documento OpenAPI corrente elenca /command/build-html5, richiamalo tramite quel percorso. In uno script di shell, acquisisci lo stato HTTP separatamente dal corpo della risposta e interrompi l’esecuzione se la richiesta o la build non riesce:

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"

Da Defold 1.13.2, questa richiesta attende il completamento della build e restituisce un risultato strutturato. L’esempio stampa il corpo della risposta, inclusi eventuali problemi della build, e prosegue soltanto con HTTP 200 e success: true. Dopo una build riuscita, l’editor apre il gioco in un browser e lo serve all’indirizzo:

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

Una build completata non significa che il gioco abbia finito di caricarsi nel browser. Attendi che il canvas e l’applicazione siano pronti prima di inviare input o verificare il gameplay. Per ulteriori dettagli, consulta Test nel browser per HTML5.

Cercare nella documentazione API

Quando è presente in /openapi.json, l’operazione /ref cerca nella documentazione API inclusa nella versione dell’editor in esecuzione. Fornisce nomi e firme corrispondenti a tale versione.

Ad esempio, per cercare una funzione, usa:

curl -sS \
  --get \
  --data-urlencode "q=go.animate" \
  "$BASE_URL/ref" |
  jq

Filtra in base all’ambiente e al linguaggio:

curl -sS \
  --get \
  --data-urlencode "environment=runtime" \
  --data-urlencode "language=Lua" \
  --data-urlencode "q=collision message|raycast" \
  "$BASE_URL/ref" |
  jq

I parametri di ricerca sono:

environment

editor, runtime o valori separati da virgole.

language

Lua, C, C++ o valori separati da virgole.

q

Un’espressione senza distinzione tra maiuscole e minuscole. Gli spazi rappresentano AND, mentre | rappresenta OR.

Esistono anche risorse di documentazione in formato compatto: l’indice della documentazione per LLM rimanda ai manuali ufficiali, ai namespace API e agli esempi, mentre la documentazione completa per LLM raccoglie l’intera documentazione per consentire la ricerca offline e l’indicizzazione locale.

Gli agenti IA dovrebbero tuttavia preferire ricerche mirate anziché recuperare un intero documento di riferimento quando occorre soltanto un’API o un messaggio, in modo da risparmiare token e disporre di un contesto privo di informazioni superflue e più adatto all’attività da svolgere.

Leggere l’output della console

Leggi la console dell’editor in formato JSON:

curl -sS "$BASE_URL/console" | jq

La risposta contiene il testo della console in lines e regioni semantiche in regions, inclusi errori, risultati delle valutazioni e riferimenti alle risorse.

Per seguire continuamente l’output della console, usa:

curl -N "$BASE_URL/console/stream"

Il flusso include le righe già presenti nella console e poi rimane aperto per il nuovo output. Chiudilo dopo aver ricevuto un indicatore di completamento o un errore, aver rilevato la terminazione del processo o aver raggiunto un timeout o un limite di righe.

Per la delimitazione dei risultati dei test e la classificazione degli errori, consulta Test automatici e verifica.

Renderizzare le anteprime delle scene

L’editor Defold (a partire dalla versione 1.13.1) può renderizzare in formato PNG una “schermata” di una risorsa di scena supportata tramite il comando /preview/{path}:

mkdir -p build/automation

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

Questo comando renderizza la collezione principale del progetto aperto basato sul modello Basic 3D in una vista iniziale predefinita:

Puoi utilizzare il rendering per ottenere anteprime delle risorse che usano l’editor visivo delle scene. Ad esempio, puoi renderizzare allo stesso modo un componente modello per verificarne l’aspetto o la correttezza dello shader:

curl -sS \
  "$BASE_URL/preview/assets/models/cube.model?width=1280&height=720" \
  --output build/automation/cube-preview.png

Il percorso dopo /preview/ non include una barra iniziale. Le dimensioni facoltative utilizzano per impostazione predefinita le dimensioni di visualizzazione del progetto e devono essere comprese tra 1 e 4096.

Le anteprime possono essere molto utili per l’analisi visiva del progetto: controllo dei layout dei livelli e delle GUI, configurazione di shader e illuminazione, regressioni visive o creazione di miniature per la documentazione.

Eseguire Lua nell’editor

L’operazione autenticata POST /eval esegue Lua nell’ambiente delle estensioni dell’editor. Il token bearer valido per la sessione è memorizzato in:

.internal/editor.token

Leggi il token ed esegui il codice:

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"

L’output stampato e i valori restituiti vengono inviati come testo. Le risposte tipiche sono:

Un client può riprovare dopo 503, ma dovrebbe utilizzare un numero limitato di tentativi. Correggi il codice prima di ripetere una richiesta che ha restituito 422.

Il codice valutato può utilizzare l’API dell’editor e l’ambiente di scripting dell’editor. Non può utilizzare le API di runtime del gioco come go.* per manipolare un gioco in esecuzione. Per il gameplay, utilizza un test a runtime, il debugger, un test nel browser o un’API di automazione a runtime.

Modificare risorse e file

Molte risorse sorgente Defold utilizzano formati testuali e possono essere modificate con qualsiasi strumento di editing del testo. Per modificare risorse strutturate di un progetto Defold, prediligi le transazioni dell’editor.

Ispeziona una risorsa prima di modificarla:

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"

Controlla editor.can_get(), editor.can_set() e le altre funzioni editor.can_*() prima di eseguire una transazione.

Usa editor.execute() in Lua dell’editor per eseguire un formatter, un validatore o un generatore:

local output = editor.execute(
  "python3",
  "scripts/generate_levels.py",
  {
    out = "capture"
  }
)

print(output)

Quando il comando non modifica le risorse del progetto, imposta reload_resources = false per evitare un ricaricamento non necessario.

Preferenze

Le preferenze dell’editor possono essere lette e scritte tramite il percorso documentato in OpenAPI, attualmente /prefs/{path}.

Ad esempio, puoi leggere la dimensione configurata del carattere del codice:

curl -sS "$BASE_URL/prefs/code/font/size" | jq

Oppure impostarla, ad esempio, su 16:

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  --data '16' \
  "$BASE_URL/prefs/code/font/size"

L’editor convalida il valore rispetto allo schema delle preferenze. Un percorso o un valore non valido restituisce HTTP 400.

Le preferenze sono impostazioni persistenti dell’utente, globali o specifiche del progetto, non configurazioni del progetto archiviate in game.project. Se l’automazione deve modificare temporaneamente una preferenza, salva il valore precedente e ripristinalo in seguito.

Route definite dal progetto

Gli script dell’editor possono definire route aggiuntive con get_http_server_routes(). Una tabella facoltativa delle operazioni OpenAPI espone una route tramite lo stesso documento /openapi.json delle operazioni integrate.

Le route definite dal progetto possono fornire generazione di contenuti, convalida, report, controlli di localizzazione, analisi delle risorse, test specifici del progetto o un’interfaccia più essenziale per un IDE o un controller esterno.

Una buona route dovrebbe eseguire un’unica operazione dal nome chiaro, convalidarne l’input, restituire un risultato strutturato, essere idempotente ove possibile e limitare le attività dispendiose.

Le route definite dal progetto non sono protette automaticamente dal token di /eval. Aggiungi autenticazione e controlli di sicurezza specifici del progetto quando una route esegue operazioni sensibili.

Hook del ciclo di vita

Gli hook sono funzioni eseguibili prima e dopo le build, prima e dopo la creazione dei bundle e quando un processo di gioco viene avviato o terminato. Un progetto può contenere un file hooks.editor_script nella propria directory radice. Soltanto il file hook nella directory radice riceve questi eventi, offrendo al progetto un unico punto in cui definirne l’ordine.

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

Un errore generato da on_build_started() interrompe la build dell’editor. Gli hook del ciclo di vita vengono eseguiti soltanto nell’editor; inserisci la logica condivisa di convalida e generazione in script autonomi che possano essere richiamati anche dalla CI.

Sicurezza e compatibilità

Considera l’intero server dell’editor come un’interfaccia locale attendibile:

• Non esporre pubblicamente l’accesso alla porta.
• Proteggi .internal/editor.token; autorizza /eval per la sessione corrente.
• Non concedere a soggetti esterni accesso senza restrizioni a /eval.
• Mantieni il token nel livello di integrazione locale anziché nei prompt, nei report o nei log.
• Ricorda che le route definite dal progetto non ereditano l’autenticazione di /eval.
• Utilizza un /openapi.json aggiornato.
• Utilizza tempi di attesa limitati per i comandi automatici asincroni e per l’avvio dell’editor.

Server del motore

Il server dell’editor appartiene al processo dell’editor. Un gioco in esecuzione dispone di una porta diversa e di responsabilità differenti, descritte nel manuale del servizio del motore e dell’API HTTP a runtime.