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:

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.

PreviousTelemetry Providers - Samples & PatternsNextComponents

Last updated