Vitals

Documentation Unreal Engine Combat Framework Vitals Health

Give enemies and the player resource pools: health that hits take, stamina that refills on its own, and any other pool you name, spent by moves, drained over time and read by the AI and the HUD.


Health, stamina, stance, mana. One component holds them for enemies and the player alike, spends them, refills them on a timer, drains them while a move lasts, and tells the rest of the framework the moment one runs out.

Set it up

2 minutes
  1. 1

    Find the Vitals component

    Both character bases carry a UCF Vitals component with one row: Health at 100 with no regeneration. On an enemy built on Enemy Character Base or UCF Enemy Character Base it is named Vitals; on a character built on the UCF character base, VitalsComponent. Hits come off it with no wiring of your own.
    On any other pawn, press Add Component and pick UCF Vitals.
  2. 2

    Add stamina that refills itself

    Press + on the Vitals array for a second row. Point Vital Tag at UCF.Vital.Stamina and give it a regeneration rate and a delay. This one recovers 15 a second, starting 1.5 seconds after anything last touched it.
    Vitals
    ▾Vitals > Index [1]
    Vital Tag 
    Max Value 
    Regen Rate Per Second0.0
    Regen Delay Seconds0.0
    Regen Delay Seconds is the pause after any change before the pool starts climbing again.
  3. 3

    Give a move a price

    On the player's action graph, select the dodge node, press + on its Costs, pick Vital, point it at UCF.Vital.Stamina and set an Amount: the dodge runs only while the pool can pay, and pays as it starts. On an enemy's action, add a Vital Gate to its Scoring > Gates list on the same tag: the AI picks the move only while the pool holds enough.
  4. 4

    Play, and watch the pools

    Press Play and run UCF.Debug.Vitals 1. Every pawn carrying vitals, enemy or player, gets its pools above its head, value against maximum. Dodge and the stamina drops, then climbs back; take a hit and Health drops.
A pool a pawn has no row for reads differently on each side. The enemy's readers forgive it: a Vital Gate passes, a Vital Scorer scores flat, and health reads as full. The player's readers refuse it: a Vital gate stays shut, a Vital Threshold condition fails, and a Vital cost never affords. So a mistyped tag leaves an enemy that cannot be gated, and a player move that never runs. The write side warns either way: Modify Vital, Drain Vital, Set Vital and Fill Vital each name the tag they could not find, and a hit on a pawn with no health pool warns once for its class.

Author a pool

Each row in the Vitals array is one pool. A row needs a tag and a maximum; the rest is optional.
Details
UCF Vitals
Vitals
Vitals
1 Array element
Index [ 0 ]
Vital Tag
UCF.Vital.Health
Max Value
100
Regen Rate Per Second
0
Regen Delay Seconds
0
Depleted Loose Tag
None
Depleted Result Tag
None
Depleted Gameplay Event
None
Debug
Debug Overlay Vitals
Both character bases carry it with one Health row at 100 and no regeneration: named Vitals on Enemy Character Base, VitalsComponent on the UCF character base. Add a row for stamina, stance, or any other pool.
FieldSets
Vital TagWhich pool this row is. UCF.Vital.Health, UCF.Vital.Stamina and UCF.Vital.Stance ship with the plugin, and any tag you author works the same way.
Max ValueThe pool's upper bound. The pool starts full. A row at 0 is skipped with a warning.
Regen Rate Per SecondHow fast the pool climbs back once the delay elapses, in units per second. 0 turns regeneration off.
Regen Delay SecondsSeconds after any change before the pool starts climbing; each change restarts the wait. 0 resumes in the same instant.
Depleted Loose TagHeld on the pawn's ability system while the pool sits at zero with no regeneration running. Dropped when regeneration starts or the pool refills.
Depleted Result TagAdded to the hit report on the exact blow that empties the pool, so the attack that broke it can answer with its own effect. Later hits on the empty pool do not add it again.
Depleted Gameplay EventSent to the pawn once per depletion, on the server. Skipped when the pawn has no ability system.
Two rows naming one tag keep the first. A pawn with an empty Vitals array carries no pools and does nothing.

Spend it, heal it, read it

These nodes change a pool. Each runs on the server; called on a client, a node changes nothing and returns its default.
NodeDoes
Modify VitalAdds or subtracts. A spend the pool cannot pay in full changes nothing and returns false, so one call is both the affordability check and the spend. A gain clamps at the maximum.
Drain VitalTakes up to the amount asked, floors at zero, and returns how much came off. A pool at 30 drained by 50 empties and returns 30.
Set VitalSets the pool, clamped between zero and the maximum. Restarts the regeneration delay even when the value does not move.
Fill VitalSets the pool to its maximum.
Five more read a pool. They work on any machine, at any time, and cost nothing to poll every frame.
NodeReturns
Get Vital ValueThe current value, regeneration included. 0 for a pool with no row.
Get Vital FractionThe same value as 0 to 1 of the maximum. Bind a bar to this.
Get Vital MaxThe authored maximum.
Has VitalWhether the pawn carries a row for the tag.
Is Vital DepletedWhether the pool sits at zero.
Regeneration's smooth rise fires no events. For a bar that climbs, poll Get Vital Fraction on Tick; for a bar that only redraws on a hit, bind On Vital Changed instead.

Drain a pool over time

A held sprint, a raised guard or a channelled spell pays while it lasts rather than once. Start Vital Drain takes a pool down at a steady rate, in units per second, and returns a drain handle; keep the handle and pass it to Stop Vital Drain when the effort ends. Both run on the server, like the nodes above.
While a drain runsWhat happens
The pool reaches zeroIt stops there and empties the way any pool does: On Vital Depleted fires, the Depleted Loose Tag goes on, and the Depleted Gameplay Event is sent. The drain keeps running until it is stopped, so the pool stays empty.
RegenerationWaits. Once the last drain on the pool stops, Regen Delay Seconds starts over from there.
A second drain on the same poolThe two add up. Stopping one leaves the other running.
A spend or a hitComes off as usual, and the drain carries on from the new value.
A tag with no row, or a rate of 0 or less, starts nothing and hands back a handle that names nothing. Stopping that handle, or one already stopped, does nothing.

Make something happen when a pool empties

Three fields on the row cover the usual jobs, so a guard break or an exhaustion state needs no event graph at all.
  • Depleted Loose Tag holds a tag on the pawn while the pool is empty. Put that tag in an action's or a reaction's Block Tags, or in a transition's Blocked Tags, and the move stops being available while the pool is spent.
  • Depleted Gameplay Event fires an ability directly. Point a stagger ability's activation at it and a stance pool at zero staggers the character.
  • Depleted Result Tag rides back on the blow that broke the pool, so the attacker can play a guard-break impact on that hit alone. See Melee Trace and Damage.
The loose tag and the gameplay event both go through the pawn's ability system, so a pawn without one gets neither. The result tag rides the hit report and needs no ability system.
For anything else, bind On Vital Depleted, which carries the tag of the pool that emptied.

On an enemy: health, stamina and death

Two tags in Project Settings, under Plugins > Universal Combat Framework Enemy > Vitals, tell the enemy AI which of your pools is which.
SettingDefaultDrives
Health Vital TagUCF.Vital.HealthDeath, the Health Scorer, the health fraction the AI scores against, and the row an enemy on Enemy Character Base starts with.
Stamina Vital TagUCF.Vital.StaminaThe stamina value the AI reads, and the Stamina Gate.
An enemy carrying no vitals component, or no row for the configured tag, reads as full health and 100 stamina wherever those feed. A health pool renamed without changing the setting gives an enemy that shrugs off everything.
Auto Handle Death on Health Depleted on the enemy controller's UCF Combat Controller component is on by default. The moment the health pool empties it stops the brain, cancels the running action and reaction, stops melee tracing, unregisters the combat role, clears focus, and broadcasts On Death. The pawn itself is left standing, ready for your ragdoll, dissolve or destroy. Untick it when a project drives death on its own trigger and calls Handle Death itself.

Bringing one back

Handle Revive puts a dead enemy back under AI control. Death drops what the enemy holds when Drop Weapon on Death is ticked on its UCF Combat Controller, so hand it an item again afterwards with its Equipment Manager's Equip Item.

Cost and score enemy actions against a pool

Two entries under an action's Scoring read any pool by tag, a Vital Gate in its Gates and a Vital Scorer in its Scorers, alongside the other scorers and gates.
EntryDoes
Vital GateBlocks the action unless the pool holds at least Min Value. This is how an enemy move declares its stamina cost. Tick Use Fraction to compare against 0 to 1 instead of raw units.
Vital ScorerFavors or disfavors the action as the pool rises or falls, shaped by its range fields: Min Value, Optimal Min, Optimal Max and Max Value. Use Fraction is on by default, so an authored range survives a change to the pool's maximum.
Both pass or score flat on a pawn that carries no row for the tag, so putting either in a shared Action Set does not disable an enemy type that lacks the pool. The same two work on reactions: see Reaction System.
A gate checks the pool. It does not spend it. Take the cost off in the ability that runs the move, with Modify Vital, or let a defensive answer charge it through Cost Vital Tag on Defense.

On the player: health and death

Health Vital Tag, in the class defaults of a character built on the UCF character base, names the pool a hit takes its damage off. It is UCF.Vital.Health, the row every such character starts with. A character whose life is named something else points both this and its Vitals row at the other tag. It is a setting of its own, apart from the enemy one in Project Settings.
Nothing happens on its own when the player's health empties: the character is left standing for your game to decide. Two places hear it.
  • On Damage Taken on the character reports every hit after the pools drain, and its Result carries Was Fatal, true on the hit that emptied the health pool. This is where a death that follows a blow belongs: a death montage, a ragdoll, a respawn. See Melee Trace and Damage.
  • On Vital Depleted on the Vitals component fires for any pool that empties, a drain or a script included.

What reads a pool on the player's side

Moves, the sprint and the guard read pools by tag, so any row you author works with them.
WhereReads it to
A node's Costs, the Vital costPay to run the move. A positive Amount must be affordable and comes off as the move starts; a negative one fills the pool instead, for a meter that builds per action.
A node's Gates, the Vital gateAllow the move only while the pool meets a level, without spending any of it.
A transition's Vital Threshold conditionChoose a different move while the level is not met.
A node's Hooks, the Drain Vital hookDrain the pool for as long as the node runs, at Drain Rate Per Second, and say through End Behavior what happens when it empties: None keeps the node running, Finish ends it, Cancel cuts it.
UCF Sprint's Stamina VitalSpend Stamina Drain Per Second while sprinting, stop when it runs dry, and wait for Min Stamina to Start before sprinting again.
A defense response's Cost Vital TagCharge a raised guard. See Defense.
Gates, Costs and Cooldowns covers costs, gates and the conditions on edges in full.

One pool, both layers

UCF.Vital.Health, UCF.Vital.Stamina and UCF.Vital.Stance are one tag each, whichever layer reads them. Pools stay on each pawn: every reader looks at its own pawn's component, so an enemy's stamina and the player's never mix.
  • One row serves both readers. A UCF.Vital.Stamina row on an enemy is what its Stamina Gate reads and what a Vital cost on its action graph nodes spends.
  • A combo spends the enemy's own pools. An enemy playing an Action Graph Combo runs graph nodes, and their Vital costs pay from the enemy's UCF Vitals. Enemy Character Base ships a Health row only, so a node costing UCF.Vital.Stamina never starts on an enemy with no Stamina row, while that enemy's own Vital Gate on the same tag passes. Add the row to every enemy whose graph spends it.
  • Poise and Stance on an enemy. Every demo enemy carries a UCF.Vital.Poise and a UCF.Vital.Stance row beside Health, as the player does. A hit drains poise through its damage config, and the hit that empties it flinches the enemy and fills it again; a guard spends stance. A boss's Stance is its posture as well: each parry the player lands drains it, and an empty Stance stuns the boss. See Defense.
  • Two Health Vital Tags. The enemy's lives in Project Settings, the player's in each character's class defaults. Renaming the health pool means changing both.

Debug it

UCF.Debug.Vitals 1        // Every pool above each pawn, value against maximum
UCF.Debug.All 1           // Every overlay section at once
UCF.Debug.WatchPawn ComboEnemy // Narrow the overlays to one pawn by name
The overlay reads on a client as well as the server. To leave it on for one pawn without touching the console, tick Debug Overlay Vitals on that pawn's UCF Vitals component.
AdvancedNothing is spending or refilling
  • The tag has no row. Mutators do nothing and readers answer 0. Modify Vital, Drain Vital, Set Vital and Fill Vital each warn with the tag they could not find, so the log names the typo; Has Vital answers the same question in one node.
  • The call ran on a client. Modify, Drain, Set and Fill are server-only. Called from a Blueprint on a client they change nothing and return their default, so Modify Vital answers false as if the pool could not pay; called from C++ they also log a warning. Route the spend through a server event, or let the ability that runs the move do it on the authority. A Vital cost on an action graph node pays on the server for you.
  • Max Value is 0. The row is skipped at BeginPlay with a warning in the log.
  • Regen Rate Per Second is 0. The pool holds wherever it was left.
  • Something keeps touching the pool. Every change restarts Regen Delay Seconds, so a pool nibbled at faster than its delay never starts climbing.
  • A drain is running. Regeneration waits while any drain on the pool runs, and its delay starts over once the last one stops.
  • The Depleted Loose Tag is not appearing. It needs an ability system on the pawn, and it is dropped as soon as regeneration starts. A row with a rate above 0 and a delay of 0 begins recovering in the same instant it empties, so the tag is not held at all.
AdvancedDraining several pools in one call
An attack that takes health and stance together does it in one call. Drain Vitals takes a list of tag-and-amount rows on its Vital Damage input and reports how much came off each, one entry per row that landed. A row naming a pool the target does not carry drops out in silence, and a row bigger than its pool reports what the pool had left.
Can Afford Vital Drain answers the same list before you commit: true when every pool named holds at least what the list asks of it. Rows naming one pool add up, so two rows of 30 against a pool of 50 answer false. An empty list is affordable.
The attack side of this is Additional Vital Damage on the Damage Config, one row per extra pool a swing drains beyond health. See Melee Trace and Damage.
AdvancedEvery vital event
EventFires
On Vital ChangedOn each discrete change: a spend, damage, a set or fill, or regeneration reaching the maximum. Carries the tag, the new value, the previous value and the maximum. Regeneration's rise between those points fires nothing, and neither does a drain's fall until it empties the pool.
On Vital DepletedOnce per depletion episode, not again until the pool recovers and empties anew. The Depleted Loose Tag is already applied when it fires.
On Vital FullWhen the pool reaches its maximum, by a gain or by regeneration finishing.
All three fire on the server and on clients, for the same transition on both sides.
MultiplayerMultiplayer: anchor replication and late-arriving ability systems
The server owns every value. Mutators run there and clients receive the result on their own.
Replication is anchor-based rather than per-tick: the server sends one record per discrete change, holding the value, the server timestamp it was written at, and the rate running from it, a regeneration climbing or a drain falling. Every machine works out the current value by extrapolating that record against the shared server clock, so a regenerating or draining bar renders smooth while costing no bandwidth between changes. Starting or stopping a drain is one such change each. Client UI polls Get Vital Value with no extra wiring.
Event edges derive from the raw record values on both sides, so the server and each client fire the same event for the same transition whatever the latency. Only the displayed value extrapolates.
Refresh Ability State re-applies the depleted tags after the pawn's ability system appears or changes. Single-player needs no call. In multiplayer, call it where a custom pawn initializes its ability system, since a PlayerState ability system arriving late would otherwise miss a tag applied before it existed. It is safe to call repeatedly. A pawn that calls Notify Ability System Ready, as the UCF character base does on its own, gets this call with it.
The Vitals array is authored config, read at BeginPlay on every machine, and does not replicate. Only the runtime records do.
AdvancedReading the raw replication record
Get Vital Anchor copies the live record for a tag: the raw value, the server timestamp it was written at, and the rate running from it. It exists for debugging and tests. Gameplay reads Get Vital Value.