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
- 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,Alwaysalso with the default presenter (widgets in the viewport),Nevernot 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()andGetAttributeBarList()return the widgets the host shows, also ones the host placed itself, not only ones the subsystem added. - 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::NotifyAbilitySystemReadyadds when it is missing (the combat component calls it), without GAS the Pulse Attributes component. - 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.
- 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
BindToPlayerit follows the player’s pawn;SetSourceshows 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,SourceRemovedofUPulseAttributeSubsystem; the Pulse GAS Attributes component reports when it begins play) and on the nextRefresh. Entries(field notify) is the sorted list;OnEntriesChangedfires after a change.GetRemaining(Entry)andGetRemainingFraction(Entry)give the time left now.- It listens to the ability system (effect added, removed, stack and time changes, inhibition) and to
ModifiersChangedof the attribute source, and builds the list again once per frame. Building is the pure functionPulse::StatusHUD::BuildEntriesoverFPulseStatusEffectInfocopies, so own rules can be tested without an ability system. UIDataOverridereplaces 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
PulseStatusHUDBartakes the name of the stat register.
A local player shows, in this order, a bar with the same id replacing an earlier one:
- the Attribute Bars of the Status HUD settings,
- bars other modules registered:
IPulseStatusHUD::Get().RegisterAttributeBar(Bar)(e.g. inStartupModuleof a plugin with its own attributes;UnregisterAttributeBarinShutdownModule), - 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).