🧪 Status Effects — System Guarantees Matrix¶
This page defines the behavioural contract of the Status Effects system.
No marketing. No implication. Just guarantees — and explicit non‑guarantees.
🔎 Quick Navigation¶
- Core Controller
- Effect Lifecycle
- Stacking
- Potency / Resistance
- Authority
- Time / Ticking
- Integrations
- UI
- Built‑in Effects
- Determinism
- Public API
- Non‑Guarantees
- Final Summary
1️⃣ Core Controller¶
StatusEffectController¶
| Aspect | Guarantee |
|---|---|
| Controller owns status truth | ✔ Yes |
| Effects self-register with controller | ❌ Never |
| External mutation of active effects list | ❌ Not supported |
| Multiple controllers per scene supported | ✔ Yes |
| Controller required for runtime behaviour | ✔ Yes |
| UI required | ❌ No |
| Inspector configuration required | ❌ No |
Guarantee:
The controller is the only supported mutation authority.
All application, refresh, and removal of effects must go through StatusEffectController.
Direct mutation of effect instances is unsupported.
2️⃣ Effect Lifecycle¶
| Aspect | Guarantee |
|---|---|
| Effects applied via controller | ✔ Yes |
| Effects tick themselves | ❌ Never |
| Controller drives ticking | ✔ Yes |
| Effects may refresh duration | ✔ Yes |
| Controller handles expiry | ✔ Yes |
| Effects removed directly outside controller | ❌ Not supported |
3️⃣ Stacking¶
| Aspect | Guarantee |
|---|---|
| Stacking rule defined per effect | ✔ Yes |
| Replace behaviour supported | ✔ Yes |
| Refresh behaviour supported | ✔ Yes |
| Stack behaviour supported | ✔ Yes |
| Per‑source stacking supported | ✔ Yes |
| Stack caps configurable | ✔ Yes |
| Stacking implemented inside effects | ❌ Not supported |
4️⃣ Potency / Resistance¶
| Aspect | Guarantee |
|---|---|
| Potency scaling supported | ✔ Yes |
| Duration scaling supported | ✔ Yes |
| Potency applied via providers | ✔ Yes |
| Resistance applied via providers | ✔ Yes |
| Potency compounding across recalculations | ❌ Never |
| Effects required to support potency | ❌ Optional |
Potency is recomputed from current providers each time it is evaluated.
It is not accumulated or compounded across recalculations.
5️⃣ Authority¶
| Aspect | Guarantee |
|---|---|
| Authority gating supported | ✔ Yes |
| Authority binder optional | ✔ Yes |
| Effects tick without authority | ❌ Not allowed |
| Effects mutate without authority | ❌ Not allowed |
| Authority affects read queries | ❌ No |
| Multiplayer replication | ❌ Not provided |
6️⃣ Time / Ticking¶
| Aspect | Guarantee |
|---|---|
| Controller-driven ticking | ✔ Yes |
| Scaled time supported | ✔ Yes |
| Unscaled time supported | ✔ Yes |
| Paused time supported | ✔ Yes |
| Custom time source supported | ✔ Yes |
| Direct use of UnityEngine.Time required | ❌ No |
7️⃣ Integrations¶
| Aspect | Guarantee |
|---|---|
| Core system independent of other modules | ✔ Yes |
| Health integration optional | ✔ Yes |
| Movement integration optional | ✔ Yes |
| Integration bridges required | ❌ No |
| Core depends on integrations | ❌ Never |
| Effects function without integrations present | ✔ Yes |
8️⃣ UI¶
| Aspect | Guarantee |
|---|---|
| UI required for system operation | ❌ No |
| Built-in buff bar available | ✔ Yes |
| Custom UI supported | ✔ Yes |
| UI allowed to mutate status state | ❌ Never |
UI must observe state via events or queries.
UI must never drive or mutate status logic.
9️⃣ Built‑in Effects¶
| Aspect | Guarantee |
|---|---|
| Built-in effect examples included | ✔ Yes |
| Built-in effects required | ❌ No |
| Custom effects supported | ✔ Yes |
| Definitions optional | ✔ Yes |
🔟 Determinism¶
| Aspect | Guarantee |
|---|---|
| Controller lifecycle deterministic | ✔ Yes |
| Behaviour deterministic given stable inputs | ✔ Yes |
| Network determinism provided | ❌ Not guaranteed |
| Cross-system determinism guaranteed | ❌ Not guaranteed |
Determinism assumes:
- consistent time input
- consistent provider composition
- consistent execution order from the calling environment
11️⃣ Public API¶
| Aspect | Guarantee |
|---|---|
| Stable controller API surface | ✔ Yes |
| Stable extension interfaces | ✔ Yes |
| Internal controller helpers public | ❌ No |
| Integration bridges public | Optional |
🚨 Non‑Guarantees¶
Status Effects does not guarantee:
- Multiplayer replication
- Network prediction or reconciliation
- Atomic mutation across external gameplay systems
- Deterministic behaviour across machines without external synchronization
- Safe mutation of status state outside
StatusEffectController - Deterministic ordering of external provider discovery
- Automatic UI updates without subscribing to events
- Ordering of Active effects list
🎯 Final Summary¶
| Layer | Strong Guarantee | Best Effort | Not Guaranteed |
|---|---|---|---|
| Controller ownership of effects | ✔ | ||
| Mutation through controller only | ✔ | ||
| Deterministic lifecycle execution | ✔ | ||
| Potency / resistance scaling | ✔ | ||
| Built-in UI helpers | ✔ | ||
| Multiplayer replication | ❌ | ||
| Cross-system atomic behaviour | ❌ |
System Philosophy¶
Status Effects is:
- Controller‑driven
- Instance‑based
- Extension‑oriented
- Authority‑aware
- Explicit about guarantees