# Telemetry Settings

The **Telemetry Settings** asset defines how the Runtime Spawner (and related systems like the Region Controller or Special Encounter Manager) record, visualize, and broadcast runtime diagnostic data.\
It provides a unified place to configure performance metrics, event logging, and optional on-screen telemetry overlays.

***

### Overview

Telemetry Settings allow designers and developers to:

* Monitor spawn performance and frequency.
* Track runtime activity (spawn counts, deferred jobs, region activation).
* Enable or disable detailed logs without editing code.
* Optionally display an on-screen **Diagnostics HUD** for live tuning.

This system is primarily used in **development builds** and **debug sessions**, but can also be integrated into in-game analytics or custom telemetry pipelines.

***

### Creating a Telemetry Settings Asset

Create via the Unity menu:

```
Create → Megacrush → Spawner → Telemetry Settings
```

Once created, assign it to systems that support telemetry (for example, `RuntimeSpawner`, `SpecialEncounterManager`, or `RegionPopulationController`).

***

### Key Properties

| Setting                              | Description                                                                                                                                     |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable Telemetry**                 | Master toggle for telemetry collection. When off, no runtime data is captured or logged.                                                        |
| **Enable Debug Logs**                | Prints key runtime events (spawn success, deferrals, hints, pooling, etc.) to the Console. Useful for tracking spawn decisions and performance. |
| **Show Diagnostics HUD**             | Enables an on-screen overlay during Play Mode displaying live counters (active spawns, deferred queue, pool usage, etc.).                       |
| **HUD Refresh Rate**                 | Frequency (in seconds) at which the HUD updates. Higher values reduce overhead.                                                                 |
| **Log Level**                        | Controls verbosity (e.g., *Minimal*, *Standard*, *Verbose*). Verbose logs include full placement reasoning and timings.                         |
| **Track Regions**                    | If enabled, tracks per-region spawn totals, density curves, and timing for the RegionPopulationController.                                      |
| **Track Special Encounters**         | Logs when special encounters are triggered, skipped, or completed.                                                                              |
| **Output File / Channel (Optional)** | Optionally direct telemetry to a file, Scriptable event channel, or custom analytics backend.                                                   |

> The available fields may vary slightly depending on the systems installed (e.g., Region, Encounter, or Network modules).

***

### Example Use

1. **Create a Telemetry Settings asset** and enable `Enable Telemetry` and `Enable Debug Logs`.
2. Assign it to your **RuntimeSpawner** and **RegionPopulationController**.
3. Enter Play Mode.
   * Watch the in-editor **Diagnostics HUD** for active spawn counts.
   * Check the Console for entries like:

     ```
     [Spawner] Spawned Enemy_Grunt (pool active=12)
     [Spawner] Deferred 3x WaveSpawn due to NavMesh not ready
     [Region] Active density step: 0.75
     ```
4. Adjust parameters (spawn rates, region curves) and observe telemetry output in real time.

***

### HUD Overlay Example

When **Show Diagnostics HUD** is enabled, a small overlay appears in the top-left of the Game View showing:

```
Spawner: Active=24  Deferred=2  Seed=12345
Region:  Step=0.80  ActiveRegions=5
Pool:    Alloc=128  InUse=47
```

This visualization helps validate density scaling, seeding, and pooling efficiency during gameplay.

***

### Integration Notes

* The Telemetry asset is **non-destructive** - disabling it at runtime or removing it from a component restores silent mode.
* Compatible with all factories (local and networked).
* Lightweight: telemetry collection runs on a low-frequency update loop to minimize overhead.
* The `onTelemetryEvent` channel (if implemented) can be hooked into external systems (custom analytics, in-editor graphs, etc.).

***

### Recommended Setup

* Use one shared **Telemetry Settings** asset across your entire scene or project.
* Keep **Debug Logs** off for release builds.
* Use **HUD Refresh = 0.25–0.5s** for real-time testing.
* Combine with **Deterministic Seed** and **Spawn Hint Debug Logs** for detailed runtime validation.

***

### ✅ Summary

**Telemetry Settings** centralize all debugging and profiling options for the Runtime Spawner ecosystem.

| Benefit             | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| **Unified control** | Enable or disable all spawn/region/encounter telemetry in one place. |
| **Debug insights**  | Track spawn logic, placement decisions, and deferred jobs.           |
| **Live feedback**   | On-screen HUD and log output for performance validation.             |
| **Extensible**      | Can be extended or redirected to custom analytics systems.           |

> **In short:**\
> Telemetry Settings give you clear visibility into what your spawners are doing - and when - without cluttering your game code.
