Unreal Engine 5.5–5.8Windows de 64 bits

Guía de usuario de FrameDoctor

Graba lo que ocurre en tu escena, encuentra tareas de CPU costosas y comprueba si un cambio manual ayuda. Empieza aquí aunque sea tu primer proyecto de Unreal Engine.

Grabar tu primera captura Instalar FrameDoctor

Capturar una escena
Leer las pruebas
Hacer un cambio
Comparar ejecuciones
Guardar el resultado

Un fotograma es una imagen de tu juego. El tiempo de fotograma es lo que tarda el juego en producir su siguiente imagen. Los fotogramas largos se perciben como pausas o tirones. FrameDoctor graba una traza, un archivo que contiene eventos con sus tiempos, y los convierte en un gráfico y una lista de ámbitos de CPU.

Capture: graba una escena en ejecución.
Findings: consulta tiempos de fotograma e inspecciona una parte del trabajo de CPU.
Compare: mide dos compilaciones Development conservadas, antes y después de un cambio.
Runs: vuelve a abrir grabaciones y exporta pruebas.
Settings: guarda perfiles de captura y elige umbrales.

El cambio lo haces tú. FrameDoctor te ayuda a investigar y medir. No reescribe tu código ni corrige tu juego automáticamente. El análisis se ejecuta de forma local.

La guía está traducida; los controles del plugin que aparecen aquí conservan sus etiquetas en inglés. El selector de idioma cambia esta guía. Un breve glosario explica los términos de Unreal que quizás no conozcas.

Instalar y abrir FrameDoctor

FrameDoctor es compatible con Unreal Engine 5.5, 5.6, 5.7 y 5.8 en Windows de 64 bits. Elige el paquete del plugin correspondiente a tu versión del motor.

Si nunca has abierto Unreal

Abre Epic Games Launcher → Unreal Engine → Library e inicia el motor instalado. Abre un proyecto existente o elige Games → Blank → Blueprint, indica un nombre y una carpeta para el proyecto y pulsa Create. Un proyecto contiene tu juego; un mapa, también llamado nivel, contiene una escena dentro de él.

Instalar desde Fab

Cierra Unreal Editor. En la Fab Library del lanzador, busca FrameDoctor y pulsa Install to Engine.
Selecciona la versión del motor que usa tu proyecto y termina la instalación.
Abre tu proyecto. Ve a Edit → Plugins, busca FrameDoctor, actívalo y reinicia el editor cuando se solicite.
Abre Tools → FrameDoctor en el menú principal del editor.

Instalar un ZIP suministrado

Cierra el editor y extrae el plugin.
Coloca su única carpeta FrameDoctor en la carpeta Plugins de tu proyecto. Crea Plugins si no existe.
Comprueba la ruta siguiente. Evita añadir otra carpeta anidada FrameDoctor/FrameDoctor.
Abre el proyecto, activa el plugin en Edit → Plugins, reinicia y abre Tools → FrameDoctor.

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

¿Qué hago si Unreal pide compilar módulos?

Un paquete compilado también incluye Binaries. Un paquete que solo contiene código fuente necesita una cadena de herramientas de compilación C++ compatible, aunque tu juego use Blueprints. Instala Visual Studio 2022 con Game development with C++ y el Windows SDK que requiera tu motor. En un proyecto que solo use Blueprints, utiliza Tools → New C++ Class para añadir una clase mínima y crear el destino C++ del proyecto. Cierra Unreal y compila el destino Development Editor / Win64 del proyecto en Visual Studio. Después, vuelve a abrir el proyecto. Si la compilación falla, lee el primer error y confirma que las versiones del motor y del paquete coinciden.

Guía de Epic: activar e instalar plugins.

Tu primera grabación

Empieza con una escena. Un escenario indica a FrameDoctor cuándo está lista la escena y cuándo puede comenzar la medición. Para aprender e investigar, puedes usar el escenario opcional disponible en el proyecto de ejemplo separado.

Antes del paso 1: Instala FrameDoctor para tu versión del motor; se recomienda instalarlo en el motor. Descarga el proyecto de ejemplo opcional (UE 5.5–5.8, Win64) y descomprímelo. Este proyecto solo contiene recursos, necesita el plugin instalado por separado y está asociado a UE 5.5. Para UE 5.6–5.8, primero haz clic derecho en FrameDoctorExample.uproject, elige Switch Unreal Engine version y selecciona tu motor. Abre FrameDoctorExample.uproject con ese motor y comprueba que FrameDoctor esté activado.

Abre y guarda un mapa. En el proyecto de ejemplo, abre un mapa o elige File → New Level, guárdalo en la carpeta Content del proyecto y usa File → Save All.
Inicia Play. Pulsa el botón triangular Play de la barra del editor. Esto es Play In Editor, o PIE. Pulsa Shift + F1 para liberar el ratón y usar el editor mientras el juego sigue ejecutándose.
Elige Capture. Abre Tools → FrameDoctor → Capture. Deja desmarcada la opción Use a packaged Development build. PIE graba el mapa que ya se está ejecutando en Play; elegir otro valor en Map no cambia ese mundo.
Selecciona el ejemplo. En Scenario, busca BP_ExploratoryScenario. Para encontrar su recurso, abre Content Browser o Content Drawer con Ctrl + Space y busca en Content → FrameDoctorExample → Scenarios (/Game/FrameDoctorExample/Scenarios). El escenario se selecciona en FrameDoctor; no se arrastra al nivel.
Graba. Mantén 10 segundos de calentamiento y 60 segundos de medición. Lee Preflight y pulsa Capture running PIE. Mantén Play en ejecución y realiza la acción que quieras investigar. El calentamiento queda fuera del resultado medido.
Lee Findings. Cuando termine la captura, abre Findings si aún no está seleccionado. Lee Capture quality and unavailable reasons y selecciona un ámbito de CPU para ver sus pruebas.

El primer ejemplo es exploratorio. Su descripción no establece condiciones de juego repetibles. Puedes inspeccionar la traza, pero necesitas un escenario debidamente descrito y dos compilaciones Development antes de confirmar un efecto A/B.

Mantén el juego en ejecución hasta que termine la grabación. Esc o el botón Stop del editor pueden finalizar PIE e interrumpir la captura. Usa Cancel en FrameDoctor para cancelar su tarea actual.

Elegir qué grabar

Capture tiene dos destinos. Con Use a packaged Development build desmarcado, graba el mundo PIE actual. Con la opción marcada, FrameDoctor inicia un juego empaquetado independiente. Usa la vía del juego empaquetado para mediciones repetibles antes y después de un cambio.

Controles de captura
Control	Cómo usarlo
Baseline Development executable	Selecciona la compilación A conservada con Browse. Esta ruta se comparte con Compare.
Map y Scenario	Selecciona tu clase de escenario. Para Development, proporciona el mapa preparado y la ruta de la clase del escenario.
Warmup	Tiempo para que la escena se estabilice tras estar lista. No se incluye en la medición.
Measurement	Tiempo incluido en el resultado. Empieza con 60 segundos.
Detailed naming for investigation	Incluye más eventos con nombre. Añade sobrecarga; usa el mismo ajuste en ambos lados A/B.
Preflight	Lee el modo seleccionado, los canales de traza y el espacio en disco disponible antes de empezar.

El perfil normal de CPU usa cpu,frame,bookmark. Los eventos CPU describen trabajo; los eventos frame delimitan los fotogramas; los marcadores bookmark señalan el intervalo de medición. Una grabación externa ya activa debe finalizar antes de que FrameDoctor inicie su propia traza.

Primero se espera a que el escenario esté listo, luego viene el calentamiento y después la medición. Ready timeout y Maximum trace size se configuran en Settings. Las grabaciones canceladas o interrumpidas se conservan con su estado; no son referencias completas para comparar.

Página Capture con destino Development, mapa, escenario, calentamiento, medición y Preflight. — Ejemplo ilustrativo de configuración Development empaquetada. En el proyecto de ejemplo separado, usa PIE y deja desmarcada la casilla del build empaquetado.

Leer las pruebas de CPU

Abrir una traza existente

Pulsa Import trace, elige un archivo .utrace cuya grabación haya finalizado y espera a que aparezca Findings. Detén la grabación antes de importarlo. Conserva el archivo adyacente manifest.json y los archivos originales de la ejecución junto con la traza cuando necesites acreditar su procedencia para comparar. Lee Capture quality and unavailable reasons para comprobar los datos disponibles de CPU, fotogramas y medición.

Si no hay un único par completo de marcadores de inicio y fin de medición de FrameDoctor, toda la traza se analiza como una grabación exploratoria. Si falta el manifiesto de ejecución o no es compatible, la integridad de la captura queda sin verificar. Puedes inspeccionar los eventos disponibles, pero no usar datos sin verificar o exploratorios como referencia A/B confirmada.

Empieza por el estado y la calidad de la captura. Abre Capture quality and unavailable reasons si faltan datos o un valor indica Unavailable. Esto significa que el valor no pudo establecerse; no significa cero.

Lee Game frame p95 y la duración medida. Compara la curva con el presupuesto de fotograma.
Usa Search scopes… para buscar un temporizador por nombre, o All threads para seleccionar un hilo. Un hilo es un flujo de trabajo de la CPU; GameThread suele ejecutar la lógica del juego.
Pulsa una fila de ámbito. Su panel explica Measured (lo medido), Interpretation (interpretación), Next experiment (siguiente experimento) y Behavior risk (riesgo para el comportamiento del juego).
Usa Copy evidence para copiar la identidad del temporizador, hilo e intervalo seleccionados. Usa Open in Insights para abrir la misma traza en Unreal Insights y navegar manualmente hasta ese intervalo.

Exclusive / frame es la duración del ámbito tras restar sus ámbitos hijos en el mismo hilo, promediada sobre los fotogramas válidos. Calls cuenta las llamadas iniciadas en el intervalo de medición. Un ámbito puede incluir esperas. Su nombre por sí solo no identifica un recurso concreto ni demuestra el coste de un nodo Blueprint.

La búsqueda tiene un límite visible. La tabla carga las primeras 250 filas ordenadas por clasificación. La búsqueda y el filtro de hilo se aplican a esas filas cargadas. El JSON de análisis completo conserva los demás agregados de ámbitos. Usa Clear filters para restaurar la tabla.

No sumes tiempos inclusivos anidados ni tiempos de hilos paralelos para estimar el coste por fotograma. Los fotogramas de juego, los de renderizado y el contexto de la cola de GPU tienen significados distintos. Si falta un valor de fotograma GPU que sea una referencia fiable, seguirá sin estar disponible.

Findings con un gráfico real de fotogramas, el ámbito EnemyAwareness::Update seleccionado y su panel de pruebas. — Un ámbito seleccionado relaciona un coste medido con un paso de investigación. Los valores mostrados pertenecen a una grabación de ejemplo.

Explorar el gráfico de tiempos de fotograma

El eje horizontal muestra el tiempo transcurrido en la medición; el vertical, la duración del fotograma en milisegundos. Los picos más altos son fotogramas más lentos. La línea discontinua de presupuesto es el objetivo elegido: 16.67 ms equivalen aproximadamente a 60 fotogramas por segundo.

Ampliar: usa la rueda del ratón sobre el gráfico o arrastra los tiradores ámbar de la pequeña vista general situada debajo.
Desplazar: arrastra dentro del intervalo seleccionado en la vista general. Si el gráfico tiene el foco del teclado, las flechas izquierda y derecha desplazan el intervalo visible.
Inspeccionar: mueve el puntero sobre el gráfico. La lectura muestra el instante o grupo agregado, el número de muestras y la duración mínima/máxima disponible.
Restablecer: pulsa Reset view. Home o Esc también restablecen el gráfico que tiene el foco.

El zoom cambia la vista. El valor principal p95, la lista de ámbitos de CPU y las pruebas siguen usando toda la medición. Una vista más estrecha no vuelve a calcularlos para ese intervalo.

Al alejar mucho la vista, varios fotogramas pueden compartir un grupo de dibujo. Lee el número de muestras y el intervalo de ese grupo en vez de tratarlo como un único fotograma. Los huecos permanecen cuando faltan datos de fotogramas.

Gráfico de tiempos de fotograma ampliado, con tiradores de vista general, lectura de un grupo bajo el puntero y métricas de toda la medición sin cambios. — La vista general marca la porción visible; el texto indica qué valores siguen describiendo toda la grabación.

Preparar dos compilaciones Development

Una compilación Development es un juego empaquetado que puedes ejecutar fuera del editor con funciones de desarrollo activadas. Baseline A es tu compilación original. Candidate B contiene un cambio previsto. Conserva cada compilación completa en una carpeta independiente.

Guarda tu mapa y un escenario preparado para comparar. Activa FrameDoctor en el proyecto.
Abre Edit → Project Settings → Packaging. Incluye tu mapa en List of maps to include in a packaged build. Asegúrate de que el Blueprint del escenario también se prepare: mantén una referencia directa desde contenido incluido o añade su carpeta a Additional Asset Directories to Cook.
En los controles de empaquetado Platforms → Windows del editor, elige Development como configuración y empaqueta el proyecto. Los menús pueden agruparse de forma distinta según la versión del motor. Conserva toda esta salida como compilación A.
Haz un cambio manual que quieras probar. Guarda y empaqueta la compilación B en otro directorio. Mantén iguales la escena, las entradas, la cámara, los NPC y los ajustes de captura.
En Capture, marca Use a packaged Development build. Busca el ejecutable de A, selecciona el mapa e introduce la ruta de la clase generada del escenario.

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

Usa tus propios nombres de recursos. /Game es la carpeta Content del proyecto tal como la ve Unreal; no es una unidad de Windows. La clase Blueprint generada termina en _C. Conserva toda la carpeta empaquetada con su contenido; no basta con copiar el ejecutable.

Preflight comprueba la configuración solicitada. La carga real demuestra si la compilación externa contiene ese mapa y escenario. Capture está pensado para configuraciones de desarrollo; las compilaciones Shipping y Test no pueden grabar capturas de FrameDoctor.

Guía de Epic: empaquetar un proyecto de Unreal.

Comprobar si tu cambio ha ayudado

Prepara A y B como se explica arriba. En Compare, despliega New Development comparison.
Elige Baseline Development executable y Candidate Development executable. Describe exactamente qué cambiaste en Intended change.
Elige Primary metric antes de iniciar: p95GameFrame para los fotogramas lentos, meanGameFrame para la duración media o p99GameFrame para el extremo más lento de la distribución.
Empieza con 5 pares, 10 segundos de calentamiento y 60 segundos de medición. Mantén solo gameBuildId como diferencia normalmente permitida para el cambio de compilación previsto. Iguala resolución, ajustes gráficos, VSync, límite de fotogramas, escenario e instrumentación.
Pulsa Launch paired Development series. FrameDoctor ejecuta las compilaciones conservadas alternando el orden AB/BA. No cambies ninguna de las dos carpetas hasta que termine la serie.
Lee el veredicto y sus razones, la diferencia emparejada, el ruido, el umbral y cada par de datos sin procesar. Usa Open HTML report u Open report folder para ver el resultado guardado.

Qué significa el veredicto de la comparación
Veredicto	Siguiente paso
Improved	La métrica de tiempo de fotograma elegida disminuyó de forma consistente más allá del umbral de confirmación. Comprueba por separado que el juego funciona correctamente.
Regressed	La métrica elegida aumentó de forma consistente más allá del umbral. Investiga o deshaz el cambio.
Inconclusive	El efecto es demasiado pequeño, inconsistente o no tiene suficientes datos válidos. Esto no demuestra igualdad ni ausencia de efecto.
InvalidComparison	Las ejecuciones no permiten una comparación válida. Lee las razones de discrepancia o falta de datos y corrígelas primero.

La confirmación requiere al menos 5 pares completos, 30 segundos medidos y 300 fotogramas completos válidos en cada ejecución, además de condiciones comparables. Las capturas más cortas pueden servir para explorar. El escenario exploratorio de ejemplo no puede confirmar un efecto.

Menos milisegundos es mejor. La diferencia emparejada es la mediana de las diferencias B − A de cada par. Puede diferir de la resta de las dos medianas mostradas. El efecto debe superar el mayor de estos valores: umbral absoluto, umbral relativo y ruido estimado, con al menos un 80% de los pares de acuerdo en la dirección. Los valores predeterminados son 0.5 ms y 5%. Estas comprobaciones ayudan a juzgar la estabilidad; por sí solas no establecen la causa.

Para volver a una serie terminada, usa Import series and export report y selecciona su series.json. Las diferencias permitidas no anulan discrepancias en la instrumentación ni en los métodos de cálculo.

Comparación real de cinco pares con veredicto, ejecuciones individuales, diferencia emparejada, ruido y umbral. — Inspecciona todos los pares y sus condiciones junto con el veredicto resumido.

Volver a abrir y compartir tus pruebas

Abre Runs y pulsa Refresh saved runs. Selecciona una fila para leer los detalles de su origen. Haz doble clic en una ejecución o pulsa Open selected evidence para volver a abrir Findings. Una serie abre su informe emparejado.

La salida predeterminada es <YourProject>/Saved/FrameDoctor; Settings permite elegir otra carpeta. Una ejecución individual conserva su .utrace original, el manifiesto y el análisis. Una serie conserva series.json, comparison.json, un informe HTML y referencias a las ejecuciones originales.

Carga la serie que quieras compartir.
Elige si deseas incluir las trazas originales con Include source traces in the export. Deja activado Remove absolute paths and username from exported JSON cuando sea apropiado.
Pulsa Export paired series bundle, elige dónde exportar y espera a que termine.
Revisa los archivos exportados y envía el paquete completo a la persona que revisará el resultado.

Las trazas sin procesar conservan su contenido original. La supresión de datos en JSON no elimina rutas ni mensajes dentro de una traza. Ambas casillas de exportación están activadas de forma predeterminada. Puedes omitir las trazas para obtener un paquete de revisión más pequeño, pero el destinatario necesita las ejecuciones válidas originales y las trazas sin procesar para volver a confirmar el resultado después de trasladarlo.

Promote current run to baseline guarda una ejecución completa, comparable y que cumpla los requisitos en <YourProject>/FrameDoctor/Baselines. Una captura corta o exploratoria no es apta. Conserva los datos originales hasta que ya no necesites inspeccionarlos ni volver a confirmarlos.

Ejecuciones completas guardadas, disponibilidad de trazas originales, opciones de exportación y grabación de origen seleccionada. — Las trazas originales disponibles mantienen el informe vinculado a la grabación real.

Guardar los ajustes que reutilizas

Un perfil es un conjunto guardado de ajustes de captura y análisis. En Settings, elige un Profile ID y un nombre, configura los campos y usa Save profile. Con Load profile puedes volver a abrir un archivo JSON de perfil. Guarda los perfiles en la carpeta FrameDoctor/Profiles del proyecto para seguirlos con su historial.

Ajustes que conviene entender primero
Ajuste	Significado
Trace channels	Usa cpu,frame,bookmark para grabaciones normales de CPU y fotogramas.
Ready timeout	Cuánto esperar a que el escenario esté listo, antes de que empiece el calentamiento.
Maximum trace size	Presupuesto de disco para una traza. Una ejecución que lo supere falla y conserva datos parciales.
Frame budget	Tu duración objetivo por fotograma; el valor predeterminado es 16.67 ms.
Hitch threshold	Umbral para contar fotogramas largos; el valor predeterminado es 50 ms.
Absolute / relative effect threshold	Efecto mínimo de comparación antes de considerar la comprobación del ruido; valores predeterminados de 0.5 ms y 5%.
Output folder	Dónde se guardan nuevas grabaciones e informes. Vacío usa la ubicación predeterminada Saved/FrameDoctor.

Usa el mismo perfil en ambos lados A/B. Cambia los umbrales según tu objetivo antes de iniciar el experimento. Editar el formulario durante una tarea no reescribe los ajustes registrados para esa tarea. Un perfil con un esquema más nuevo no compatible se abre en modo de solo lectura; usa un plugin compatible en vez de cambiar manualmente el número de esquema.

Página Settings con campos de perfil, límites de captura, umbrales de análisis y ubicación de salida. — Guarda un perfil para que las capturas posteriores usen las mismas condiciones elegidas de forma consciente.

Crear un escenario repetible

Usa este procedimiento cuando estés listo para confirmar un cambio antes y después. El escenario debe establecer y describir las condiciones reales de cámara, entrada, NPC y aleatoriedad. Sus hooks pueden implementarse con Blueprints; C++ es opcional para crear escenarios.

Para usar el ejemplo separado en un proyecto existente, abre el proyecto de ejemplo, haz clic derecho en BP_ExploratoryScenario en Content Browser y elige Asset Actions → Migrate. Selecciona la carpeta Content de tu propio proyecto como destino y activa FrameDoctor en él. También puedes crear tu propio escenario con los pasos siguientes.

En Content Browser, elige Add → Blueprint Class → All Classes. Busca FrameDoctorScenario y crea BP_TestScenario en el contenido de tu proyecto.
Abre ese Blueprint. En su menú Overrides, implementa los hooks siguientes. Es un objeto que se selecciona para la captura, no un Actor que se coloca en el nivel.
Compila y guarda el Blueprint y el mapa. Selecciona la clase en FrameDoctor. Para capturas empaquetadas, incluye el mapa y el escenario en la preparación de recursos como se explica en Preparar A y B.
Haz una grabación exploratoria corta para comprobar la disponibilidad y la limpieza antes de iniciar una comparación larga.

Hooks del escenario
Hook	Qué hace tu Blueprint
Prepare(World)	Busca los actores reales de la escena, guarda los ajustes que cambiarás, establece el estado de cámara/entrada/NPC e inicializa cualquier flujo aleatorio utilizado.
IsReady	Devuelve true solo cuando los actores, recursos y estado inicial requeridos estén listos. Por defecto devuelve false. Un retraso fijo por sí solo no establece que todo esté listo.
BeginMeasurement	Inicia la acción controlada después del calentamiento.
EndMeasurement	Detiene esa acción al terminar la medición, incluida una cancelación después de haber empezado.
Cleanup	Revierte solo los cambios de tu escenario. Contempla la preparación parcial y la cancelación.
DescribeScenario	Devuelve un Frame Doctor Scenario Snapshot que describa las condiciones siguientes.

Rellenar la descripción del escenario

En DescribeScenario, conecta Make Frame Doctor Scenario Snapshot al valor de retorno. Rellena estos campos con datos veraces:

ScenarioId / Revision: identidad y revisión estables y no vacías.
CameraRoute: el punto de vista fijo real o un recorrido reproducible.
InputConditions: la entrada usada o cómo se excluye la entrada del jugador.
NpcConditions: la población y su comportamiento, indicando expresamente si no hay NPC.
ParametersJson: objeto JSON válido opcional, por ejemplo {"route":"fixed","npcCount":0} solo cuando describa la escena.
SeedPolicy / RandomSeed: Known solo cuando realmente inicializas la aleatoriedad del juego con esa semilla; NotUsed cuando no se usa aleatoriedad; Unknown cuando no está establecido.
DeclaredNondeterminism: variación restante, como física, carga en streaming o planificación del sistema operativo.

Escribir un número de semilla no inicializa el juego por ti. Con condiciones desconocidas, la captura sigue siendo exploratoria. El BP_ExploratoryScenario disponible en el proyecto de ejemplo separado devuelve deliberadamente una descripción vacía.

No elimines actores ni grabaciones de otro sistema durante Cleanup. Comprueba por separado el comportamiento del juego después de un cambio de rendimiento; unas condiciones de medición iguales no demuestran que tu nueva lógica sea correcta.

Cuando algo no funciona

FrameDoctor no aparece en Tools

Comprueba Edit → Plugins, activa FrameDoctor y reinicia. Confirma que el paquete corresponde a tu motor y que FrameDoctor.uplugin está directamente dentro de su carpeta de plugin. Si usas código fuente, termina primero la compilación Development Editor.

Capture running PIE no está disponible

Inicia la escena con Play. Deja desmarcada la casilla de compilación empaquetada, elige una clase concreta de escenario y espera a que termine otra tarea activa. Libera el ratón de PIE con Shift+F1 para usar la pestaña.

No se ve el escenario de ejemplo

El ejemplo opcional se descarga por separado; el paquete del plugin no contiene ejemplos Blueprint. Abre el proyecto de ejemplo con FrameDoctor instalado y activado, busca BP_ExploratoryScenario en Content → FrameDoctorExample → Scenarios y selecciona su clase en Capture. En tu propio proyecto, primero transfiere el recurso con Migrate. No es un Actor del nivel.

Se agota Ready timeout

El escenario no estuvo listo a tiempo. Comprueba tu implementación de IsReady, los actores/recursos reales, el mapa y la ruta de la clase preparada. La clase base devuelve false. Aumenta Ready timeout si la carga realmente necesita más tiempo; conserva una comprobación de disponibilidad significativa.

El tiempo de fotograma o el coste exclusivo indican Unavailable

Los tiempos necesitan eventos de fotograma y fotogramas completos dentro del intervalo de medición. El coste exclusivo de CPU también requiere una jerarquía de ámbitos completa y coherente. Graba cpu,frame,bookmark, mantén la ejecución activa y lee la razón conservada. Nunca interpretes un valor no disponible como cero.

La comparación indica Inconclusive o InvalidComparison

Lee sus razones. Comprueba el estado de cada ejecución, cinco pares completos, 30 segundos medidos y 300 fotogramas completos por ejecución, un escenario totalmente descrito, condiciones estables e instrumentación coincidente. Inconclusive no demuestra ausencia de efecto; corrige los problemas de validez antes de interpretar una diferencia.

Una compilación empaquetada no encuentra el mapa o escenario

Empaqueta una compilación Development con FrameDoctor activado. Incluye tanto el mapa como el escenario en la preparación. Usa rutas de recursos /Game/... y el sufijo de clase Blueprint _C. Selecciona el ejecutable de la carpeta completa de la compilación conservada.

La captura falla, se detiene o supera su límite de disco

Lee el estado y la razón de la ejecución guardada. Comprueba espacio en disco, permisos de escritura, límite de tamaño de traza y si hay otro grabador activo. Reduce el detalle de eventos o la duración para una captura nueva. Mantén Play activo y evita cambiar de mapa o de ajustes gráficos durante la medición.

Open in Insights no puede abrir la traza

Instala la herramienta Unreal Insights para tu motor. Mantén disponible la traza original. FrameDoctor abre la misma fuente; la navegación exacta al temporizador/hilo/intervalo es manual. Si un motor no puede abrir una ruta con caracteres no ASCII, usa una ubicación de trabajo sencilla con caracteres ASCII conservando la grabación original.

El informe se abre, pero falta su traza original

El informe exportado puede verse sin trazas, pero volver a confirmar requiere los datos originales válidos sin procesar. Exporta otro paquete con trazas originales o restaura las carpetas completas de las ejecuciones originales. Suprimir datos del JSON no crea las trazas que faltan.

Un breve glosario

Proyecto / mapa: El espacio de trabajo de tu juego / un nivel o escena guardado en él.
Blueprint: Un recurso de Unreal para programación visual. Conectas nodos en lugar de escribir C++.
PIE: Play In Editor: el juego en ejecución dentro de Unreal Editor.
Development / Shipping: Una compilación para desarrollo / una configuración de distribución final. Usa Development para capturas empaquetadas.
Traza / .utrace: El archivo original de eventos de tiempos grabados.
Ámbito / temporizador / hilo: Un tramo de trabajo medido / su nombre / el flujo de trabajo de CPU donde se ejecutó.
ms / FPS: Milisegundos por fotograma / fotogramas por segundo. Con 16.67 ms por fotograma, se producen unos 60 fotogramas por segundo.
Media / p95 / p99: Duración media de fotograma / la duración que el 95% / 99% de los fotogramas completos no supera. Un percentil mayor destaca los fotogramas más lentos.
Calentamiento / medición: Tiempo de estabilización excluido del resultado / el intervalo usado para calcularlo.
Referencia / candidata / par: La compilación original / una compilación con tu cambio / una ejecución de cada una usadas juntas.
Ruido / umbral: Variación entre repeticiones / el efecto estable mínimo necesario para confirmar.
Cook: La preparación de recursos que realiza Unreal para que puedan ejecutarse en un juego empaquetado.
Manifiesto / perfil: Las condiciones y el estado guardados de una grabación / los ajustes elegidos para grabar.

Versión y soporte

FrameDoctor 1.0.0 · Unreal Engine 5.5, 5.6, 5.7 y 5.8 · Windows de 64 bits.

Al pedir ayuda, incluye las versiones del motor y del plugin, si usaste PIE o Development, la acción que pulsaste, el estado/razón guardados y qué esperabas que ocurriera. Adjunta una captura de pantalla o un paquete de pruebas revisado si ayuda. Evita compartir rutas personales o registros sin procesar que no hayas comprobado.

Si hay un error o una instrucción poco clara en esta guía, abre una incidencia de documentación. Para recibir soporte del plugin, usa el contacto de soporte de la página de producto de FrameDoctor o tu canal de compra.