Skip to content

Shields — Pools

Folder Overview

This folder contains shield value aggregators intended for UI, FX, and external gameplay systems.

These types do not absorb damage and are not shields in the IShield sense.

Purpose

Pools provide:

  • Aggregated shield values for UI and feedback
  • Safe multi-contributor tracking via tickets
  • Decoupled inputs for external systems

What Lives Here

ShieldPool (Ticketed)

Implements IShieldTicketPool.

API:

int ticket = pool.AddReturnTicket(amount);
pool.RemoveByTicket(ticket);
pool.ClearAll();

Behaviour:

  • Each AddReturnTicket creates an independent contribution
  • Returns a unique ticket ID
  • Removing a ticket removes only that contribution
  • Total equals the sum of active contributions

Notes:

  • AddReturnTicket(0) returns -1 (no ticket created)
  • Removing an unknown ticket is a no-op
  • Total is clamped to >= 0

Important Notes

Events

ShieldPool exposes:

  • Inspector event: onTotalChanged(int total)
  • C# event: event Action<int> TotalChanged

These fire when the aggregate total changes.

Typical uses:

  • UI shield bars
  • Feedback and FX scaling
  • Debug overlays

Behaviour

  • The ticket dictionary is the source of truth
  • The cached total exists for quick reads and inspector visibility
  • Totals are recomputed on enable to remain correct across pooling and reloads

Boundaries

Pools are not:

  • Damage absorbers (IShield)
  • Ordering or stacking systems
  • Networking or replication systems

Do not:

  • Treat ShieldPool as a shield
  • Expect it to reduce damage
  • Share ticket IDs across systems
  • Use it as a networking sync mechanism

Usage Guidance

Recommended pattern:

  1. Call AddReturnTicket(amount)
  2. Store the returned ticket ID
  3. On expiry, call RemoveByTicket(ticket)
  4. Do not mutate totals directly

This allows multiple systems to contribute safely.

  • Shields (Abstractions)
  • Shields (Builtin