Equip Unequip

The Equip Unequip item ability is responsible for actually doing the item equip or unequip. When any other equip item ability are activated the actual equip/unequip is done by the Equip Unequip ability. Instead of equipping or unequipping a specific slot the ability instead works by Item Set. By working with ItemSets it ensures the wrong combination of weapons aren’t equipped. The ability can be started manually by calling the StartEquipUnequip(ItemSetIndex) method.

Equip Troubleshooting

If your item isn’t equipping ensure the following is set:

  • The Item Set Manager contains a reference to the Item Collection.
  • The Equip Unequip ability exists and has an Item Set Category set to the same category as what the Item Definition belongs to.
  • The Equip Event on the Item component is set correctly. If it is waiting for an animation event ensure the Animator executes the OnAnimatorItemEquip event. As a test to ensure this is not the cause you can disable the Wait for Animation Event toggle so it will instead equip after a set duration.
  • Similar to above, ensure the Equip Complete Event is set correctly. If Wait for Animation Event is enabled then the ability will wait for the OnAnimatorItemEquipComplete event.
  • The Item Definition is specified within the Default Loadout of the Inventory (this only applies if you want your item equipped when the character spawns).
  • The Item Definition that is specified within the Default Loadout matches the Item Definition specified on your Item component. The Item component is located under the YourCharacter/Items/YourItem GameObject.
  • The First/Third Person Perspective Item component specifies a Visible Object. The First/Third Perspective Item component is located under the YourCharacter/Items/YourItem GameObject.


In order to equip or unequip an item the StartEquipUnequip method can be started. The item set index parameter is the corresponding index within the Item Set Manager that should be equipped.

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

public class MyAIAgent : MonoBehaviour
    [Tooltip("A reference to the Ultimate Character Controller character.")]
    [SerializeField] protected GameObject m_Character;

    /// <summary>
    /// Equips the item.
    /// </summary>
    private void Start ()
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        if (characterLocomotion != null) {
            // Equip a specific index within the ItemSetManager with the EquipUnequip ability.
            var equipUnequip = characterLocomotion.GetAbility<EquipUnequip>();
            if (equipUnequip != null) {
                // Equip the ItemSet at index 2 within the ItemSetManager.

Inspected Fields

Auto Equip

Mask which specifies when to auto equip a new item.

  • Always: Always equip a picked up item.
  • Unequipped: Equip the item if there are no items equipped.
  • OutOfUsableItem: Equip the item if the current item has no more usable Item Definitions left.
  • NotPreset: Equip the item if the item hasn’t been added to the inventory already.
  • FirstTime: Equip the item the first time the item has been added.
Equip Item State Index

The Item State Index while equipping. This index will be set within the animator so an equip animation can play.

Unequip Item State Index

The Item State Index while unequipping. This index will be set within the animator so an unequip animation can play.

Aim Item Substate Index Addition

The value to add to the Item Substate Index when the character is aiming.