Skip to content

🧪 Health — Diagnostics (Performance Smoke)

This folder contains diagnostic utilities for the Health system.

These are developer-facing tools, not gameplay systems.

📦 What This Folder Is

Diagnostics are:

  • Debug / profiling helpers
  • Stress or sanity-check scripts
  • Tools for investigating behaviour (performance, allocations, flow)

Diagnostics are NOT:

  • Part of the supported runtime API
  • Required for any system to function
  • Production-ready gameplay code
  • Benchmarks you should treat as scientific truth

⚙️ Included Tools

HealthPerfSmoke

A brutal, no-frills stress harness for the Health system.

It:

  • Spawns a large number of HealthSystem instances
  • Repeatedly calls ApplyDamage(...)
  • Logs rough timing and allocation deltas

  • Lets you hammer either:

  • a single instance (hot-path focus)

  • or many instances (broader load)

HealthRulePerfSmoke

A rule-chain diagnostics tool used to measure how cost scales with increasing rule count.

It:

  • Spawns buckets of targets with 0 → N rules attached
  • Runs both PreviewDamage and ApplyDamage

  • Measures:

  • total time

  • per-call cost (μs)
  • allocation deltas

  • Lets you compare:

  • no rules vs many rules

  • preview vs apply
  • spread vs single-target load

🧠 What These Are Actually Useful For

Use these to:

  • sanity check performance after changes
  • confirm no GC allocations in hot paths
  • measure relative cost changes (before vs after)
  • understand where cost actually comes from
  • stress the system without building a full game

🔍 What We’ve Proven (From These Tests)

From HealthRulePerfSmoke:

  • Rule-chain depth (0 → 20 rules) has minimal overhead
  • Core cost sits in the HealthSystem pipeline, not empty rule traversal
  • PreviewDamage is extremely cheap (~sub-microsecond per call)
  • ApplyDamage is stable and predictable (~~5 μs per call range)
  • 0 allocations across all tests

👉 Translation:

The framework itself is not doing stupid shit.

❗ Where Cost Actually Comes From (Real Talk)

If your game is slow, it’s usually NOT this system.

It’s:

  • ❌ Too many rules (design issue)
  • ❌ Expensive logic inside custom rules
  • ❌ Per-frame UI updates (biggest offender)
  • ❌ Bad usage patterns (spam, polling, unnecessary calls)

👉 These diagnostics help prove that.

❌ What This Is NOT

Let’s be crystal clear:

  • ❌ Not a benchmark
  • ❌ Not representative of real gameplay
  • ❌ Not proof your game will perform well
  • ❌ Not comparable across different projects or hardware

If you treat this like a benchmark, you’re lying to yourself.

🕹️ How to Use

  1. Create an empty scene
  2. Add a diagnostics script (HealthPerfSmoke or HealthRulePerfSmoke)
  3. Press Play
  4. Open the Profiler (CPU + Timeline + GC)

  5. Adjust:

  6. instance count

  7. calls per burst
  8. rule counts (rule test only)
  9. spread vs single target
  10. burst mode

Watch for:

  • CPU spikes
  • GC allocations
  • frame time stability

⚠️ Practical Advice

  • Start small before going stupid high
  • Use BurstOncePerSecond for readable profiling
  • Always test in isolation first
  • Then test inside your real game

👉 If it’s fast here but slow in your game:

your game is the problem — not the system

🧩 Support Boundary

These scripts:

  • may change or be removed at any time
  • are not covered by compatibility guarantees
  • are provided "as-is" for investigation purposes

✅ Key Takeaway

These are smoke tests, not benchmarks.

They tell you if something is obviously wrong.

They do NOT tell you everything is right.

💬 Final Reality Check

If you can hammer:

  • tens of thousands of calls
  • across hundreds of instances
  • with multiple rules
  • at zero allocations

…and it still behaves?

👉 The core system is solid.

Anything that breaks after that is on usage — not the framework.