Руководство пользователя FrameDoctor

FrameDoctor поддерживает Unreal Engine 5.5, 5.6, 5.7 и 5.8 на Windows 64-bit. Выберите пакет плагина для вашей версии движка.

Если вы ещё не открывали Unreal

Откройте Epic Games Launcher → Unreal Engine → Library и запустите установленный движок. Откройте существующий проект или выберите Games → Blank → Blueprint, задайте имя и папку проекта, затем нажмите Create. Проект хранит вашу игру; карта, которую также называют уровнем, хранит отдельную сцену внутри проекта.

Установка из Fab

1. Закройте Unreal Editor. В разделе Fab Library программы запуска найдите FrameDoctor и нажмите Install to Engine.
2. Выберите версию движка, которую использует ваш проект, и завершите установку.
3. Откройте проект. Перейдите в Edit → Plugins, найдите FrameDoctor, включите его и перезапустите редактор, когда он предложит это сделать.
4. Откройте Tools → FrameDoctor в главном меню редактора.

Установка из предоставленного ZIP-архива

1. Закройте редактор и распакуйте плагин.
2. Поместите одну папку FrameDoctor из архива в папку Plugins вашего проекта. Если папки Plugins нет, создайте её.
3. Проверьте путь по примеру ниже. Не допускайте лишней вложенности FrameDoctor/FrameDoctor.
4. Откройте проект, включите плагин в Edit → Plugins, перезапустите редактор, затем откройте Tools → FrameDoctor.

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

Руководство Epic: включение и установка плагинов.

Начните с одной сцены. Сценарий сообщает FrameDoctor, когда сцена готова и можно начинать измерение. Для обучения и исследования можно использовать необязательный сценарий из отдельного проекта-примера.

Перед шагом 1: Установите FrameDoctor для своей версии движка; рекомендуется установка в движок. Скачайте отдельный проект-пример (UE 5.5–5.8, Win64) и распакуйте его. Проект содержит только контент, требует отдельной установки плагина и привязан к UE 5.5. Для UE 5.6–5.8 сначала нажмите правой кнопкой на FrameDoctorExample.uproject, выберите Switch Unreal Engine version и укажите свой движок. Откройте FrameDoctorExample.uproject в этом движке и убедитесь, что FrameDoctor включён.

1. Откройте и сохраните карту. В проекте-примере откройте карту или выберите File → New Level, сохраните её в папку Content проекта, затем выполните File → Save All.
2. Запустите игру. Нажмите треугольную кнопку Play на панели инструментов редактора. Это режим Play In Editor, или PIE. Нажмите Shift + F1, чтобы освободить указатель мыши и работать с редактором, пока игра продолжает выполняться.
3. Выберите Capture. Откройте Tools → FrameDoctor → Capture. Оставьте флажок Use a packaged Development build выключенным. PIE записывает карту, уже запущенную в Play; выбор другой карты в поле Map не переключает работающий мир.
4. Выберите пример. В поле Scenario найдите BP_ExploratoryScenario. Чтобы найти этот ресурс, откройте Content Browser или Content Drawer сочетанием Ctrl + Space и перейдите в Content → FrameDoctorExample → Scenarios (/Game/FrameDoctorExample/Scenarios). Сценарий выбирают в FrameDoctor; перетаскивать его на уровень не нужно.
5. Начните запись. Оставьте прогрев 10 секунд и измерение 60 секунд. Прочитайте Preflight и нажмите Capture running PIE. Не останавливайте Play и выполните действие, которое хотите исследовать. Прогрев не входит в измеряемый результат.
6. Изучите Findings. Когда запись завершится, откройте Findings, если этот раздел ещё не выбран. Прочитайте Capture quality and unavailable reasons, затем выберите участок работы CPU, чтобы увидеть данные по нему.

Не останавливайте игру до завершения записи. Esc или кнопка Stop в редакторе могут завершить PIE и прервать запись. Чтобы отменить текущую задачу FrameDoctor, используйте в нём Cancel.

В Capture есть два источника записи. Если флажок Use a packaged Development build выключен, записывается текущий мир PIE. Если включён, FrameDoctor запускает отдельную упакованную игру. Для воспроизводимых измерений до и после изменения используйте упакованную сборку.

Обычный профиль CPU использует cpu,frame,bookmark. События CPU описывают работу; события кадров задают их границы; закладки отмечают интервал измерения. Уже выполняющаяся внешняя запись должна завершиться до того, как FrameDoctor начнёт собственную трассировку.

Сначала ожидается готовность, затем идут прогрев и измерение. Ready timeout и Maximum trace size задаются в Settings. Отменённые и прерванные записи сохраняются вместе со статусом; они не являются завершёнными исходными записями для сравнения.

Откройте существующую трассировку

Нажмите Import trace, выберите готовый файл .utrace и дождитесь открытия Findings. Перед импортом остановите запись. Храните соседний файл manifest.json и исходные файлы прогона вместе с трассировкой, если нужно сохранить сведения о её происхождении и условиях для сравнения. Прочитайте Capture quality and unavailable reasons, чтобы проверить доступные данные CPU, кадров и измерения.

Если нет одной однозначной полной пары закладок FrameDoctor, отмечающих начало и конец измерения, вся трассировка анализируется как исследовательская запись. Если манифест прогона отсутствует или не поддерживается, полнота записи остаётся непроверенной. Доступные события можно изучать, но использовать непроверенные или исследовательские данные в качестве подтверждённой исходной записи A/B нельзя.

Начните со статуса и качества записи. Откройте Capture quality and unavailable reasons, если данные неполные или вместо значения указано Unavailable. Это значит, что значение не удалось определить; это не ноль.

1. Посмотрите Game frame p95 и длительность измерения. Сравните кривую с целевым временем кадра.
2. Используйте Search scopes… для поиска имени таймера или All threads для выбора потока. Поток — последовательность работы на CPU; GameThread обычно выполняет игровую логику.
3. Нажмите строку участка работы. Панель поясняет Measured (что измерено), Interpretation (как понимать результат), Next experiment (следующий эксперимент) и Behavior risk (риск изменения поведения).
4. Кнопка Copy evidence копирует идентификаторы выбранного таймера, потока и интервала. Кнопка Open in Insights открывает ту же трассировку в Unreal Insights; перейти к нужному интервалу нужно вручную.

Exclusive / frame — длительность участка работы после вычитания его дочерних участков в том же потоке, усреднённая по допустимым кадрам. Calls — число вызовов, начавшихся в интервале измерения. Участок может включать ожидание. Одно его название не определяет конкретный ресурс и не доказывает стоимость отдельного узла Blueprint.

Не складывайте время вложенных участков с учётом дочерних вызовов или время параллельных потоков, чтобы оценить стоимость кадра. Игровые кадры, кадры рендеринга и контекст очереди GPU имеют разный смысл. Если достоверного значения времени кадра GPU нет, оно остаётся недоступным.

По горизонтали отложено время внутри измерения; по вертикали — длительность кадра в миллисекундах. Более высокие пики означают более медленные кадры. Пунктирная линия — выбранное вами целевое время: 16.67 ms соответствует примерно 60 кадрам в секунду.

• Масштаб: прокрутите колесо мыши над графиком или перетащите янтарные маркеры в небольшом обзорном графике под ним.
• Перемещение: перетащите выбранный диапазон в обзорном графике. Когда основной график находится в фокусе клавиатуры, стрелки влево и вправо сдвигают видимый диапазон.
• Просмотр значений: наведите указатель на график. Подсказка показывает время или группу объединённых отсчётов, число отсчётов и доступные минимальную и максимальную длительности.
• Сброс: нажмите Reset view. Клавиши Home и Esc также сбрасывают вид графика, если он в фокусе.

При показе большого промежутка времени несколько кадров могут объединяться в одну группу для отрисовки. Учитывайте число отсчётов и диапазон этой группы, а не считайте её одним кадром. Если данных кадров нет, на графике остаются разрывы.

Сборка Development — упакованная игра с включёнными средствами разработки, которую можно запускать вне редактора. Baseline A — ваша исходная сборка. Candidate B содержит одно запланированное изменение. Храните каждую сборку целиком в отдельной папке.

1. Сохраните карту и сценарий, готовый для сравнения. Включите FrameDoctor в проекте.
2. Откройте Edit → Project Settings → Packaging. Добавьте карту в List of maps to include in a packaged build. Убедитесь, что Blueprint сценария тоже проходит подготовку ресурсов (cook): сохраните на него жёсткую ссылку из включённого содержимого или добавьте его папку в Additional Asset Directories to Cook.
3. В элементах упаковки Platforms → Windows редактора выберите конфигурацию сборки Development, затем упакуйте проект. В разных версиях движка пункты меню могут быть сгруппированы иначе. Сохраните весь полученный комплект как сборку A.
4. Вручную внесите одно изменение, которое хотите проверить. Сохраните и упакуйте сборку B в другой каталог. Сохраняйте одинаковыми сцену, ввод, камеру, NPC и настройки записи.
5. В Capture включите Use a packaged Development build. Выберите исполняемый файл A, затем карту и введите путь к сгенерированному классу сценария.

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

Подставьте собственные имена ресурсов. /Game — представление папки Content проекта внутри Unreal, а не диск Windows. Имя сгенерированного класса Blueprint заканчивается на _C. Храните всю папку упакованной сборки вместе с содержимым; одного исполняемого файла недостаточно.

Preflight проверяет запрошенные настройки. Только фактическая загрузка показывает, содержит ли выбранная внешняя сборка нужные карту и сценарий. Запись предназначена для конфигураций разработки; сборки Shipping и Test не могут записывать трассировки FrameDoctor.

Руководство Epic: упаковка проекта Unreal.

1. Подготовьте A и B, как описано выше. В Compare раскройте New Development comparison.
2. Выберите Baseline Development executable и Candidate Development executable. В Intended change точно опишите внесённое изменение.
3. До запуска выберите Primary metric: p95GameFrame для медленных кадров, meanGameFrame для средней длительности кадра или p99GameFrame для наиболее медленной части распределения.
4. Начните с 5 пар, прогрева 10 секунд и измерения 60 секунд. Для запланированного изменения сборки оставьте только gameBuildId в качестве обычного разрешённого различия. Установите одинаковые разрешение, графические настройки, VSync, ограничение частоты кадров, сценарий и средства сбора данных.
5. Нажмите Launch paired Development series. FrameDoctor запускает сохранённые сборки, чередуя порядок AB/BA. Не меняйте обе папки сборок до завершения серии.
6. Изучите вердикт и его причины, парную разницу, шум, порог и исходные данные каждой пары. Для просмотра сохранённого результата используйте Open HTML report или Open report folder.

Для подтверждения нужны не менее 5 полных пар, а в каждом прогоне — не менее 30 секунд измерения и 300 полных допустимых кадров, а также сопоставимые условия. Более короткие записи подходят для исследования. Пример исследовательского сценария не может подтвердить эффект.

Чем меньше миллисекунд, тем лучше. Парная разница — медиана разниц B − A в каждой паре. Она может отличаться от результата вычитания двух показанных медиан. Эффект должен превышать наибольшее из трёх значений: абсолютного порога, относительного порога и оценки шума; при этом не менее 80% пар должны совпадать по направлению изменения. Значения по умолчанию — 0.5 ms и 5%. Эти проверки помогают оценить стабильность, но сами по себе не устанавливают причину.

Чтобы снова открыть завершённую серию, используйте Import series and export report и выберите её series.json. Разрешённые различия не могут отменить требования к совпадению средств сбора данных и методов расчёта.

Откройте Runs и нажмите Refresh saved runs. Выберите строку для просмотра сведений об источнике. Дважды нажмите на прогон или нажмите Open selected evidence, чтобы снова открыть Findings. Для серии откроется отчёт по парам.

Папка вывода по умолчанию — <YourProject>/Saved/FrameDoctor; в Settings можно выбрать другую. Отдельный прогон сохраняет исходный .utrace, манифест и анализ. Серия сохраняет series.json, comparison.json, HTML-отчёт и ссылки на исходные прогоны.

1. Загрузите серию, которой хотите поделиться.
2. Решите, включать ли Include source traces in the export — исходные трассировки в экспорт. При необходимости оставьте включённым Remove absolute paths and username from exported JSON для удаления абсолютных путей и имени пользователя из экспортируемого JSON.
3. Нажмите Export paired series bundle, выберите место экспорта и дождитесь завершения.
4. Проверьте экспортированные файлы, затем отправьте весь комплект человеку, который будет оценивать результат.

Promote current run to baseline сохраняет подходящий завершённый и сопоставимый прогон в <YourProject>/FrameDoctor/Baselines. Короткая или исследовательская запись для этого не подходит. Храните исходные данные, пока они могут понадобиться для изучения или повторного подтверждения.

Профиль — сохранённый набор настроек записи и анализа. В Settings выберите Profile ID и имя, настройте поля и нажмите Save profile. Кнопка Load profile открывает JSON-файл профиля. Храните профили в папке проекта FrameDoctor/Profiles, если хотите учитывать их в истории изменений проекта.

Используйте один профиль для обеих сторон A/B. До начала эксперимента задайте пороги в соответствии с вашей целью. Изменение формы во время работы задачи не переписывает сохранённые настройки этой задачи. Профиль с более новой неподдерживаемой схемой открывается только для чтения; используйте совместимый плагин вместо ручного изменения номера схемы.

Этот раздел нужен, когда вы готовы подтвердить результат изменения до и после. Сценарий должен задавать и описывать фактические условия камеры, ввода, NPC и случайности. Его методы можно реализовать в Blueprints; писать C++ для создания сценария необязательно.

Чтобы использовать отдельный пример в существующем проекте, откройте проект-пример, нажмите правой кнопкой на BP_ExploratoryScenario в Content Browser и выберите Asset Actions → Migrate. Укажите папку Content своего проекта как место назначения и включите в нём FrameDoctor. Либо создайте собственный сценарий по шагам ниже.

1. В Content Browser выберите Add → Blueprint Class → All Classes. Найдите FrameDoctorScenario и создайте BP_TestScenario в содержимом проекта.
2. Откройте этот Blueprint. В меню Overrides реализуйте перечисленные ниже методы. Это объект, выбираемый при записи, а не Actor для размещения на уровне.
3. Скомпилируйте и сохраните Blueprint и карту. Выберите класс в FrameDoctor. Для записи упакованной сборки включите карту и сценарий в cook, как описано в разделе «Подготовка A и B».
4. Перед долгим сравнением сделайте одну короткую исследовательскую запись, чтобы проверить готовность и очистку.

Не удаляйте объекты или запись другой системы во время Cleanup. После изменения производительности отдельно проверьте игровое поведение: одинаковые условия измерения не доказывают правильность новой логики.

Проект / карта

Рабочее пространство вашей игры / отдельный уровень или сцена внутри него.

Blueprint

Ресурс Unreal для визуального программирования. Вы соединяете узлы вместо написания C++.

PIE

Play In Editor: игра, запущенная внутри Unreal Editor.

Development / Shipping

Сборка для разработки / конфигурация для итогового распространения. Для записи упакованной игры используйте Development.

Трассировка / .utrace

Исходный файл записанных событий и их времени.

Участок работы (scope) / таймер / поток

Измеренный отрезок работы / его имя / поток работы CPU, в котором он выполнялся.

ms / FPS

Миллисекунды на кадр / кадры в секунду. При 16.67 ms на кадр игра создаёт примерно 60 кадров в секунду.

Среднее / p95 / p99

Средняя длительность кадра / длительность, которую не превышают 95% / 99% полных кадров соответственно. Более высокий процентиль акцентирует более медленные кадры.

Прогрев / измерение

Время стабилизации, исключённое из результата / интервал, по которому вычисляется результат.

Исходная сборка / кандидат / пара

Первоначальная сборка / сборка с вашим изменением / по одному прогону каждой сборки, используемые вместе.

Шум / порог

Разброс между повторениями / минимальный стабильный эффект, необходимый для подтверждения.

Cook

Подготовка ресурсов в Unreal для работы в упакованной игре.

Манифест / профиль

Сохранённые условия и статус записи / настройки, выбранные для записи.

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

Обращаясь за помощью, укажите версии движка и плагина, режим PIE или Development, нажатую кнопку, сохранённые статус и причину, а также ожидаемый результат. При необходимости приложите снимок экрана или проверенный комплект данных. Не публикуйте личные пути и необработанные журналы, которые вы не проверили.

Если в руководстве есть ошибка или непонятная инструкция, создайте обращение по документации. Для поддержки плагина используйте контакт на странице продукта FrameDoctor или в месте покупки.