Attributes

Export

Attributes store bounded values such as health, shield, stamina, hunger, battery charge, or durability. Add them to an Attribute Manager when gameplay needs a named value that other UCC components can read, spend, restore, or update over time.

Attribute Manager Inspector listing Health, Shield, and Stamina with Stamina selected

Choose the setup path

Goal	Start here
Give a UCC character health, shield, death, and respawn support	In Character Manager, enable Health. This adds Character Attribute Manager, Character Health, and Character Respawner. Continue with Health.
Add stamina or another value to a character that already has health	Add the new entry to its existing Character Attribute Manager.
Add attributes to a character without the health system	Add Character Attribute Manager to the character so initialization follows the UCC character lifecycle.
Add charge, durability, or another value to an item or ordinary GameObject	Add the standard Attribute Manager component to that object.

The manager stores values; it does not decide what consumes them. Connect each attribute to a Health component, ability Attribute Modifier, item action, UI monitor, or custom system by using the exact same attribute name.

Add and configure an attribute

For a character that needs health, open Tools > Opsive > Ultimate Character Controller > Character Manager, assign Character, enable Health, and select Build Character or Update Character.
Select the GameObject and locate Character Attribute Manager or Attribute Manager in the Inspector.
Select the plus button below the Attribute list. Select the new row to show its settings.
Set Name to a unique, nonempty value such as Stamina. Names are case-sensitive at runtime, so copy the same spelling into every component that references it.
Set Min Value, Max Value, and the starting Value. The Inspector keeps the range valid and clamps the starting value inside it.
Choose Auto Update Value Type. Use None for a value changed only by gameplay, Increase to move toward Max Value, or Decrease to move toward Min Value.
When automatic updates are enabled, configure Update When Inactive, Auto Update Start Delay, Auto Update Interval, and Auto Update Amount.
Configure the component that consumes the value. For example, select Health in Character Health > Health Attribute, or select Stamina in an ability’s Attribute Modifier.
Enter Play Mode and change the value through the real gameplay action before duplicating the setup.

Disabling Health in Character Manager removes the character’s attribute manager together with Character Health and Character Respawner. Preserve or recreate any custom attributes before deliberately removing that managed component set.

Choose the value and update settings

Setting	Decision
Name	Use a stable, unique identifier. `GetAttribute` and UCC consumers match this exact string.
Min Value and Max Value	Define the legal range. Runtime assignments and automatic updates are clamped to these bounds.
Value	Set the starting value captured when the attribute initializes. `ResetValue()` returns to this starting value.
Auto Update Value Type	Choose Increase for regeneration, Decrease for continuous depletion, or None when another system owns every change.
Update When Inactive	Enable it only when automatic updates must continue while the owning GameObject is inactive.
Auto Update Start Delay	Set how long an automatic update waits after initialization or a direct value change. Every `Value` assignment restarts this delay.
Auto Update Interval	Set the time between automatic update steps. Short intervals look smoother but execute more often.
Auto Update Amount	Enter the positive amount applied on each step. Increase adds it; Decrease subtracts it.

Use the States foldout only when a named UCC state should override attribute settings. Keep the default values correct first, then test every state transition that changes the range or automatic update behavior. See the State System.

Configure common scenarios

Health and a regenerating shield

Keep the Health attribute at its full starting value with Auto Update Value Type set to None unless the game deliberately regenerates health. Add a separate Shield attribute, choose Increase, and use Auto Update Start Delay to create the pause after taking damage. In Character Health, set Health Attribute and Shield Attribute to those exact names.

The Health component applies shield damage before health and provides damage, healing, death, hitbox, and fall-damage behavior. Follow the direct child guide: Health.

Stamina used by an ability

Add Stamina to Character Attribute Manager and let it regenerate with Increase. On the ability, select Stamina in Attribute Modifier, set a negative Amount, and enable the modifier’s Auto Update when the cost should repeat while the ability remains active. The ability checks the modifier before starting and can stop when the repeated cost reaches the minimum.

The ability modifier temporarily owns the attribute’s auto-update settings while active, then restores the previous settings and schedules the normal attribute update again. Test the transition from drain to regeneration rather than configuring both in isolation.

Hunger or another continuous countdown

Choose Decrease, set the starting Value near Max Value, and use a longer Auto Update Interval with a suitable Auto Update Amount. Another gameplay system must decide what happens at the minimum; the Attribute Manager only changes and reports the value.

Item charge or durability

Put an Attribute Manager on the item when the value belongs to that item rather than the character. UCC item actions can reference values such as a usable action’s use attribute or a shield’s durability attribute. Ensure the action’s attribute name matches the manager entry exactly.

How attributes run

When an Attribute Manager initializes, it builds a name lookup and records each attribute’s starting value. Assigning Value clamps it between Min Value and Max Value, sends OnAttributeUpdateValue, cancels the previous automatic-update schedule, and starts a new delay when the attribute is not already at its destination.

After the delay, Increase adds Auto Update Amount until Max Value, while Decrease subtracts it until Min Value. Each step sends another update event. Reaching the destination sends OnAttributeReachedDestinationValue on that Attribute instance. If Update When Inactive is disabled, the automatic update does not run while the owning GameObject is inactive.

Attribute names must remain unique. The manager builds its runtime lookup by name, and GetAttribute returns null when no exact match exists.

Verify in Play Mode

Inspect the manager immediately after the scene starts. Every attribute should begin inside its configured range with the intended starting value.
Trigger the real action that spends or restores the value. Confirm it changes once by the expected amount and never passes its minimum or maximum.
For an auto-updating attribute, change the value and time the Auto Update Start Delay. Confirm each later step follows Auto Update Interval and reaches the correct bound.
Change the value again during the delay. Confirm the delay restarts rather than allowing an older scheduled update to run.
Start and stop any ability that uses Attribute Modifier. Confirm the ability cost, minimum-value stop, and return to the attribute’s normal regeneration behavior.
If Update When Inactive matters, disable and re-enable the GameObject during the delay and during repeated updates. Confirm the result matches the chosen setting.
Verify every UI element and consuming component follows the correct attribute, especially when Health, Shield, and Stamina exist together.
Test any required reset path. Character Health resets its configured Health and Shield attributes on respawn; custom attributes need their own deliberate reset behavior.

Troubleshooting

Symptom	Check	Fix
A component cannot find the attribute.	Its name may be blank, duplicated, misspelled, or use different capitalization.	Give every entry a unique name and copy that exact value into the consuming component.
The value immediately snaps to an unexpected number.	Value may be outside Min Value and Max Value, or a state may override the range.	Correct the default range, inspect active States, and retest from a fresh initialization.
Regeneration never starts.	Auto Update Value Type may be None, the value may already be at its destination, or the GameObject may be inactive without Update When Inactive.	Choose Increase or Decrease, move the value away from its destination, and select the inactive behavior deliberately.
Regeneration begins too soon after repeated damage or use.	Auto Update Start Delay may be too short, or an active State or Attribute Modifier may temporarily replace the update settings.	Inspect the active overrides, then increase the normal start delay and retest the complete transition.
A drain increases the value instead.	Auto Update Amount on the Attribute should be positive, or an Attribute Modifier may have the wrong sign.	Use a positive Attribute amount with Decrease, and a negative modifier Amount for a cost.
An ability starts without enough stamina or stops immediately.	Its Attribute Modifier may reference the wrong name, use an unsuitable amount, or begin at the minimum.	Select the correct attribute, verify the cost against the starting value, and retest the ability from full stamina.
Health changes but the shield does not absorb damage.	Character Health > Shield Attribute may be empty or may not match the Shield entry.	Assign the exact shield name and verify the shield starts above its minimum.
Custom attributes disappeared after a Character Manager update.	The Health option may have been disabled, which removes Character Attribute Manager with the managed health set.	Restore the managed components and attributes from version control or a backup, then keep Health enabled when using that set.
The UI does not update.	It may observe a different GameObject or attribute name, or it may not listen for `OnAttributeUpdateValue`.	Point the monitor at the manager’s GameObject and exact name, then verify the update event is registered and unregistered correctly.

Health covers health, shield, damage, healing, death, and fall damage.
Character Creation explains the Character Manager workflow that adds the managed health component set.
Abilities explains ability configuration and the Attribute Modifier shared by abilities.
Usable Item Actions describes item and character use attributes.
Shield uses an item Attribute Manager for durability.
Die connects depleted health to character death and respawn.
Events explains registering and unregistering UCC events.
Event Names lists the attribute update, destination, and modifier events.

Developer reference

Retrieve an attribute by its exact name, guard against a missing entry, and change it through Value so clamping, events, and the automatic-update delay all run.

using UnityEngine;
using Opsive.Shared.Events;
using Opsive.UltimateCharacterController.Traits;
using Attribute = Opsive.UltimateCharacterController.Traits.Attribute;

[RequireComponent(typeof(AttributeManager))]
public class StaminaConsumer : MonoBehaviour
{
    private AttributeManager m_AttributeManager;
    private Attribute m_Stamina;

    private void Awake()
    {
        m_AttributeManager = GetComponent<AttributeManager>();
        m_Stamina = m_AttributeManager.GetAttribute("Stamina");
        EventHandler.RegisterEvent<Attribute>(gameObject, "OnAttributeUpdateValue", OnAttributeUpdateValue);
    }

    public bool TrySpend(float amount)
    {
        if (m_Stamina == null || amount < 0 || !m_Stamina.IsValid(-amount)) {
            return false;
        }

        m_Stamina.Value -= amount;
        return true;
    }

    private void OnAttributeUpdateValue(Attribute attribute)
    {
        if (attribute == m_Stamina) {
            Debug.Log($"Stamina: {attribute.Value}");
        }
    }

    private void OnDestroy()
    {
        EventHandler.UnregisterEvent<Attribute>(gameObject, "OnAttributeUpdateValue", OnAttributeUpdateValue);
    }
}

The current Version 3 runtime surface includes:

AttributeManager.Attributes to replace or inspect the managed array and GetAttribute(string) to retrieve an entry.
Attribute.Value, MinValue, and MaxValue, with clamping performed through the Value setter.
ScheduleAutoUpdate(float), CancelAutoUpdate(), IsAtDestinationValue(), IsValid(float), and ResetValue() for lifecycle control.
AttributeModifier.Initialize, IsValid, and EnableModifier for one-time or repeated changes owned by abilities and other systems.
OnAttributeUpdateValue on the manager’s GameObject, OnAttributeReachedDestinationValue on the Attribute instance, and OnAttributeModifierAutoUpdateEnabled on the AttributeModifier instance.