Status effects and attribute bars

Module PulseStatusHUD (depends on the UI host and the attribute contract of Pulse Foundation, its GAS adapter PulseFoundationGAS and the Gameplay Ability System). It adds two things to the UI host (the Pulse HUD by default) of every local player:

  • the effect bar: the active gameplay effects of the player’s pawn and the Pulse modifiers it sees, with icon, remaining time and stacks;
  • attribute bars: one bar for any Pulse attribute (Pulse.Stat.Stamina, mana, hunger, thirst, …) of any attribute source (the Pulse Attributes component, the GAS adapter with the health and stamina sets of PulseGameplay, an own source), with name, icon and value.

Both follow the pawn of the player, also after a respawn, and work the same on a listen server, a dedicated server’s clients and in single player. Neither ticks: the effect bar updates its times on a timer while a timed effect shows, attribute bars update on the events of the source and, while a rate runs, on a timer of the game clock.

Overview

Type What it is
UPulseStatusEffectUIData Status Effect UI Data: icon, name, text, kind and priority per effect tag
FPulseStatusEffectInfo One active effect or visible modifier as plain data (tags, start, duration, stacks)
FPulseStatusEffectEntry One icon of the effect bar: the effects with one UI entry, merged
Pulse::StatusHUD::BuildEntries Pure rule: filter by UI entry, merge, sort
UMVVMPulseStatusEffects Pulse Status Effects View Model: the list of entries for own widgets
UPulseStatusEffectBar, UPulseStatusEffectIcon Pulse Status Effect Bar and its icons
FPulseAttributeBarInfo One attribute bar: attribute tag, fill on or off, name, icon, color role, priority
UPulseAttributeBarWidget, UPulseAttributeBarList Pulse Attribute Bar and the list of all bars of a player
UPulseStatusHUDSubsystem Local player subsystem: puts both on the UI host, keeps the bars of the player
UPulseStatusHUDSettings Project Settings > Pulse > Gameplay > Status HUD

Setup

  1. Turn on the Pulse HUD (bEnableHUD). Status HUD Activation decides when the module starts: With UI Host (default) with the Pulse HUD or a Presenter Class of your own in Project Settings > Pulse > Foundation > UI, Always also with the default presenter (widgets in the viewport), Never not at all. The status HUD subsystem then adds the effect bar (top left) and the list of attribute bars (bottom left, above the health bar) to the gameplay part of the UI host (the Gameplay Root of the HUD layout) whenever the host is ready, again after every map change. A host that already shows a Pulse Status Effect Bar or a Pulse Attribute Bar List (placed in the layout) keeps its own. GetEffectBar() and GetAttributeBarList() return the widgets the host shows, also ones the host placed itself, not only ones the subsystem added.
  2. For gameplay effects on the effect bar the pawn (or its player state) needs an ability system component, as for combat; modifiers of an attribute source show without one. Attribute bars need an attribute source on the pawn or its player state: with GAS the Pulse GAS Attributes component, which Pulse::Attributes::GAS::NotifyAbilitySystemReady adds when it is missing (the combat component calls it), without GAS the Pulse Attributes component.
  3. Make a Status Effect UI Data asset (Add > Pulse > Gameplay > Status Effect UI Data) with an entry per effect tag and add it to Effect UI Data in the Status HUD settings.
  4. For attribute bars, add entries to Attribute Bars in the settings, or let a plugin register them (below).

Which effects show

Only effects the player should see show up: an active effect is shown when one of its tags (asset tags, granted tags, also the dynamic tags of its spec) has an entry in a Status Effect UI Data asset of the settings. Cooldowns and internal effects without an entry stay hidden.

Entry field What it does
EffectTag Effects with this tag or a child of it use the entry. An exact tag wins over a parent; on a tie the first entry
DisplayName, Description Name and text (tooltip of the icon, own widgets)
Icon Icon (soft reference, loaded when shown)
Kind Buff, Debuff or Neutral: the color of the frame (Pulse.UI.Color.Positive, .Negative, .Outline)
SortPriority Higher comes first in the bar
bShowStacks, bShowRemaining Show the stacks (from 2 on) and the remaining time

Pulse modifiers show the same way: a modifier of the attribute source with an EffectTag that has an entry, and that the local player sees (Visibility All, or Owner on the owner’s machine; None stays on the server). So a sprint buff, an equipment bonus or the modifier of a band (“Starving”) gets an icon also on a pawn without an ability system. The modifiers of one source key with the same EffectTag are one effect. Its remaining time runs on the game clock until the modifier ends; a modifier without duration shows no time. Clients do not get the Duration of a modifier: they count its start from when they first saw it, so after a join the time of a running modifier starts full. The effects that carry Pulse modifiers on an ability system (subclasses of UPulseAttributeModifierEffect and the Modifier Effects of the attribute map) show once, as their modifier.

Effects with the same entry become one icon: their stacks add up, and the icon shows the time of the effect that lasts longest (an effect without duration wins). The bar is sorted by priority, then by start (older first). Inhibited effects (their ongoing tag requirements fail) are not shown.

Remaining time

Gameplay effects run on the world time; on clients the ability system moves their start into the client’s clock. The view model copies start and duration once; the effect bar asks Pulse::StatusHUD::GetRemaining with the world time when its timer fires (every Remaining Update Interval, only while a timed effect is shown). The text is FormatRemaining: “8 s”, “3 min”, “2 h”, rounded up.

The view model

UMVVMPulseStatusEffects is the list for own widgets (MVVM, or C++ and Blueprint):

  • With the Pulse Player View Model Resolver or BindToPlayer it follows the player’s pawn; SetSource shows any actor (an enemy, a party member).
  • It finds the ability system with Pulse::Attributes::GAS::FindAbilitySystem (the actor, its pawn or its player state). An ability system given later is picked up when an attribute source of the actor reports it is ready or gone (SourceReady, SourceRemoved of UPulseAttributeSubsystem; the Pulse GAS Attributes component reports when it begins play) and on the next Refresh.
  • Entries (field notify) is the sorted list; OnEntriesChanged fires after a change. GetRemaining(Entry) and GetRemainingFraction(Entry) give the time left now.
  • It listens to the ability system (effect added, removed, stack and time changes, inhibition) and to ModifiersChanged of the attribute source, and builds the list again once per frame. Building is the pure function Pulse::StatusHUD::BuildEntries over FPulseStatusEffectInfo copies, so own rules can be tested without an ability system.
  • UIDataOverride replaces the UI data of the settings for this view model.

Attribute bars

A Pulse Attribute Bar shows the Pulse attribute Attribute (a tag below Pulse.Stat) of the player’s pawn through a Pulse Attribute Value view model (UMVVMPulseAttributeValue of Pulse Foundation). It reads the attribute through the attribute contract (Pulse::Attributes::Read), so it works the same for the Pulse Attributes component, the GAS adapter and an own source. The fill is the percent of the source, the value between its bounds ((Value - Min) / (Max - Min); for health Health / MaxHealth); the numbers are the value, kept between its bounds, and the maximum. Without a pawn (dead, before the first possession) it shows the player state.

  • Show Fill (bShowFill, default on) shows the fill and “value / maximum”; off shows only the number (a stat such as armor without a maximum to fill up to).
  • Hide Without Attribute (default on) hides the bar while the source of the pawn does not know the attribute, so a bar for an attribute of another system stays out of levels without it.
  • An empty Display Name hides the name; the cheat PulseStatusHUDBar takes the name of the stat register.

A local player shows, in this order, a bar with the same id replacing an earlier one:

  1. the Attribute Bars of the Status HUD settings,
  2. bars other modules registered: IPulseStatusHUD::Get().RegisterAttributeBar(Bar) (e.g. in StartupModule of a plugin with its own attributes; UnregisterAttributeBar in ShutdownModule),
  3. bars added at runtime: UPulseStatusHUDSubsystem::AddAttributeBar / RemoveAttributeBar (Blueprint too).

The list is sorted by SortPriority (higher on top). The id is Id, or the attribute tag (Pulse.Stat.Stamina).

// A plugin with hunger registers its bar for every player
FPulseAttributeBarInfo hunger;
hunger.Attribute = MyGame::Tags::Stat_Hunger;
hunger.DisplayName = LOCTEXT("Hunger", "Hunger");
hunger.FillColorRole = Pulse::UI::Tags::Color_Warning;
IPulseStatusHUD::Get().RegisterAttributeBar(hunger);

Own widgets and look

The default widgets build their layout in C++ and take their look from the UI theme: the icon frame uses the role Pulse.UI.Panel.Inset, texts Pulse.UI.Text.Number, .Small and .Caption, the bar Pulse.UI.ProgressBar.Default with the fill color of FillColorRole (default Pulse.UI.Color.Accent). A Blueprint child can bind its own parts:

Widget Bindable parts
Pulse Status Effect Bar EffectList (any panel), IconClass
Pulse Status Effect Icon KindBorder, Frame, IconImage, StackText, RemainingText
Pulse Attribute Bar IconImage, NameText, FillBar, ValueText
Pulse Attribute Bar List BarList (any panel), BarClass

Set the classes in the Status HUD settings, or place the widgets in your HUD layout (then the subsystem adds none). SetViewModel on the effect bar shows another view model, SetSource on an attribute bar another actor.

Settings

Setting Default Description
StatusHUDActivation With UI Host When the module starts (With UI Host, Always, Never)
EffectUIData the example data Status Effect UI Data assets; only effects with an entry show
bAddEffectBarToHUD true Adds the effect bar to the HUD
EffectBarClass UPulseStatusEffectBar The effect bar
EffectBarAnchor, EffectBarOffset (0, 0), (32, 32) Corner and distance
RemainingUpdateInterval 0.25 s How often the remaining times update
AttributeBars none Attribute bars of every player
bAddAttributeBarsToHUD true Adds the list of attribute bars to the HUD
AttributeBarListClass, AttributeBarClass UPulseAttributeBarList, UPulseAttributeBarWidget List and bar
AttributeBarsAnchor, AttributeBarsOffset (0, 1), (32, 150) Corner and distance
AttributeBarWidth 220 Width of one bar
AttributeViewModelClass UMVVMPulseAttributeValue View model an attribute bar creates for itself (Pulse Foundation); a child (C++ or Blueprint) adds fields without a widget subclass, empty uses the base class
StatusEffectsViewModelClass UMVVMPulseStatusEffects View model the effect bar creates when none is set with SetViewModel; empty uses the base class

Example

Play the PulseGameplay example map (a listen server and a client work too), then as the player:

PulseGameplayGrant
PulseStatusHUDApply Burning 45 2
PulseStatusHUDApply Poisoned 300 3
PulseStatusHUDApply Regeneration -1
PulseStatusHUDBar Stamina

The effect bar shows the three example effects of DA_PulseStatusHUD_ExampleEffects (/PulseGameplay/StatusHUD) with their stacks and times; Burning goes away after 45 seconds. The example tags (Pulse.StatusHUD.Example.*) never come from a game, so the example data in the settings does no harm; replace it with your own.

Switching it off. UPulseStatusHUDSubsystem is switchable: add it to Disabled Subsystems (Project Settings > Pulse > Foundation > Subsystems) when your game brings its own status bars. An attribute bar list in a layout then shows the bars of the settings only. See Replacing and switching off subsystems.

Cheats

Cheat Runs on What it does
PulseStatusHUDApply <tag> [seconds] [stacks] server Applies an example effect with the tag (short names below Pulse.StatusHUD.Example); 0 seconds = 10 s, negative = until cleared
PulseStatusHUDClear server Removes the example effects
PulseStatusHUDBar <attribute> [name] local Adds an attribute bar for this player: a tag such as Pulse.Stat.Stamina or a short name below Pulse.Stat such as Stamina; without a name the name of the stat register
PulseStatusHUDBarRemove <id> local Removes a bar added at runtime (id = the attribute tag unless the bar has its own)
PulseStatusHUDInfo local Prints the shown effects with their time left and the attribute bars

Log category LogPulseStatusHUD; the status HUD subsystem is a snapshot provider (category StatusHUD). Specs: PulseStatusHUD (filter by UI entry, remaining time, stacks, sorting, attribute bars), without world or ability system, and PulseStatusHUD.ViewModels (view model classes from the settings, fallback to the base classes).


PulseGameplay plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.