Skip to content

🧪 Status Effects — Documentation Guide

🧭 Where should I start?

🔹 New to Status Effects?

Start with:

👉 System Overview (README + Mental Model)

This explains: - What the Status Effects system is - How the controller-driven lifecycle works - How statuses integrate potency, resistance, immunity, authority, and optional bridges - Typical setup and usage patterns

🔹 Want to know what you can safely depend on?

Read:

👉 PublicAPI/

This document defines: - The supported runtime surface - Stable controllers, interfaces, value types, and extension seams - Guaranteed behaviours - Explicitly unsupported usage

If something is not listed there, it is not supported — even if it appears public in code.

This is the contract.

🔹 Adding gameplay or extending the system?

Start with:

👉 Integration Surfaces/

This shows exactly where logic belongs: - effect implementations - definitions and authoring - potency, resistance, and immunity providers - time and authority seams - integration bridges and UI layers

Then use:

👉 FAQ/

The FAQ answers questions like: - Should I use definitions or build effects directly? - Why is my effect not ticking or expiring? - Where should stacking rules live? - Should I enable authority? - What should I avoid?

It focuses on decision-making, not API reference.

🧠 How these documents work together

Document Purpose
Overview Explains the system
Public API Defines what is supported
FAQ Guides correct usage choices
Integration Surfaces Shows where new logic should plug in
Mental Model Explains how to think about the system
Guarantees Matrix Defines behavioural contracts

Each document serves a specific purpose.
You do not need to read everything — start with what matches your task.

🛑 Important support note

RevFramework Status Effects is:

  • Controller-driven
  • Instance-based
  • Authority-aware
  • Integration-optional
  • UI-optional
  • Netcode-agnostic

Support is provided for:

  • Behaviour defined in PublicAPI
  • Usage patterns described in Overview, FAQ, and Integration Surfaces
  • Guarantees listed in the Guarantees Matrix

Support is not provided for:

  • Applying or mutating statuses outside StatusEffectController
  • Depending on undocumented controller internals
  • Reflecting into runtime internals
  • Encoding stacking or lifecycle ownership inside effects
  • Treating definitions as runtime behaviour containers

  • Teaching Panels
    Add debug or teachable panels to inspect status application, ticking, stacking, and expiry live

  • Samples
    See /Samples/StatusEffects/ for runnable examples

  • MkDocs site
    Mirrors this documentation for web browsing

🧠 System philosophy

Status Effects is:

  • A controller-owned lifecycle system (not free-form buff components)
  • A runtime instance model (effects are built, applied, ticked, refreshed, and removed)
  • A layered extension system (potency, resistance, immunity, authority, time)
  • A strict mutation-boundary design (StatusEffectController owns status truth)

Every public extension seam exists for a reason.
If something feels unclear, you're likely using the wrong layer.

✅ TL;DR

  • Want to understand Status Effects → Overview
  • Want to build safely → Public API
  • Want to choose correctly → FAQ
  • Want to extend cleanly → Integration Surfaces

If you stay within these boundaries, Status Effects will behave predictably and remain supportable.