在游戏编辑器中用 3D 热力图查看性能热点

构建对比能告诉你帧时间等性能指标变差了多少。要继续排查，还需要知道这种变化是在地图的什么位置观测到的。

Framedash 的热力图一直会在仪表盘的地图图片上显示这个「在哪里」。从 2026-07-24 的 Unity、Unreal Engine 5 和 Godot (C#) SDK 更新开始，同一批聚合格子也能显示在编辑器中。无需关闭关卡，就可以把性能数据以半透明 3D 体素叠加到实际关卡结构上。

把聚合后的性能数据以 3D 形式叠加到关卡上

每一个体素就是一个服务端聚合出来的格子，放在遥测记录下来的世界坐标上。编辑器会向 API 请求 XYZ 聚合，所以带有实测 z 的格子会以那个高度为中心画成一个半透明的方块，而不是贴在地面上的一片色块。

这个差别正是这次更新的重点。平面网格会把上下重叠的空间合在一起：例如，在阳台和下方中庭测得的数值可能落进同一个格子，经过平均后不再显眼。保留高度信息后，就能分辨哪一层的数值更高。没有 z 的旧 API 响应仍旧作为地图底面高度的平面格子显示，所以迁移途中也不会突然什么都看不见。

三个编辑器共用一套从蓝到红的五档配色。颜色按响应中最大的那个格子归一化，所以红色代表的是「这次取回来的范围里最差的格子」，而不是一个固定阈值。Unity 的叠加控件和 Godot 的面板都会在图例旁边给出格子数和最大值。到底是真的重，还是一张安静的地图里相对偏红，就靠这两个数字来分辨。一次请求最多返回 API 上限的 10,000 个格子。

每个引擎怎么打开

三个编辑器都用带 analytics:read 权限的只读 API 密钥加项目 ID 来读数据。它与游戏发送事件时使用的只写采集密钥分开。编辑器只获得读取聚合结果所需的权限，从而避免误写数据、污染比较结果。如果不想把密钥填进工程，就在启动编辑器之前设好 FRAMEDASH_ANALYTICS_API_KEY。三个 SDK 都会把它当作回退值读取，只在当前编辑器进程里使用，并且不做持久化；显式配置过的密钥仍然优先。

Unity：SceneView 叠加层

打开 Window > Framedash Heatmap，填好只读 API 密钥和项目 ID，刷新地图列表，选一张地图，点 Fetch。不需要进 Play 模式。

之后 SceneView 上会多出一个 Framedash Heatmap 叠加层，带 Show、Frame、Controls 三个动作。Frame 会把 SceneView 对准已加载数据的范围，在大关卡里省下不少找地方的工夫。关掉控件窗口，叠加层本身不会跟着消失。所选地图和叠加层开关按工程保存；控件窗口开着时遇到脚本重载，它会恢复地图列表并重新取一次数据。Play 模式期间显示会暂停，退出后只要开关还开着就会回来。

坐标直接沿用 Unity 的 Vector3：遥测的 X/Y/Z 对应 SceneView 的 X/Y/Z，不做地面轴的重映射。Z Offset 只在你想刻意平移显示位置时用，它不会改写云端坐标。

这个叠加层本身是 2026-07-17 的 Unity SDK 0.1.4 以平面四边形的形式加进来的，2026-07-24 的 0.1.7 才变成体素。

Unreal Engine 5：按视口的显示开关

UE5 SDK 0.1.13 把取数据和显示拆开了。Window > Framedash > Framedash Heatmap 是取数据的面板，在 PIE 之外取。显示交给每个关卡视口各自的 Show > Framedash Heatmap 开关，默认关闭，并且跨视口布局互相独立。于是你可以让一个视口保持干净用来搭场景，另一个开着热力图当参照。关掉取数据的面板，正在显示的热力图不会消失。

因为可视化是走编辑器场景的主渲染通道，标准的 F9 和高分辨率视口截图都会把热力图一起拍进去。按一次 F9，就能生成可附在工单中的截图。Play In Editor 期间显示会挂起，播放结束后恢复你原来的视口选择。

云端体素按颜色批处理，并且从冷色到暖色依次绘制，高负载的格子不会被盖住；整个过程也不跑逐格碰撞检测。API URL、项目 ID、只读密钥、不透明度、对齐和 Z 偏移都在 Project Settings > Plugins > Framedash Heatmap 下面。

Godot (C#)：编辑器面板

在 Godot SDK 0.1.8 里，启用插件会给编辑器加一个 Framedash Heatmap 面板。填入只读密钥、项目 ID 和 API 基础 URL，选好时间范围和格子大小，点 Refresh Maps。选一张地图，执行 Fetch Heatmap，打开 Show，再用 Frame Heatmap 把 3D 编辑器的相机对准数据。

最多 10,000 个格子会画成一整块缓存好的半透明体素网格，而不是每格一个节点或一次物理射线。除了 Show 和 Frame，还有不透明度、Z 偏移，以及事件、时间、格子的筛选，外加图例、格子数和最大值。设置保存在 Godot 按工程的编辑器元数据（.godot/editor/editor_layout.cfg）里，不在 project.godot，所以记得把 .godot/ 排除出版本控制。编辑器在转发只读密钥之前会拦截重定向，游戏运行期间隐藏叠加层，播放结束后再恢复。所有热力图代码都由 TOOLS 守卫，因此它和只读密钥都不会进入导出后的游戏。

靠你已经在发的遥测就能跑

这件事不需要重新埋一遍点。格子的原料是带位置的事件，也就是你带着非空 map_id 发出去的事件；前提只有一条，那张地图已经在仪表盘里注册过。自动的 perf_heartbeat 的 map_id 是空的，也没有位置，所以单靠它进不了空间网格。

能放到地图上的指标是 FPS、帧时间、GPU 时间和内存占用。内存之所以能按格子看，是因为 SDK 不只把内存类指标挂在心跳上，也挂在带位置的事件上。2026-07-17 的 Unity 0.1.4 加入 mem.vram 和 mem.heap，为的正是这件事。相机旋转的记录默认开启，每个事件还会带上偏航和俯仰，于是格子详情里可以按「当时朝哪边看」把一个热点拆开。

两种视图回答的问题不一样。用仪表盘比较构建和平台，用编辑器把性能下降的位置与关卡结构对照起来。体素显示的是数值被观测到的位置，并不能直接证明原因。可以从这里开始检查附近的渲染负载、脚本和资源。发布前也能保持关卡打开，直接查看本次构建所改区域的热力图。

如何开始

如果你的游戏已经带着地图 ID 在发遥测，那只要更新 SDK 再建一把只读密钥就行。如果还没有，SDK 集成大概 5 分钟，第一张热力图在 Free 方案上就能看到。

• 概念和仪表盘一侧的筛选整理在性能热力图里。
• 各引擎的具体配置在 Unity、Unreal、Godot 的 SDK 指南里。