# API Reference

AfterPrime Systems | AP CooldownSuite

# Contents

Class	Description
Enums	`EAP_CooldownModifierType`, `EAP_StackReplenishMode`
Structs	`FAP_CooldownModifier`, `FAP_CooldownEntry`
UAP_CooldownDefinition	Data asset defining a cooldown template
UAP_CooldownSuiteComponent	Primary component — add to any replicated actor
UAP_CooldownBarWidget	Base class for a single-cooldown HUD widget
UAP_CooldownAbilityBarWidget	Dynamic container managing multiple cooldown bars

# Enums

# EAP_CooldownModifierType

Controls how a modifier value is applied to a cooldown duration.

Value	Description
`Multiplier`	Multiplies the base duration. `0.8` = 20% reduction, `1.5` = 50% increase.
`FlatOffset`	Added to the duration after all multipliers. `-1.0` = 1 second shorter.

# EAP_StackReplenishMode

Controls how stacks are returned when a cooldown expires.

Value	Description
`Sequential`	One stack replenishes per cooldown interval. Each charge refills on its own timer.
`AllAtOnce`	All consumed stacks replenish together when the cooldown expires.

# Structs

# FAP_CooldownModifier

Defines a runtime modifier that adjusts cooldown duration. Applied at cooldown start time — does not affect cooldowns already running.

Property	Type	Description
`ModifierTag`	`FGameplayTag`	Unique identifier for this modifier. Used with `RemoveModifier`.
`TargetCooldownTag`	`FGameplayTag`	The cooldown this modifier applies to. Leave empty for a global modifier that applies to all cooldowns.
`ModifierType`	`EAP_CooldownModifierType`	`Multiplier` or `FlatOffset`.
`Value`	`float`	The modifier value. For Multiplier: `0.8` = 20% reduction. For FlatOffset: `-1.0` = 1 second reduction.

Duration formula:

EffectiveDuration = (BaseDuration × ProductOfAllMultipliers) + SumOfAllFlatOffsets
EffectiveDuration = max(EffectiveDuration, MinimumCooldownDuration)

# FAP_CooldownEntry

Represents a single active cooldown instance. Replicated to clients via FastArray.

Property	Type	Description
`CooldownTag`	`FGameplayTag`	Identifies this cooldown.
`TotalDuration`	`float`	Effective duration after modifiers were applied at start time.
`StartServerTime`	`float`	Server world time when the cooldown started. Used by server-side query functions.
`CurrentStacks`	`int32`	Available stack count. `0` means all stacks are consumed.
`MaxStacks`	`int32`	Maximum charge count for this cooldown.
`StackReplenishMode`	`EAP_StackReplenishMode`	How stacks replenish.
`bIsOnCooldown`	`bool`	`true` when all stacks are consumed and the ability cannot be used.
`bWasCancelled`	`bool`	Set to `true` by the server before removing a cancelled entry. Clients read this in `PreReplicatedRemove` to fire the correct delegate.
`RemainingTimeAtCancel`	`float`	Time remaining when `CancelCooldown` was called. Carried to clients for the `OnCooldownCancelled` payload.

Not for Direct Manipulation

FAP_CooldownEntry is not intended for direct Blueprint manipulation. Use the query functions on UAP_CooldownSuiteComponent instead.

# UAP_CooldownDefinition

Type: UPrimaryDataAsset Category: CooldownSuite

A data asset that defines the configuration for a named cooldown. Create instances in the Content Browser: Right-click → Miscellaneous → Data Asset → AP_CooldownDefinition.

# Properties

Property	Type	Default	Description
`CooldownTag`	`FGameplayTag`	—	Gameplay Tag identifying this cooldown. Must be unique per definition.
`BaseDuration`	`float`	`1.0`	Cooldown duration in seconds before modifiers. Minimum `0.1`.
`MaxStacks`	`int32`	`1`	Number of charges. `1` = no stacking. `3` = three uses before entering cooldown.
`StackReplenishMode`	`EAP_StackReplenishMode`	`Sequential`	How stacks return after the cooldown expires.
`DefaultModifiers`	`TArray<FAP_CooldownModifier>`	empty	Modifiers automatically applied when this cooldown starts, in addition to any on the component.

# UAP_CooldownSuiteComponent

Type: UActorComponent Display Name: AP_CooldownSuite Category: CooldownSuite

Add this component to any Actor Blueprint via the Components panel. All cooldown state is authoritative on the server and replicates to clients via FastArray.

Authority Model

All mutation methods require server authority — call them on the server or via the provided Server RPC variants. All query methods are safe to call on any machine using the client snapshot pattern.

# Properties

Property	Type	Default	Description
`MinimumCooldownDuration`	`float`	`0.1`	Floor applied after modifiers. Cooldowns can never be shorter than this value.

# Delegates

All delegates are BlueprintAssignable. Bind via the Details panel Events section or via Assign nodes in the Event Graph.

Multiplayer Binding

Delegates fire on whichever machine the event originates on. On the server they fire directly after state mutation. On clients they fire from FastArray replication callbacks. Bind on both server and client if you need the event everywhere.

# OnCooldownStarted

Fires when all stacks are consumed and bIsOnCooldown becomes true. For MaxStacks=1 this fires on every use. For stacked cooldowns this fires only when the last stack is consumed.

Parameter	Type	Description
`CooldownTag`	`FGameplayTag`	The cooldown that started
`Duration`	`float`	Effective duration after modifiers
`CurrentStacks`	`int32`	Remaining available stacks
`MaxStacks`	`int32`	Maximum stack count

# OnCooldownFinished

Fires when a cooldown timer expires naturally and stacks have fully replenished.

Parameter	Type	Description
`CooldownTag`	`FGameplayTag`	The cooldown that expired
`Duration`	`float`	Original effective duration

# OnCooldownCancelled

Fires when CancelCooldown is called before the timer expires. Does not fire on natural expiry — use OnCooldownFinished for that.

Parameter	Type	Description
`CooldownTag`	`FGameplayTag`	The cooldown that was cancelled
`RemainingTime`	`float`	Time remaining at the moment of cancellation

# OnCooldownStackChanged

Fires when a stack is consumed or replenished, including during sequential replenishment as each stack returns.

Parameter	Type	Description
`CooldownTag`	`FGameplayTag`	The cooldown whose stacks changed
`NewStackCount`	`int32`	Current available stacks after the change
`MaxStacks`	`int32`	Maximum stack count

# Lifecycle Functions

Server Only

# `StartCooldown`

bool StartCooldown(FGameplayTag CooldownTag, float Duration)

Starts a cooldown by tag with an explicit duration. MaxStacks = 1, no stacking, no Data Asset required.

Returns: true if the cooldown started. false if the tag is already on cooldown.

# `StartCooldownFromDefinition`

bool StartCooldownFromDefinition(UAP_CooldownDefinition* Definition)

Starts a cooldown from a Data Asset definition. Applies the definition's MaxStacks, StackReplenishMode, BaseDuration, and DefaultModifiers. Component-level modifiers are also applied.

Returns: true on success. false if Definition is null or all stacks are consumed.

# `CancelCooldown`

bool CancelCooldown(FGameplayTag CooldownTag)

Cancels an active cooldown before it expires. Fires OnCooldownCancelled with the remaining time.

Returns: true if found and cancelled. false if the tag is not currently tracked.

# Server RPC Functions

Call these from clients to request cooldown operations on the server. Safe to call from the server directly — the server routes to the direct function automatically.

Function	Description
`ServerStartCooldown(CooldownTag, Duration)`	Client requests server to start a cooldown by tag and duration
`ServerStartCooldownFromDefinition(Definition)`	Client requests server to start a cooldown from a Data Asset
`ServerCancelCooldown(CooldownTag)`	Client requests server to cancel a cooldown

# Query Functions

Server + Client

All query functions are BlueprintPure. Accurate on both server and client using the client snapshot pattern.

# `IsOnCooldown`

bool IsOnCooldown(FGameplayTag CooldownTag) const

Returns true if the tag is on cooldown (all stacks consumed). Returns false if stacks are available or the tag is not tracked.

# `GetRemainingTime`

float GetRemainingTime(FGameplayTag CooldownTag) const

Returns seconds remaining on the active cooldown. Returns 0.0 if not on cooldown.

On the server this uses StartServerTime. On clients this uses a locally recorded SnapshotReceivedTime set when the replication delta arrived — avoiding a server round-trip and preventing lag artifacts in cooldown display.

# `GetProgress`

float GetProgress(FGameplayTag CooldownTag) const

Returns a normalized value from 0.0 (just started) to 1.0 (finished). Returns 1.0 if the tag is not on cooldown. Use this to drive progress bars.

# `GetCurrentStacks`

int32 GetCurrentStacks(FGameplayTag CooldownTag) const

Returns the number of available stacks. Returns 1 if the tag is not tracked (all available by default for single-stack cooldowns).

# `GetMaxStacks`

int32 GetMaxStacks(FGameplayTag CooldownTag) const

Returns the maximum stack count. Returns 0 if the tag is not tracked.

# `GetTotalDuration`

float GetTotalDuration(FGameplayTag CooldownTag) const

Returns the effective duration after modifiers. Returns 0.0 if not on cooldown.

# `GetAllActiveCooldownTags`

TArray<FGameplayTag> GetAllActiveCooldownTags() const

Returns all tags that currently have entries in the cooldown array. Includes tags with stacks partially consumed — use IsOnCooldown to filter for fully active cooldowns only.

# Modifier Functions

Server Only

Modifiers are applied at cooldown start time and do not affect running cooldowns.

# `AddModifier`

void AddModifier(FAP_CooldownModifier Modifier)

Adds a modifier to this component. If a modifier with the same ModifierTag already exists, it is replaced.

# `RemoveModifier`

bool RemoveModifier(FGameplayTag ModifierTag)

Removes the modifier with the given ModifierTag. Returns: true if found and removed.

# `ClearAllModifiers`

void ClearAllModifiers()

Removes all modifiers from this component.

# `HasModifier`

bool HasModifier(FGameplayTag ModifierTag) const

Returns true if a modifier with this tag exists on the component. Safe to call on any machine.

# UAP_CooldownBarWidget

Type: UUserWidget Category: CooldownSuite

C++ base class for a single-cooldown HUD widget. Tracks one FGameplayTag and forwards delegate events to Blueprint-overridable functions. Create a Widget Blueprint with this as the parent class and build your visual layout in the Designer.

# Properties

Property	Type	Description
`TrackedCooldownTag`	`FGameplayTag`	The cooldown tag this widget displays. Set via `InitializeWidget` or in the Blueprint Details panel.

# Functions

# `InitializeWidget`

void InitializeWidget(UAP_CooldownSuiteComponent* InComponent, FGameplayTag InTag)

Binds this widget to a component and tag. Call once during setup. Subscribes to OnCooldownStarted, OnCooldownFinished, and OnCooldownStackChanged on the component.

When using UAP_CooldownAbilityBarWidget, InitializeWidget is called automatically — do not call it manually.

# `GetBoundComponent`

UAP_CooldownSuiteComponent* GetBoundComponent() const

Returns the component this widget was bound to. Use this in a polling timer to call GetProgress and GetRemainingTime for smooth progress bar updates.

# `OnCooldownUpdated` (BlueprintNativeEvent)

Called when the tracked cooldown starts or its stack count changes. Override in Blueprint to update your progress bar, stack badge, and other UI elements.

Parameter	Type	Description
`CooldownTag`	`FGameplayTag`	The tag that changed
`Duration`	`float`	Effective duration
`CurrentStacks`	`int32`	Current available stacks
`MaxStacks`	`int32`	Maximum stack count

# `OnCooldownComplete` (BlueprintNativeEvent)

Called when the tracked cooldown finishes naturally or is cancelled. Override in Blueprint to play a ready animation, reset the progress bar, or show a flash effect.

Parameter	Type	Description
`CooldownTag`	`FGameplayTag`	The tag that finished
`Duration`	`float`	Original duration

Add a looping timer in Blueprint (Set Timer by Event, 0.05s interval) that calls GetProgress and GetRemainingTime on the bound component each tick for smooth visual updates without using Event Tick.

# UAP_CooldownAbilityBarWidget

Type: UUserWidget Category: CooldownSuite

Container widget that manages a dynamic set of UAP_CooldownBarWidget instances. Listens to a UAP_CooldownSuiteComponent and automatically spawns a bar when a cooldown becomes active and removes it when the cooldown finishes or is cancelled.

# Properties

Property	Type	Description
`CooldownBarWidgetClass`	`TSubclassOf<UAP_CooldownBarWidget>`	The widget class to instantiate for each active cooldown. Assign your `WBP_AP_CooldownBar` here in Class Defaults.

# Functions

# `InitializeContainer`

void InitializeContainer(UAP_CooldownSuiteComponent* InComponent)

Binds the container to a cooldown component. Call once during setup (e.g., in the HUD or character BeginPlay). Subscribes to OnCooldownStarted, OnCooldownFinished, and OnCooldownCancelled. Also spawns bars for any cooldowns already active at bind time.

# `OnCooldownBarAdded` (BlueprintNativeEvent)

Called when a new cooldown becomes active and a bar widget has been created. Override in Blueprint to add the widget to your Horizontal Box or Vertical Box.

Parameter	Type	Description
`Widget`	`UAP_CooldownBarWidget*`	The newly created bar widget
`CooldownTag`	`FGameplayTag`	The cooldown it represents

# `OnCooldownBarRemoved` (BlueprintNativeEvent)

Called when a cooldown finishes or is cancelled. Override in Blueprint to remove the widget from your panel.

Parameter	Type	Description
`Widget`	`UAP_CooldownBarWidget*`	The bar widget being removed
`CooldownTag`	`FGameplayTag`	The cooldown that ended

# Setup Summary

Create WBP_AP_AbilityBar — Widget Blueprint with parent class AP_CooldownAbilityBarWidget
Add a Horizontal Box or Vertical Box to the canvas
Override OnCooldownBarAdded → Add Child to your box
Override OnCooldownBarRemoved → Remove From Parent on the widget
In Class Defaults set Cooldown Bar Widget Class to your WBP_AP_CooldownBar
In character or HUD BeginPlay:
- Create WBP_AP_AbilityBar
- Call Initialize Container with your AP_CooldownSuite component
- Call Add to Viewport

AfterPrime Systems — Building the Gameplay Foundation

# API Reference

# Contents

# Enums

# EAP_CooldownModifierType

# EAP_StackReplenishMode

# Structs

# FAP_CooldownModifier

# FAP_CooldownEntry

Not for Direct Manipulation

# UAP_CooldownDefinition

# Properties

# UAP_CooldownSuiteComponent

Authority Model

# Properties

# Delegates

Multiplayer Binding

# OnCooldownStarted

# OnCooldownFinished

# OnCooldownCancelled

# OnCooldownStackChanged

# Lifecycle Functions

# StartCooldown

# StartCooldownFromDefinition

# CancelCooldown

# Server RPC Functions

# Query Functions

# IsOnCooldown

# GetRemainingTime

# GetProgress

# GetCurrentStacks

# GetMaxStacks

# GetTotalDuration

# GetAllActiveCooldownTags

# Modifier Functions

# AddModifier

# RemoveModifier

# ClearAllModifiers

# HasModifier

# UAP_CooldownBarWidget

# Properties

# Functions

# InitializeWidget

# GetBoundComponent

# OnCooldownUpdated (BlueprintNativeEvent)

# OnCooldownComplete (BlueprintNativeEvent)

# Recommended Widget Timer Pattern

# UAP_CooldownAbilityBarWidget

# Properties

# Functions

# InitializeContainer

# OnCooldownBarAdded (BlueprintNativeEvent)

# OnCooldownBarRemoved (BlueprintNativeEvent)

# Setup Summary

# `StartCooldown`

# `StartCooldownFromDefinition`

# `CancelCooldown`

# `IsOnCooldown`

# `GetRemainingTime`

# `GetProgress`

# `GetCurrentStacks`

# `GetMaxStacks`

# `GetTotalDuration`

# `GetAllActiveCooldownTags`

# `AddModifier`

# `RemoveModifier`

# `ClearAllModifiers`

# `HasModifier`

# `InitializeWidget`

# `GetBoundComponent`

# `OnCooldownUpdated` (BlueprintNativeEvent)

# `OnCooldownComplete` (BlueprintNativeEvent)

# `InitializeContainer`

# `OnCooldownBarAdded` (BlueprintNativeEvent)

# `OnCooldownBarRemoved` (BlueprintNativeEvent)