Spatial Tracking & Heatmaps

Heatmaps show where players interact with your game world. Find death hotspots, identify camping areas, or optimize level design based on real player behavior.

Tracking Spatial Data

Send position data with game events. Include X, Y, and optionally Z coordinates:

# Track player death with position
QuestData.track("player_death", {
  "level": "level_1",
  "pos_x": 128.5,
  "pos_y": 64.2,
  "pos_z": 0,
  "cause": "enemy_collision"
})

# Track item pickups
QuestData.track("item_pickup", {
  "item_id": "health_potion",
  "level": "level_1",
  "pos_x": 200.0,
  "pos_y": 150.5,
  "pos_z": 0
})

# Track player movement (sample every 5 seconds)
if movement_sample_timer.is_stopped():
  QuestData.track("player_movement", {
    "level": "level_1",
    "pos_x": global_position.x,
    "pos_y": global_position.y,
    "activity": "walking"
  })

Dashboard Features

Feature	Use Case
Heat Intensity	Darker colors = more density (deaths, traffic)
Level Filter	Switch between levels
Event Filter	Show only deaths, pickups, or movement
Map Overlay	Upload level screenshot as background
Z Projection	Collapse 3D height data into 2D top-down view

Uploading Map Images

Two ways to provide level art:

From the dashboard — for one-off uploads or pre-rendered art:

Go to Heatmap page
Click Upload Map Image for a level
Select a 1:1 scale screenshot (16:9 or 4:3 aspect ratio)
The heatmap automatically aligns to the image

From the SDK — for procedural levels or art that changes between builds:

# Captures the current viewport, encodes on a worker thread, uploads
QuestData.upload_level_screenshot("level_1")

The server hashes the image, so calling this on every level load only consumes storage when the art actually changes. See Spatial Tracking SDK page for bounds, projections, and SubViewport capture.

Interpreting Heatmaps

Death hotspots (red clusters):

Confirm they match difficult enemy positions
Check if collision geometry is correct
Adjust difficulty if too concentrated

Movement patterns:

Show player traffic flow
Identify skipped areas (design failed to attract)
Verify intended pathways

API Reference

curl "https://api.questdata.io/v1/stats/heatmap?level=level_1&event=player_death&from=2026-01-01&to=2026-04-01" \
  -H "x-game-api-key: YOUR_API_KEY"

Response:

{
  "level": "level_1",
  "event": "player_death",
  "data": [
    { "x": 128.5, "y": 64.2, "z": 0, "count": 45, "intensity": 0.95 },
    { "x": 200.0, "y": 150.5, "z": 0, "count": 12, "intensity": 0.25 }
  ]
}