Guia do usuário do FrameDoctor

O FrameDoctor é compatível com Unreal Engine 5.5, 5.6, 5.7 e 5.8 no Windows 64-bit. Escolha o pacote do plugin correspondente à versão do seu motor.

Se você nunca abriu o Unreal

Abra Epic Games Launcher → Unreal Engine → Library e inicie o motor instalado. Abra um projeto existente ou escolha Games → Blank → Blueprint, informe o nome e a pasta do projeto e clique em Create. Um projeto guarda seu jogo; um mapa, também chamado de nível, guarda uma cena dentro dele.

Instalação pelo Fab

1. Feche o Unreal Editor. Na Fab Library do inicializador, encontre o FrameDoctor e clique em Install to Engine.
2. Selecione a versão do motor usada no projeto e conclua a instalação.
3. Abra seu projeto. Acesse Edit → Plugins, procure FrameDoctor, ative-o e reinicie o editor quando solicitado.
4. Abra Tools → FrameDoctor no menu principal do editor.

Instalação de um ZIP fornecido

1. Feche o editor e extraia o plugin.
2. Coloque a pasta única FrameDoctor na pasta Plugins do seu projeto. Crie Plugins se ela não existir.
3. Confira o caminho abaixo. Evite uma pasta extra aninhada como FrameDoctor/FrameDoctor.
4. Abra o projeto, ative o plugin em Edit → Plugins, reinicie e abra Tools → FrameDoctor.

YourProject/
  YourProject.uproject
  Plugins/
    FrameDoctor/
      FrameDoctor.uplugin
      Content/
      Resources/
      Source/

Guia da Epic: ativar e instalar plugins.

Comece com uma cena. Um cenário informa ao FrameDoctor quando a cena está pronta e a medição pode começar. Para aprender e investigar, você pode usar o cenário opcional disponível no projeto de exemplo separado.

Antes da etapa 1: Instale o FrameDoctor para a sua versão do motor; recomendamos a instalação no motor. Baixe o projeto de exemplo opcional (UE 5.5–5.8, Win64) e extraia o arquivo. Este projeto contém apenas recursos, exige o plugin instalado separadamente e está associado ao UE 5.5. Para UE 5.6–5.8, primeiro clique com o botão direito em FrameDoctorExample.uproject, escolha Switch Unreal Engine version e selecione seu motor. Abra FrameDoctorExample.uproject com esse motor e confirme que o FrameDoctor está ativado.

1. Abra e salve um mapa. No projeto de exemplo, abra um mapa ou escolha File → New Level, salve-o na pasta Content do projeto e use File → Save All.
2. Inicie o jogo. Clique no botão triangular Play na barra de ferramentas do editor. Esse modo é o Play In Editor, ou PIE. Pressione Shift + F1 para liberar o mouse e usar o editor enquanto o jogo continua em execução.
3. Escolha Capture. Abra Tools → FrameDoctor → Capture. Deixe Use a packaged Development build desmarcado. O PIE grava o mapa que já está em execução no Play; escolher outro mapa no campo Map não troca esse mundo.
4. Selecione o exemplo. Em Scenario, procure BP_ExploratoryScenario. Para encontrar esse recurso, abra o Content Browser ou o Content Drawer com Ctrl + Space e procure em Content → FrameDoctorExample → Scenarios (/Game/FrameDoctorExample/Scenarios). O cenário é selecionado no FrameDoctor; você não precisa arrastá-lo para o nível.
5. Grave. Mantenha 10 segundos de aquecimento e 60 segundos de medição. Leia o Preflight e clique em Capture running PIE. Mantenha o Play em execução e realize a ação que deseja investigar. O aquecimento fica fora do resultado medido.
6. Leia Findings. Quando a gravação terminar, abra Findings se essa seção ainda não estiver selecionada. Leia Capture quality and unavailable reasons e selecione um trecho de trabalho da CPU para ver os dados correspondentes.

Mantenha o jogo em execução até o fim da gravação. Esc ou o botão Stop do editor podem encerrar o PIE e interromper a gravação. Use Cancel no FrameDoctor para cancelar a tarefa atual.

Capture oferece dois alvos. Com Use a packaged Development build desmarcado, grava o mundo PIE atual. Com a opção marcada, o FrameDoctor inicia um jogo empacotado separado. Use o jogo empacotado para medições reproduzíveis antes e depois de uma alteração.

O perfil normal de CPU usa cpu,frame,bookmark. Eventos de CPU descrevem o trabalho; eventos de quadro fornecem os limites dos quadros; marcadores delimitam o intervalo de medição. Uma gravação externa em andamento precisa terminar antes de o FrameDoctor iniciar seu próprio rastreamento.

Primeiro vem a prontidão, depois o aquecimento e, por fim, a medição. Ready timeout e Maximum trace size são definidos em Settings. Gravações canceladas ou interrompidas são mantidas com seu status; elas não são referências concluídas para comparação.

Abra um rastreamento existente

Clique em Import trace, escolha um arquivo .utrace concluído e aguarde Findings. Pare a gravação antes de importá-la. Mantenha o manifest.json ao lado do rastreamento e os arquivos originais da execução com ele quando precisar preservar as informações de origem e condições para comparação. Leia Capture quality and unavailable reasons para verificar os dados disponíveis de CPU, quadros e medição.

Sem um único par completo e inequívoco de marcadores de início e fim da medição do FrameDoctor, todo o rastreamento é analisado como uma gravação exploratória. Se o manifesto da execução estiver ausente ou não for compatível, a completude da gravação permanece não verificada. Você pode examinar os eventos disponíveis, mas não pode usar dados não verificados ou exploratórios como uma referência A/B confirmada.

Comece pelo status e pela qualidade da gravação. Abra Capture quality and unavailable reasons se os dados estiverem incompletos ou um valor mostrar Unavailable. Isso significa que o valor não pôde ser determinado; não significa zero.

1. Leia Game frame p95 e a duração medida. Compare a curva com o tempo-alvo por quadro.
2. Use Search scopes… para encontrar o nome de um temporizador ou All threads para selecionar uma thread. Uma thread é uma sequência de trabalho na CPU; a GameThread normalmente executa a lógica do jogo.
3. Clique em uma linha de escopo. O painel explica Measured (o que foi medido), Interpretation (como interpretar), Next experiment (próximo experimento) e Behavior risk (risco para o comportamento).
4. Use Copy evidence para copiar a identificação do temporizador, da thread e do intervalo selecionados. Use Open in Insights para abrir o mesmo rastreamento no Unreal Insights e navegar manualmente até o intervalo.

Exclusive / frame é a duração do escopo após subtrair seus escopos filhos na mesma thread, calculada como média dos quadros válidos. Calls conta as chamadas iniciadas no intervalo de medição. Um escopo pode incluir espera. Seu nome, sozinho, não identifica um recurso específico nem comprova o custo de um único nó de Blueprint.

Não some tempos inclusivos de escopos aninhados nem tempos de threads paralelas para estimar o custo do quadro. Quadros de jogo, quadros de renderização e contexto da fila da GPU têm significados diferentes. Se não houver um valor confiável para o quadro da GPU, ele permanece indisponível.

O eixo horizontal mostra o tempo ao longo da medição; o vertical mostra a duração dos quadros em milissegundos. Picos mais altos são quadros mais lentos. A linha tracejada representa sua meta: 16.67 ms equivalem a aproximadamente 60 quadros por segundo.

• Zoom: use a roda do mouse sobre o gráfico ou arraste as alças âmbar na pequena visão geral abaixo dele.
• Deslocamento: arraste dentro do intervalo selecionado na visão geral. Quando o gráfico tem o foco do teclado, as setas para a esquerda e para a direita deslocam o intervalo visível.
• Inspeção: mova o ponteiro sobre o gráfico. A leitura mostra o tempo ou grupo de amostras agregadas, a contagem de amostras e as durações mínima e máxima disponíveis.
• Redefinição: clique em Reset view. Home ou Esc também redefinem o gráfico em foco.

Ao mostrar um intervalo amplo, vários quadros podem compartilhar um grupo de desenho. Leia a contagem e a faixa das amostras desse grupo em vez de tratá-lo como um único quadro. Ausências de dados dos quadros permanecem como lacunas.

Uma versão Development é um jogo empacotado que pode ser executado fora do editor com recursos de desenvolvimento ativados. Baseline A é sua versão original. Candidate B contém uma alteração planejada. Mantenha cada versão completa em uma pasta separada.

1. Salve seu mapa e o cenário pronto para comparação. Ative o FrameDoctor no projeto.
2. Abra Edit → Project Settings → Packaging. Inclua seu mapa em List of maps to include in a packaged build. Garanta que o Blueprint do cenário também passe pelo cook: mantenha uma referência direta a ele em conteúdo incluído ou adicione a pasta dele a Additional Asset Directories to Cook.
3. Nos controles de empacotamento Platforms → Windows do editor, escolha Development como configuração de compilação e empacote o projeto. Os menus podem estar agrupados de forma diferente conforme a versão do motor. Guarde toda essa saída como versão A.
4. Faça uma alteração manual que queira testar. Salve e empacote a versão B em outra pasta. Mantenha consistentes a cena, a entrada, a câmera, os NPCs e as configurações de gravação.
5. Em Capture, marque Use a packaged Development build. Procure o executável de A, selecione o mapa e informe o caminho da classe gerada do cenário.

Map: /Game/Maps/TestMap
Scenario: /Game/Scenarios/BP_TestScenario.BP_TestScenario_C
Executable: BuildA/Windows/YourProject/Binaries/Win64/YourProject.exe

Use os nomes dos seus próprios recursos. /Game representa a pasta Content do projeto dentro do Unreal; não é uma unidade do Windows. A classe gerada do Blueprint termina em _C. Mantenha a pasta empacotada completa, incluindo seu conteúdo; copiar apenas o executável não basta.

O Preflight verifica a configuração solicitada. O carregamento real confirma se a versão externa contém o mapa e o cenário. A gravação é destinada a configurações de desenvolvimento; versões Shipping e Test não podem gravar com o FrameDoctor.

Guia da Epic: empacotar um projeto Unreal.

1. Prepare A e B conforme explicado acima. Em Compare, expanda New Development comparison.
2. Escolha Baseline Development executable e Candidate Development executable. Descreva exatamente o que você mudou em Intended change.
3. Antes de iniciar, escolha Primary metric: p95GameFrame para quadros mais lentos, meanGameFrame para a duração média dos quadros ou p99GameFrame para a cauda mais lenta da distribuição.
4. Comece com 5 pares, 10 segundos de aquecimento e 60 segundos de medição. Mantenha apenas gameBuildId como diferença normalmente permitida para a alteração planejada na versão. Use a mesma resolução, configurações gráficas, VSync, limite de quadros, cenário e instrumentação.
5. Clique em Launch paired Development series. O FrameDoctor executa as versões preservadas alternando a ordem AB/BA. Mantenha as duas pastas inalteradas até o fim da série.
6. Leia o veredito e seus motivos, a diferença pareada, o ruído, o limite e os dados brutos de cada par. Use Open HTML report ou Open report folder para acessar o resultado salvo.

A confirmação exige pelo menos 5 pares completos, com 30 segundos medidos e 300 quadros completos e válidos em cada execução, além de condições comparáveis. Gravações mais curtas ajudam na exploração. O cenário exploratório de exemplo não pode confirmar um efeito.

Menos milissegundos é melhor. A diferença pareada é a mediana das diferenças B − A de cada par. Ela pode ser diferente da subtração das duas medianas exibidas. O efeito precisa superar o maior valor entre o limite absoluto, o limite relativo e o ruído estimado, com pelo menos 80% dos pares concordando na direção. Os padrões são 0.5 ms e 5%. Essas verificações ajudam a avaliar a estabilidade; sozinhas, não estabelecem a causa.

Para rever uma série concluída, use Import series and export report e selecione o arquivo series.json. Diferenças permitidas não anulam divergências de instrumentação ou de métodos de cálculo.

Abra Runs e clique em Refresh saved runs. Selecione uma linha para ler os detalhes da origem. Clique duas vezes em uma execução ou clique em Open selected evidence para reabrir Findings. Uma série abre seu relatório pareado.

A pasta de saída padrão é <YourProject>/Saved/FrameDoctor; você pode escolher outra em Settings. Uma execução individual mantém o arquivo .utrace original, o manifesto e a análise. Uma série mantém series.json, comparison.json, um relatório HTML e referências às execuções originais.

1. Carregue a série que deseja compartilhar.
2. Escolha se deseja usar Include source traces in the export para incluir os rastreamentos originais na exportação. Quando apropriado, deixe Remove absolute paths and username from exported JSON ativado para remover caminhos absolutos e o nome de usuário do JSON exportado.
3. Clique em Export paired series bundle, escolha o local de exportação e aguarde a conclusão.
4. Revise os arquivos exportados e envie o pacote completo à pessoa que vai avaliar o resultado.

Promote current run to baseline salva uma execução concluída, comparável e elegível em <YourProject>/FrameDoctor/Baselines. Uma gravação curta ou exploratória não é elegível. Guarde os dados originais até não precisar mais examiná-los ou reconfirmá-los.

Um perfil é um conjunto salvo de configurações de gravação e análise. Em Settings, escolha um Profile ID e um nome, configure os campos e use Save profile. Use Load profile para reabrir um arquivo JSON de perfil. Guarde os perfis na pasta FrameDoctor/Profiles do projeto se quiser acompanhá-los no histórico do projeto.

Use o mesmo perfil nos dois lados de A/B. Ajuste os limites conforme sua meta antes de iniciar o experimento. Editar o formulário enquanto uma tarefa está em execução não altera as configurações já registradas dessa tarefa. Um perfil de um esquema mais novo e não compatível abre somente para leitura; use um plugin compatível em vez de alterar manualmente o número do esquema.

Use esta seção quando estiver pronto para confirmar o resultado de uma alteração antes e depois. Um cenário precisa estabelecer e descrever as condições reais de câmera, entrada, NPCs e aleatoriedade. Seus métodos podem ser implementados em Blueprints; C++ é opcional para criar cenários.

Para usar o exemplo separado em um projeto existente, abra o projeto de exemplo, clique com o botão direito em BP_ExploratoryScenario no Content Browser e escolha Asset Actions → Migrate. Selecione a pasta Content do seu próprio projeto como destino e ative o FrameDoctor nele. Você também pode criar seu próprio cenário com as etapas abaixo.

1. No Content Browser, escolha Add → Blueprint Class → All Classes. Procure FrameDoctorScenario e crie BP_TestScenario no conteúdo do seu projeto.
2. Abra esse Blueprint. No menu Overrides, implemente os métodos abaixo. Esse é um objeto selecionado pela gravação, não um Actor para colocar no nível.
3. Compile e salve o Blueprint e o mapa. Selecione a classe no FrameDoctor. Para gravações empacotadas, inclua o mapa e o cenário no cook conforme explicado em Prepare A e B.
4. Faça uma gravação exploratória curta para verificar a prontidão e a limpeza antes de iniciar uma comparação longa.

Não remova atores nem gravações de outro sistema durante Cleanup. Verifique o comportamento do jogo separadamente depois de uma alteração de desempenho; condições de temporização iguais não estabelecem que sua nova lógica está correta.

Projeto / mapa

Espaço de trabalho do seu jogo / um nível ou uma cena armazenada nele.

Blueprint

Recurso do Unreal para programação visual. Você conecta nós em vez de escrever C++.

PIE

Play In Editor: o jogo em execução dentro do Unreal Editor.

Development / Shipping

Uma versão para desenvolvimento / uma configuração de distribuição final. Use Development para gravações empacotadas.

Rastreamento / .utrace

O arquivo original dos eventos de temporização gravados.

Escopo / temporizador / thread

Um trecho de trabalho medido / seu nome / a sequência de trabalho da CPU na qual ele foi executado.

ms / FPS

Milissegundos por quadro / quadros por segundo. Com 16.67 ms por quadro, o jogo produz aproximadamente 60 quadros por segundo.

Média / p95 / p99

Duração média dos quadros / uma duração que 95% / 99% dos quadros completos, respectivamente, não ultrapassam. Um percentil mais alto destaca quadros mais lentos.

Aquecimento / medição

Tempo de estabilização excluído do resultado / o intervalo usado para calculá-lo.

Referência / candidata / par

A versão original / uma versão com sua alteração / uma execução de cada versão usadas em conjunto.

Ruído / limite

Variação entre repetições / o efeito estável mínimo necessário para confirmação.

Cook

Preparação dos recursos pelo Unreal para que funcionem em um jogo empacotado.

Manifesto / perfil

Condições e status salvos de uma gravação / as configurações escolhidas para uma gravação.

FrameDoctor 1.0.0 · Unreal Engine 5.5, 5.6, 5.7 e 5.8 · Windows 64-bit.

Ao pedir ajuda, informe as versões do motor e do plugin, se usou PIE ou Development, a ação em que clicou, o status e o motivo salvos e o que esperava que acontecesse. Anexe uma captura de tela ou um pacote de dados revisado quando isso ajudar. Evite compartilhar caminhos pessoais ou logs brutos que você não conferiu.

Para um erro ou uma instrução pouco clara neste guia, abra uma issue de documentação. Para suporte do plugin, use o contato de suporte na página do produto FrameDoctor ou no canal em que realizou a compra.