This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
O Defold inclui ferramentas de profiling integradas à engine e ao pipeline de build. Elas ajudam a encontrar problemas de desempenho, memória e uso de recursos. Os dados de profiling em tempo de execução podem ser consumidos por vários recursos:
A configuração Profiler no Manifesto do aplicativo controla se o código do profiler é vinculado a um build. Debug Only é o padrão, None o exclui e Always o inclui em builds debug e release. As configurações profiler no game.project controlam o comportamento em tempo de execução, mas não vinculam novamente a um build o código do profiler que foi excluído. Em particular, Track CPU controla a amostragem de uso da CPU; ela é separada da escolha feita no Manifesto do aplicativo.
Builds que incluem suporte ao profiler têm um profiler visual em tempo de execução que exibe informações ao vivo sobre a aplicação em execução:
function on_reload(self)
-- Alterna o perfilador visual no hot reload.
profiler.enable_ui(true)
end

O perfilador visual fornece várias funções diferentes que podem ser usadas para alterar como ele apresenta seus dados:
profiler.set_ui_mode()
profiler.set_ui_view_mode()
profiler.view_recorded_frame()
Consulte a referência da API do profiler para mais informações sobre as funções do perfilador.
Enquanto uma build desktop ou mobile com suporte ao profiler está em execução, os profilers interativos de frames e recursos podem ser acessados por um navegador.
O Frame profiler permite amostrar seu jogo enquanto ele está em execução e analisar frames individuais em detalhe. Para acessar o perfilador:
O perfilador de frames é dividido em várias seções que fornecem diferentes visões do jogo em execução. Pressione o botão Pause no canto superior direito para interromper temporariamente a atualização das visualizações pelo perfilador.

Quando você usa vários alvos simultaneamente, pode alternar manualmente entre eles alterando o campo Connection Address no topo da página para corresponder à URL do perfilador Remotery mostrada no console quando o alvo foi iniciado:
INFO:ENGINE: Defold Engine 1.3.4 (80b1b73)
INFO:DLIB: Initialized Remotery (ws://127.0.0.1:17815/rmt)
INFO:ENGINE: Loading data from: build/default



O valor LuaMem é a quantidade de memória em kilobytes usada pela VM Lua conforme relatado pelo coletor de lixo do Lua. Memory é a quantidade de memória em kilobytes usada pela engine.
A configuração Max Sample Count limita o número de amostras do profiler registradas por thread e por frame. Se o profiler informar que o limite foi excedido, primeiro verifique se o código de profiling das extensões nativas tem algum par de início/fim de escopo sem correspondência. Aumente o limite somente quando um frame legítimo contiver mais escopos do que o limite configurado.
O Resource profiler permite inspecionar seu jogo enquanto ele está em execução e analisar o uso de recursos em detalhe. Para acessar o perfilador:
http://<address>:<port>/. Use o endereço e a porta informados no console pela engine em execução.O perfilador de recursos é dividido em 2 seções, uma mostrando uma visualização hierárquica das coleções, objetos de jogo e componentes atualmente instanciados no seu jogo, e a outra mostrando todos os recursos atualmente carregados.

Você também pode inspecionar quanto tempo cada recurso leva para carregar. Habilite Resource → Profile em game.project antes de iniciar o jogo. Na visualização de texto, a configuração é:
[resource]
profile = 1
A configuração está desabilitada por padrão. Reinicie o jogo após habilitá-la para medir os carregamentos da inicialização. Cada carregamento concluído ou com falha grava uma entrada de log no nível INFO com o caminho do recurso, o tempo total e os tempos das etapas de pré-carregamento, leitura, criação, pós-criação, fila e espera. Acertos no cache não produzem novos registros de carregamento.
No profiler de recursos, clique em Capture e depois em Show load times para revelar as colunas de tempo. Capture atualiza a visualização das medições armazenadas; não habilita o profiling nem mede retroativamente carregamentos anteriores.
| Coluna | Significado |
|---|---|
| Load (ms) | Tempo total decorrido no carregamento inicial, incluindo dependências, trabalho de pós-criação, enfileiramento e espera. |
| Preload (ms) | Tempo gasto preparando o recurso em seu callback de pré-carregamento. |
| Read (ms) | Tempo gasto lendo os dados do recurso. |
| Create (ms) | Tempo gasto criando o recurso de runtime em seu callback de criação. |
Exibir os tempos de carregamento ordena a tabela pelo tempo total, com os recursos mais lentos primeiro. Clique no cabeçalho de uma coluna de tempo para ordenar por essa etapa; clique novamente para inverter a ordem. As barras da coluna Load mostram cada total em relação ao recurso visível mais lento. Clique em Hide load times para ocultar as colunas novamente.
Os tempos de carregamento e de callbacks incluem o trabalho de dependências aninhadas. Não some os totais dos recursos para calcular o tempo de inicialização, pois o mesmo trabalho pode aparecer na medição de mais de um recurso. As colunas Preload, Read e Create também não representam todo o tempo total de carregamento; o log fornece as etapas adicionais.
Um travessão (—) significa que nenhuma medição concluída está disponível, por exemplo porque o profiling estava desabilitado ou o carregamento inicial ainda não terminou. Um zero medido é exibido como 0.000. As medições descrevem o carregamento inicial: acertos no cache e hot reloads não as alteram, e descarregar um recurso remove sua medição armazenada.
O serviço HTTP da engine pode capturar comandos da GPU Metal em um documento .gputrace no macOS. Abra o rastreamento concluído no Xcode para inspecionar os frames capturados. Esse recurso está integrado à engine de depuração.
Crie um bundle de depuração macOS com o backend gráfico Metal nativo incluído. Se usar um App Manifest, selecione uma opção de Graphics (macOS) que inclua Metal; consulte backends gráficos.
Inicie o executável do bundle em um terminal com METAL_CAPTURE_ENABLED=1 e selecione o adaptador Metal. Substitua o caminho do bundle e o nome do executável neste exemplo:
METAL_CAPTURE_ENABLED=1 \
"/absolute/path/MyGame.app/Contents/MacOS/MyGame" --graphics-adapter=metal
A variável de ambiente deve estar definida quando a engine iniciar. Defini-la apenas em um terminal usado para requisições HTTP não habilita a captura em uma engine já em execução.
Em um segundo terminal, use a porta do serviço da engine impressa no log. Os exemplos abaixo usam curl e jq:
ENGINE_URL="http://127.0.0.1:<port>"
curl -fsS "$ENGINE_URL/openapi.json" | jq '.paths["/profiler/gputrace"]'
curl -sS -i "$ENGINE_URL/profiler/gputrace"
A rota é registrada apenas no macOS. Uma entrada null no documento OpenAPI significa que essa engine não a expõe. Mesmo quando a rota está presente, o suporte à captura depende do adaptador gráfico e do ambiente de inicialização. GET /profiler/gputrace retorna HTTP 501 com error.code: "gputrace_unsupported" quando a captura Metal está indisponível. Verifique se a engine está usando Metal e foi iniciada com METAL_CAPTURE_ENABLED=1 antes de prosseguir. Uma requisição compatível retorna HTTP 200 com o status da captura.
Escolha um caminho absoluto de saída com permissão de escrita que termine em .gputrace, com um diretório pai existente e sem um rastreamento já presente nesse caminho. O caminho se refere ao computador que executa a engine. Para uma engine local, este exemplo cria um novo diretório temporário e solicita um frame:
GPU_TRACE_DIR=$(mktemp -d /tmp/defold-gputrace.XXXXXX)
GPU_TRACE_PATH="$GPU_TRACE_DIR/frame.gputrace"
GPU_TRACE_REQUEST=$(jq -n --arg path "$GPU_TRACE_PATH" '{path: $path, frames: 1}')
curl -fsS -X POST \
-H 'Content-Type: application/json' \
--data "$GPU_TRACE_REQUEST" \
"$ENGINE_URL/profiler/gputrace" | jq
frames é opcional, tem valor padrão 1 e aceita inteiros de 1 a 10000. A captura começa antes do próximo frame renderizado e termina após o envio da quantidade solicitada de frames completos. Mantenha o jogo renderizando durante a espera. Apenas uma captura pode estar pendente ou ativa; outra solicitação de início retorna HTTP 409 com error.code: "gputrace_active".
POST retorna HTTP 200 com ok: true e data.state: "pending" quando a captura é agendada. A conclusão é informada por requisições posteriores de status. Repita a requisição de status até que data.state se torne complete, canceled ou failed:
curl -fsS "$ENGINE_URL/profiler/gputrace" | jq
data.state |
Significado |
|---|---|
idle |
Nenhuma captura foi agendada. |
pending |
A captura aguarda o início da renderização. |
capturing |
A captura está ativa; data.frames_captured informa os frames concluídos. |
complete |
A captura terminou e o rastreamento pode ser aberto. |
canceled |
Uma captura pendente foi cancelada antes de iniciar. |
failed |
A captura não conseguiu iniciar; inspecione data.error para ver o erro nativo. |
GET descreve a captura atual ou mais recente. Verifique se data.path corresponde ao caminho solicitado. Uma captura com falha ainda retorna HTTP 200 com ok: true; inspecione data.state e data.error para determinar o resultado. Em um cliente automatizado, consulte com intervalo e limite de tempo.
Quando o estado for complete, abra o rastreamento no Xcode no Mac da engine:
open -a Xcode "$GPU_TRACE_PATH"
O endpoint HTTP retorna o status; o rastreamento é salvo em data.path no host da engine. Para uma engine remota, recupere o documento concluído desse host antes de abri-lo localmente.
Para cancelar uma captura pendente ou encerrar antecipadamente uma captura ativa:
curl -fsS -X DELETE "$ENGINE_URL/profiler/gputrace" | jq
Uma captura pendente muda para canceled. Em uma captura ativa, data.stop_requested passa a ser true, e a captura termina após o envio do frame renderizado atual. Continue consultando GET até atingir um estado final. DELETE mantém qualquer rastreamento já gravado em disco. Se não houver captura pendente ou ativa, retorna HTTP 409 com error.code: "gputrace_inactive".
O HTML5 usa a API Web Performance em vez do Remotery para a timeline do navegador. Para registrar escopos do Defold:
profiler.performance_timeline_enabled) em game.project.Essa timeline do navegador é separada tanto do profiler visual dentro do jogo quanto do profiler web interativo Remotery.
Ao empacotar seu jogo, há uma opção para criar um relatório de build. Isso é muito útil para entender o tamanho de todos os assets que fazem parte do pacote do seu jogo. Basta marcar a caixa de seleção Generate build report ao empacotar o jogo.

O builder produzirá um arquivo chamado report.html ao lado do pacote do jogo. Abra o arquivo em um navegador web para inspecionar o relatório:

Overview fornece uma decomposição visual geral do tamanho do projeto com base no tipo de recurso.
Resources mostra uma lista detalhada de recursos que você pode ordenar por tamanho, taxa de compressão, criptografia, tipo e nome de diretório. Use o campo “search” para filtrar as entradas de recursos exibidas.
A seção Structure mostra tamanhos com base em como os recursos estão organizados na estrutura de arquivos do projeto. As entradas são codificadas por cor, de verde (leve) a azul (pesado), de acordo com o tamanho relativo do conteúdo de arquivos e diretórios.
Além das ferramentas integradas, há uma ampla variedade de ferramentas gratuitas de tracing e profiling de alta qualidade disponíveis. Aqui está uma seleção:
Observe que perfiladores em Lua pura adicionam bastante overhead a cada hook que instalam. Por esse motivo, você deve ter certa cautela com os perfis de tempo obtidos por esse tipo de ferramenta. Perfis de contagem, porém, são suficientemente precisos.

Esta ferramenta permite inspecionar uma aplicação Defold em execução e ver como ela usa OpenGL. Ela permite fazer traces de chamadas de função OpenGL, definir breakpoints em funções OpenGL, investigar recursos da aplicação (texturas, programas, shaders etc.), examinar o conteúdo de buffers e verificar outros aspectos do estado do OpenGL.

Um conjunto de ferramentas de profiling que captura dados em tempo real da atividade de CPU, memória e rede do seu jogo. Você pode realizar tracing de métodos baseado em amostras da execução do código, capturar heap dumps, ver alocações de memória e inspecionar os detalhes de arquivos transmitidos pela rede. Usar a ferramenta exige que você defina android:debuggable="true" em AndroidManifest.xml.

Observação: desde o Android Studio 4.1, também é possível executar as ferramentas de profiling sem iniciar o Android Studio.
Esta é uma coleção de ferramentas que permite inspecionar, ajustar e reproduzir chamadas de uma aplicação para um driver gráfico. Usar a ferramenta exige que você defina android:debuggable="true" em AndroidManifest.xml.
