Spatial Analytics & Death Heatmaps

The SpatialTracker records 3D world coordinates $(X, Y, Z)$ when players die or complete actions, making it easy to generate death heatmaps and pinpoint tricky obstacle jumps or combat bottlenecks.

---

Combat & Death Tracking Pipeline

flowchart LR
    A[Humanoid.Died] --> B[Capture Coordinates X, Y, Z]\n    B --> C{Check Creator Tag}
    C -->|Creator Tag Found| D[Extract Killer & Equipped Tool]
    C -->|No Tag & Y < -150| E[Cause: Void]
    C -->|No Tag & Normal Y| F[Cause: Hazard / Environment]
    D --> G[Round Vector3 to 1 Decimal]
    E --> G
    F --> G
    G --> H[Dispatch PlayerDeath Event]

---

Dispatched Event: PlayerDeath

When a player dies, the module collects character metadata and dispatches a spatial event:

{
  "name": "PlayerDeath",
  "category": "spatial",
  "userId": 201989656,
  "data": {
    "position": { "x": 142.5, "y": 12.0, "z": -85.2 },
    "causeOfDeath": "PvP",
    "killerUserId": 789012,
    "killerName": "SwordMaster",
    "equippedToolName": "IronDagger",
    "lifeDurationSeconds": 48.5
  }
}

Cause of Death Classifications

Cause	Detection Trigger
PvP	creator ObjectValue found inside Humanoid pointing to an active Player
Void	Character position $Y < -150$
Hazard	Environmental trap, lava part, or falling without killer attribution

---

Custom Spatial Telemetry

In addition to death heatmaps, track any 3D world position with Analytics:TrackSpatial:

-- Track where players open treasure chests
Analytics:TrackSpatial(player, "ChestOpened", chestPart.Position, {
    chestType = "Gold",
    tier = 3,
})

-- Track where players use abilities or drop items
Analytics:TrackSpatial(player, "GrenadeExploded", explosionPosition, {
    blastRadius = 15,
})