Vitals and Stamina

Give the player health that can be damaged, healed and revived, and a sprint stamina based on heart rate. Sprinting raises the pulse, and when it peaks the player is exhausted until the pulse recovers. In this guide you add PlayerVitals, check its settings and connect a health bar.

On this page

1. Add the component
2. Health
3. Heart-rate stamina
4. Events
5. Connect a health bar
6. Multiplayer
7. Common pitfalls

Add the component#

1. Select the player root, the GameObject with PlayerLocomotion.
2. Add PlayerVitals. The Setup Wizard does not add it.
3. Press Play. Health starts at Max Health.

Health#

maxHealth float default 100, minimum 1

Maximum health, which is also the starting value.

While the player is dead, PlayerLocomotion ignores movement and jump input.

Heart-rate stamina#

The stamina is modelled by PlayerExertion, a field of PlayerVitals. Sprinting only raises the pulse while the player is moving. The pulse is shown in beats per minute (Bpm).

1. Sprint. The pulse rises by Rise Per Second until it reaches Maximum Bpm.
2. Exhaustion. At Maximum Bpm the player is exhausted and CanSprint becomes false. The pulse stays at its peak for Peak Hold Seconds.
3. Release. The hold ends and the pulse must drop to Resume Bpm. The sprint key must also be released once before sprint works again.
4. Recovery. After you stop sprinting, the pulse waits Recovery Delay Seconds. It then drops toward Walking Bpm while you walk, or toward Resting Bpm while you stand.

restingBpm default 72

Pulse while standing still. It is also the starting pulse.

walkingBpm default 90

Pulse the player settles at while walking.

maximumBpm default 176

Pulse at which the player is exhausted and sprint locks.

resumeBpm default 118

Pulse below which an exhausted player may sprint again, after the release.

risePerSecond default 8

Pulse increase per second while sprinting.

walkingRecoveryPerSecond default 5, restingRecoveryPerSecond default 7

Pulse decrease per second while walking and while standing still.

peakHoldSeconds default 3

Seconds the pulse holds at its peak after exhaustion.

recoveryDelaySeconds default 1.5

Seconds after a sprint before the pulse starts to recover.

The Inspector keeps these values in a consistent order. For example, Maximum Bpm is always at least 40 above Resting Bpm, and Resume Bpm stays below Maximum Bpm.

Events#

Connect a health bar#

Subscribe to HealthChanged from code, or wire OnHealthChanged to a method in the Inspector. The bar reads NormalizedHealth, which is the value between 0 and 1:

using Player;
using UnityEngine;
using UnityEngine.UI;

public class HealthBar : MonoBehaviour
{
    [SerializeField] private PlayerVitals vitals;
    [SerializeField] private Slider slider;

    private void OnEnable()
    {
        vitals.HealthChanged += Refresh;
        Refresh(vitals.Health);
    }

    private void OnDisable()
    {
        vitals.HealthChanged -= Refresh;
    }

    private void Refresh(float _)
    {
        slider.value = vitals.NormalizedHealth;
    }
}

Read vitals.Bpm and vitals.CanSprint in Update to show the pulse or a sprint-locked icon.

Multiplayer#

Health is local. The FishNet and PurrNet add-ons do not synchronize it. On a networked game, let the server apply damage and mirror the value to clients with SetHealth.

Common pitfalls#