在游戏编辑器中用 3D 热力图查看事件分布

Framedash 的编辑器内 3D 热力图，可以把记录到的事件分布叠加到实际关卡中。在 Unity、Unreal Engine 5 和 Godot (C#) 中，半透明方块能帮助你查看阶梯、门口或上下重叠的楼层附近的事件分布，无需只凭俯视地图推断位置。

使用前需要明确颜色的含义：当前编辑器叠加层按事件数量着色。仪表盘另有性能指标视图，但 SDK 的编辑器控件不能选择 FPS、帧时间、GPU 时间或内存作为着色指标。红色体素表示该单元格在本次获取的数据中记录了较多事件，不能据此判定这里存在性能问题。

一个体素代表什么

体素是表示一个聚合网格单元的小方块。编辑器向 API 请求按 XYZ 三个轴聚合的数据，再将单元格绘制在对应的网格坐标上。它呈现的是事件分布，不是每个事件的精确位置，也不是会话回放。

按三个轴分组，有助于区分平面视图中重叠的空间。例如，只要单元格足够小，阳台上和下方中庭里发生的事件就能落入不同单元格；网格过粗时，两者仍可能合并。对于不含 z 的旧版 API 响应，编辑器会在配置的地图基准面上继续显示平面单元格。

从蓝到红的五段渐变色，以响应中的最大 weight 为基准。当前编辑器端点返回的这个权重就是事件数量。Unity 和 Godot 会在图例旁显示单元格数量和最大权重。比较截图前先看这些数值：两次获取结果中同样呈红色的单元格，事件数量未必相同。

每次最多返回 10,000 个单元格，按权重从大到小排序。如果达到上限，部分事件较少的单元格可能未被返回。可以缩短时间范围、按事件名称筛选，或增大单元格后重新获取。没有记录到符合条件的事件时，相应区域也会留空；空白不能证明该区域性能良好。

准备数据和读取权限

叠加层需要带有非空 map_id 和有效世界坐标的事件，以及 Framedash 中已注册的对应地图。还要检查地图的世界坐标边界，边界外的事件不会计入网格。如果已经在发送符合这些条件的事件，就可以直接使用现有数据。自动发送的 perf_heartbeat 没有位置，map_id 也为空，因此仅靠心跳事件无法生成这个空间网格。

为编辑器配置具有 analytics:read 权限的 Read API Key，以及对应的项目 ID。这与游戏发送事件时使用的只写摄取密钥不同。如果不想把读取密钥保存到编辑器设置中，可以在启动编辑器前设置 FRAMEDASH_ANALYTICS_API_KEY，并将密钥输入框留空。三个 SDK 都支持这种方式；如果输入框中已有密钥，则优先使用输入的值。

只读密钥仍然是凭据，不应出现在版本控制、导出的游戏、日志或截图中。API 基础 URL 应指向实际保存数据的部署环境。

在各引擎中打开热力图

下面介绍的操作来自 2026 年 7 月 24 日的 SDK 更新：Unity 0.1.7、UE5 0.1.13 和 Godot 0.1.8。这些版本号说明功能从何时开始提供，并不表示各 SDK 的最新版本。

Unity SceneView

1. 打开 Window > Framedash Heatmap，设置读取密钥、项目 ID 和 API 基础 URL。
2. 刷新地图列表并选择地图，设置时间范围、单元格大小和可选的事件名称筛选条件。在 Play 模式之外点击 Fetch。
3. 在 SceneView 的 Framedash Heatmap 叠加层中，用 Show 切换显示，用 Frame 将视图对准全部数据，用 Controls 重新打开设置窗口。

关闭设置窗口后，叠加层仍然可用。所选地图和显示设置按项目保存，进入 Play 模式时会隐藏叠加层。

Unity 记录的 Vector3 分量直接对应 SceneView 的 X/Y/Z，不会为适配地面而交换坐标轴。Z Offset 只移动显示位置，不能修正或改写已存储的坐标。

Unreal Engine 5 关卡视口

在 Project Settings > Plugins > Framedash Heatmap 中设置 API URL、项目 ID、读取密钥和显示选项。打开 Window > Framedash > Framedash Heatmap，选择地图和查询条件，在 Play In Editor（PIE）之外获取数据。

然后，在需要显示叠加层的关卡视口中启用 Show > Framedash Heatmap。这个标志默认关闭，各视口相互独立，因此可以保留一个不显示热力图的视口用于编辑。关闭数据面板不会移除已经获取的叠加层。

普通 F9 截图和高分辨率视口截图都会包含热力图。将截图附到问题单时，同时记录地图、时间范围、单元格大小和事件筛选条件，方便其他开发者理解颜色。PIE 期间会暂停显示，结束后恢复原来的视口选择。

Godot (C#) 3D 编辑器

构建并启用 C# 插件后，打开 Framedash Heatmap 面板。输入读取密钥、项目 ID 和 API 基础 URL，选择时间范围与单元格大小。点击 Refresh Maps，选择地图，再点击 Fetch Heatmap。启用 Show，然后用 Frame Heatmap 将 3D 编辑器摄像机对准已加载的单元格。

面板还提供事件名称筛选、不透明度和 Z 偏移设置。单元格由缓存的半透明网格绘制，游戏运行时会隐藏叠加层。设置保存在项目的编辑器元数据 .godot/editor/editor_layout.cfg 中，因此应将 .godot/ 排除在版本控制之外。热力图代码仅在编辑器中使用。

如何配合性能排查

仪表盘和编辑器展示的数据范围不一定相同。当前编辑器可按地图、时间范围、单元格大小和事件名称筛选，不会继承仪表盘所选的构建、平台或性能指标。

排查性能问题时，可以按以下顺序使用：

1. 在仪表盘选择地图、构建、目标平台和时间范围，查看性能指标及其数值。热力图一次显示一个构建；基线与候选构建的数值对比在 Regression 页面进行。
2. 打开对应关卡，获取编辑器中的事件视图，确认埋点记录到的活动分布在哪里。如果所选时段包含多个构建或平台，就不能把这些体素当作仪表盘所选构建的独立结果。
3. 在合适的测量构建中复现可疑路线或场景，用引擎分析器捕获数据，再根据捕获结果排查渲染工作、脚本或内存分配。体素出现在某个资源附近，并不能证明开销来自该资源。
4. 修改后，在可比条件下重新测量，保持设备、设置、路线和测量区间一致，再比较数值。编辑器颜色变冷，可能只是事件减少或相对最大值改变，不能据此确认修复有效。

事件密度也取决于埋点的位置和频率。死亡事件热力图描述的是记录到的死亡分布；定时采集的位置事件描述的是采样活动。两者都不会自动成为停留时长图。采样率改变后，可用于比较的数据也会改变。

没有显示或位置不对时

先检查项目 ID 和密钥权限，再核对已注册的地图 ID、时间范围和事件名称筛选条件。确认事件确实到达，坐标符合预期，且位于地图边界内。用 Frame 或 Frame Heatmap 找到加载的数据，并检查是否已在非运行状态下启用显示开关。

如果叠加层发生偏移，先核对关卡与记录数据的坐标系，再调整显示偏移。事件记录之后若移动了关卡几何结构，旧数据即使正确对应旧布局，在当前场景中也可能看起来错位。

第一次验证时，选一张地图和一种发生位置已知的事件。确认它出现在预期位置后，再扩大查询范围。

• 仪表盘的指标和筛选方式见性能热力图。
• SDK 的安装与配置见 Unity、Unreal 和 Godot 指南。