FrameDoctor 用户指南

FrameDoctor 支持 Windows 64 位上的 Unreal Engine 5.5、5.6、5.7 和 5.8。请选择与引擎版本匹配的插件包。

如果你从未打开过 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 按钮。这就是 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，或按 Ctrl + Space 打开 Content Drawer，然后查看 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 事件描述工作，frame 事件提供帧边界，bookmark 标记测量区间。如果已有外部记录正在运行，必须先结束它，FrameDoctor 才能开始自己的跟踪。

顺序是先准备就绪，再预热，最后测量。Ready timeout 和 Maximum trace size 在 Settings 中设置。被取消或中断的记录会连同状态一起保留，但不能作为已完成的比较基准。

打开现有跟踪

点击 Import trace，选择已经结束记录的 .utrace 文件，等待 Findings 显示。导入前请先停止记录。如需保留比较的来源依据，请将相邻的 manifest.json 和原始运行文件与跟踪一起保留。阅读 Capture quality and unavailable reasons，检查可用的 CPU、帧和测量数据。

如果无法唯一确定一对完整的 FrameDoctor 测量开始和测量结束书签，就会将整个跟踪作为探索记录进行分析。运行清单缺失或其格式不受支持时，记录的完整性仍处于未验证状态。你可以检查可用事件，但不能将未验证数据或探索数据作为已确认的 A/B 基准。

先查看记录状态和质量。如果数据不完整或某个值显示 Unavailable，请打开 Capture quality and unavailable reasons。这表示无法确定该值，并不表示它等于零。

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 会被烘焙：从已包含的内容中保留对它的硬引用，或将其文件夹加入 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 是 Unreal 中的项目 Content 文件夹，不是 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 启用。
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 和随机条件。可通过 Blueprint 实现其钩子；编写情景不强制要求 C++。

要在现有项目中使用单独提供的示例，请先打开示例项目，在 Content Browser 中右键点击 BP_ExploratoryScenario，选择 Asset Actions → Migrate。将你自己项目的 Content 文件夹设为目标位置，并在该项目中启用 FrameDoctor。也可以按照以下步骤创建自己的情景。

1. 在 Content Browser 中选择 Add → Blueprint Class → All Classes。搜索 FrameDoctorScenario，在项目内容中创建 BP_TestScenario。
2. 打开该 Blueprint，在 Overrides 菜单中实现下面的钩子。这是记录时选择的对象，不是放置在关卡中的 Actor。
3. 编译并保存 Blueprint 和地图。在 FrameDoctor 中选择该类。打包记录时，请按准备 A 和 B中的说明，将地图和情景包含在烘焙中。
4. 开始长时间比较前，先进行一次简短的探索记录，检查就绪判断和清理逻辑。

不要在 Cleanup 中移除其他系统的 Actor 或记录。性能修改后，请另外检查游戏行为；计时条件相同并不代表新逻辑正确。

Project / map（项目／地图）

游戏的工作空间／保存在其中的一个关卡或场景。

Blueprint（蓝图）

用于可视化脚本的 Unreal 资产。你通过连接节点编程，而不必编写 C++。

PIE

Play In Editor，即在 Unreal Editor 内运行游戏。

Development / Shipping

用于开发的构建／最终发布配置。打包记录应使用 Development。

Trace / .utrace（跟踪）

记录计时事件的原始文件。

Scope / timer / thread（作用域／计时器／线程）

测量的一段工作／它的名称／运行这段工作的 CPU 工作流。

ms / FPS

每帧毫秒数／每秒帧数。每帧耗时 16.67 ms 时，游戏每秒大约生成 60 帧。

Mean / p95 / p99（平均值／p95／p99）

平均帧耗时／95%／99% 的完整帧耗时不超过的值。百分位数越高，越侧重较慢的帧。

Warmup / measurement（预热／测量）

不计入结果的稳定等待时间／用于计算结果的区间。

Baseline / candidate / pair（基准／候选／配对）

原始构建／包含修改的构建／两者各运行一次后组合使用。

Noise / threshold（噪声／阈值）

重复运行之间的变化／确认效果所需的最小稳定变化。

Cook（烘焙）

Unreal 准备资产，使其能在打包游戏中运行的过程。

Manifest / profile（清单／配置）

记录保存的条件和状态／为记录选择的设置。

FrameDoctor 1.0.0 · Unreal Engine 5.5、5.6、5.7 和 5.8 · Windows 64 位。

寻求帮助时，请提供引擎和插件版本、使用的是 PIE 还是 Development、点击的操作、保存的状态和原因，以及预期结果。必要时可附上截图或已审查内容的验证数据包。避免分享个人路径或尚未检查的原始日志。

如发现本指南有错误或说明不清，请提交文档问题。插件支持请使用 FrameDoctor 产品页面或购买渠道上的支持联系方式。