Skip to content

RevFramework — Status Effects System

Overview

The Status module is a scene-scoped, authority-aware buff/debuff system for applying timed effects such as DOTs, HOTs, crowd control, and stat modifiers.

It is built for production — not prototypes — with clean interfaces, strict ownership rules, and full event transparency.

🧠 Core Principle

Status Effects are controller-managed runtime effect instances applied over time.

The StatusEffectController is the only authority that:

  • applies effects
  • updates effects
  • removes effects

If something modifies status state outside the controller, it is a bug.

Key design goals

  • Controller-centric: StatusEffectController owns all active effects and handles stacking, timing, and cleanup.
  • Interface-driven: Extensible via IStatusEffect, IStatusPotency, IStatusResistance, and IStatusImmunity.
  • Deterministic: Effects tick and expire based on a controlled time source.
  • Extensible: Add effects, bridges, or sinks without modifying core code.
  • Authority-ready: Works in single-player by default and supports multiplayer authority gating.
  • Integration-optional: Effects still function even when external systems are not present.

What's included

Category Purpose
StatusEffectController Runtime owner of all status state, lifecycle, stacking, and events
StatusEffectDefinitionBase ScriptableObject definitions for designer-authored effects
TimedStatusEffect Base class for time-driven runtime behaviour
StatusContext Source attribution (instigator, ability, item, etc.)
IStatusPotency / Resistance / Immunity Receiver-side scaling and filtering
IAdjustableMagnitude Enables live potency scaling
IStatusAuthority Authority gating for mutation and ticking
StatusUtility / Math Service Potency and duration calculation helpers
StatusFx Optional visual FX seam
StatusUseEvents Global telemetry events
UI Components Buff bar and icon system
Teaching Panels Interactive in-editor examples
Integration Bridges Clean adapters for Health, Shields, etc.

Hook-up summary

1️⃣ Add a controller

Attach StatusEffectController to any actor that should receive statuses.

This is required.

2️⃣ (Optional) Add modifiers

Attach:

  • IStatusPotency → scales magnitude
  • IStatusResistance → scales duration
  • IStatusImmunity → blocks effects

3️⃣ Create definitions (optional)

Use ScriptableObjects for designer-driven workflows.

Definitions only build effects — they do not run logic.

4️⃣ Apply effects

ctrl.ApplyStatus(new PoisonStatus(5f, 10f),
    StatusContext.FromAbility("firebolt"));

Or:

ctrl.ApplyStatus(poisonDef.BuildEffect(),
    StatusContext.FromItemUse(itemDef, slotIndex));

All application must go through the controller.

5️⃣ (Optional) Add UI

Use StatusBuffBar or your own UI.

UI observes state — it never controls it.

6️⃣ (Optional) Enable authority

Enable requireAuthority and provide an IStatusAuthority implementation.

When authority is denied:

  • effects do not apply
  • effects do not tick
  • effects do not mutate

🔗 Integrations

The system integrates with other modules but does not depend on them.

Examples:

Module Interaction
Health Damage, regen, shields
Movement Speed scaling
Cooldowns Haste effects
Combat Damage modifiers

If integrations are missing:

  • effects still apply
  • effects still tick
  • effects still expire
  • only the integration behaviour is skipped

🧩 Multiplayer Note

The system provides authority gating, not replication.

You must replicate:

  • active effects
  • timers
  • stacks

The system remains netcode-agnostic by design.

You get the rules — you implement the transport.

Extension points

You can safely extend the system by:

  • Creating new TimedStatusEffect implementations
  • Adding new provider components
  • Creating integration bridges
  • Implementing custom math services
  • Extending UI

Do not:

  • modify controller internals
  • add logic to definitions
  • bypass the controller

Typical usage

StatusUtility.Apply(target, new RegenStatus(4f, 8f));

Where to learn

  • MkDocs Site
  • Videos (Overview, Stacking, Potency, Authority)
  • In-Editor Teaching Panels

TL;DR

  • One controller owns all status state
  • Effects are runtime instances
  • Lifecycle is controller-driven
  • Potency = strength
  • Resistance = duration
  • Integrations are optional
  • Authority gates execution