Skip to content

✨ Status Effects System — Overview

A modular, deterministic buff / debuff / CC runtime pipeline for Unity.

The Status Effects system provides a predictable way to:

  • apply and manage effects
  • control stacking and lifecycle
  • scale potency and duration
  • support UI, integration, and multiplayer authority

It is modular, runtime-safe, and netcode-agnostic.

Important: This system does not define gameplay balance or rules. It provides a pipeline for executing them.

🧠 Mental Model

The system is built around a simple separation of concerns:

  • Effects → define behaviour
  • Controller → manages lifecycle and rules
  • Modifiers → influence incoming math
  • UI / Integration → reflect or extend behaviour

Effects describe what happens. The controller decides when and how it happens.

🧠 Usage Guidance

  1. Add StatusEffectController to a GameObject
  2. Create an effect (definition or direct instance)
  3. Apply it through the controller
ctrl.ApplyStatus(
    new PoisonStatus(5f, 10f),
    StatusContext.FromAbility("firebolt")
);

Or:

ctrl.ApplyOrRefresh(
    () => new PoisonStatus(5f, 10f),
    StatusContext.FromAbility("firebolt")
);

🧩 What Lives Here

Layer Responsibility Required
Core Lifecycle, stacking, authority, ticking ✔
Effects Behaviour implementations ❌
Definitions ScriptableObject authoring ❌
Abstractions Contracts and extension seams ❌
Authority Mutation gating ❌
UI Visualisation ❌
Integration External system bridges ❌
Timing Time source implementations ❌
UnityIntegration Optimised math resolution ❌

Only the controller is required.

📦 Folder Overview

  • Core → runtime pipeline (controller, registry, lifecycle)

  • Effects

  • Definitions → authoring assets

  • Implementations → runtime behaviour
  • Abstractions → contracts, ids, metadata, modifiers
  • Authority → mutation gating
  • Auras → optional area-based modifiers
  • Integration → external system hooks (Health, etc.)
  • System → shared helpers and global hooks
  • Timing → time source implementations
  • UnityIntegration → component-based math optimisation
  • UI → optional presentation layer

🧠 Usage Guidance

Controller owns lifecycle

StatusEffectController is the single source of truth.

It controls:

  • apply / refresh / remove
  • stacking rules
  • ticking and expiry
  • authority checks

Effects are behaviour only

Effects:

  • respond to lifecycle calls
  • may hold internal state
  • do not control system rules

Modifiers influence, not control

Receiver-side modifiers (IStatusPotency, IStatusResistance, IStatusImmunity):

  • adjust incoming effects
  • do not mutate effect state directly

Time is injectable

Status ticking is driven by ITimeSource, not Unity globals.

Supports:

  • slow motion
  • pause control
  • per-entity time behaviour

Authority is optional

When enabled, mutation and ticking are gated via IStatusAuthority.

⚠️ Important Notes

  • Effects must be new instances per application
  • requireAuthority = true without a binder results in no-op behaviour
  • UI reflects state — it does not drive gameplay
  • Definitions must not contain runtime logic
  • Some integrations are optional and may no-op safely

🚫 Not for Production Use

  • UI layer is optional and intended for presentation only
  • Sample integrations and helpers are not required for runtime use
  • Definitions are authoring assets and should not contain gameplay logic
  • Core — runtime lifecycle and controller
  • Abstractions — contracts and extension seams
  • Effects — definitions and implementations
  • Authority — multiplayer gating
  • Auras — area-based modifiers
  • Integration — external system hooks
  • UI — visual components
  • Timing — time source system