Obby & FPS Death Heatmaps

Obstacle courses (Obbies) and multiplayer shooters rely heavily on level balance. If a jump is too punishing or a spawn point is camped, players leave. This tutorial demonstrates how to use the module to track death hotspots and checkpoint bottlenecks.

1. Setup Server Script

In ServerScriptService, create ObbyTelemetry.server.luau:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local AnalyticsModule = require(ReplicatedStorage.AnalyticsModule)
local Analytics = AnalyticsModule.init({
    debugMode = true,
    autoTrackDeaths = true, -- Automatically captures Humanoid.Died coordinates
})

-- Track Checkpoints
local checkpointsFolder = workspace:WaitForChild("Checkpoints")

for _, checkpoint in ipairs(checkpointsFolder:GetChildren()) do
    if checkpoint:IsA("BasePart") then
        checkpoint.Touched:Connect(function(hit)
            local character = hit.Parent
            local player = Players:GetPlayerFromCharacter(character)
            if player then
                -- Track when player reaches this checkpoint
                Analytics:TrackSpatial(player, "CheckpointReached", checkpoint.Position, {
                    stageNumber = checkpoint:GetAttribute("Stage") or 1,
                    stageName = checkpoint.Name,
                })
            end
        end)
    end
end

2. Analyzing the Data

When players fail jumps or die to hazards:

1. The module dispatches PlayerDeath with exact { x, y, z } coordinates and causeOfDeath.
2. Compare the timestamp difference between CheckpointReached on Stage 1 vs Stage 2 to calculate average time-to-complete per stage.
3. Identify stages where death frequency spikes:
   • High deaths + Low progression = Frustrating bottleneck.
   • Low deaths + Fast completion = Too easy.