Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Monitores de desempenho personalizados

Introdução

Conforme explicado na documentação Painel do depurador, o Godot apresenta um painel inferior Debugger > Monitors que permite rastrear vários valores com gráficos mostrando sua evolução ao longo do tempo. Os dados para esses gráficos são originados do singleton Performance da engine.

O Godot permite que você declare valores personalizados para serem exibidos na aba Monitors. Exemplos de casos de uso para monitores de desempenho personalizados incluem:

• Exibir métricas de desempenho que são específicas do seu projeto. Por exemplo, em um jogo de voxel, você poderia criar um monitor de desempenho para rastrear o número de chunks que são carregados a cada segundo.

• Exibir métricas internas do jogo que não estão estritamente relacionadas ao desempenho, mas que ainda são úteis de colocar em gráfico para fins de depuração. Por exemplo, você poderia rastrear o número de inimigos presentes no jogo para garantir que sua mecânica de spawning funcione como pretendido.

Criando um monitor de desempenho personalizado

Neste exemplo, criaremos um monitor de desempenho personalizado para rastrear quantos inimigos estão presentes no projeto em execução no momento.

A cena principal apresenta um nó Timer com o seguinte script anexado:

extends Timer


func _ready():
    # The slash delimiter is used to determine the category of the monitor.
    # If there is no slash in the monitor name, a generic "Custom" category
    # will be used instead.
    Performance.add_custom_monitor("game/enemies", get_enemy_count)
    timeout.connect(_on_timeout)
    # Spawn 20 enemies per second.
    wait_time = 0.05
    start()


func _on_timeout():
    var enemy = preload("res://enemy.tscn").instantiate()
    get_parent().add_child(enemy)


# This function is called every time the performance monitor is queried
# (this occurs once per second in the editor, more if called manually).
# The function must return a number greater than or equal to 0 (int or float).
func get_enemy_count():
    return get_tree().get_nodes_in_group("enemies").size()

O segundo parâmetro de Performance.add_custom_monitor é um Callable.

enemy.tscn é uma cena com um nó raiz Node2D e um nó filho Timer. O Node2D possui o seguinte script anexado:

extends Node2D


func _ready():
    add_to_group("enemies")
    $Timer.timeout.connect(_on_timer_timeout)
    # Despawn enemies 2.5 seconds after they spawn.
    $Timer.wait_time = 2.5
    $Timer.start()


func _on_timer_timeout():
    queue_free()

Neste exemplo, como criamos 20 inimigos por segundo, e cada inimigo desaparece (despawns) 2,5 segundos após surgir, esperamos que o número de inimigos presentes na cena se estabilize em 50. Podemos nos certificar disso olhando para o gráfico.

Para visualizar o gráfico criado a partir deste monitor de desempenho personalizado, execute o projeto, mude para o editor enquanto o projeto estiver rodando e abra Debugger > Monitors na parte inferior da janela do editor. Role para baixo até a recém-disponível seção Game e marque Enemies. Você deve ver um gráfico aparecendo da seguinte forma:

Exemplo de gráfico do editor a partir de um monitor de desempenho personalizado

Nota

O código de manipulação do monitor de desempenho não precisa residir no mesmo script que os próprios nós. Você pode optar por mover o registro do monitor de desempenho e a função getter para um autoload em vez disso.

Consultando um monitor de desempenho em um projeto

Se você deseja exibir o valor do monitor de desempenho na janela do projeto em execução (em vez do editor), use Performance.get_custom_monitor("category/name") para buscar o valor do monitor personalizado. Você pode exibir o valor usando um Label, RichTextLabel, Desenho personalizado em 2D, Texto 3D, etc.

Este método também pode ser usado em projetos exportados (modo debug e release), o que permite criar visualizações fora do editor.