// SDK guide

The six shapes that drive every visualization.

Every event you fire takes one of six shapes. The shape determines how the viewer renders it: a Point becomes a heatmap cluster; a Pair becomes a line; a Volume becomes a translucent sphere. Custom event IDs work with any shape — you decide what your kill_combo or boss_hit looks like.

Point

The default. One world position, no orientation. Renders as DBSCAN cluster spheres.

Traced.TrackEvent("pickup", transform.position);

Use for: anything where where matters but where you're facing doesn't. Pickups, area entries, button presses, ability casts.

Oriented

Point + rotation. Future visualizations include compass-rose plots and direction arrows.

Traced.TrackEvent("death", transform.position, transform.rotation);

Use for: deaths (which way were they facing?), wall hits (impact normal), weapon fires (where did they aim?), sight-line checks.

Pair

Two world positions. Renders as a line segment with bright source dot and faded target.

Traced.TrackPair("kill_link", killerPos, victimPos,
  new Dictionary<string, string> { { "weapon", "sniper" } });

Use for: kill links, teleports, beam weapons, line-of-sight rays, anything with two endpoints in space.

Volume

Center + radius. Renders as a translucent sphere with a wireframe outline.

Traced.TrackVolume("explosion", center, radius: 4.5f,
  new Dictionary<string, string> { { "type", "grenade" } });

Use for: explosions, AoE damage, capture-zone triggers, sound emitters, hazard radii.

Frustum

Position + rotation + field-of-view + range. Renders as a translucent view cone.

Traced.TrackFrustum("ai_sight",
  eyePosition, eyeRotation, fov: 90f, range: 25f);

Use for: AI sight cones, weapon FOV spread, NPC awareness windows, scope view analysis. The viewer caps at 260 instances per layer for render performance.

Trail

Point flagged for path linkage. The dashboard joins the event with preceding TrackPosition samples from the same player to render an approach trail.

Traced.TrackEventWithTrail("first_shot",
  transform.position, playerId: "p_42");

Use for: pivotal moments where the lead-up movement matters. Fire sparingly — Trails are render-capped at 220.

Position streams (continuous)

Not technically an event shape, but flows through the same SDK. Call every frame (or every fixed step). Stored in a separate position_samples table.

void Update() {
  Traced.TrackPosition(playerId, transform.position,
    transform.rotation, rb.velocity);
}

Free tier: position streams are rejected (the SDK rate-limits client-side anyway, so this is a 403 from the ingest endpoint, not a flood). Pro+ tier: persisted and rendered as flowing path curves in the viewer.

Preset helpers

For the most common event IDs, use Traced.TracedPresets.Death(...), Kill(...), Spawn(...), Pickup(...), ObjectiveComplete(...), DamageDealt(...), AreaEntered(...), AreaExited(...). These wrap TrackEvent with standardized event IDs that the dashboard recognizes and styles automatically.

Putting it together

See the use cases page for full integration patterns by genre (shooters, VR training, level design QA).