Item Abilities

Item abilities connect character input and animation to equipped items and their Item Actions. Regular abilities handle character-wide behavior such as jumping, falling, and dying; item abilities handle aiming, using, reloading, blocking, dropping, and switching equipment. They appear in a separate Item Abilities list on the Ultimate Character Locomotion component.

Multiple item abilities can usually remain active together. For example, Aim can stay active while Use fires a weapon. An item ability can still block another ability, change character input or rotation, and control the Animator when its behavior requires it.

Add and configure an item ability

1. Select the character GameObject.
2. In the Ultimate Character Locomotion component, expand Item Abilities.
3. Select the plus button and choose the concrete item ability type.
4. Select the new row to show its settings below the list, then confirm Enabled.
5. Configure its Input Names, Slot ID, Action ID, Item Category, and animation settings where that ability exposes them.
6. Drag the row to the required list position. List order does not normally decide whether item abilities may run together, but it does decide which active item ability supplies the Animator state for a slot.
7. Equip a compatible item and verify the complete action in Play Mode.

Choose by item scenario

Aim, use, and protect a held item

For specialized melee behavior, In Air Melee Use extends Use for airborne attacks, and Melee Counter Attack starts a counterattack after a valid block.

Defend, reload, or discard equipment

Equip and switch loadouts

Item Set is the shared authoring reference for equipment-switching abilities. It is an abstract base, so select one of these concrete abilities from the picker instead:

• Equip Unequip performs the actual animated equip and unequip operation for an Item Set category.
• Equip Next and Equip Previous move through valid Item Sets in one category.
• Equip Scroll chooses the next or previous valid Item Set from an axis value.
• Toggle Equip switches between the active Item Set and the category’s default set.

Make the matching decisions first

• Slot ID selects the equipment slot an ability controls. On abilities that support it, -1 applies to all compatible slots.
• Action ID must match the Item Action on the equipped Character Item. Use separate Use or Reload abilities when the same item exposes different actions or controls.
• Item Category connects an Item Set switcher to an Item Set Group. Add an Equip Unequip ability with the same category for Equip Next, Equip Previous, Equip Scroll, or Toggle Equip to perform the change.
• Use separate category-specific switchers when primary weapons, secondary items, or grenades need independent controls.
• If multiple Item Set Groups can supply the same slot, the earlier group in the Item Set Manager has the higher equipment priority.

Understand concurrency and list order

Item abilities do not use list priority to decide ordinary coexistence. They can be active together unless an ability explicitly blocks or stops another one. Important built-in relationships include:

• Aim and Use can run together.
• An active Use has priority over Reload for the item being used.
• Equip Unequip can prevent Use or Reload while an item is being unequipped.
• Drop resolves active Use or Reload behavior before removing the item.
• Item Pullback blocks shootable Use and Reload while its collision volume is obstructed.
• A regular character ability can still block an item ability; Interact is a common example.

List order matters when two active item abilities both provide Animator values for the same slot. The first active row with a usable Item State Index or substate value wins for that parameter. Move the animation that should win higher in Item Abilities. An Item State Index of -1 means that ability does not provide the parameter.

Verify in Play Mode

1. Equip the Character Item and confirm its slot, Item Category, and Item Action match the item ability.
2. Keep the Ultimate Character Locomotion Inspector visible, trigger the action, and confirm (Active) appears beside the expected item ability.
3. Confirm the correct slot changes animation and that the expected Item Action runs.
4. Hold Aim while starting Use and confirm both remain active when the item supports that combination.
5. Try to reload the item while it is actively being used and confirm Use keeps control. After Use stops, confirm Reload can start.
6. For Item Sets, switch to another valid set and confirm Equip Unequip completes the visible equipment and Animator transition.
7. For third-person Item Pullback, move the configured collider near an obstacle and confirm shootable Use and Reload resume only after the obstruction clears.

Troubleshoot item abilities

• The ability is missing from the picker: confirm the required perspective package is installed. Item Set is an abstract reference; add a concrete switcher such as Equip Unequip or Equip Next.
• The row becomes active but the item does nothing: confirm the item is equipped in Slot ID and its Item Action uses the matching Action ID.
• The wrong animation plays: check Item State Index, the item’s substate configuration, and which active item ability appears first in the list.
• An Item Set switcher is disabled or has no effect: add Equip Unequip for the same Item Category, then confirm the target Item Set is valid for the current inventory.
• Use or Reload will not start: check for an active Equip Unequip, Drop, Item Pullback, Interact, or another item ability that deliberately blocks the action.
• Equip, reload, block, or drop never completes: verify the configured animation event or duration on the linked ability and its Item Action.
• One Item Set Group unexpectedly replaces another: check Item Set Group order and whether both groups claim the same slot.

Related topics

• Abilities explains the shared lifecycle, input types, and character-ability priority system.
• Items and Inventory explains the complete character item workflow.
• Item Set and Rules explains Item Set Groups, validity, and equipment selection.
• Item Actions explains how Action IDs connect abilities to item behavior.
• New Ability provides the base authoring workflow used when creating a custom ItemAbility subclass.

Developer reference

The built-in event system sends OnCharacterItemAbilityActive with the item ability and an active-state boolean whenever an item ability starts or stops. The corresponding Unity event on the locomotion component is also invoked.

using UnityEngine;
using Opsive.Shared.Events;
using Opsive.UltimateCharacterController.Character.Abilities.Items;

public class MyObject : MonoBehaviour
{
    /// <summary>
    /// Initialize the default values.
    /// </summary>
    public void Awake()
    {
        EventHandler.RegisterEvent<ItemAbility, bool>(gameObject, "OnCharacterItemAbilityActive", OnItemAbilityActive);
    }

    /// <summary>
    /// The specified item ability has started or stopped.
    /// </summary>
    /// <param name="itemAbility">The item ability that has been started or stopped.</param>
    /// <param name="activated">Was the ability activated?</param>
    /// </summary>
    private void OnItemAbilityActive(ItemAbility itemAbility, bool activated)
    {
        Debug.Log(itemAbility + " activated: " + activated);
    }

    /// <summary>
    /// The GameObject has been destroyed.
    /// </summary>
    public void OnDestroy()
    {
        EventHandler.UnregisterEvent<ItemAbility, bool>(gameObject, "OnCharacterItemAbilityActive", OnItemAbilityActive);
    }
}