Profiler
O Turian vem com um profiler integrado no engine para que a otimização seja baseada em dados, e não em suposições. Trata-se do profiler do jogo — ele mede o trabalho que o engine e seus scripts realizam, e não a interface (chrome) do editor — e ele é executado tanto dentro do Turian Studio quanto no jogo compilado.
O que ele mede
- Zonas de CPU — temporizadores aninhados e escopados em cada thread. As zonas nativas cobrem o renderizador de cena de GPU (
render.scene,render.upload,render.shadow,render.main) e atualizações de script (scripts.update); você pode adicionar as suas próprias. - Contadores de renderização — draw calls por frame, triângulos, vértices, vinculações de textura (texture binds), trocas de material e texturas criadas, obtidos diretamente do renderizador de cena de GPU.
- Tempo de frame — tempo real de CPU por frame (wall-clock CPU time), mapeado ao longo dos últimos segundos.
Gravação: vinculada ao modo Play
A análise de perfil (profiling) ocorre apenas no modo Play, e você controla quando:
- ● Record / ❚❚ Pause inicia e pausa a captura durante a execução — útil quando você só quer analisar uma parte posterior da execução.
- auto-record on Play (caixa de seleção) define se a gravação começa no instante em que você pressiona Play ou se espera até você clicar em Record.
- Pressionar Stop congela o histórico capturado para que você possa analisá-lo.
A viewport ociosa do editor nunca é medida, portanto os números sempre refletem o seu jogo. Uma linha de status (● recording / ❚❚ paused / ■ idle) mostra o estado atual.
O painel do Studio
Abra-o em View ▸ Show Profiler (alternador). O painel flutuante exibe:
- Os controles de transporte de gravação, um alternador de VSync e um seletor de limite de FPS (cap) (unlimited / 30 / 60 / 90 / 120). O VSync é independente do limite — limites acima da taxa de atualização do seu monitor só entram em vigor com o VSync desativado.
- Botões de Capture Screenshot (Capturar tela) e Export Trace (Exportar rastro) (veja abaixo).
- Um gráfico de tempo de frame em uma escala fixa de 0 a 50 ms com linhas de referência de 60 fps e 30 fps, de forma que uma mudança na taxa de quadros altera visivelmente as barras. Cada barra é dividida: a parte CPU-busy (CPU ocupada) na base (colorida em azul/amarelo/vermelho conforme se encaixa no orçamento de 60/30 fps) e a parte idle / cap-wait (ociosa/espera do limite) no topo em cinza escuro. Portanto, limitar o fps gera uma barra alta, majoritariamente cinza — a altura da barra mostra a taxa de quadros mais baixa, mas ela não fica vermelha porque o seu código não está lento; ele está apenas aguardando o limite de tempo. Clique ou arraste pelo gráfico para navegar (scrub) pelo frame fixado na linha do tempo; a coluna mais recente (ou ● live) volta a acompanhar o frame mais recente. Um marcador branco mostra o frame fixado/ativo, e um seletor de histórico (2 s / 4 s / 8 s) define até onde você pode navegar no tempo.
- Uma linha do tempo (timeline) — a peça central. Cada thread é uma faixa (lane); as zonas aninhadas se empilham para baixo por profundidade e são dispostas da esquerda para a direita na proporção da duração do frame, como um gráfico de chamas (flame graph). As cores das zonas são estáveis entre frames, portanto um escopo mantém sua cor enquanto você o assiste. A linha do tempo mostra o frame fixado, permitindo que você navegue pelo histórico e inspecione exatamente o que foi executado em qualquer frame.
- Contadores de renderização (cena) para o frame exibido.
- Uma seção colapsável Editor CPU (studio) — o tempo de frame do próprio editor, recolhido para que as métricas da cena do jogo permaneçam em destaque.
Como o renderizador é compartilhado entre a viewport do editor e o jogo final, os números exibidos no painel representam o custo real de renderização da sua cena.
Exportar para análise (Perfetto)
Export Trace grava o histórico registrado em <project>/profiles/trace_NNNN.json no formato de evento de rastro (Chrome/Perfetto trace-event). Abra-o em ui.perfetto.dev ou chrome://tracing para analisar zonas entre frames, comparar frames e explorar gráficos de chama (flame charts) com uma ferramenta repleta de recursos (o Perfetto é a parte de análise, portanto não há necessidade de importar os rastros de volta para o Studio).
Capturas de tela (Screenshots)
Capture a viewport 3D (a cena real renderizada por GPU) em um PNG a qualquer momento — útil para detectar problemas de renderização (glitches) e verificar proporções, além de compartilhar um frame com um colega de equipe ou um assistente de IA (arquivos PNG abrem em qualquer lugar).
- View ▸ Capture Screenshot, ou o botão Capture Screenshot no painel do profiler.
- Os arquivos são salvos em
<project>/screenshots/shot_NNNN.png(o próximo índice livre, garantindo que capturas nunca sejam sobrescritas). O painel informa o caminho do arquivo salvo.
Analisando o perfil do seu próprio código
Envolva qualquer seção de um script em uma zona de escopo — ela aparecerá na linha do tempo:
const engine = @import("engine");
pub fn update(self: *@This(), frame: engine.Frame) void {
var z = engine.Profiler.zone("MyScript.heavyWork");
defer z.end();
// ... trabalho pesado/caro ...
}
As zonas são aninhadas automaticamente: uma zona aberta dentro de outra se torna filha dela no gráfico de chamas (flame graph).
Custo quando desabilitado
O profiler fica ativo por padrão em builds Debug e inativo caso contrário, de modo que os jogos finais em release não sofrem nenhum impacto de desempenho, a menos que optem por ativá-lo:
engine.Profiler.enabled = true; // ativa-o em um build de release
Quando desabilitado, cada ponto de entrada realiza um retorno rápido (early-out) em uma única instrução de ramificação (branch).
Perfil em jogos compilados
Os jogos compilados executam o mesmo profiler: o loop de jogo gerado envolve cada frame com Profiler.beginFrame/endFrame and registra as zonas do renderizador e atualizações de script. Um HUD de sobreposição na tela, exportação de dados de frame (JSON/CSV) e integração opcional com o Tracy estão no roadmap (issue #35).