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.