RevFramework — Status Effects • FAQ¶

This FAQ answers decision questions about the Status Effects system.
It is not a feature list and does not repeat the README content.

Use this when you’re asking:

• “Am I using this correctly?”
• “Is this the right extension point?”
• “Why does this behave like this?”

If you're new to the system, start with the Mental Model page first.
The FAQ assumes you already understand the controller‑driven lifecycle of status effects.

Core Rule (Read This First)¶

How do I integrate Status Effects into my project?¶

Minimum setup:

1. Add StatusEffectController to any actor that should receive statuses
2. Apply effects via:
3. ApplyStatus(...), or
4. ApplyOrRefresh(...) (preferred)

That’s it.

Everything else — UI, Auras, Authority, Integration bridges — is optional.

Should I use ScriptableObject definitions or build effects directly?¶

Both are supported. Choose based on intent:

Definitions are data blueprints that build runtime effect instances.

They do not change runtime behaviour — they only configure it.

Why does my effect not tick or expire?¶

Almost always one of these:

If none of these apply, it may be a real issue.

Why doesn’t Status Effects replicate over the network?¶

Because it is not a netcode framework.

Status Effects:

• Applies logic locally
• Exposes authority hooks
• Leaves replication to your netcode

You must replicate:

• Active status IDs
• Remaining time
• Stack counts
• Context (if needed)

This keeps the system netcode‑agnostic by design.

Should I enable requireAuthority?¶

Only if you are doing multiplayer or deterministic simulation.

If enabled without a binder, everything no‑ops by design.

Is it safe to delete folders I don’t use?¶

Not inside the runtime assembly, no. Everything under Runtime/Systems/StatusEffects compiles into one assembly with no define gating inside it, so deleting a folder from it is an unconditional compile error — not a feature that switches off.

What optionality actually exists. Whole systems are optional — delete Runtime/Systems/StatusEffects entirely and the rest of RevFramework still compiles, because cross-system code is gated behind REV_*_PRESENT defines. Within a system, the assembly is the unit, not the folder.

Where should stacking rules live?¶

Always in the controller.

Do not:

• Encode stacking inside effects
• Track stacks manually in effects
• Query other effects from an effect

Use:

• StatusStackingRule
• SetStackCap(...)
• SetPerSourceStacks(...)

Why doesn’t potency affect my effect?¶

Only effects implementing IAdjustableMagnitude respond to potency changes.

Check:

• Does the effect implement IAdjustableMagnitude?
• Are you recomputing potency via the controller?
• Is a potency provider present on the target?

Potency is absolute, not compounding.

Why does my UI flicker when effects refresh?¶

Replace/Refresh stacking briefly removes and re‑adds effects.

The provided UI:

• Uses a destroy‑grace window
• Coalesces rapid refreshes
• Uses unscaled time for stability

If you write your own UI, replicate this behaviour.

Can I apply statuses without a StatusEffectController?¶

The system will warn (in editor) and safely no‑op.

Where should gameplay rules live?¶

If something feels ambiguous, it likely belongs in Core.

How do I create a custom status effect?¶

Create a class derived from TimedStatusEffect.

Steps:

1. Define a StatusId
2. Choose a StatusStackingRule
3. Implement behaviour in OnTick(...)
4. Optionally expose metadata via IStatusMetadata

Example:

public sealed class BleedStatus : TimedStatusEffect, IStatusMetadata
{
    public override StatusId Id => "bleed";
    public override StatusStackingRule Stacking => StatusStackingRule.Stack;

    protected override void OnTick(GameObject target, float dt)
    {
        // custom behaviour here
    }
}

Register in StatusRegistry if needed.

Can I extend this system safely?¶

Yes — that’s the point.

Safe extension points:

• New effects (TimedStatusEffect)
• New definitions
• New potency/resistance providers
• New sinks (movement, mana, stamina)
• Custom authority binders
• Custom math services

Unsafe changes:

• Modifying controller internals
• Adding logic to definitions
• Letting effects mutate global state

Before contacting support¶

Check:

1. Is requireAuthority enabled without a binder?
2. Does the target have a StatusEffectController?
3. Are you reusing effect instances?
4. Are you mutating effect state directly?
5. Are you expecting replication that doesn’t exist?

If it still looks wrong after that, it may be a real bug.

Final note¶

Status Effects is intentionally strict about ownership and responsibility.

If you work with the system boundaries, it becomes very hard to break.