Find where FPS drops happen on your game map

A frame-rate average tells you a build is slow; it does not tell you where. Framedash performance heatmaps plot each sample by its world position, so a red patch on the map is a place where FPS drops. This guide shows how to send map-qualified telemetry and then read the FPS heatmap for a specific area.

For the concept and the metrics a heatmap can show, see performance heatmaps.

1. Send map-qualified telemetry

A heatmap plots each sample by its map_id and its world-space position, so a sample lands on the map only when it carries both. You attach them by calling Track with a map identifier and the player position. The automatic perf_heartbeat is deliberately non-spatial: it carries an empty map_id and no position, so it feeds the CI regression gate and the dashboard charts rather than the map. To place performance data on the map, send position-qualified Track events from the spots you care about:

TelemetrySDK.Instance.Track(
    eventName: "player_death",
    mapId: "map_01",
    position: transform.position);

The UE5 SDK takes the same three arguments through the subsystem:

if (auto* Framedash = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    const FVector PlayerLocation(1000.0f, 2000.0f, 50.0f);
    Framedash->Track(TEXT("player_death"), TEXT("Map01"), PlayerLocation);
}

Position is stored as position_x / position_y / position_z, and map_id is a top-level field, so every sample is placed on the right map. See the data model for the full event schema.

2. Register the map image

The heatmap draws over a background image of your level. Register one in either of two ways:

• Upload an image from the dashboard, or through the API.
• Auto-capture images with world-coordinate metadata from your build pipeline, and upload them with framedash map-capture --input-dir ./captures --upload.

3. Read the FPS heatmap

Open the map detail page (Projects, then your project, then Maps, then the map) and switch to Heatmap mode to see FPS, frame time, GPU time, or memory overlaid on the level. Red areas mark the worst-performing spots. You can filter the view by build version, device profile, date range, or session, and you can put two builds side by side to check whether an optimization actually moved the hot spot.

To pull the same data programmatically, use the MCP get_heatmap tool or the REST endpoint. get_heatmap takes map_id (required) plus cell_size, days, and an optional event_name; the REST equivalent is GET /v1/projects/{id}/heatmap. An AI agent connected over MCP can answer “show the FPS heatmap for my map” directly with this tool. See the MCP server reference.

Next steps

• Performance heatmaps: metrics, filtering, and build comparison
• Data model: position, map_id, and the performance fields
• MCP server: query the heatmap in natural language