ultimate-bar-system-plugin/README.md

Universal Bars

PEAK-style universal UMG bars for Unreal Engine 5.7 — one procedural material drives every kind of stat bar (health, stamina, hunger, thirst, oxygen, cold, shield, injury, boss HP, item durability, progress), with a global subsystem API and animated damage / heal / low-value feedback.

Everything is procedural — no bar textures required. White rounded border, soft corners, dark translucent backdrop, bright flat fill: clean cartoon survival HUD.

---

1. Install / enable

The plugin lives at Plugins/UniversalBars/. It is a project plugin and is enabled by default. After pulling, regenerate project files and build the editor target once (it adds the UniversalBars runtime module). Content mounts under /UniversalBars/.

New C++ classes (a new module) cannot be hot-loaded by Live Coding — do a full editor build the first time.

---

2. What's inside

/UniversalBars/
  Materials/
    M_UI_UniversalBar          master material (Domain=UI, Translucent, procedural SDF)
    MI_UI_Bar_Health           solo green bar
    MI_UI_Bar_Stamina          solo yellow-green bar
    MI_UI_Bar_Injury           striped "broken HP" bar
    MI_UI_Bar_Shield           blue bar + shield overlay
    MI_UI_Bar_Boss             segmented boss bar
    MI_UI_Bar_PeakCombined     HP + hunger + weight in ONE bar (PEAK capacity)
  Components/
    WBP_UniversalBar           one reusable bar (parent: UUniversalBarWidget)
    WBP_BarHealth              combined-capacity variant
    WBP_BarStamina             stamina variant
    WBP_HUD_InGame             ready HUD: health + stamina + status chips
  Theme/                       put DA_UniversalBars_* theme assets here

C++ (module UniversalBars):
  UUniversalBarWidget          one animated bar
  UUniversalHUDWidget          HUD container with high-level stat setters
  UUniversalBarsSubsystem      global access point (UWorldSubsystem)
  UUniversalBarsTheme          palette / geometry / chip-colour DataAsset

---

3. Quick start

Blueprint — easiest path (global API, no widget reference)

1. On BeginPlay (player controller / HUD), call Universal Bars Subsystem → Create HUD with HUD Class = WBP_HUD_InGame.
2. From anywhere in BP:

Get World Subsystem (UniversalBarsSubsystem)
  → Set Health (0.62)        // 0..1, animates + flashes automatically
  → Set Stamina (0.8)
  → Set Hunger (0.16)        // penalty zone eats into max HP (combined bar)
  → Set Weight (0.12)
  → Damage Health (0.2)      // red flash + instant drop + lag tail
  → Heal Health (0.25)       // green flash + smooth rise

Direction is detected for you: a decrease plays the damage animation, an increase plays the heal animation.

C++

#include "UniversalBarsSubsystem.h"

if (UUniversalBarsSubsystem* Bars = UUniversalBarsSubsystem::Get(this))
{
    Bars->SetHealth(0.62f);
    Bars->SetHunger(0.16f);
    Bars->DamageHealth(0.2f);
}

Driving a single bar directly

Place a WBP_UniversalBar (or a preset variant) anywhere and call:

UUniversalBarWidget* Bar = ...;
Bar->SetFillPercent(0.5f);                 // animated
Bar->SetShieldPercent(0.25f);
Bar->SetSegmentCount(10);                  // boss segments
Bar->SetPenaltyZone("Hunger", 0.16f, FLinearColor(0.9f,0.6f,0.2f,1)); // animated zone
Bar->PlayDamageFlash();                    // manual flash

---

4. Animation model (same as the HTML prototype)

Change	Bright fill	Lag tail	Flash
Decrease / damage	snaps down instantly	holds DelayedDelays, then drains at DelayedFallSpeed	red (DamageFlashColor)
Increase / heal	eases up at FillRiseSpeed	jumps to target (lighter "incoming" band)	green (HealFlashColor)
value < LowThreshold	—	—	border pulses (low-value warning)
penalty zone change	—	zone width eases at ZoneInterpSpeed	—

All tuning fields live on UUniversalBarWidget (Bar|Anim category). Set bAutoFlashOnChange=false to drive flashes manually.

Under the hood the material exposes FillPercent, DelayedFillPercent, FlashAmount, LowHPPulseAmount — the widget tweens these every tick via a Dynamic Material Instance.

---

5. Combined "capacity" bar (PEAK)

One bar = current value (bright) + depleted-but-recoverable zone (dark) + striped penalty zones eating max from the right:

• MaxFillPercent — right edge of the usable region (1 - sum(penalties)).
• PenaltyCount + PenaltyEnd1..4 + PenaltyColor1..4 — up to 4 striped zones.

You never set these by hand — SetHunger / SetWeight / SetCold (HUD) or SetPenaltyZone(Id, Width, Color) (bar) manage them and animate the widths. Set a penalty to 0 to retract its zone.

PenaltyCount = 0 → the same material is a plain solo bar.

---

6. Material parameter reference

Scalars: FillPercent, DelayedFillPercent, ShieldPercent, MaxFillPercent, PenaltyCount, PenaltyEnd1..4, BarOpacity, BackgroundOpacity, CornerRadius, BorderSize, InnerPadding, EdgeSoftness, BarAspect, FlashAmount, LowHPPulseAmount, PulseSpeed, StripeAmount, StripeScale, StripeSpeed, SegmentCount, SegmentDividerSize, SegmentDividerOpacity, UseVerticalFill, InvertFill, NoiseAmount, TimeOffset.

Vectors: FillColor, DelayedFillColor, ShieldColor, BackgroundColor, BorderColor, EmptyColor, FlashColor, StripeColorA, StripeColorB, PenaltyColor1..4.

BarAspect must roughly match the on-screen width/height ratio so the rounded corners stay circular (default 8 ≈ a 600×75 bar).

---

7. Theme

UUniversalBarsTheme (DataAsset) centralises palette + geometry + chip colours. Create one under /UniversalBars/Theme/ (right-click → Miscellaneous → Data Asset → Universal Bars Theme), then assign it to WBP_HUD_InGame's Theme property. UUniversalHUDWidget::ApplyTheme() runs on construct and retints both bars and all chips. Per-preset look still lives in the MI_UI_Bar_* instances; the theme is the HUD-level override.

---

8. Presets (recommended values)

Preset	Fill	Notes
Health	(0.30,0.85,0.20)	white border, low-HP pulse, damage lag
Stamina	(0.85,0.95,0.30)	thinner, no pulse
Injury	(0.75,0.20,0.20) + StripeAmount=1	striped "broken" HP
Shield	(0.30,0.70,1.0) + ShieldPercent	blue + overlay
Boss	(0.85,0.15,0.15) + SegmentCount=10	wide, segmented, less rounded
PeakCombined	green + Hunger/Weight penalties	one-bar HP+hunger+weight

Keep BorderColor pure white and BorderSize 0.06–0.10 for the toy/cartoon look; CornerRadius 0.5–0.7 for horizontal bars.

---

9. Demo / study mode (WBP_HUD_InGame)

WBP_HUD_InGame ships with Demo Mode ON (UUniversalHUDWidget::bDemoMode). While on, the HUD's NativeTick runs a 10-step cycle every DemoStepInterval (1.6 s) so you can watch every animation live in PIE:

0 DamageHealth(0.25)   red flash + instant drop + lag tail
1 SetStamina(0.30)     stamina drop
2 HealHealth(0.20)     green flash + smooth rise
3 SetHunger(0.18)      amber zone eases in from the right
4 SetWeight(0.14)      red zone eases in
5 SetStamina(0.95)     stamina refill
6 HealHealth(0.30)
7 SetHunger(0.0)       hunger zone retracts
8 SetWeight(0.0)       weight zone retracts
9 DamageHealth(0.45)   big hit -> low-HP border pulse

To watch: add the HUD (Subsystem → Create HUD, or just drop it in any widget / PIE) and press Play. The cycle restarts each time the widget constructs.

Turn it off for shipping: open WBP_HUD_InGame → Class Defaults → uncheck Demo Mode, or call SetDemoMode(false). Read DemoStepNow() in UniversalHUDWidget.cpp to see exactly which API call drives each animation.

9b. Status chips (PEAK markers)

In WBP_HUD_InGame the chips live in a CanvasPanel (ChipCanvas) overlaid on the health bar, not in a row below it. Each tick UUniversalHUDWidget::PositionChips() slides them to sit just above the centre of their zone, using UUniversalBarWidget::GetUsableEnd() / GetZoneCenter("Hunger"|"Weight"|"Cold"):

• ChipHeart → the usable-HP / penalty boundary
• ChipHunger → centre of the hunger zone (hidden until SetHunger > 0)
• ChipWeight → centre of the weight zone
• ChipCold → centre of the cold zone

So when hunger/weight grow or shrink, the chips ride along with the zone edges. Add your own marker by placing an Image in ChipCanvas and binding it (or extend PositionChips). Swap the placeholder tints for real icon textures.

10. Notes / limits

• The bar is a UI-domain material — it only renders inside UMG/Slate (not on meshes). Verify visuals in the UMG designer or content-browser thumbnail.
• Up to 4 penalty zones are drawn by the material in a single draw call; the widget warns if you push more.
• SetFillPercent clamps to 0..1. Feed it CurrentHP / MaxHP, etc.