Docs
Powered by

# API - Reference

AfterPrime Systems | Version 1.0
Module: APStatusFXRuntime

# Table of Contents

  1. UAP_StatusFXSuiteComponent
  2. UAP_StatusEffectDefinition
  3. UAP_StatusFXBlueprintLibrary
  4. IAP_StatusFXSuiteTarget
  5. UAP_StatusFXSettings
  6. UAP_StackingResolver
  7. Enums
  8. Structs
  9. Delegates

# 1. UAP_StatusFXSuiteComponent

Header: Components/AP_StatusFXSuiteComponent.h
Parent: UActorComponent
Display Name: "AP StatusFX Suite"
Class Group: AfterPrime

The primary component. Add to any replicated actor to enable status effect functionality. All mutation methods are server-authoritative. All query methods work on both server and client.

# Application Methods (Server Only)

# ApplyEffect 

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.

Parameters:

  • 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).

Blueprint Category: AP > StatusFX > Application

# ApplyEffectAdvanced 

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

Apply an effect with full control via a params struct.

Parameters:

  • Definition — The effect definition.
  • Params — Application parameters including Instigator, DurationOverride, InitialStacks, and ContextTag.

Returns: true if applied successfully.

Blueprint Category: AP > StatusFX > Application

# Removal Methods (Server Only)

# RemoveEffect 

int32 RemoveEffect(FGameplayTag EffectTag)

Remove all instances of a specific effect by tag.

Returns: Number of effect instances removed.

Blueprint Category: AP > StatusFX > Removal

# RemoveEffectStacks 

int32 RemoveEffectStacks(FGameplayTag EffectTag, int32 StacksToRemove)

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

Returns: Number of stacks actually removed.

Blueprint Category: AP > StatusFX > Removal

# 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.

Blueprint Category: AP > StatusFX > Removal

# RemoveAllEffects 

int32 RemoveAllEffects()

Remove every active effect from this component.

Returns: Number of effects removed.

Blueprint Category: AP > StatusFX > Removal

# 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.

Parameters:

  • 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.

Blueprint Category: AP > StatusFX > Control

# 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.

Parameters:

  • EffectTag — The tag to become immune to.
  • Duration — Immunity duration in seconds. -1.0 = permanent until revoked.

Blueprint Category: AP > StatusFX > Immunity

# RevokeImmunity 

void RevokeImmunity(FGameplayTag EffectTag)

Immediately remove immunity for a specific effect tag.

Blueprint Category: AP > StatusFX > Immunity

# 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.

Blueprint Category: AP > StatusFX > Query

# HasEffectMatchingQuery 

bool HasEffectMatchingQuery(FGameplayTagQuery TagQuery) const

Check if any active effect matches the given tag query.

Blueprint Category: AP > StatusFX > Query

# IsImmuneToEffect 

bool IsImmuneToEffect(FGameplayTag EffectTag) const

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

Blueprint Category: AP > StatusFX > Query

# GetStackCount 

int32 GetStackCount(FGameplayTag EffectTag) const

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

Blueprint Category: AP > StatusFX > Query

# GetActiveEffectCount 

int32 GetActiveEffectCount() const

Get the total number of active effect instances.

Blueprint Category: AP > StatusFX > Query

# GetRemainingDuration 

float GetRemainingDuration(FGameplayTag EffectTag) const

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

Blueprint Category: AP > StatusFX > Query

# GetElapsedTime 

float GetElapsedTime(FGameplayTag EffectTag) const

Get how long an effect has been active in seconds.

Blueprint Category: AP > StatusFX > Query

# 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.

Blueprint Category: AP > StatusFX > Query

# 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.

Blueprint Category: AP > StatusFX > Snapshots

# GetAllActiveEffectSnapshots 

void GetAllActiveEffectSnapshots(TArray<FAP_StatusEffectSnapshot>& OutSnapshots) const

Get snapshots of all currently active effects.

Blueprint Category: AP > StatusFX > Snapshots

# GetEffectSnapshotsByQuery 

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

Get snapshots of all active effects matching a tag query.

Blueprint Category: AP > StatusFX > Snapshots

# GetActiveEffectTags 

FGameplayTagContainer GetActiveEffectTags() const

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

Blueprint Category: AP > StatusFX > Snapshots

# Delegates

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

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

Note on stack changes: When a stack count changes on the server, the server fires OnEffectStackChanged. Clients receive this as OnEffectRefreshed due to how FastArray change detection works. Bind both delegates for correct stack display on all machines.

# Extensibility

# CanApplyEffect (Virtual) 

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
Display Name: "AP StatusFX Definition"

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

# Properties

# 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
Display Name: "StatusFX Blueprint Library"

Static helper functions available in any Blueprint graph.

# Functions

# 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.

Blueprint Category: AP > StatusFX > Helpers
Meta: DefaultToSelf = "TargetActor"

# RemoveEffectsFromActorByQuery 

static int32 RemoveEffectsFromActorByQuery(
    AActor* TargetActor,
    FGameplayTagQuery TagQuery
)

Remove all matching effects from an actor.

Blueprint Category: AP > StatusFX > Helpers

# ActorHasEffect 

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

Check if an actor has a specific active effect.

Blueprint Category: AP > StatusFX > Helpers

# GetSortedEffectSnapshots 

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

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

Blueprint Category: AP > StatusFX > Helpers

# FormatEffectDuration 

static FString FormatEffectDuration(
    const FAP_StatusEffectSnapshot& Snapshot
)

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

Blueprint Category: AP > StatusFX > Utilities

# 4. IAP_StatusFXSuiteTarget

Header: Interfaces/AP_StatusFXSuiteTarget.h
Display Name: "StatusFX Suite Target"

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

# Functions

# GetStatusEffectComponent 

UAP_StatusFXSuiteComponent* GetStatusEffectComponent() const

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

Blueprint Category: StatusFX

# 5. UAP_StatusFXSettings

Header: Settings/AP_StatusFXSettings.h
Display Name: "AP StatusFX Settings"
Location: Project Settings → Plugins → AP StatusFX Suite

# Properties

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
Parent: UObject
Display Name: "AP StatusFX Stacking Resolver"
Specifiers: Abstract, Blueprintable, EditInlineNew, DefaultToInstanced

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

# Overridable Functions

# 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.

Parameters:

  • 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 (reported via OnEffectRemoved).

# 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)

Row struct for the interaction rules DataTable.

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.

# FAP_OnEffectApplied 

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

# FAP_OnEffectRemoved 

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

# FAP_OnEffectRefreshed 

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FAP_OnEffectRefreshed,
    FGameplayTag, EffectTag
);

# FAP_OnEffectStackChanged 

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FAP_OnEffectStackChanged,
    FGameplayTag, EffectTag
);

# FAP_OnEffectTick 

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

# FAP_OnEffectExpired 

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FAP_OnEffectExpired,
    FGameplayTag, EffectTag
);

AfterPrime Systems — Building the Gameplay Foundation

© Copyright 2026. All rights reserved.