# Vitals

> 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.

Markdown version of https://rigbak.com/docs/universal-combat-framework/vitals, a page of the Universal Combat Framework documentation. Link that page when citing it.

> 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. **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. **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.

   In **Vitals**, under Vitals > Index [1], set:

   | Property | Value |
   | --- | --- |
   | Vital Tag | UCF.Vital.Stamina |
   | Max Value | 100.0 |
   | Regen Rate Per Second | 15.0 (replaces 0.0) |
   | Regen Delay Seconds | 1.5 (replaces 0.0) |

   *Regen Delay Seconds is the pause after any change before the pool starts climbing again.*
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. **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.

> **Warning**
>
> 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 panel: UCF Vitals** (component, in Enemy Character Base (Vitals))

**Category: Vitals**

| Property | Value |
| --- | --- |
| Vitals | 1 Array element |
| Vitals > Index [0] > Vital Tag | UCF.Vital.Health |
| Vitals > Index [0] > Max Value | 100 |
| Vitals > Index [0] > Regen Rate Per Second | 0 |
| Vitals > Index [0] > Regen Delay Seconds | 0 |
| Vitals > Index [0] > Depleted Loose Tag | None |
| Vitals > Index [0] > Depleted Result Tag | None |
| Vitals > Index [0] > Depleted Gameplay Event | None |

**Category: Vitals > Debug**

| Property | Value |
| --- | --- |
| Debug Overlay Vitals | false |

*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.*

| Field | Sets |
| --- | --- |
| **Vital Tag** | Which 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 Value** | The pool's upper bound. The pool starts full. A row at 0 is skipped with a warning. |
| **Regen Rate Per Second** | How fast the pool climbs back once the delay elapses, in units per second. 0 turns regeneration off. |
| **Regen Delay Seconds** | Seconds after any change before the pool starts climbing; each change restarts the wait. 0 resumes in the same instant. |
| **Depleted Loose Tag** | Held 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 Tag** | Added 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 Event** | Sent 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.

| Node | Does |
| --- | --- |
| **Modify Vital** | Adds 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 Vital** | Takes 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 Vital** | Sets the pool, clamped between zero and the maximum. Restarts the regeneration delay even when the value does not move. |
| **Fill Vital** | Sets 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.

| Node | Returns |
| --- | --- |
| **Get Vital Value** | The current value, regeneration included. 0 for a pool with no row. |
| **Get Vital Fraction** | The same value as 0 to 1 of the maximum. Bind a bar to this. |
| **Get Vital Max** | The authored maximum. |
| **Has Vital** | Whether the pawn carries a row for the tag. |
| **Is Vital Depleted** | Whether the pool sits at zero. |

> **Note**
>
> 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 runs | What happens |
| --- | --- |
| The pool reaches zero | It 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. |
| Regeneration | Waits. Once the last drain on the pool stops, **Regen Delay Seconds** starts over from there. |
| A second drain on the same pool | The two add up. Stopping one leaves the other running. |
| A spend or a hit | Comes 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](https://rigbak.com/docs/universal-combat-framework/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.

| Setting | Default | Drives |
| --- | --- | --- |
| **Health Vital Tag** | `UCF.Vital.Health` | Death, the **Health Scorer**, the health fraction the AI scores against, and the row an enemy on **Enemy Character Base** starts with. |
| **Stamina Vital Tag** | `UCF.Vital.Stamina` | The 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.

> **Tip: 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](https://rigbak.com/docs/universal-combat-framework/enemy/action-system#decide-when-the-enemy-picks-a-move).

| Entry | Does |
| --- | --- |
| **Vital Gate** | Blocks 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 Scorer** | Favors 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](https://rigbak.com/docs/universal-combat-framework/enemy/reaction-system#scorers-on-reactions).

> **Note**
>
> 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](https://rigbak.com/docs/universal-combat-framework/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](https://rigbak.com/docs/universal-combat-framework/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.

| Where | Reads it to |
| --- | --- |
| A node's **Costs**, the **Vital** cost | Pay 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** gate | Allow the move only while the pool meets a level, without spending any of it. |
| A transition's **Vital Threshold** condition | Choose a different move while the level is not met. |
| A node's **Hooks**, the **Drain Vital** hook | Drain 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 Vital** | Spend **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 Tag** | Charge a raised guard. See [Defense](https://rigbak.com/docs/universal-combat-framework/defense). |

[Gates, Costs and Cooldowns](https://rigbak.com/docs/universal-combat-framework/player/gates-costs-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](https://rigbak.com/docs/universal-combat-framework/action-graphs-in-action-sets) 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](https://rigbak.com/docs/universal-combat-framework/defense#parries-against-enemies).
- **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.

<details>
<summary>Nothing is spending or refilling (Advanced)</summary>

- **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.

</details>

<details>
<summary>Draining several pools in one call (Advanced)</summary>

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](https://rigbak.com/docs/universal-combat-framework/melee-trace-and-damage).

</details>

<details>
<summary>Every vital event (Advanced)</summary>

| Event | Fires |
| --- | --- |
| **On Vital Changed** | On 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 Depleted** | Once per depletion episode, not again until the pool recovers and empties anew. The **Depleted Loose Tag** is already applied when it fires. |
| **On Vital Full** | When 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.

</details>

<details>
<summary>Multiplayer: anchor replication and late-arriving ability systems (Multiplayer)</summary>

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.

</details>

<details>
<summary>Reading the raw replication record (Advanced)</summary>

**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**.

</details>

Previous page: [Seam Patterns](https://rigbak.com/docs/universal-combat-framework/seam-patterns). Next page: [Defense](https://rigbak.com/docs/universal-combat-framework/defense)
