# API Reference

AfterPrime Systems | Version 1.0 | Module: APStatusFXRuntime

# Contents

Class	Description
UAP_StatusFXSuiteComponent	Primary component — add to any replicated actor
UAP_StatusEffectDefinition	Data asset defining a status effect template
UAP_StatusFXBlueprintLibrary	Static Blueprint helper functions
IAP_StatusFXSuiteTarget	Interface for standardized component lookup
UAP_StatusFXSettings	Project-wide plugin settings
UAP_StackingResolver	Override for custom stacking logic
Enums	`EAP_DurationType`, `EAP_StackingPolicy`, `EAP_EffectRemovalReason`
Structs	Snapshot, ApplicationParams, InteractionRule
Delegates	All `BlueprintAssignable` delegate declarations

# 1. UAP_StatusFXSuiteComponent

Header: Components/AP_StatusFXSuiteComponent.h Parent: UActorComponent Blueprint Category: AP > StatusFX

The primary component. Add to any replicated actor to enable status effect functionality.

Authority Model

All mutation methods (Apply, Remove, Refresh, Immunity) are server-authoritative — call them on the server or via Server RPCs. All query methods work on both server and client via replicated state.

# Application Methods

Server Only

# `ApplyEffect`

AP_StatusFXSuiteComponent.h
bool ApplyEffect(
    UAP_StatusEffectDefinition* Definition,
    AActor* Instigator = nullptr,
    float DurationOverride = -1.0f,
    int32 InitialStacks = 1
)

Apply a status effect using a definition asset. Handles stacking, immunity, and interaction rules internally.

Parameter	Description
`Definition`	The effect definition to apply. Must not be null.
`Instigator`	The actor responsible for this application (optional).
`DurationOverride`	Override the definition's `BaseDuration`. `-1.0` uses the default.
`InitialStacks`	Starting stack count. Only relevant for stackable policies.

Returns: true if the effect was successfully applied (not blocked by immunity or interactions).

# `ApplyEffectAdvanced`

bool ApplyEffectAdvanced(
    UAP_StatusEffectDefinition* Definition,
    const FAP_EffectApplicationParams& Params
)

Apply an effect with full control via a params struct.

Parameter	Description
`Definition`	The effect definition.
`Params`	Application parameters including `Instigator`, `DurationOverride`, `InitialStacks`, and `ContextTag`.

Returns: true if applied successfully.

# Removal Methods

Server Only

# `RemoveEffect`

int32 RemoveEffect(FGameplayTag EffectTag)

Remove all instances of a specific effect by tag. Returns: Number of effect instances removed.

# `RemoveEffectStacks`

int32 RemoveEffectStacks(FGameplayTag EffectTag, int32 StacksToRemove)

Remove a specific number of stacks. If StacksToRemove >= current stacks, removes the effect entirely.

Returns: Number of stacks actually removed.

# `RemoveEffectsByQuery`

int32 RemoveEffectsByQuery(FGameplayTagQuery TagQuery)

Remove all effects matching a Gameplay Tag query. Useful for batch operations like "remove all debuffs."

Returns: Number of effects removed.

# `RemoveAllEffects`

int32 RemoveAllEffects()

Remove every active effect from this component. Returns: Number of effects removed.

# Control Methods

Server Only

# `RefreshEffect`

bool RefreshEffect(FGameplayTag EffectTag, float NewDuration = -1.0f)

Reset the duration timer on an active effect. Optionally set a new duration.

Parameter	Description
`EffectTag`	The effect to refresh.
`NewDuration`	New duration in seconds. `-1.0` uses the original `BaseDuration`.

Returns: true if the effect was found and refreshed.

# Immunity Methods

Server Only

# `GrantImmunity`

void GrantImmunity(FGameplayTag EffectTag, float Duration = -1.0f)

Grant temporary immunity to a specific effect tag. While immune, any application of that effect is blocked.

Parameter	Description
`EffectTag`	The tag to become immune to.
`Duration`	Immunity duration in seconds. `-1.0` = permanent until revoked.

# `RevokeImmunity`

void RevokeImmunity(FGameplayTag EffectTag)

Immediately remove immunity for a specific effect tag.

# Query Methods

Server + Client

All query methods are BlueprintPure — they read replicated state and have no side effects.

# `HasEffect`

bool HasEffect(FGameplayTag EffectTag) const

Check if an effect with the given tag is currently active.

# `HasEffectMatchingQuery`

bool HasEffectMatchingQuery(FGameplayTagQuery TagQuery) const

Check if any active effect matches the given tag query.

# `IsImmuneToEffect`

bool IsImmuneToEffect(FGameplayTag EffectTag) const

Check if the target is currently immune to a specific effect tag.

# `GetStackCount`

int32 GetStackCount(FGameplayTag EffectTag) const

Get the current stack count for an active effect. Returns 0 if the effect is not active.

# `GetActiveEffectCount`

int32 GetActiveEffectCount() const

Get the total number of active effect instances.

# `GetRemainingDuration`

float GetRemainingDuration(FGameplayTag EffectTag) const

Get the remaining duration in seconds. Returns -1.0 for infinite effects. Returns 0.0 if not found.

# `GetElapsedTime`

float GetElapsedTime(FGameplayTag EffectTag) const

Get how long an effect has been active in seconds.

# `GetRemainingRatio`

float GetRemainingRatio(FGameplayTag EffectTag) const

Get the remaining duration as a 0.0–1.0 ratio — useful for progress bars. Returns 1.0 for infinite effects.

# Snapshot Methods

Server + Client

# `GetEffectSnapshot`

bool GetEffectSnapshot(FGameplayTag EffectTag, FAP_StatusEffectSnapshot& OutSnapshot) const

Get a full snapshot of an active effect's state. Returns: true if the effect was found and the snapshot is valid.

# `GetAllActiveEffectSnapshots`

void GetAllActiveEffectSnapshots(TArray<FAP_StatusEffectSnapshot>& OutSnapshots) const

Get snapshots of all currently active effects.

# `GetEffectSnapshotsByQuery`

void GetEffectSnapshotsByQuery(
    FGameplayTagQuery TagQuery,
    TArray<FAP_StatusEffectSnapshot>& OutSnapshots
) const

Get snapshots of all active effects matching a tag query.

# `GetActiveEffectTags`

FGameplayTagContainer GetActiveEffectTags() const

Get a container of all active effect tags. Useful for batch tag matching.

# Delegates

Delegate	Signature	Fires On
`OnEffectApplied`	`(FGameplayTag, FAP_StatusEffectSnapshot)`	Server + Client
`OnEffectRemoved`	`(FGameplayTag, EAP_EffectRemovalReason)`	Server + Client
`OnEffectRefreshed`	`(FGameplayTag)`	Server + Client
`OnEffectStackChanged`	`(FGameplayTag)`	Server only
`OnEffectTick`	`(FGameplayTag, FAP_StatusEffectSnapshot)`	Server only
`OnEffectExpired`	`(FGameplayTag)`	Server only

Client Event Notes

OnEffectRemoved on clients always reports RemovedManually — the specific removal reason is a server-side value not currently replicated (planned for v1.1).

Stack changes on clients fire OnEffectRefreshed instead of OnEffectStackChanged due to FastArray change detection. Bind both delegates for correct stack display on all machines.

# Extensibility

# `CanApplyEffect` (Virtual)

C++ Override

virtual bool CanApplyEffect(
    const UAP_StatusEffectDefinition* Definition,
    const FAP_EffectApplicationParams& Params
) const

Override in C++ subclasses to add custom application logic (e.g., check gameplay conditions, resource costs). Return false to block application.

# 2. UAP_StatusEffectDefinition

Header: Data/AP_StatusEffectDefinition.h Parent: UDataAsset

A data asset that defines a status effect template. Create via Right-click → Miscellaneous → Data Asset → AP_StatusEffectDefinition.

# Identity

Property	Type	Description
`EffectTag`	`FGameplayTag`	Unique Gameplay Tag identifying this effect type.
`DisplayName`	`FText`	Human-readable name for UI.
`Description`	`FText`	Description text for tooltips.
`Icon`	`UTexture2D*`	Icon texture for UI display.

# Duration

Property	Type	Default	Description
`DurationType`	`EAP_DurationType`	`Timed`	`Timed`, `Infinite`, or `Instant`.
`BaseDuration`	`float`	`5.0`	Duration in seconds (`Timed` only).

# Ticking

Property	Type	Default	Description
`TickInterval`	`float`	`0.0`	Seconds between `OnEffectTick` fires. `0` = no ticking.

# Stacking

Property	Type	Default	Description
`StackingPolicy`	`EAP_StackingPolicy`	`None`	How reapplication is handled.
`MaxStacks`	`int32`	`0`	Maximum stack count. `0` = unlimited.
`CustomStackingResolverClass`	`TSubclassOf<UAP_StackingResolver>`	`None`	Required when policy is `Custom`.

# Interactions

Property	Type	Description
`RemovesEffectsWithTags`	`FGameplayTagContainer`	Active effects with these tags are removed when this effect is applied.
`BlockedByEffectsWithTags`	`FGameplayTagContainer`	This effect cannot be applied while any effect with these tags is active.

# Immunity

Property	Type	Default	Description
`bGrantImmunityOnExpire`	`bool`	`false`	Grant immunity to this effect's tag after it expires.
`ImmunityDuration`	`float`	`3.0`	Duration of post-expire immunity.

# 3. UAP_StatusFXBlueprintLibrary

Header: Libraries/AP_StatusFXBlueprintLibrary.h

Static helper functions available in any Blueprint graph under AP > StatusFX > Helpers.

# `ApplyEffectToActor`

static bool ApplyEffectToActor(
    AActor* TargetActor,
    UAP_StatusEffectDefinition* Definition,
    AActor* Instigator = nullptr,
    float DurationOverride = -1.0f
)

Find the StatusFX component on the target actor (via interface or component search) and apply the effect. DefaultToSelf = "TargetActor".

# `RemoveEffectsFromActorByQuery`

static int32 RemoveEffectsFromActorByQuery(
    AActor* TargetActor,
    FGameplayTagQuery TagQuery
)

Remove all matching effects from an actor.

# `ActorHasEffect`

static bool ActorHasEffect(
    const AActor* TargetActor,
    FGameplayTag EffectTag
)

Check if an actor has a specific active effect.

# `GetSortedEffectSnapshots`

static bool GetSortedEffectSnapshots(
    const AActor* TargetActor,
    TArray<FAP_StatusEffectSnapshot>& OutSnapshots
)

Get all active effect snapshots from an actor, sorted by remaining time.

# `FormatEffectDuration`

static FString FormatEffectDuration(
    const FAP_StatusEffectSnapshot& Snapshot
)

Format a snapshot's remaining duration as a display string (e.g., "12.5s" or "∞").

# 4. IAP_StatusFXSuiteTarget

Header: Interfaces/AP_StatusFXSuiteTarget.h

Optional interface for standardized component lookup. Implement on actors that have a StatusFX component.

# `GetStatusEffectComponent`

UAP_StatusFXSuiteComponent* GetStatusEffectComponent() const

Return the StatusFX component on this actor. Implement in Blueprint by returning the component reference.

# 5. UAP_StatusFXSettings

Location: Project Settings → Plugins → AP StatusFX Suite

Property	Type	Default	Description
`InteractionRulesDataTable`	`TSoftObjectPtr<UDataTable>`	`None`	DataTable of `FAP_EffectInteractionRule` rows for complex interactions with immunity grants.
`GlobalMaxIndependentStacks`	`int32`	`50`	Safety cap for Independent stacking. `0` = per-definition only.
`bEnableReplicationLogging`	`bool`	`false`	Enable verbose replication logging in Development builds.

Static Access
const UAP_StatusFXSettings* Settings = UAP_StatusFXSettings::Get();

# 6. UAP_StackingResolver

Header: Stacking/AP_StackingResolver.h Specifiers: Abstract, Blueprintable, EditInlineNew, DefaultToInstanced

Override to implement custom stacking logic. Assign the subclass to a definition's CustomStackingResolverClass when using the Custom stacking policy.

# `ResolveStacking`

void ResolveStacking(
    UPARAM(ref) FAP_StatusEffectSnapshot& ExistingSnapshot,
    const FAP_EffectApplicationParams& NewParams,
    bool& OutShouldApply
)

Called when an effect with Custom stacking is applied and a matching effect already exists.

Parameter	Description
`ExistingSnapshot`	The current effect state (mutable — modify stack count, etc.).
`NewParams`	The incoming application parameters.
`OutShouldApply`	Set to `true` to create a new independent instance, `false` to modify the existing one.

# 7. Enums

# EAP_DurationType

Value	Description
`Timed`	Effect expires after `BaseDuration` seconds.
`Infinite`	Effect lasts until manually removed.
`Instant`	Effect fires once (`OnEffectApplied`) with no ongoing state.

# EAP_StackingPolicy

Value	Description
`None`	Reapplication refreshes the duration timer. Stack count stays at 1.
`StackDuration`	Each application adds its duration to the remaining time.
`StackIntensity`	Each application adds a stack (up to MaxStacks). Duration is shared.
`Independent`	Each application creates a separate tracked instance.
`Custom`	Delegates to a `UAP_StackingResolver` subclass.

# EAP_EffectRemovalReason

Value	Description
`Expired`	Duration reached zero.
`RemovedManually`	Removed via `RemoveEffect` or `RemoveAllEffects`.
`Interaction`	Removed by another effect's interaction rule.
`Immunity`	Application was blocked by immunity.

# 8. Structs

# FAP_StatusEffectSnapshot

Read-only snapshot of an active effect's state. Provided by delegates and query methods.

Field	Type	Description
`EffectTag`	`FGameplayTag`	The effect's identifying tag.
`InstanceId`	`int32`	Unique instance identifier.
`DefinitionPath`	`FSoftObjectPath`	Soft path to the source definition asset.
`StackCount`	`int32`	Current number of stacks.
`RemainingDuration`	`float`	Seconds remaining. `-1.0` for infinite.
`TotalDuration`	`float`	Original duration from definition.
`ServerTimeApplied`	`float`	Server world time when applied.
`Instigator`	`AActor*`	The actor that applied this effect.
`ContextTag`	`FGameplayTag`	Optional context tag for application metadata.
`bIsTimed`	`bool`	Whether the effect has a finite duration.
`bIsTicking`	`bool`	Whether the effect fires periodic ticks.

# FAP_EffectApplicationParams

Optional parameters for ApplyEffectAdvanced.

Field	Type	Default	Description
`Instigator`	`AActor*`	`nullptr`	The applying actor.
`DurationOverride`	`float`	`-1.0`	Override duration. `-1.0` = use definition default.
`InitialStacks`	`int32`	`1`	Starting stack count.
`ContextTag`	`FGameplayTag`	`None`	Arbitrary metadata tag.

# FAP_EffectInteractionRule (DataTable Row)

Field	Type	Description
`SourceTag`	`FGameplayTag`	The effect being applied that triggers this rule.
`TargetTagsToRemove`	`FGameplayTagContainer`	Effect tags to remove when `SourceTag` is applied.
`bGrantImmunityToRemoved`	`bool`	Whether to grant temporary immunity to removed tags.
`ImmunityDuration`	`float`	Duration of immunity granted (if enabled).

# 9. Delegates

All delegates are BlueprintAssignable (DYNAMIC_MULTICAST_DELEGATE) and appear as bindable events in Blueprint.

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(
    FAP_OnEffectApplied,
    FGameplayTag, EffectTag,
    FAP_StatusEffectSnapshot, Snapshot
);

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(
    FAP_OnEffectRemoved,
    FGameplayTag, EffectTag,
    EAP_EffectRemovalReason, Reason
);

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FAP_OnEffectRefreshed,
    FGameplayTag, EffectTag
);

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FAP_OnEffectStackChanged,
    FGameplayTag, EffectTag
);

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(
    FAP_OnEffectTick,
    FGameplayTag, EffectTag,
    FAP_StatusEffectSnapshot, Snapshot
);

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FAP_OnEffectExpired,
    FGameplayTag, EffectTag
);

AfterPrime Systems — Building the Gameplay Foundation

# API Reference

# Contents

# 1. UAP_StatusFXSuiteComponent

Authority Model

# Application Methods

# ApplyEffect

# ApplyEffectAdvanced

# Removal Methods

# RemoveEffect

# RemoveEffectStacks

# RemoveEffectsByQuery

# RemoveAllEffects

# Control Methods

# RefreshEffect

# Immunity Methods

# GrantImmunity

# RevokeImmunity

# Query Methods

# HasEffect

# HasEffectMatchingQuery

# IsImmuneToEffect

# GetStackCount

# GetActiveEffectCount

# GetRemainingDuration

# GetElapsedTime

# GetRemainingRatio

# Snapshot Methods

# GetEffectSnapshot

# GetAllActiveEffectSnapshots

# GetEffectSnapshotsByQuery

# GetActiveEffectTags

# Delegates

Client Event Notes

# Extensibility

# CanApplyEffect (Virtual)

# 2. UAP_StatusEffectDefinition

# Identity

# Duration

# Ticking

# Stacking

# Interactions

# Immunity

# 3. UAP_StatusFXBlueprintLibrary

# ApplyEffectToActor

# RemoveEffectsFromActorByQuery

# ActorHasEffect

# GetSortedEffectSnapshots

# FormatEffectDuration

# 4. IAP_StatusFXSuiteTarget

# GetStatusEffectComponent

# 5. UAP_StatusFXSettings

# 6. UAP_StackingResolver

# ResolveStacking

# 7. Enums

# EAP_DurationType

# EAP_StackingPolicy

# EAP_EffectRemovalReason

# 8. Structs

# FAP_StatusEffectSnapshot

# FAP_EffectApplicationParams

# FAP_EffectInteractionRule (DataTable Row)

# 9. Delegates

# `ApplyEffect`

# `ApplyEffectAdvanced`

# `RemoveEffect`

# `RemoveEffectStacks`

# `RemoveEffectsByQuery`

# `RemoveAllEffects`

# `RefreshEffect`

# `GrantImmunity`

# `RevokeImmunity`

# `HasEffect`

# `HasEffectMatchingQuery`

# `IsImmuneToEffect`

# `GetStackCount`

# `GetActiveEffectCount`

# `GetRemainingDuration`

# `GetElapsedTime`

# `GetRemainingRatio`

# `GetEffectSnapshot`

# `GetAllActiveEffectSnapshots`

# `GetEffectSnapshotsByQuery`

# `GetActiveEffectTags`

# `CanApplyEffect` (Virtual)

# `ApplyEffectToActor`

# `RemoveEffectsFromActorByQuery`

# `ActorHasEffect`

# `GetSortedEffectSnapshots`

# `FormatEffectDuration`

# `GetStatusEffectComponent`

# `ResolveStacking`