Health

The Health component uses the Attribute Manager to determine how much health or shield the object has left. The Health component is a generic component that can work on any object – it doesn’t have to only be added to an Ultimate Character Controller character. The Character Health is a subclass of the Health component and this allows the character to take fall damage. When the object dies a set of objects can be spawned or destroyed. This is useful for example if you want to spawn wood shards in the case of a wooden crate.

API

If you’d like to deal damage to the health component directly you can call the Damage method. This method is overloaded which allows for many different damage options. ImmediateDeath will kill the object immediately. The object can be healed with the Heal method.

using UnityEngine;
using Opsive.UltimateCharacterController.Traits;

public class MyObject : MonoBehaviour
{
    [Tooltip("The character that has the health component.")]
    [SerializeField] protected GameObject m_Character;

    /// <summary>
    /// Damages and heals the character.
    /// </summary>
    private void Start()
    {
        var health = m_Character.GetComponent<Health>();
        // Cause 10 damage to the character.
        health.Damage(10);

        // Heal the character by 10.
        health.Heal(10);

        // Kill the character.
        health.ImmediateDeath();
    }
}

Events

The Health component exposes three events: OnHealthDamage, OnHeal, and OnDeath. These events are executed through the Event System and are also executed with Unity’s built-in event system.

OnHealthDamage

When the Health component takes damage it will execute the “OnHealthDamage” event. This event can then be used by other components to determine that an action needs to be taken. For example, using the event system you can register for the OnHealthDamage event:

EventHandler.RegisterEvent<float, Vector3, Vector3, GameObject, Collider>(gameObject, "OnHealthDamage", OnDamage);

And then the OnDamage method will execute when the Health component takes damage:

private void OnDamage(float amount, Vector3 position, Vector3 force, GameObject attacker, Collider hitCollider)
{
   Debug.Log("Object took " + amount + " damage at position " + position + " with force " + force + " by attacker " + attacker + ". The collider " + hitCollider + " was hit.");
}

With this the full component looks like:

using UnityEngine;
using Opsive.Shared.Events;

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

    /// <summary>
    /// The object has taken damage.
    /// </summary>
    /// <param name="amount">The amount of damage taken.</param>
    /// <param name="position">The position of the damage.</param>
    /// <param name="force">The amount of force applied to the object while taking the damage.</param>
    /// <param name="attacker">The GameObject that did the damage.</param>
    /// <param name="hitCollider">The Collider that was hit.</param>
    private void OnDamage(float amount, Vector3 position, Vector3 force, GameObject attacker, Collider hitCollider)
    {
        Debug.Log("Object took " + amount + " damage at position " + position + " with force " + force + " by attacker " + attacker + ". The collider " + hitCollider + " was hit.");
    }

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

OnHealthHeal

The “OnHeal” event will be executed when the Heal method is called. This will increase the object’s health. You can subscribe to the OnHealth with:

EventHandler.RegisterEvent<float>(gameObject, "OnHealthHeal", OnHeal);

When OnHeal is called it will include the amount of health that the object was healed by.

/// <summary>
/// The object has been healed.
/// </summary>
/// <param name="amount">The amount of health that the object was healed by.</param>
private void OnHeal(float amount)
{
    Debug.Log("The object was healed with " + amount + " health.");
}

OnDeath

The Health component is also responsible for sending the “OnDeath” event which you can subscribe to by calling:

EventHandler.RegisterEvent<Vector3, Vector3, GameObject>(gameObject, "OnDeath", OnDeath);

When OnDeath is called it will include the force, position, and attacker that caused the death. These parameters will be the same value as those received by “OnHealthDamage”.

/// <summary>
/// The object has died.
/// </summary>
/// <param name="position">The position of the force.</param>
/// <param name="force">The amount of force which killed the object.</param>
/// <param name="attacker">The GameObject that killed the object.</param>
private void OnDeath(Vector3 position, Vector3 force, GameObject attacker)
{
    Debug.Log("The object was killed by " + attacker);
}

Invincible

Set to true if the object is invincible and cannot be destroyed.

Time Invincible After Spawn

The amount of time after the object spawns that it should be invincible. This is useful in an intense fire fight and you want to give the player a few moments to get their bearing before they can be damaged.

Health Attribute

The name of the attribute within the Attribute Manager that should be used for the object’s health. By default, the health will not regenerate automatically.

Shield Attribute

The name of the attribute within the Attribute Manager that should be used for the object’s shield. In many games the shield can regenerate so that’s why the Health component can use a second attribute.

Hitboxes

Maps a collider to a multiplier to adjust the damage based on the collider hit. This can be used for instant kills with a headshot. For an instant headshot kill the collider should be the character’s head collider, and the multiplier should be an extremely large value. When the head collider is damaged the multiplier value will increase the amount of damage done and with a large enough value the object will instantly die.

Max Hitbox Collision Count

The maximum number of colliders that can be detected when determining if a hitbox was damaged.

Spawned Objects on Death

A list of objects that should spawn when the object dies. This can be used for particle effects upon death.

Destroyed Objects on Death

A list of objects that should be destroyed when the object dies. This can be used to cleanup any objects that the object spawned.

Deactivate on Death

Set to true if the object should be deactivated when the object is killed.

Death Layer

The layer that the object should occupy upon death. This can be used to have the physics engine ignore the main CapsuleCollider on the character and instead use the ragdoll colliders.

Take Damage Audio Clip Set

A set of AudioClips which can be played when the object takes damage.

Heal Audio Clip Set

A set of AudioClips which can be played when the object is healed.

Death Audio Clip Set

A set of AudioClips which can be played when the object dies.

Apply Fall Damage

Added with the Character Health component, optionally determine if the character should take damage after landing from a predetermined height.

Min Fall Damage Height

The minimum height that the character needs to fall before taking any fall damage.

Min Fall Damage

The amount of damage to apply to the character when the character falls from the minimum height.

Max Fall Damage

The amount of damage to apply to the character when the character falls from the maximum height.

Death Height

The height at which the character should be killed because they fell from too great of a height.

Damage Curve

Specifies how much fall damage to apply based on the fall height. The x axis (0 – 1) represents the distance fallen and the y axis (0 – 1) represents the amount of damage to apply. A value of 0 on the x axis represents the minimum fall damage height while a value of 1 represents the death height. A value of 0 on the y axis represents the minimum amount of fall damage while a value of 1 represents the maximum fall damage.