Health

Export

Health turns Attribute Manager values into damage, healing, shield, death, and respawn behavior. Use Character Health for a UCC character, or the generic Health component for a crate, target, or other GameObject.

Choose the setup

Goal	Components to use
A UCC character can take damage and respawn	Character Attribute Manager, Character Health, and Character Respawner. Character Manager adds this set when Health is enabled.
A character should also play a death ability	Add Die to Ultimate Character Locomotion > Abilities after creating the health set. Character Manager does not add Die with the Health option.
A character should ragdoll or revive	Add and configure the Ragdoll or Revive ability in addition to the health set.
An ordinary object can take damage	Add Attribute Manager and Health to the same GameObject. Add Respawner only when that object should return.

Health requires an Attribute Manager on the same GameObject. Its Health Attribute and optional Shield Attribute select entries from that manager by name.

Set up character health

Place the character in the scene and open Tools > Opsive > Ultimate Character Controller > Character Manager.
Assign Character, enable Health, and select Build Character or Update Character.
Select the character and confirm it now has Character Attribute Manager, Character Health, and Character Respawner.
In Character Attribute Manager, select the default Health entry and set its Min Value, Max Value, and starting Value. The default entry starts at 100 with a minimum of 0 and maximum of 100.
In Character Health, select Health for Health Attribute.
Add and configure a Shield attribute only when damage should consume a separate shield first. Select it in Shield Attribute.
If the character needs a visible death animation, add Die to the ability list and verify its Animator transitions.
Configure Character Respawner for the intended return location and delay, then test the complete damage-to-respawn sequence in Play Mode.

For a non-character object, add Attribute Manager and Health manually, create the same named attributes, and choose them from the Health Inspector. The generic Health component supports damage, healing, hitboxes, death objects, audio, Unity events, and optional deactivation, but it does not add character fall damage.

Configure health and shield

Damage is applied to Shield first and Health second. Death occurs when neither configured attribute remains above its Min Value.

Healing uses the opposite priority: Heal fills Health first, then puts any remaining amount into Shield. Use the Attribute Manager’s automatic update when Shield should regenerate independently after a delay.

Field	Version 3 default	Use it for
Invincible	Disabled	Ignore normal damage while a state, cutscene, or gameplay rule protects the object.
Time Invincible After Spawn	`0` seconds	Ignore normal damage for this duration after `OnRespawn`. Before the first respawn, Version 3 compares the value with time since application start.
Health Attribute	`Health`	Select the primary Attribute Manager value.
Shield Attribute	(None)	Select an optional value that absorbs damage before Health.

Keep normal Health automatic updating set to None unless the game deliberately regenerates it. For a regenerating Shield, choose Increase on the Shield attribute and configure its delay, interval, and amount. Every shield value change restarts that delay.

See Attributes for the complete automatic-update workflow.

Configure hit locations

Use Hitboxes when specific colliders should change non-radius damage, such as reduced limb damage or increased head damage:

Expand Hitboxes in Health.
Add an entry and assign its Collider.
Set Damage Multiplier to 1 for unchanged damage, below 1 for reduced damage, or above 1 for increased damage.
Keep Max Hitbox Collision Count at its default 10 unless the fallback raycast can encounter more overlapping colliders.
Test each collider with the actual weapon or impact that supplies the hit collider and damage direction.

Head collider configured as a Health hitbox with an increased damage multiplier

Hitbox multipliers apply only to non-radius damage that includes a nonzero direction and a hit collider. Radius damage does not use the multiplier because one explosion can overlap multiple colliders.

Configure feedback and death

Use the foldouts in the Health Inspector for focused feedback:

Audio > Take Damage, Heal, and Death select the Audio Clip Sets played for those outcomes. Lethal damage plays Death audio instead of Take Damage audio.
UI > Damage Popup Manager ID connects the Health component to a registered Damage Popup Monitor. Leave the default -1 when no popup manager is used.
Events exposes Unity events for damage, healing, and death. Use these for local Inspector wiring; use UCC events when several systems or code listeners need the notification.
On Character Health, Damaged Effect and Damaged Effect Index select an existing character Effect to start after accepted damage.

Expand Death to configure the result:

Field	Version 3 default	Behavior
Spawned Objects On Death	Empty	Instantiates each prefab through the object pool at the object’s position and rotation.
Destroyed Objects On Death	Empty	Returns pooled objects to their pool or destroys ordinary objects.
Deactivate On Death	Disabled	Deactivates the object after Deactivate On Death Delay.
Deactivate On Death Delay	`0` seconds	Delays deactivation when that option is enabled. Keep it shorter than the minimum respawn time.
Death Layer	None	Moves the object to a single layer while dead; Character Health also updates the locomotion collision layer.

Health cancels Health and Shield regeneration on death. On OnRespawn, it restores those two attributes to their recorded starting values and restores the alive layer. Spawned or destroyed death objects are not automatically reversed; another system must restore any persistent scene state.

The Character Respawner added by Character Manager defaults to Start Location, a random delay between Min Respawn Time 2 and Max Respawn Time 3, and scheduling on death. Follow Respawner when the character should use a Spawn Point, stay dead, or be revived by another system.

Configure fall damage

Character Health adds a Fall Damage foldout. The generic Health component does not receive character landing events.

Field	Version 3 default	Behavior
Apply Fall Damage	Disabled	Enables damage when the reported fall height reaches the minimum.
Min Fall Damage Height	`3`	Falls below this height do no damage.
Min Fall Damage	`1`	Damage at the minimum height.
Max Fall Damage	`50`	Damage just below Death Height.
Death Height	`20`	A fall at or above this height sends infinite damage through the normal damage path.
Damage Curve	Linear	Maps the normalized distance between minimum height and death height to the range between minimum and maximum damage.

Test the curve with several known ledge heights. Invincible and Time Invincible After Spawn also guard fall damage because Character Health sends the calculated amount through the normal Damage method.

How health runs

An accepted damage request follows this order:

Reject zero damage, an already-dead object, Invincible, or the active spawn grace period.
Apply a qualifying hitbox multiplier.
Subtract from Shield down to its minimum, then apply any remainder to Health down to its minimum.
Apply force through the character force interface or a non-kinematic Rigidbody.
Send damage events and update the optional damage popup.
If both configured attributes are at their minimum, run death behavior and send OnDeath; otherwise play Take Damage audio.

Death spawns and destroys configured objects, changes the death layer, plays Death audio, optionally schedules deactivation, cancels attribute regeneration, and notifies UCC systems. Ultimate Character Locomotion, Die, Ragdoll, inventory, camera, UI, and Respawner can respond to the same OnDeath event.

Heal clamps the applied amount to the available Health and Shield capacity and returns false when nothing changed. Healing attribute values after death does not run the respawn lifecycle by itself; use Respawner or a configured Revive workflow to restore the full character state.

Verify in Play Mode

Confirm the Inspector shows the intended starting Health and Shield values after initialization.
Apply damage smaller than the current Shield. Shield should decrease, Health should remain unchanged, and shield regeneration should restart only after its delay.
Apply enough damage to exhaust Shield. Confirm only the remainder reduces Health.
Heal a partially damaged object. Health should fill before any remaining amount restores Shield.
Strike every configured hitbox with the real damage source. Confirm its multiplier changes non-radius damage and radius damage remains unmultiplied.
Toggle Invincible, then respawn and test during Time Invincible After Spawn. No damage, force, damage event, or popup should occur while the request is rejected.
Apply lethal damage. Confirm death audio, Unity/UCC events, layer changes, death objects, ability behavior, and deactivation occur once.
Let Respawner complete. Health and Shield should return to their starting values, the alive layer should be restored, and the character should move and receive damage again after the grace period.
For Character Health, test falls below the minimum, near the minimum, between the limits, and at Death Height.

Troubleshooting

Symptom	Check	Fix
Health shows an Attribute Manager warning or fails during initialization.	The same GameObject may not have Attribute Manager or Character Attribute Manager.	Add the correct manager before Health and create the referenced attributes.
Damage has no effect.	The object may already be considered dead, be Invincible, still be inside the spawn grace period, or receive zero damage.	Confirm at least one configured attribute is above its minimum, then disable immunity or wait for the grace period.
Damage skips Shield.	Shield Attribute may be (None), miss the exact attribute, or already be at its minimum.	Select the Shield entry in Character Health and verify its starting value and range.
Healing restores Shield before Health.	Another system may be changing the attributes directly rather than calling `Health.Heal`.	Use `Heal` when the intended rule is Health first, then Shield.
A headshot multiplier does not apply.	The damage may be radius-based, omit its direction or hit collider, or reference a different collider.	Send non-radius damage with the actual collider and direction, then verify the Hitboxes entry.
The character reaches zero Health but never plays a death animation.	Character Manager adds the health component set, not the Die ability or its Animator transitions.	Add and configure Die.
The object deactivates after it already respawned.	Deactivate On Death Delay may be longer than the Respawner’s minimum delay.	Shorten the deactivation delay, lengthen the respawn delay, or disable death deactivation.
Shield or Health regenerates after death.	A separate system may be changing the attributes or scheduling its own updates.	Confirm Health owns the same attributes, remove the competing update, and verify death reaches `OnDeath`.
`Heal` raises the values but the dead character remains unusable.	Healing does not send `OnRespawn` or restore locomotion and ability state.	Use Character Respawner or the Revive workflow.
Fall damage never occurs.	The component may be generic Health, Apply Fall Damage may be disabled, or the landing height may be below the minimum.	Use Character Health, enable the option, and test from a measured height above the threshold.
Damage feedback appears twice.	The same response may be wired to both the Inspector Unity event and a UCC event listener.	Keep one owner for each audio, UI, or gameplay response.

Attributes configures bounds, regeneration, names, and attribute events.
Character Creation adds the character health component set through Character Manager.
Die, Ragdoll, and Revive define visible character death and recovery behavior.
Respawner configures timing and return location.
Damage Processor describes reusable damage-data processing.
Health Pickup restores health through a pickup.
Damage Visualization reacts to health damage with character feedback.
Events explains UCC event registration and cleanup.
Event Names lists the standard health, death, and respawn signatures.

Developer reference

Damage, heal, and death APIs

Use positive amounts and the simplest overload that preserves the information the gameplay needs. Damage(float) applies value damage without a direction, force, attacker, or hit collider; richer overloads and Damage(DamageData) support those details.

using UnityEngine;
using Opsive.UltimateCharacterController.Traits;

public class HealthCommands : MonoBehaviour
{
    [SerializeField] private Health m_Health;

    public void ApplyDamage(float amount)
    {
        if (amount > 0) {
            m_Health.Damage(amount);
        }
    }

    public bool ApplyHealing(float amount)
    {
        return amount > 0 && m_Health.Heal(amount);
    }

    public void KillImmediately()
    {
        m_Health.ImmediateDeath();
    }
}

ImmediateDeath temporarily bypasses Invincible and sends enough damage through the normal damage path. In the current Version 3 implementation, Time Invincible After Spawn still rejects that request while its grace period is active.

Useful runtime properties include HealthValue, ShieldValue, combined Value, HealthAttribute, ShieldAttribute, Invincible, and the configured attribute-name, hitbox, death, audio, popup, and Unity-event properties. IsAlive() returns true while either configured Health or Shield is above its minimum.

Health events

using UnityEngine;
using Opsive.Shared.Events;

public class HealthListener : MonoBehaviour
{
    private void Awake()
    {
        EventHandler.RegisterEvent<float, Vector3, Vector3, GameObject, Collider>(
            gameObject, "OnHealthDamage", OnDamage);
        EventHandler.RegisterEvent<float>(gameObject, "OnHealthHeal", OnHeal);
        EventHandler.RegisterEvent<Vector3, Vector3, GameObject>(gameObject, "OnDeath", OnDeath);
    }

    private void OnDamage(float amount, Vector3 position, Vector3 force, GameObject attacker, Collider hitCollider)
    {
        Debug.Log($"Damage remaining after Shield: {amount}");
    }

    private void OnHeal(float amount)
    {
        Debug.Log($"Health and Shield restored: {amount}");
    }

    private void OnDeath(Vector3 position, Vector3 force, GameObject attacker)
    {
        Debug.Log($"Killed by: {attacker}");
    }

    private void OnDestroy()
    {
        EventHandler.UnregisterEvent<float, Vector3, Vector3, GameObject, Collider>(
            gameObject, "OnHealthDamage", OnDamage);
        EventHandler.UnregisterEvent<float>(gameObject, "OnHealthHeal", OnHeal);
        EventHandler.UnregisterEvent<Vector3, Vector3, GameObject>(gameObject, "OnDeath", OnDeath);
    }
}

The current Version 3 event surface is:

OnHealthDamage(float amount, Vector3 position, Vector3 force, GameObject attacker, Collider hitCollider). The float is the damage remaining after Shield absorption in the current processing order.
OnHealthDamageWithData(DamageData damageData) for the structured damage context available during the callback. Scalar Damage overloads use pooled data, so listeners should not retain that instance after the callback.
OnHealthHeal(float amount) with the amount actually applied, not the amount requested.
OnDeath(Vector3 position, Vector3 force, GameObject attacker) after death processing runs.
OnRespawn() from Respawner; Health uses it to reset Health, Shield, layer, and spawn-grace timing.

The Events foldout also exposes Unity callbacks for damage (float, position, force, attacker), healing (float), and death (position, force, attacker). The Unity damage callback does not include the hit collider or full DamageData.