# Telemetry Integration & Troubleshooting

Once you’ve created a telemetry provider — whether through a ScriptableObject or runtime code — the final step is confirming that it’s connected and working correctly.

This page covers **setup order**, **runtime verification**, and **common issues** when using telemetry with the **Special Encounter Manager**.

***

### 1. Setup Flow Overview

To ensure telemetry is evaluated correctly, the following flow must occur during initialization:

```mermaid
flowchart TD
    A[RuntimeSpawner.Init()] --> B[SpecialEncounterManager.Init()]
    B --> C[TelemetryProvider assigned]
    C --> D[RuntimeSpawner.StartSpawners()]
    D --> E[SpecialEncounterManager.Begin()]
```

#### Quick Checklist

| Step                                   | Description                                               |
| -------------------------------------- | --------------------------------------------------------- |
| **1. RuntimeSpawner in scene**         | Must be initialized first (`Init()` → `StartSpawners()`). |
| **2. SpecialEncounterManager present** | Assigned a valid **Special Profile** with rules.          |
| **3. Telemetry Provider assigned**     | Via inspector (SO) or `SetTelemetryProvider(...)`.        |
| **4. Begin() called**                  | The manager’s internal timer starts rule evaluation.      |

***

### 2. Verifying Telemetry at Runtime

#### Option A — Diagnostics HUD

If your HUD includes the **Specials** section:

* “**Pressure:**” and “**Avg HP:**” values update live as the manager polls the provider.
* “**Next:**” shows when the next rule evaluation will occur.
* “**Last Spawn:**” confirms when a special was successfully triggered.

Example HUD output:

```
Specials: Pressure=0.84  AvgHP=0.67  Next: 4.2s
Last Spawn: 12s ago (Tag: Boss)
```

If these values stay at **0.00**, telemetry is not connected or not returning data.

#### Option B — Console Logs

Enable **Debug Logs** in your Telemetry Settings or manager inspector to print evaluations:

```
[Specials] Evaluating rule "Flanker"
[Specials] Pressure=0.84, AvgHP=0.67 → PASS
[Specials] Spawned Flanker_Special (anchor=Hint_03)
```

***

### 3. Timing & Evaluation Behavior

* Telemetry is checked **each evaluation cycle**, defined by the `evalEverySeconds` value on each Special Rule.
* If rules share the same interval, they evaluate in sequence.
* Rules can also be step-gated — if the Director step doesn’t match, the telemetry condition isn’t checked.

> **Tip:** When testing, shorten `evalEverySeconds` (e.g. 1–3s) and lower cooldowns to quickly validate rule behavior.

***

### 4. Common Issues & Fixes

| Symptom                                              | Cause                                                                  | Fix                                                                                     |
| ---------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **No special encounters spawning**                   | Telemetry provider not assigned or returning false.                    | Assign a provider in inspector or inject one via code.                                  |
| **HUD shows Pressure=0.00 / AvgHP=0.00**             | Your provider returns default values.                                  | Verify that `TryGetPressure` and `TryGetAveragePlayerHP` return `true` and set `value`. |
| **“Specials: (unscheduled)”**                        | All rules are ineligible (wrong step, cooldown, or telemetry missing). | Advance the Director step or reduce gating thresholds.                                  |
| **Specials spawn too often**                         | Thresholds too low or cooldowns too short.                             | Increase `minPressure`, `cooldownSeconds`, or rule caps.                                |
| **Rules never pass even with high telemetry values** | Provider not returning normalized (0–1) data.                          | Normalize your pressure and HP values.                                                  |
| **Force Roll Now does nothing**                      | Editor-only command not wired or manager not active.                   | Ensure you’ve called `Begin()` or re-enable the editor utility.                         |

***

### 5. Force Evaluation (Editor Utility)

In Play Mode, you can trigger an immediate check of all special rules:

**Context Menu → Force Specials Roll Now**

* This command bypasses normal cooldowns and eval timers.
* Use it to quickly test rule eligibility, thresholds, and anchor selection.
* Available only in Editor builds (`#if UNITY_EDITOR`).

***

### 6. Best Practices

| Goal                  | Recommendation                                                           |
| --------------------- | ------------------------------------------------------------------------ |
| **Stable values**     | Update telemetry in your game loop before the manager’s next evaluation. |
| **Consistent scale**  | Keep both Pressure and AvgHP between 0–1.                                |
| **Debug clarity**     | Enable the HUD and logs while tuning; disable for release.               |
| **Fallback behavior** | Remember: no telemetry = rule fail (safe default).                       |
| **Iterate safely**    | Use the BasicSample provider to verify setup before wiring real data.    |

***

### 7. Example Validation Flow

1. Start with `BasicSpecialsTelemetry` asset assigned.
2. Confirm rule thresholds (e.g., Min Pressure ≥ 0.8, Min Avg HP ≥ 0.5).
3. Enter Play Mode and adjust sliders:
   * At `pressure=0.9`, rule should pass.
   * Drop to `pressure=0.5`, rule should fail.
4. Replace with real provider (`GameLinkedTelemetry` or runtime injected version).
5. Confirm HUD values track gameplay data.
6. Test rule timing and cooldowns under real load.

***

### ✅ Summary

Telemetry integration is lightweight and fault-tolerant:

* The **Special Encounter Manager** polls telemetry every evaluation cycle.
* You can supply data through **ScriptableObject** or **runtime interface** providers.
* Missing telemetry never breaks the system — it simply prevents those rules from spawning.
* Use the **Diagnostics HUD** and **Force Roll Now** tool for fast iteration.

> **In short:**\
> If your specials aren’t spawning, start with telemetry — confirm values, scale them correctly, and watch them drive your encounter pacing.