// SDK guide

Get your Unity level into the dashboard viewer.

Out of the box, the viewer renders heatmaps over a generic procedural arena. To replace it with your real level geometry, use the SceneExporter editor tool that ships with the SDK.

What it does

SceneExporter walks every Collider in the open scene and writes a JSON description (boxes, spheres, capsules, with world-space transforms). The dashboard renders these primitives natively in Three.js, so there's no GLB conversion or texture-baking step.

Limits

  • BoxCollider, SphereCollider, CapsuleCollider: exported as primitives.
  • MeshCollider: flattened to its AABB (a single oriented box).
  • Other components (renderers, terrain, particles) are ignored.
  • Inactive GameObjects: optional, off by default.
  • Triggers (isTrigger=true): optional, off by default.
  • Layer mask filter: select which layers to include.

For complex mesh-based level geometry, the AABB fallback is rough — primitives give the most useful spatial reference. Full GLB export with vertex-accurate meshes is on the roadmap for Studio tier.

Exporting

  1. Open the scene you want to capture.
  2. In Unity menu: Traced → Export Scene Map…
  3. Set a map name (defaults to scene name).
  4. Pick a layer mask filter, or leave at "everything".
  5. Click Export to file.

The exporter writes to Assets/TracedMaps/<name>-<timestamp>.spatialpulse.map.json and opens the folder so you can grab the file. It also logs a summary to the Console — primitive counts by type, world AABB.

Uploading

  1. Open your project's Maps page in the dashboard.
  2. Click Choose file and select the exported .spatialpulse.map.json.
  3. The first upload auto-activates. Subsequent uploads stay inactive until you click Set active.

The viewer on the project Overview swaps the procedural arena for your uploaded geometry within a second of the active map changing.

Wire format (spatialpulse.v1)

{
  "format": "spatialpulse.v1",
  "name": "Arena 01",
  "scene": "Arena_01",
  "exported_at": "2026-05-15T18:14:33Z",
  "bounds": {
    "min": { "x": -30, "y": 0, "z": -30 },
    "max": { "x":  30, "y": 8, "z":  30 }
  },
  "primitives": [
    { "type": "box", "pos": {...}, "rot": {...}, "size": {...} },
    { "type": "sphere", "pos": {...}, "radius": 1.2 },
    { "type": "capsule", "pos": {...}, "rot": {...},
      "radius": 0.5, "height": 2, "direction": 1 }
  ]
}

Linking a map to your events (slug)

Multi-map projects need a way to tell the dashboard which uploaded map a given event came from. Traced uses the SDK's session_context.map field as the link.

  1. In your Unity bootstrap, set the map name as part of the session context:
Traced.SetSessionContext(new Dictionary<string, string> {
  { "map", "arena_01" },          // ← this is the slug
  { "mode", "deathmatch" },
  { "build_version", Application.version },
});
  1. On the dashboard's Maps page, set the SDK slug field of your uploaded map to the same string (arena_01).

From that point on, the project Overview and any Report scope events to sessions whose context.map matches the active map's slug — so the heat you see is always over the right geometry. A toggle chip near the top of each view lets you opt out and see all events.

If the slug is empty, no scoping happens — every event in the project renders on whatever map is active. Fine for single-map projects.

Best practices

  • Use layer masks to exclude trigger volumes, navmesh-only geometry, and other clutter.
  • Export once per major map version. Old maps don't auto-update; set the new one active.
  • Keep map files under a few hundred KB — the viewer renders all primitives every frame.
  • For VR / training simulations with many small props, mesh colliders flatten to AABBs aggressively. Consider tagging key landmarks with explicit BoxColliders for a cleaner viewer.