Ultimate Character Controller

https://opsive.com/support/documentation/ultimate-character-controller
Admin
A powerful and flexible character controller for game development, available on the Unity Asset...
Tokens:29,367
Snippets:182
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Register for Aim Ability Start Event - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/aim

This C# code snippet demonstrates how to register for and handle the 'OnAimAbilityStart' event. This event is invoked when the Aim ability starts, providing boolean parameters to indicate if the ability started and if it was initiated by player input. It also shows how to unregister the event to prevent memory leaks.

```csharp
using UnityEngine;
using Opsive.Shared.Events;

public class MyObject : MonoBehaviour
{
    public void Awake()
    {
        EventHandler.RegisterEvent<bool, bool>(gameObject, "OnAimAbilityStart", OnAim);
    }

    /// <summary>
    /// The Aim ability has started or stopped.
    /// </summary>
    /// <param name="start">Has the Aim ability started?</param>
    /// <param name="inputStart">Was the ability started from input?</param>
    private void OnAim(bool aim, bool inputStart)
    {
        // Ignore the event if the aim ability wasn't explicitly started.
        if (!inputStart) {
            return;
        }
        Debug.Log("Aim ability start: " + aim);
    }

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

--------------------------------

### Ability Starter Abstract Class Methods (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/ability-starter

This snippet outlines the core abstract and virtual methods of the Ability Starter class. These methods define the contract for custom ability starters, including checks for starting the ability, notifications for ability start/stop, and cleanup during object destruction. It serves as a base for creating custom ability start logic.

```csharp
/// <summary>
/// Can the starter start the ability?
/// </summary>
/// <param name="playerInput">A reference to the input component.</param>
/// <returns>True if the starter can start the ability.</returns>
public abstract bool CanInputStartAbility(PlayerInput playerInput);

/// <summary>
/// The ability has started.
/// </summary>
public virtual void AbilityStarted()

/// <summary>
/// The ability has stopped running.
/// </summary>
public virtual void AbilityStopped()

/// <summary>
/// The object has been destroyed.
/// </summary>
public virtual void OnDestroy()
```

--------------------------------

### C# Example Implementation of GetMoveTowardsLocations

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location

This C# code demonstrates an example implementation of the GetMoveTowardsLocations method for an Interact ability. It retrieves MoveTowardsLocation components from the GameObject associated with the m_Interactable object, indicating where the interaction can begin.

```csharp
public override MoveTowardsLocation[] GetMoveTowardsLocations()
{
	return m_Interactable.gameObject.GetCachedComponents<MoveTowardsLocation>();
}
```

--------------------------------

### Custom Usable Action Module Example - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory/action-modules-groups

This C# example shows how to create a custom Usable Action Module by inheriting from UsableActionModule and implementing the IModuleUseItem interface. It logs a customizable message when the item is used.

```csharp
/// <summary>
/// A simple module which has a boolean to enable can start.
/// </summary>
[Serializable]
public class DebugUse : UsableActionModule, IModuleUseItem
{
    [Tooltip("The message to print on Use")]
    [SerializeField] private string m_Message = "Hello :)";

    /// <summary>
    /// Use the item.
    /// </summary>
    public void UseItem()
    {
        Debug.Log(m_Message);
    }
}
```

--------------------------------

### Start and Stop Jump Ability using C# API

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities

This C# code demonstrates how to get a reference to the Ultimate Character Locomotion component and use TryStartAbility and TryStopAbility to control the Jump ability. It checks if the ability is active before attempting to stop it. Dependencies include UnityEngine and Opsive.UltimateCharacterController namespaces.

```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Character.Abilities;

public class MyObject : MonoBehaviour
{
    [Tooltip("The character that should start and stop the jump ability.")]
    [SerializeField] protected GameObject m_Character;

    /// <summary>
    /// Starts and stops the jump ability.
    /// </summary>
    private void Start()
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        var jumpAbility = characterLocomotion.GetAbility<Jump>();
        // Tries to start the jump ability. There are many cases where the ability may not start, 
        // such as if it doesn't have a high enough priority or if CanStartAbility returns false.
        characterLocomotion.TryStartAbility(jumpAbility);

        // Stop the jump ability if it is active.
        if (jumpAbility.IsActive) {
            characterLocomotion.TryStopAbility(jumpAbility);
        }
    }
}
```

--------------------------------

### Start and Stop Earthquake Effect - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/effects

This C# script demonstrates how to get a reference to the Ultimate Character Locomotion component, retrieve an Earthquake effect, and then start and stop it. It checks if the effect is active before attempting to stop it. This is useful for triggering camera shakes or similar effects manually from other game objects.

```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Character.Effects;

public class MyObject : MonoBehaviour
{
    [Tooltip("The character that should start and stop the earthquake effect.")]
    [SerializeField] protected GameObject m_Character;

    /// <summary>
    /// Starts and stops the earthquake effect.
    /// </summary>
    private void Start()
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        var earthquakeEffect = characterLocomotion.GetEffect<Earthquake>();
        // Tries to start the earthquake effect. There are many cases where the effect will not start, 
        // such as if it isn't enabled or if CanStartEffect returns false.
        characterLocomotion.TryStartEffect(earthquakeEffect );

        // Stop the effect if it is active.
        if (earthquakeEffect.IsActive) {
            characterLocomotion.TryStopEffect(earthquakeEffect);
        }
    }
}
```

--------------------------------

### Equip ItemSet Script

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory

This script demonstrates how to equip a specific ItemSet from the ItemSetManager. It requires the character GameObject, the group index, and the ItemSet index as input. The ItemSet must be picked up before it can be equipped. The script finds the EquipUnequip ability and starts the equipping process.

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

/// <summary>
/// Equips the specified ItemSet within the Start method.
/// </summary>
public class Equip : MonoBehaviour
{
    [Tooltip("The character that should drop the item.")]
    [SerializeField] protected GameObject m_Character;
    [Tooltip("The index of the groupthat the ItemSet belongs to.")]
    [SerializeField] protected int m_GroupIndex;
    [Tooltip("The index of the ItemSet that should be equipped.")]
    [SerializeField] protected int m_ItemSetIndex;

    /// <summary>
    /// Equips the ItemSet.
    /// </summary>
    public void Start()
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        var equipUnequipAbilities = characterLocomotion.GetAbilities<EquipUnequip>();
        for (int i = 0; i < equipUnequipAbilities.Length; ++i) {
            if (equipUnequipAbilities[i].ItemSetCategoryIndex == m_CategoryIndex) {
                // Starts equipping to the specified ItemSet.
                // ItemSetIndex: The ItemSet to equip/unequip the items to.
                // ForceEquipUnequip: Should the ability be force started? This will stop all abilities that would prevent EquipUnequip from starting.
                // ImmediateEquipUnequip: Should the items be equipped or unequipped immediately?
                equipUnequipAbilities[i].StartEquipUnequip(m_ItemSetIndex, true, false);
                return;
            }
        }
    }
}
```

--------------------------------

### Custom Item Set Rule Example (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system

An example of a custom ItemSetRule that can be created by inheriting from InventorySystemItemSetRule. This class demonstrates overriding methods to define custom validation logic for item sets and character items.

```csharp
/// <summary>
/// And Example of an ItemSetRule.
/// </summary>
[CreateAssetMenu(menuName = "Opsive/Ultimate Character Controller/Inventory/Example Item Set Rule",
    fileName = "ExampleItemSetRule", order = 0)]
[Serializable]
public class ExampleItemSetRule : InventorySystemItemSetRule
{
    /// <summary>
    /// Returns if an item set is valid for the allowed slots mask.
    /// </summary>
    /// <param name="itemSet">The item set to check.</param>
    /// <param name="allowedSlotsMask">The allowed slots mask.</param>
    /// <returns>Returns true if the item set is valid.</returns>
    public override bool IsItemSetValid(ItemSet itemSet, int allowedSlotsMask)
    {
        return true;
    }
    /// <summary>
    /// Does the character item match this rule.
    /// </summary>
    /// <param name="itemSetRuleStreamData">The item set rule stream data.</param>
    /// <param name="currentPermutation">The current item permutation so far.</param>
    /// <param name="characterItem">The character item to check.</param>
    /// <returns>True if the character item matches this rule.</returns>
    public override bool DoesCharacterItemMatchRule(ItemSetRuleStreamData itemSetRuleStreamData, ListSlice<IItemIdentifier> currentPermutation,
        CharacterItem characterItem)
    {
        // Add some condition here to say whether you item matches this rule or not
        return false;
    }
    /// <summary>
    /// Can the slot be empty for this rule.
    /// </summary>
    /// <param name="slotID">The slot ID to check.</param>
    /// <returns>True if it can be empty.</returns>
    protected override bool CanSlotBeNull(int slotID)
    {
        return true;
    }
}
```

--------------------------------

### Manually Call Drop Item Action in C# - Ultimate Character Controller

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory/item-actions

This C# code snippet demonstrates how to directly call the 'DropItemAction' in the Ultimate Character Controller. It requires obtaining the ItemInfo, ItemAction, and ItemUser components. The example shows how to find an item, adjust its quantity, get the ItemUser, create and initialize the DropItemAction, check if it can be invoked, and finally invoke it. Limitations for certain item actions are also noted.

```csharp
public void ManuallyCallDropItemAction()
{
    //To call an item action directly in code you will need 3 things
    //1) The ItemInfo
    //2) The ItemAction
    //3) The ItemUser

    //First get the item you want. Here we'll get the first stack of apples we find.
    var result = m_Inventory.GetItemInfo(InventorySystemManager.GetItemDefinition("Apple"));
    
    //if the result does not have a value we do no have Apples in the inventory
    if(result.HasValue == false){ return; }
    //We have the apple ItemInfo now.
    var appleItemInfo = result.Value;
    
    //Lets trim to 2 apples maximum
    appleItemInfo = new ItemInfo(Mathf.Max(2, appleItemInfo.Amount), appleItemInfo);
    
    //Lets get the ItemUser. This is usually placed of the same gameobject as the Inventory, but not always
    var itemUser = m_Inventory.GetComponent<ItemUser>();
    
    //now lets create the drop item action, You can cache this object and reuse it if you which for more performance.
    var dropItemAction = new DropItemAction();
    
    //You must initialize the item action before using it. This can be only once
    dropItemAction.Initialize(false);
    
    //OPTIONAL: check if you are allowed to invoke the action (it will do this anyways internally)
    var canInvoke = dropItemAction.CanInvoke(appleItemInfo, itemUser);
    
    //Invoke the action
    dropItemAction.InvokeAction(appleItemInfo, itemUser);
    
    //For some actions you'll even have extra data you can use
    //For example drop action keeps track of the last dropped pickup object
    var droppedPickup = dropItemAction.PickUpGameObject;
}

```

--------------------------------

### Initialize ImpactCollisionData Manually - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory/impact-actions

Shows how to manually initialize ImpactCollisionData, providing all necessary collision details like position, direction, strength, and surface impact. This example is derived from the ImpactZone demo script.

```csharp
var impactCollisionData = m_ImpactCallbackContext.ImpactCollisionData;
impactCollisionData.Reset();
impactCollisionData.Initialize();
impactCollisionData.SetImpactSource(gameObject,null);
impactCollisionData.SetImpactTarget(collider);
impactCollisionData.ImpactDirection = Vector3.zero;
impactCollisionData.ImpactPosition = collider.transform.position + Random.insideUnitSphere;
impactCollisionData.ImpactStrength = 1;
impactCollisionData.SurfaceImpact = m_SurfaceImpact;
```

--------------------------------

### Custom Item Set Rule Example

Source: https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system

Demonstrates how to create a custom item set rule by inheriting from `InventorySystemItemSetRule`.

```APIDOC
## POST /api/itemsetrules

### Description
This section provides an example of a custom item set rule. You can create custom rules by inheriting from the `ItemSetRule` or `InventorySystemItemSetRule` class and implementing the necessary methods.

### Method
POST

### Endpoint
/api/itemsetrules

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This endpoint does not accept a request body for creating item set rules. Rules are defined in code.

### Request Example
```csharp
// Example of an ItemSetRule.
[CreateAssetMenu(menuName = "Opsive/Ultimate Character Controller/Inventory/Example Item Set Rule",
    fileName = "ExampleItemSetRule", order = 0)]
[Serializable]
public class ExampleItemSetRule : InventorySystemItemSetRule
{
    /// <summary>
    /// Returns if an item set is valid for the allowed slots mask.
    /// </summary>
    /// <param name="itemSet">The item set to check.</param>
    /// <param name="allowedSlotsMask">The allowed slots mask.</param>
    /// <returns>Returns true if the item set is valid.</returns>
    public override bool IsItemSetValid(ItemSet itemSet, int allowedSlotsMask)
    {
        return true;
    }
    /// <summary>
    /// Does the character item match this rule.
    /// </summary>
    /// <param name="itemSetRuleStreamData">The item set rule stream data.</param>
    /// <param name="currentPermutation">The current item permutation so far.</param>
    /// <param name="characterItem">The character item to check.</param>
    /// <returns>True if the character item matches this rule.</returns>
    public override bool DoesCharacterItemMatchRule(ItemSetRuleStreamData itemSetRuleStreamData, ListSlice<IItemIdentifier> currentPermutation,
        CharacterItem characterItem)
    {
        // Add some condition here to say whether you item matches this rule or not
        return false;
    }
    /// <summary>
    /// Can the slot be empty for this rule.
    /// </summary>
    /// <param name="slotID">The slot ID to check.</param>
    /// <returns>True if it can be empty.</returns>
    protected override bool CanSlotBeNull(int slotID)
    {
        return true;
    }
}
```

### Response
#### Success Response (200)
This endpoint does not return a response body. Custom rules are compiled into the game's code.

#### Response Example
N/A
```

--------------------------------

### Get Item Info by Item - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory

Retrieves the first matching item stack in the inventory for a given item. Returns a nullable ItemInfo, which will be null if no item stack is found.

```csharp
//You can get the first matching item stack to an item.
var retrievedItemInfo = inventory.GetItemInfo(myItem);
if (retrievedItemInfo.HasValue == false) {
    //No item stack with that description was found in the inventory.
}
```

--------------------------------

### Start Equip Unequip Item - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/item-set/equip-unequip

This C# script demonstrates how to equip an item using the EquipUnequip ability in the Ultimate Character Controller. It retrieves the EquipUnequip ability from the character's locomotion and then calls StartEquipUnequip with a specific item set index. Ensure the 'm_Character' GameObject is assigned in the inspector.

```csharp
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.
                equipUnequip.StartEquipUnequip(2);
            }
        }
    }
}
```

--------------------------------

### Subscribe to Item Ability Activation Events (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities

This C# script demonstrates how to subscribe to and handle the 'OnCharacterItemAbilityActive' event using Opsive's EventHandler. It logs when an item ability starts or stops. This requires the Opsive.Shared.Events and Opsive.UltimateCharacterController.Character.Abilities.Items namespaces.

```csharp
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);
    }
}
```

--------------------------------

### Get All Items in Inventory

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory

Retrieves all items stored within the inventory, excluding specific ignored collections like 'Hide' and 'Loadout'. This provides a comprehensive view of all available items.

```csharp
// Get all the items in the inventory (includes all the item collections except the ignored ones 'Hide' and 'Loadout')
var allItems = inventory.AllItemInfos;
```

--------------------------------

### Create Multiplier Damage Processor - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor

Demonstrates how to create a custom Damage Processor by inheriting from the base DamageProcessor class and overriding the Process function. This example multiplies the damage amount by a specified multiplier before applying it to the target. It requires the 'Ultimate Character Controller' library.

```csharp
using UnityEngine;

[CreateAssetMenu(fileName = "MultiplierDamageProcessor", menuName = "Ultimate Character Controller/Damage Processors/Multiplier Damage Processor")]
public class MultiplierDamageProcessor: DamageProcessor
{
	[SerializeField] protected float m_Multiplier;

	/// <summary>
	/// Processes the DamageData on the DamageTarget.
	/// </summary>
	/// <param name="target">The object receiving the damage.</param>
	/// <param name="damageData">The damage data to be applied to the target.</param>
    public override void Process(IDamageTarget target, DamageData damageData)
    {
		damageData.Amount *= m_Multiplier;
		target.Damage(damageData);
    }
}
```

--------------------------------

### Get All CharacterItems

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item

Illustrates how to retrieve a list of all CharacterItems currently present in the character's inventory. This can be used for UI displays or inventory management.

```csharp
ReadOnlyList<CharacterItem> characterItems = m_Inventory.GetAllCharacterItems();
```

--------------------------------

### Use Item with Use Ability (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence

Shows how an AI agent can use an equipped item by accessing the Ultimate Character Controller and starting the 'Use' ability. This requires a reference to the character's locomotion component and the 'Use' ability itself.

```csharp
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>
    /// Uses the item.
    /// </summary>
    private void Start () 
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        if (characterLocomotion != null) {
            // Get the Use ability.
            var useAbility = characterLocomotion.GetAbility<Use>();
            if (useAbility != null) {
                // Try to start the use ability. If the ability is started it will use the currently equipped item.
                characterLocomotion.TryStartAbility(useAbility);
            }
        }
    }
}
```

--------------------------------

### Get All Character Items in Inventory

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory

Returns a read-only list of all CharacterItems currently stored in the inventory. This provides a snapshot of all owned items.

```csharp
ReadOnlyList<CharacterItem> characterItems = inventory.GetAllCharacterItems();
```

--------------------------------

### Resolve Namespace Conflict with C# Example

Source: https://opsive.com/support/documentation/ultimate-character-controller/getting-started

Demonstrates how to resolve namespace conflicts in C# by enclosing a class within a namespace. This prevents errors when importing assets that may have similarly named classes.

```csharp
using UnityEngine;

public class Health : MonoBehaviour
{
    /// <summary>
    /// Damages the object.
    /// </summary>
    public void Damage()
    {
        // My implementation.
    }
}
```

```csharp
using UnityEngine;

namespace MyProject
{
    public class Health : MonoBehaviour
    {
        /// <summary>
        /// Damages the object.
        /// </summary>
        public void Damage()
        {
            // My implementation.
        }
    }
}
```

--------------------------------

### Accessing and Managing Inventory Items with C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system

Demonstrates how to get references to the inventory system, add items, equip and unequip them using the Character Inventory Bridge. It covers soft and active equipping states and moving items between collections. Assumes the InventorySystemManager and CharacterInventoryBridge are set up.

```csharp
///
/// Get a reference to the Inventory
///
// Get the Inventory system Inventory from anywhere using the manager.
var inventory = InventorySystemManager.GetInventoryIdentifier(1).Inventory;
// Get the character Inventory Bridge from the Inventory.
var characterInventoryBridge = inventory.gameObject.GetCachedComponent<CharacterInventoryBridge>();
// Get all the equippable item collection, returns a Item Collection Group.
var equippableItemCollections = characterInventoryBridge.BridgeItemCollections;
///
/// Add Items
///
//Items must be added to the Inventory before they can be added.
// This adds the item to the main item collection.
var addedItem = inventory.AddItem("Assault Rifle", 1);
///
/// Soft&Active Equip/Unequip Items
///
// Unequipped -> Item is in the Inventory but not in the bridgeItemCollections
// Soft Equipped -> The Item is one of the BridgeItemCollections but it is not actively equipped
// Active Equipped -> The Item is in one fo the BridgeItemCollection and it is actively equipped on the character
// Before an item can be equipped it must be part of one of the Equippable Item Collection.
var equippableCollectionIndex = 0;
var slotIndex = -1; //The itemcollection slot index.
characterInventoryBridge.MoveItemToEquippable(addedItem, equippableCollectionIndex, slotIndex);
// Once the item ins in equippable it can be equipped.
characterInventoryBridge.Equip(addedItem, true);
// And unequipped
characterInventoryBridge.Equip(addedItem, false);
// Note that the item is still in equippable at this point and it can be sent back to default item collection with
characterInventoryBridge.MoveItemToDefault(addedItem, equippableCollectionIndex, slotIndex);
// It is actually more efficient to use the MoveEquip if you plan to move to equippable and equip directly after.
// Moving the item to one of the Equippable item collection and Equipping it can be done in one line of code.
characterInventoryBridge.MoveEquip(addedItem, true);
// It can be unequipped too.
characterInventoryBridge.MoveEquip(addedItem, false);
///
/// Get Active Equipped Items
///
// Get the "Active" equipped item by checking the UCC slotID:
var activeEquippedItemInSlot0 = characterInventoryBridge.GetActiveInventoryItem(0);
//In this case the SlotID is the UCC slotID, not the ItemSlotCollection slot index, they are not always the same.
//Get the soft&active equipped items by looping over the items in the equippable item collections:
var allEquippedItems = characterInventoryBridge.BridgeItemCollections.GetAllItemStacks();
for (int i = 0; i < allEquippedItems.Count; i++) {
    var item = allEquippedItems[i].Item;
    var isActive = characterInventoryBridge.IsItemActive(item);
    //Do stuff with the soft or active equipped item.
}
///
/// Get Soft Equipped Items
/// 
// Get a character Item from an inventory Item.
var slotID = -1; // The Item Set slot. 
var characterItem = characterInventoryBridge.GetCharacterItem(addedItem.Item, slotID);
// For multi inventory item can have multiple character items
var cachedListResult = new List<CharacterItem>();
var characterItems = characterInventoryBridge.GetCharacterItems(addedItem.Item,cachedListResult);
// you can get the inventory item from a character item.
var inventoryItem = characterInventoryBridge.GetInventoryItem(characterItem);
///
/// Drop Items
///
var inventoryDrop = characterInventoryBridge.DropItem(addedItem, true, true);

```

--------------------------------

### Example Custom Movement Type - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/movement-types

A C# example demonstrating a custom Movement Type that does not modify character rotation or input vector. This implementation ensures characters move relative to their current rotation.

```csharp
using Opsive.UltimateCharacterController.Character.MovementTypes;

public class MyMovementType : MovementType
{
    public override bool FirstPersonPerspective { get { return false; } }

    public override float GetDeltaYawRotation(float characterHorizontalMovement, float characterForwardMovement, float cameraHorizontalMovement, float cameraVerticalMovement)
    {
        return 0;
    }

    public override Vector2 GetInputVector(Vector2 inputVector)
    {
        return inputVector;
    }
}
```

--------------------------------

### Get and Return Non-GameObjects with GenericObjectPool

Source: https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool

This C# code snippet shows how to utilize the GenericObjectPool for pooling non-GameObject types derived from System.object. It uses the Get and Return methods to retrieve and return objects to the pool, improving efficiency. Make sure to include the Opsive.Shared.Utility namespace.

```csharp
// Include the namespace that the GenericObjectPool component is located in.
using Opsive.Shared.Utility;

// Keep a reference to the object so it can later be destroyed.
private ActiveInputEvent m_PooledInputEvent;

// Get a new ActiveInputEvent object.
m_PooledInputEvent = GenericObjectPool.Get<ActiveInputEvent>();

// The object can be returned back to the pool at a later point in time.
GenericObjectPool.Return(m_PooledInputEvent);
```

--------------------------------

### Block Item Abilities in Crawl - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability

Implements the ShouldBlockAbilityStart method to prevent item abilities (Equip, Unequip, Use) from starting while the Crawl ability is active. This ensures exclusive control during crawling.

```csharp
/// <summary>
    /// Called when another ability is attempting to start and the current ability is active.
    /// Returns true or false depending on if the new ability should be blocked from starting.
    /// </summary>
    /// <param name="startingAbility">The ability that is starting.</param>
    /// <returns>True if the ability should be blocked.</returns>
    public override bool ShouldBlockAbilityStart(Ability startingAbility)
    {
        return startingAbility is ItemAbility;
    }
```

--------------------------------

### Move Character Towards Destination via Script (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/move-towards

This script demonstrates how to initiate the Move Towards ability programmatically. It requires a reference to the character GameObject and the target destination Vector3. The MoveTowardsLocation method of the MoveTowardsAbility is called on the UltimateCharacterLocomotion component to start the movement.

```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Character.Abilities;

public class MyObject : MonoBehaviour
{
    [Tooltip("The character that should move towards the destination.")]
    [SerializeField] protected GameObject m_Character;
    [Tooltip("The destination that the character should move towards.")]
    [SerializeField] protected Vector3 m_Destination;

    /// <summary>
    /// Starts moving to the destination.
    /// </summary>
    private void Start()
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        characterLocomotion.MoveTowardsAbility.MoveTowardsLocation(m_Destination);
    }
}
```

--------------------------------

### Subscribe to Camera Zoom Event (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/camera

Subscribes to the OnCameraZoom event, which is triggered when the camera controller starts or stops zooming. It takes a boolean indicating the zoom state.

```csharp
EventHandler.RegisterEvent<bool>(gameObject, "OnCameraZoom", OnZoom);

/// <summary>
/// The camera has toggled zoom state.
/// </summary>
/// <param name="zoomed">Is the camera zoomed?</param>
private void OnZoom(bool zoomed)
{
        Debug.Log("The camera is now in a " + (zoomed ? "zoomed" : "not zoomed") + " state.");
}
```

--------------------------------

### Get CharacterItem Actions

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item

Shows how to access the array of ItemAction components attached to a CharacterItem. This allows for executing various item-specific actions like shooting or melee attacks.

```csharp
CharacterItemAction[] itemActions = m_CharacterItem.ItemActions;
```

--------------------------------

### Get Item Infos with Filter/Sort - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory

Retrieves a list of item infos from the inventory based on specified filter and sort parameters. Supports using pooled arrays for efficiency and custom filter functions.

```csharp
//You can get multiple items from your item collections
//You'll need an array to store your item infos.
var array = new ItemInfo[0];
//You can use a pooled array instead of creating a new array each time. IMPORTANT: make sure to return the pooled array once you finished using it.
var pooledArray = GenericObjectPool.Get<ItemInfo[]>();

//Set your filter and sort parameters, for this example we'll filter by category.
var filterParameter = InventorySystemManager.GetItemCategory("MyCategory");

//Item info list slice will have all the itemInfos in the inventory that contain inherits the category.
//You can set whatever filter parameter you want.
var itemInfoListSlice = inventory.GetItemInfos(ref pooledArray, filterParameter,
    //Specify your filter
    (candidateItemInfo, category) => { return category.InherentlyContains(candidateItemInfo.Item); }
);

//IMPORTANT: Don't forget to return the pooled array once you finished using the array.
GenericObjectPool.Return(pooledArray);
```

--------------------------------

### Retrieve Item Category and Create ItemIdentifier in C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory/item-type-definition-category

Provides examples for retrieving the main item category of an ItemDefinition and creating a new ItemIdentifier from an ItemDefinition. These operations are fundamental for item management and instantiation within the system.

```csharp
IItemCategoryIdentifier category = m_ItemDefinition.GetItemCategory();
IItemIdentifier item = m_ItemDefinition.CreateItemIdentifier();
```

--------------------------------

### Get CharacterItem by Identifier

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item

Shows how to fetch a CharacterItem from the inventory based on its unique ItemIdentifier and slot ID. Useful for direct item access when the slot is unknown.

```csharp
CharacterItem characterItem = m_Inventory.GetCharacterItem(itemIdentifier, slotID);
```

--------------------------------

### Get Active Perspective Item

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item

Demonstrates how to retrieve the currently active PerspectiveItem associated with a CharacterItem. This is relevant for visual representation and rendering logic.

```csharp
PerspectiveItem perspectiveItem = m_CharacterItem.ActivePerspectiveItem;
```

--------------------------------

### Example Component Registering and Unregistering an Event - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events

Demonstrates a Unity MonoBehaviour component that registers for a custom 'OnDeath' event upon waking and unregisters it when destroyed. The event includes three parameters: Vector3, Vector3, and GameObject.

```csharp
using UnityEngine;
using Opsive.Shared.Events;

public class MyComponent : MonoBehaviour
{
    public void Awake()
    {
        // Register for the event when the component starts. The event registers with the local GameObject (the first parameter) so 
        // the component must be added to the same GameObject as the object that is sending the "OnDeath" event.
        EventHandler.RegisterEvent<Vector3, Vector3, GameObject>(gameObject, "OnDeath", OnDeath);
    }

    /// <summary>
    /// Receives the "OnDeath" event.
    /// </summary>
    private void OnDeath(Vector3 position, Vector3 force, GameObject attacker)
    {
        Debug.Log("The object " + gameObject + " died.");
    }

    public void OnDestroy()
    {
        // Unregister from the event when the component is no longer interested in it. In this example the component is interested for the lifetime of 
        // the component (Awake -> OnDestroy). 
        EventHandler.UnregisterEvent<Vector3, Vector3, GameObject>(gameObject, "OnDeath", OnDeath);
    }
}
```

--------------------------------

### Create Custom Camera Shake Effect - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/effects

This C# code defines a custom effect that inherits from the base `Effect` class. It overrides `EffectStarted` to schedule the stopping of the effect after 3 seconds using the `Scheduler`, and `Update` to apply positional and rotational forces to the camera. This example showcases how to create custom effects with timed behavior and camera manipulation.

```csharp
using Opsive.UltimateCharacterController.Character.Effects;
using Opsive.UltimateCharacterController.Game;
using Opsive.UltimateCharacterController.Motion;

public class MyEffect : Effect
{
    protected override void EffectStarted()
    {
        base.EffectStarted();

        Scheduler.Schedule(3, StopEffect);
    }

    public override void Update()
    {
        m_CameraController.AddPositionalForce(SmoothRandom.GetVector3Centered(1));
        m_CameraController.AddRotationalForce(SmoothRandom.GetVector3Centered(1));
    }
}
```

--------------------------------

### Accessing Character Items from Inventory (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory/character-item

Demonstrates how to retrieve CharacterItems from the inventory using various methods like getting the active item, an item by its identifier, or all items.

```csharp
CharacterItem characterItem = m_Inventory.GetActiveCharacterItem(slotID);
CharacterItem characterItem = m_Inventory.GetCharacterItem(itemIdentifier, slotID);
ReadOnlyList<CharacterItem> characterItems = m_Inventory.GetAllCharacterItems();
```

--------------------------------

### Override Character Spawning Logic with PUN - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/editors/setup

This C# script demonstrates how to override the GetCharacterPrefab method in the SpawnManagerBase class to customize character spawning logic for PUN multiplayer games. This allows for unique character models per player or team-based spawning. The GetCharacterPrefab method must return a deterministic value on each client.

```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.AddOns.Multiplayer.PhotonPun.Game;
using Photon.Realtime;

public class MySpawnManager : SpawnManagerBase
{
    /// <summary>
    /// Virtual method which allows for a character to be spawned based on the game logic.
    /// </summary>
    /// <param name="newPlayer">The player that entered the room.</param>
    /// <returns>The character prefab that should spawn.</returns>
    protected override GameObject GetCharacterPrefab(Player newPlayer)
    {
        return null; // Replace with your own game logic.
    }
}
```

--------------------------------

### Move Character with Move Method (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence

Provides an example of how to control character movement programmatically using the Move method of the UltimateCharacterLocomotion component. This method allows for precise control over the character's direction and speed, suitable for AI navigation.

```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Game;

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

    private UltimateCharacterLocomotion m_CharacterLocomotion;

    /// <summary>
    /// Initializes the default values.
    /// </summary>
    private void Start()
    {
        m_CharacterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
    }

    /// <summary>
    /// Move the character in the forward direction with a slight turn.
    /// </summary>
    private void Update()
    {
        m_CharacterLocomotion.Move(0, 1, 5);
    }
}
```

--------------------------------

### Get Active and Next ItemSet - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules

Provides methods to retrieve the currently active ItemSet and the next ItemSet in the sequence for a given group index. It also allows fetching the index of the active and next ItemSets. This is useful for understanding the current and upcoming equipment states.

```csharp
ItemSet itemSet = m_ItemSetManager.GetActiveItemSet(groupIndex);

// Get active ItemSet index:
int itemSetIndex = m_ItemSetManager.GetActiveItemSetIndex(groupIndex);

// Get next ItemSet:
ItemSet itemSet = m_ItemSetManager.GetNextItemSet(groupIndex);

// Get next ItemSet index:
int itemSetIndex = m_ItemSetManager.GetNextItemSetIndex(groupIndex);
```

--------------------------------

### C# GetMoveTowardsLocations Method Signature

Source: https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location

This C# method signature defines the interface for retrieving possible MoveTowardsLocation objects that a character can move towards. It's a virtual method within the Ability class, allowing derived classes to implement their specific logic for determining start locations.

```csharp
/// <summary>
/// Returns the possible MoveTowardsLocations that the character can move towards.
/// </summary>
/// <returns>The possible MoveTowardsLocations that the character can move towards.</returns>
MoveTowardsLocation[] GetMoveTowardsLocations()
```

--------------------------------

### Retrieve Combat View Type using C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types

This C# snippet demonstrates how to find the main camera, get the Camera Controller component, and retrieve a specific view type (Combat) using the GetViewType method. It includes error handling for when the camera is not found.

```csharp
using UnityEngine;
using Opsive.Shared.Camera;
using Opsive.UltimateCharacterController.Camera;

public class MyObject : MonoBehaviour
{
    /// <summary>
    /// Retrieves the combat view type.
    /// </summary>
    private void Start()
    {
        var camera = CameraUtility.FindCamera(null);
        if (camera == null) {
            return;
        }

        var combatViewType = camera.GetComponent<CameraController>().GetViewType<Opsive.UltimateCharacterController.FirstPersonController.Camera.ViewTypes.Combat>();
        if (combatViewType != null) {
            Debug.Log("Found the Combat view type.");
        }
    }
}
```

--------------------------------

### Create Items from Definitions

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory

Facilitates the creation of new item instances within the game world. Items can be instantiated either by first retrieving an ItemDefinition and then creating an item from it, or directly by providing the ItemDefinition's name.

```csharp
//Find your item definition.
var myItemDefinition = InventorySystemManager.GetItemDefinition("MyItemDefinition");
//Create an item from that definition.
var myItem = InventorySystemManager.CreateItem(myItemDefinition);

//Or you can directly create an item from the item definition name.
var myOtherItem = InventorySystemManager.CreateItem("MyOtherItemDefinition");
```

--------------------------------

### Output Item Ammo Amount - Unity C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory

This Unity C# script, OutputItemAmount, retrieves and logs the current ammo count for the active item within the character's inventory. It requires a reference to the character GameObject and utilizes the Opsive.UltimateCharacterController inventory system. The script iterates through inventory slots, identifies active items, and then accesses their shootable actions to get the remaining ammo.

```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.Inventory;
using Opsive.UltimateCharacterController.Items.Actions;

/// <summary>
/// Outputs the amount of ammo the active item has.
/// </summary>
public class OutputItemAmount : MonoBehaviour
{
    [Tooltip("The character that contains the inventory.")]
    [SerializeField] protected GameObject m_Character;

    /// <summary>
    /// Outputs the item amount.
    /// </summary>
    public void Start()
    {
        var inventory = m_Character.GetComponent<InventoryBase>();
        if (inventory == null) {
            return;
        }

        for (int i = 0; i < inventory.SlotCount; ++i) {
            var item = inventory.GetActiveCharacterItem(i);
            if (item != null) {
                Debug.Log("Inventory Amount: " + inventory.GetItemIdentifierAmount(item.ItemIdentifier));
                // A single item can have multiple Item Actions.
                var itemActions = item.ItemActions;
                for (int j = 0; j < itemActions.Length; ++j) {
                    var shootableAction = itemActions[j] as ShootableAction;
                    if (shootableAction != null) {
                        var ammoModuleGroup = shootableAction.AmmoModuleGroup;
                        if (ammoModuleGroup != null) {
                            for (int k = 0; k < ammoModuleGroup.ModuleCount; ++k) {
                                var shootableAmmoModule = ammoModuleGroup.Modules[k] as Items.Actions.Modules.Shootable.ShootableAmmoModule;
                                if (shootableAmmoModule != null) {
                                    Debug.Log("Ammo Remaining: " + shootableAmmoModule.GetAmmoRemainingCount());
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```

--------------------------------

### Audio Manager API Methods - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/audio

Commonly used methods for the AudioManager singleton, allowing playback and stopping of audio clips on specified GameObjects. These methods abstract the underlying Audio Source management.

```csharp
// <summary>
// Plays the clip on the GameObject. The AudioManager will find the next available Audio Source on the specified GameObject.
// </summary>
Play(GameObject gameObject, AudioClip clip)

// <summary>
// Plays the clip on the GameObject with the specified delay. The AudioManager will find the next available Audio Source
// on the specified GameObject.
// </summary>
PlayDelayed(GameObject gameObject, AudioClip clip)

// <summary>
// Stops playing the clip on the Audio Source at the reserved index.
// </summary>
Stop(GameObject gameObject)
```

--------------------------------

### Initialize ImpactCollisionData with RaycastHit - C#

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory/impact-actions

Demonstrates how to initialize ImpactCollisionData using a RaycastHit, setting various properties like direction, strength, and the impact source. This is commonly used in modules like ShooterModule.

```csharp
var impactData = m_ShootableImpactCallbackContext.ImpactCollisionData;
impactData.Reset();
impactData.Initialize();
impactData.SetRaycast(closestRaycastHit);
impactData.SetImpactSource(ShootableAction);
{
    impactData.ImpactDirection = fireDirection;
    impactData.ImpactStrength = strength;
}
ShootableAction.OnFireImpact(m_ShootableImpactCallbackContext);
```

--------------------------------

### Create ItemInfo from Item

Source: https://opsive.com/support/documentation/ultimate-character-controller/inventory

Constructs an ItemInfo object, which encapsulates item details like amount and origin. This is particularly useful for managing unique items or items within multi-stack collections, providing greater control over item manipulation.

```csharp
//Make your item Info, Note double (( )) the (1,myItem) is an itemAmount.
//Note: ItemInfos can have a reference to the item stack and the itemcollection/inventory where the item comes from.
var myItemInfo = new ItemInfo( (1,myItem) );
inventory.AddItem(myItemInfo);

//Alternatively you can directly cast the item amount to an item info both are structs not classes.
//Note: It returns the item info added, this allows you to know the amount of item added and in which stack it was added to. 
var itemInfoActuallyAdded = inventory.AddItem((ItemInfo) (1, myItem));
```

--------------------------------

### Get CharacterItem Identifier

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item

Explains how to access the unique ItemIdentifier associated with a CharacterItem. The ItemIdentifier is crucial for distinguishing between different items.

```csharp
IItemIdentifier itemIdentifier = m_CharacterItem.ItemIdentifier;
```

--------------------------------

### Get All Item Identifiers in Inventory

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory

Retrieves a list of all ItemIdentifiers currently present in the inventory. This method is useful for iterating through all owned items.

```csharp
List<CharacterItem> items = inventory.GetAllItemIdentifiers();
```

--------------------------------

### Equip Item with Item Abilities (C#)

Source: https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence

Illustrates how an AI can equip or unequip items using the 'EquipNext' and 'EquipUnequip' abilities. This involves obtaining the relevant abilities from the character's locomotion component and initiating their actions.

```csharp
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) {
            // Get the EquipNext ability and start it. The next item within the ItemSetManager will be equipped.
            var equipNext = characterLocomotion.GetAbility<EquipNext>();
            if (equipNext != null) {
                characterLocomotion.TryStartAbility(equipNext);
            }

            // 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.
                equipUnequip.StartEquipUnequip(2);
            }
        }
    }
}
```

--------------------------------

### Get Item Identifier Amount in Inventory

Source: https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory

Returns the current amount of a specific ItemIdentifier within the inventory. This is useful for checking stock levels.

```csharp
int amount = inventory.GetItemIdentifierAmount(itemIdentifier);
```
Tokens:
Raw