RevFramework — Status Effects • Core¶

Core runtime types for the Status Effects system.

This folder contains the central runtime pieces that own status lifecycle execution: application, ticking, refresh handling, stack policy enforcement, removal, expiry, and runtime queries.

Purpose¶

This is the runtime heart of the Status Effects system.

It contains the types that:

• track active status instances
• execute effect lifecycle over time
• enforce stacking and removal rules
• preserve source context
• coordinate runtime status mutation

Usage Guidance¶

The Status system separates responsibilities across folders:

• contracts → Abstractions
• behaviour → Effects
• authority → Authority
• time → Timing

Core brings these pieces together into a runtime pipeline.

• effects describe behaviour
• abstractions define contracts
• core executes lifecycle

What Lives Here¶

StatusEffectController¶

Main runtime host.

Handles:

• applying effects
• ticking effects
• refresh / replace / stack decisions
• immunity checks
• context tracking
• dispel / cleanse / clear logic
• runtime events
• authority-gated mutation

StatusRegistry¶

Id-based builder registry for constructing effects.

Used when callers want to resolve effects by id instead of constructing them directly.

TimedStatusEffect¶

Base implementation for time-based effects.

Provides:

• duration storage
• remaining-time tracking
• default ticking
• refresh / extend support
• optional FX hooks

UtilityFallbackMath¶

Fallback math adapter used when no external IStatusMathService is resolved.

Folder Overview¶

• Runtime controller and lifecycle execution
• Id-based effect construction support
• Base implementations for timed effects
• Fallback math support

Important Notes¶

• Core executes lifecycle but does not define all system behaviour
• Effects do not control stacking, authority, or time progression
• Authority and time are resolved through external seams
• Registry builders should return new effect instances

Usage Guidance¶

Controller owns lifecycle¶

StatusEffectController is the runtime source of truth.

It controls:

• application, refresh, and removal
• stacking behaviour
• ticking and expiry
• authority-gated mutation

Stack policy support¶

The controller supports:

• replace
• refresh
• stack
• per-id stack limits
• optional per-source matching

Authority-gated runtime¶

When authority is required, ticking and mutation only proceed if authority resolves and allows it.

What the gate does not cover. SetStackCap, ClearStackCap, SetPerSourceStacks, SetTimeMode and RefreshAuthority are configuration rather than effect state, and none of them is gated: they change how the next gated apply stacks, or how gated ticks measure time, or which authority is asked. Effect state is only ever changed through the gated mutators and the gated tick.

Time-driven ticking¶

Ticking uses StatusTimeMode with an ITimeSource.

Potency and duration recompute¶

The controller can recompute:

• potency for effects implementing IAdjustableMagnitude
• duration for tracked effects based on current inputs

Diagnostics¶

Common pitfalls:

• requireAuthority = true with no authority results in no-op behaviour
• TimedStatusEffect.Apply() resets duration
• Only effects implementing IAdjustableMagnitude respond to recompute
• RecomputeDurationsForAll() updates existing effects in place

Not for Production Use¶

Related Documentation¶

• Abstractions → contracts and shared types
• Effects → concrete behaviour implementations
• Authority → mutation gating
• Timing → time sources
• Auras → optional area modifiers
• UI → presentation