Automação do editor Defold

O editor Defold abre um servidor especial para ações automatizadas. A API HTTP controla o projeto aberto. Use-a para comandos do editor, builds, recursos do projeto, pré-visualizações, preferências, saída do console, busca na documentação ou integrações de scripts do editor. Para inspecionar ou controlar o jogo em execução, use o serviço do engine ou uma API de automação em tempo de execução.

Inicialização do editor por uma ferramenta externa

Uma ferramenta externa precisa do arquivo executável do editor e do caminho absoluto para o arquivo game.project do projeto.

As versões instaladas do Defold podem ser localizadas por meio de installations.json, conforme descrito no manual do editor. Seu campo launcherPath contém o executável a ser iniciado. Passe o caminho de game.project como o primeiro argumento posicional para abrir esse projeto diretamente.

O argumento opcional --port ou -p seleciona a porta do servidor do editor. Omiti-lo permite que o Defold escolha uma porta disponível e geralmente é preferível quando vários projetos podem estar abertos.

# 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

O editor é uma aplicação gráfica para desktop. Inicie-o em uma sessão interativa do usuário com acesso ao display. Use o Bob quando uma sessão gráfica não estiver disponível, como em CI headless, ou para automação apenas de compilação e criação de pacotes autônomos.

Depois de iniciar o editor, aguarde até que o projeto tenha sido aberto e .internal/editor.port exista. Então, consulte /openapi.json até que ele retorne um documento válido. Não presuma que a criação do processo significa que o projeto está pronto.

Localização do servidor do editor

O editor inicia um servidor HTTP local enquanto um projeto está aberto. Selecione Ajuda ▸ Abrir Servidor do Editor para abrir a página inicial no navegador padrão:

A porta selecionada é gravada dentro do projeto em:

.internal/editor.port

Daqui em diante, os exemplos e comandos deste manual se referem a estas variáveis do shell:

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

O arquivo da porta pertence à sessão atual do editor. Leia-o novamente depois de reiniciar o editor.

Descoberta de operações por meio de OpenAPI

As únicas informações de inicialização específicas do Defold de que uma ferramenta externa deve precisar são a porta do editor e o documento OpenAPI:

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

O documento OpenAPI 3.0.3 retornado descreve as operações compatíveis com a versão do editor em execução, incluindo caminhos, métodos, parâmetros, nomes de comandos, formatos de solicitação, respostas, códigos de status e requisitos de autenticação.

Liste os caminhos documentados:

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

Liste os comandos disponíveis do editor:

curl -sS "$BASE_URL/openapi.json" |
  jq -r '
    .paths["/command/{command}"].post.parameters[]
    | select(.name == "command")
    | .schema.enum[]
  '

Uma integração ciente da versão deve verificar cada operação necessária e configurar as solicitações com base no esquema retornado. Não recomendamos manter uma cópia supostamente completa dos nomes de endpoints ou comandos, pois ela pode ficar desatualizada.

Rotas definidas pelo projeto também aparecem em /openapi.json quando seus scripts do editor fornecem uma descrição de operação OpenAPI.

Execução de comandos do editor

Os comandos do editor são chamados por meio de:

POST /command/{command}

Por exemplo, o comando atual build compila e executa o projeto:

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

Um build bem-sucedido retorna um resultado estruturado:

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

Um build com falha retorna o status HTTP 422 com problemas como:

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

Os campos disponíveis dependem do erro. Use o caminho do recurso e o intervalo do código-fonte quando estiverem presentes, mas também trate problemas que contenham apenas uma mensagem.

Comandos normalmente úteis, quando listados pelo editor em execução, incluem:

build

Compila e executa o projeto.

clean-build

Limpa o cache de build e depois compila e executa. Use esse comando apenas quando um build comum se comportar de maneira inconsistente ou parecer ignorar alterações.

build-html5

Compila o projeto para HTML5 e disponibiliza a saída por meio do servidor do editor.

fetch-libraries

Baixa e recarrega as dependências do projeto.

hot-reload

Recarrega recursos modificados em um jogo em execução.

reload-extensions

Recarrega scripts do editor.

debugger-start, debugger-stop e os comandos de passo do depurador

Controlam uma sessão de depuração e o projeto em execução.

Os nomes exatos e a disponibilidade dependem da versão e do estado atual do editor; descubra-os em /openapi.json.

Os comandos que operam nos recursos do projeto sincronizam as alterações externas nos arquivos antes da execução.

Respostas de comandos e trabalho assíncrono

A operação de comando documenta os códigos de resposta no esquema OpenAPI atual.

Uma resposta HTTP 202 não comprova que o resultado solicitado existe. Aguarde a saída, o recurso, o marcador do console ou a URL servida relevante e aplique um tempo limite.

Build para HTML5

Se o documento OpenAPI atual listar build-html5, chame-o por meio da operação de comando:

curl -sS \
  -X POST \
  "$BASE_URL/command/build-html5"

O comando é executado de forma assíncrona e normalmente retorna HTTP 202. Após a conclusão do build, o editor o disponibiliza em:

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

Aguarde até que a URL esteja disponível antes de iniciar os testes de navegador. Consulte Testes em navegador para HTML5 para obter mais detalhes.

Busca na documentação de API

Quando presente em /openapi.json, a operação /ref pesquisa a documentação de API incluída na versão do editor em execução. Ela fornece nomes e assinaturas que correspondem a essa versão.

Por exemplo, para pesquisar uma função, use:

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

Filtre por ambiente e linguagem:

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

Os parâmetros de busca são:

environment

editor, runtime ou valores separados por vírgula.

language

Lua, C, C++ ou valores separados por vírgula.

q

Uma expressão que não diferencia maiúsculas e minúsculas. Espaços em branco representam AND, enquanto | representa OR.

Também existem recursos de documentação condensada: o índice de documentação para LLMs contém links para manuais oficiais, namespaces de API e exemplos, e a documentação completa para LLMs apresenta a documentação completa para permitir busca offline e indexação local.

No entanto, os agentes de IA devem preferir buscas específicas em vez de recuperar uma referência inteira quando apenas uma API ou mensagem for necessária, para economizar tokens e ter um contexto mais bem preparado e limpo para determinada tarefa.

Leitura da saída do console

Leia o console do editor como JSON:

curl -sS "$BASE_URL/console" | jq

A resposta contém o texto do console em lines e regiões semânticas em regions, incluindo erros, resultados de avaliação e referências a recursos.

Para acompanhar continuamente a saída do console, use:

curl -N "$BASE_URL/console/stream"

O stream inclui as linhas atuais do console e então permanece aberto para novas saídas. Feche-o após receber um marcador de conclusão ou erro, detectar o encerramento do processo ou atingir um tempo limite ou limite de linhas.

Para enquadramento de resultados de teste e classificação de falhas, consulte Testes automatizados e verificação.

Renderização de pré-visualizações de cenas

O editor Defold (desde a versão 1.13.1) pode renderizar uma “captura de tela” de um recurso de cena compatível como PNG por meio do 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

Isso renderiza a coleção principal do projeto aberto do modelo Basic 3D em uma visualização inicial padrão:

Você pode usar a renderização para obter pré-visualizações de recursos que utilizam o editor visual de cenas. Por exemplo, é possível renderizar um componente de modelo da mesma maneira, o que permite verificar sua aparência ou, por exemplo, a correção do shader:

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

O caminho após /preview/ não inclui uma barra inicial. Por padrão, as dimensões opcionais usam o tamanho de display do projeto e devem estar entre 1 e 4096.

As pré-visualizações podem ser muito úteis para a análise visual do projeto: verificação de layouts de níveis e GUI, configuração de shaders e iluminação, regressões visuais ou criação de miniaturas para a documentação.

Execução de Lua no editor

A operação autenticada POST /eval executa Lua no ambiente de extensões do editor. O bearer token de cada sessão é armazenado em:

.internal/editor.token

Leia o token e execute o código:

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"

A saída impressa e os valores retornados são devolvidos como texto. As respostas típicas são:

Um cliente pode tentar novamente após 503, mas deve usar um número limitado de tentativas. Corrija o código antes de repetir uma solicitação que retornou 422.

O código avaliado pode usar a API do editor e o ambiente de scripts do editor. Ele não pode usar APIs de tempo de execução do jogo, como go.*, para manipular um jogo em execução. Use um teste de tempo de execução, depurador, teste em navegador ou uma API de automação em tempo de execução para a jogabilidade.

Modificação de recursos e arquivos

Muitos recursos de código-fonte do Defold usam formatos de texto e podem ser editados com qualquer ferramenta de edição de texto. Para modificar recursos estruturados do projeto Defold, prefira transações do editor.

Inspecione um recurso antes de alterá-lo:

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"

Verifique editor.can_get(), editor.can_set() e as outras funções editor.can_*() antes de executar uma transação.

Use editor.execute() em Lua no editor para executar um formatador, validador ou gerador:

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

print(output)

Quando o comando não modificar recursos do projeto, defina reload_resources = false para evitar um recarregamento desnecessário.

Preferências

As preferências do editor podem ser lidas e gravadas pelo caminho documentado no OpenAPI, atualmente /prefs/{path}.

Por exemplo, você pode ler o tamanho configurado da fonte do código:

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

Ou defini-lo como, por exemplo, 16:

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

O editor valida o valor de acordo com seu esquema de preferências. Um caminho ou valor inválido retorna HTTP 400.

As preferências são configurações persistentes do usuário ou do usuário no projeto, e não configurações do projeto armazenadas em game.project. Se a automação precisar alterar temporariamente uma preferência, salve o valor anterior e restaure-o depois.

Rotas definidas pelo projeto

Os scripts do editor podem definir rotas adicionais com get_http_server_routes(). Uma tabela opcional de operações OpenAPI expõe uma rota por meio do mesmo documento /openapi.json que as operações integradas.

As rotas definidas pelo projeto podem fornecer geração de conteúdo, validação, relatórios, verificações de localização, análise de recursos, testes específicos do projeto ou uma interface menor para uma IDE ou controlador externo.

Uma boa rota deve executar uma operação com nome claro, validar sua entrada, retornar um resultado estruturado, ser idempotente quando possível e limitar trabalhos custosos.

As rotas definidas pelo projeto não são protegidas automaticamente pelo token de /eval. Adicione autenticação e verificações de segurança específicas do projeto quando uma rota executar operações sensíveis.

Hooks de ciclo de vida

Hooks são funções que podem ser executadas antes e depois de builds, antes e depois da criação de pacotes e quando um processo do jogo é iniciado ou encerrado. Um projeto pode conter um arquivo hooks.editor_script em sua raiz. Somente o arquivo de hook raiz recebe esses eventos, oferecendo ao projeto um único local para definir a ordem deles.

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

Um erro gerado em on_build_started() interrompe o build do editor. Os hooks de ciclo de vida são executados apenas no editor; coloque a lógica compartilhada de validação e geração em scripts autônomos que também possam ser chamados pela CI.

Segurança e compatibilidade

Trate todo o servidor do editor como uma interface local confiável:

• Não exponha publicamente o acesso à porta.
• Proteja .internal/editor.token; ele autoriza /eval para a sessão atual.
• Não conceda acesso externo irrestrito a /eval.
• Mantenha o token na camada de integração local, e não em prompts, relatórios ou logs.
• Lembre-se de que as rotas definidas pelo projeto não herdam a autenticação de /eval.
• Use um /openapi.json atualizado.
• Use esperas limitadas para comandos automáticos assíncronos e para a inicialização do editor.

Servidor do engine

O servidor do editor pertence ao processo do editor. Um jogo em execução tem uma porta diferente e responsabilidades distintas, descritas no manual do serviço do engine e da API HTTP de tempo de execução.