Automatiser l’éditeur Defold

L’éditeur Defold ouvre un serveur spécial pour les actions automatisées. L’API HTTP contrôle le projet ouvert. Utilisez-la pour les commandes de l’éditeur, les builds, les ressources du projet, les aperçus, les préférences, la sortie de la console, la recherche dans la documentation ou les intégrations de scripts de l’éditeur. Pour inspecter ou contrôler le jeu en cours d’exécution, utilisez plutôt le service du moteur ou une API d’automatisation à l’exécution.

Démarrer l’éditeur depuis un outil externe

Un outil externe a besoin du fichier exécutable de l’éditeur et du chemin absolu vers le fichier game.project du projet.

Les versions de Defold installées peuvent être localisées grâce à installations.json, comme décrit dans le manuel de l’éditeur. Son champ launcherPath contient le fichier exécutable à démarrer. Transmettez le chemin de game.project comme premier argument positionnel pour ouvrir directement ce projet.

L’argument facultatif --port ou -p sélectionne le port du serveur de l’éditeur. Si vous l’omettez, Defold choisit un port disponible, ce qui est généralement préférable lorsque plusieurs projets peuvent être ouverts.

# 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’éditeur est une application de bureau graphique. Démarrez-le dans une session utilisateur interactive ayant accès à l’affichage. Utilisez Bob lorsqu’aucune session graphique n’est disponible, par exemple dans une CI sans interface graphique, ou pour créer des bundles autonomes. Un éditeur ouvert permet également d’automatiser la compilation seule via /command/compile.

Après avoir démarré l’éditeur, attendez que le projet soit ouvert et que .internal/editor.port existe. Interrogez ensuite /openapi.json jusqu’à ce qu’il renvoie un document valide. Ne supposez pas que la création du processus signifie que le projet est prêt.

Localiser le serveur de l’éditeur

L’éditeur démarre un serveur HTTP local tant qu’un projet est ouvert. Sélectionnez Help ▸ Open Editor Server pour ouvrir sa page d’accueil dans le navigateur par défaut :

Le port sélectionné est écrit dans le projet à l’emplacement suivant :

.internal/editor.port

À partir de maintenant, les exemples et commandes de ce manuel utiliseront les variables shell suivantes :

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

Le fichier du port appartient à la session actuelle de l’éditeur. Relisez-le après avoir redémarré l’éditeur.

Découvrir les opérations grâce à OpenAPI

Les seules informations de démarrage propres à Defold dont un outil externe devrait avoir besoin sont le port de l’éditeur et le document OpenAPI :

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

Le document OpenAPI 3.0.3 renvoyé décrit les opérations prises en charge par la version de l’éditeur en cours d’exécution, notamment les chemins, les méthodes, les paramètres, les noms de commandes, les formats des requêtes, les réponses, les codes d’état et les exigences d’authentification.

Listez les chemins documentés :

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

Listez les chemins documentés des commandes de l’éditeur :

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

Dans Defold 1.13.2 et les versions ultérieures, chaque commande possède son propre chemin dans le document OpenAPI. Les versions antérieures décrivent les commandes au moyen du chemin /command/{command} et d’une énumération de noms de commandes.

Une intégration qui tient compte de la version devrait vérifier chaque opération requise et configurer les requêtes à partir du schéma renvoyé. Nous déconseillons de maintenir une copie prétendument exhaustive des noms de points de terminaison ou de commandes, car elle peut devenir obsolète.

Les routes définies par le projet apparaissent également dans /openapi.json lorsque leurs scripts de l’éditeur fournissent une description d’opération OpenAPI.

Exécuter des commandes de l’éditeur

Appelez les commandes de l’éditeur en envoyant une requête POST au chemin documenté de la commande, par exemple :

POST /command/compile
POST /command/run

Pour compiler le projet sans l’exécuter :

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

Pour compiler et exécuter le projet :

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

Ces pipelines affichent le corps de la réponse. Dans les scripts d’automatisation, vérifiez aussi le statut HTTP et success, en suivant le modèle de la section Création d’un build HTML5.

Une compilation réussie renvoie le statut HTTP 200 avec un résultat structuré :

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

Un échec du build renvoie l’état HTTP 422 avec des problèmes tels que :

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

Les champs disponibles dépendent de l’erreur. Utilisez le chemin de la ressource et la plage de positions dans le code source lorsqu’ils sont présents, mais gérez également les problèmes qui ne contiennent qu’un message.

Les commandes couramment utiles, lorsqu’elles sont répertoriées par l’éditeur en cours d’exécution, comprennent :

compile

Compile le projet sans l’exécuter.

run

Compiler et exécuter le projet.

clean-build

Vider le cache de build, puis compiler et exécuter. Ne l’utilisez que lorsqu’un build ordinaire se comporte de manière incohérente ou semble ignorer des modifications.

build-html5

Compiler le projet pour HTML5 et rendre la sortie disponible par l’intermédiaire du serveur de l’éditeur.

fetch-libraries

Télécharger et recharger les dépendances du projet.

hot-reload

Recharger les ressources modifiées dans un jeu en cours d’exécution.

reload-extensions

Recharger les scripts de l’éditeur.

debugger-start, debugger-stop et les commandes pas à pas du débogueur

Contrôler une session de débogage et le projet en cours d’exécution.

Les noms exacts et leur disponibilité dépendent de la version et de l’état actuel de l’éditeur ; découvrez-les dans /openapi.json.

Les commandes qui agissent sur les ressources du projet synchronisent les modifications de fichiers externes avant leur exécution.

Réponses aux commandes et travail asynchrone

Les réponses dépendent de la commande. Dans Defold 1.13.2 et les versions ultérieures, compile, run, clean-build, build-html5, debugger-start et hot-reload attendent la fin de la commande et renvoient un résultat structuré avec success et issues, comme ci-dessus. Un résultat réussi renvoie HTTP 200 ; un échec de build ou de validation renvoie 422.

D’autres commandes peuvent encore renvoyer 202, par exemple debugger-break. Examinez l’opération dans le schéma OpenAPI actuel et traitez le statut HTTP effectivement renvoyé :

Une réponse HTTP 202 ne prouve pas que le résultat demandé existe. Attendez la sortie, la ressource, le marqueur de console ou l’URL servie qui convient, et imposez un délai d’expiration.

Build HTML5

Si le document OpenAPI actuel répertorie /command/build-html5, appelez ce chemin. Dans un script shell, capturez le statut HTTP séparément du corps de la réponse et arrêtez le script si la requête ou le build échoue :

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"

Dans Defold 1.13.2 et les versions ultérieures, cette requête attend la fin du build et renvoie un résultat structuré. L’exemple affiche le corps de la réponse, y compris les problèmes de build, et ne poursuit l’exécution qu’avec HTTP 200 et success: true. Après un build réussi, l’éditeur ouvre le jeu dans un navigateur et le sert à l’adresse suivante :

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

La fin du build ne signifie pas que le jeu a terminé son chargement dans le navigateur. Attendez que le canevas et l’application soient prêts avant d’envoyer des entrées ou de vérifier le déroulement du jeu. Consultez Tests dans un navigateur pour HTML5 pour plus de détails.

Rechercher dans la documentation de l’API

Lorsqu’elle est présente dans /openapi.json, l’opération /ref recherche dans la documentation de l’API incluse avec la version de l’éditeur en cours d’exécution. Elle fournit les noms et les signatures qui correspondent à cette version.

Par exemple, pour rechercher une fonction, utilisez :

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

Filtrez par environnement et par langage :

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

Les paramètres de recherche sont les suivants :

environment

editor, runtime ou des valeurs séparées par des virgules.

language

Lua, C, C++ ou des valeurs séparées par des virgules.

q

Une expression insensible à la casse. Les espaces représentent un ET, tandis que | représente un OU.

Il existe également des ressources de documentation condensées : l’index de documentation pour LLM renvoie vers les manuels officiels, les espaces de noms (namespace) de l’API et des exemples, tandis que la documentation LLM complète fournit la documentation complète pour la recherche hors ligne et l’indexation locale.

Les agents IA devraient toutefois préférer des recherches ciblées au téléchargement d’une référence complète lorsqu’une seule API ou un seul message est nécessaire, afin d’économiser des jetons et de disposer d’un contexte mieux préparé et plus clair pour une tâche donnée.

Lire la sortie de la console

Lisez la console de l’éditeur au format JSON :

curl -sS "$BASE_URL/console" | jq

La réponse contient le texte de la console dans lines et les régions sémantiques dans regions, notamment les erreurs, les résultats d’évaluation et les références de ressources.

Pour suivre en continu la sortie de la console, utilisez :

curl -N "$BASE_URL/console/stream"

Le flux inclut les lignes déjà présentes dans la console, puis reste ouvert pour les nouvelles sorties. Fermez-le après avoir reçu un marqueur de fin ou une erreur, détecté l’arrêt du processus, ou atteint un délai d’expiration ou une limite de lignes.

Pour la délimitation des résultats de test et la classification des échecs, consultez Tests et vérification automatisés.

Générer des aperçus de scènes

L’éditeur Defold (depuis la version 1.13.1) peut générer une « capture d’écran » PNG d’une ressource de scène prise en charge au moyen de la commande /preview/{path} :

mkdir -p build/automation

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

Cette commande produit un rendu de la collection principale du projet ouvert à partir du modèle Basic 3D, dans une vue initiale par défaut :

Vous pouvez utiliser ce rendu pour obtenir des aperçus des ressources qui emploient l’éditeur de scène visuel. Par exemple, il est possible de générer de la même manière l’aperçu d’un composant (component) de modèle, ce qui permet de vérifier son apparence ou, par exemple, le bon fonctionnement du shader :

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

Le chemin situé après /preview/ ne commence pas par une barre oblique. Les dimensions facultatives correspondent par défaut à la taille d’affichage du projet et doivent être comprises entre 1 et 4096.

Les aperçus peuvent être très utiles pour l’analyse visuelle du projet : vérification de la disposition des niveaux et des interfaces graphiques, de la configuration des shaders et de l’éclairage, des régressions visuelles ou création de miniatures pour la documentation.

Exécuter du code Lua dans l’éditeur

L’opération authentifiée POST /eval exécute du code Lua dans l’environnement des extensions de l’éditeur. Le jeton Bearer propre à la session est stocké dans :

.internal/editor.token

Lisez le jeton et exécutez le code :

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"

La sortie imprimée et les valeurs de retour sont renvoyées sous forme de texte. Les réponses courantes sont :

Un client peut réessayer après une erreur 503, mais il devrait limiter le nombre de tentatives. Corrigez le code avant de répéter une requête qui a renvoyé 422.

Le code évalué peut utiliser l’API de l’éditeur et l’environnement des scripts de l’éditeur. Il ne peut pas utiliser les API d’exécution du jeu telles que go.* pour manipuler un jeu en cours d’exécution. Utilisez un test à l’exécution, le débogueur, un test dans un navigateur ou une API d’automatisation à l’exécution pour le comportement du jeu.

Modifier les ressources et les fichiers

De nombreuses ressources source de Defold utilisent des formats texte et peuvent être modifiées avec n’importe quel éditeur de texte. Pour modifier les ressources structurées d’un projet Defold, préférez les transactions de l’éditeur.

Inspectez une ressource avant de la modifier :

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"

Vérifiez editor.can_get(), editor.can_set() et les autres fonctions editor.can_*() avant d’effectuer une transaction.

Utilisez editor.execute() dans le code Lua de l’éditeur pour exécuter un outil de formatage, un validateur ou un générateur :

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

print(output)

Lorsque la commande ne modifie pas les ressources du projet, définissez reload_resources = false pour éviter un rechargement inutile.

Préférences

Les préférences de l’éditeur peuvent être lues et écrites au moyen du chemin documenté dans OpenAPI, actuellement /prefs/{path}.

Vous pouvez par exemple lire la taille configurée de la police du code :

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

Ou la définir, par exemple, sur 16 :

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

L’éditeur valide la valeur par rapport à son schéma de préférences. Un chemin ou une valeur non valide renvoie l’état HTTP 400.

Les préférences sont des paramètres persistants associés à l’utilisateur ou au couple projet-utilisateur ; il ne s’agit pas de la configuration du projet stockée dans game.project. Si l’automatisation doit modifier temporairement une préférence, enregistrez sa valeur précédente et restaurez-la ensuite.

Routes définies par le projet

Les scripts de l’éditeur peuvent définir des routes supplémentaires avec get_http_server_routes(). Une table d’opération OpenAPI facultative expose une route dans le même document /openapi.json que les opérations intégrées.

Les routes définies par le projet peuvent assurer la génération de contenu, la validation, les rapports, les contrôles de localisation, l’analyse des ressources, les tests propres au projet ou une interface plus restreinte pour un IDE ou un contrôleur externe.

Une bonne route devrait effectuer une seule opération au nom explicite, valider son entrée, renvoyer un résultat structuré, être idempotente lorsque cela est possible et limiter les travaux coûteux.

Les routes définies par le projet ne sont pas automatiquement protégées par le jeton de /eval. Ajoutez une authentification propre au projet et des contrôles de sécurité lorsqu’une route effectue des opérations sensibles.

Hooks de cycle de vie

Les hooks sont des fonctions qui peuvent être exécutées avant et après les builds, avant et après la création de bundles, et lorsqu’un processus de jeu démarre ou se termine. Un projet peut contenir un fichier hooks.editor_script à sa racine. Seul ce fichier de hooks racine reçoit ces événements, ce qui donne au projet un emplacement unique pour définir leur ordre.

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

Une erreur levée dans on_build_started() arrête le build de l’éditeur. Les hooks de cycle de vie ne s’exécutent que dans l’éditeur ; placez la logique partagée de validation et de génération dans des scripts autonomes pouvant également être appelés depuis la CI.

Sécurité et compatibilité

Considérez l’ensemble du serveur de l’éditeur comme une interface locale de confiance :

• N’exposez pas publiquement l’accès au port.
• Protégez .internal/editor.token ; ce jeton autorise /eval pour la session actuelle.
• N’accordez pas à des tiers un accès sans restriction à /eval.
• Conservez le jeton dans la couche d’intégration locale plutôt que dans les prompts, les rapports ou les journaux.
• N’oubliez pas que les routes définies par le projet n’héritent pas de l’authentification /eval.
• Utilisez un /openapi.json à jour.
• Limitez les temps d’attente pour les commandes automatiques asynchrones et pour le démarrage de l’éditeur.

Serveur du moteur

Le serveur de l’éditeur appartient au processus de l’éditeur. Un jeu en cours d’exécution utilise un autre port et assume d’autres responsabilités, décrites dans le manuel du service du moteur et de l’API HTTP d’exécution.