Abilities

The ability system is an extremely versatile system which allows you to add new functionality to your character without having to modify the core character locomotion system. Any “extra” character functionality within the Ultimate Character Controller is implemented using the ability system – this includes jumping, restricting the character’s rotation, or even firing a weapon. Unlike effects, abilities can use the Animator and they are also synchronized across the network.

New abilities can be created by following this example. The ability system is designed to be extensible so it is highly recommended that you create new abilities specific for your game.

Priority

Abilities use a priority system when added to the Ultimate Character Locomotion component. The higher the ability is in the list, the higher priority it is. Consider this setup:

With this setup the Interact ability has a higher priority than the Die ability. The result of this is that the die animation would not be able to play if the character gets killed while interacting with an object. The Die ability should be above the Interact ability in order for the die animation to play correctly while the character is interacting with an object.

If an ability should be able to be active at the same time as another ability – such as the Speed Change ability, then the ability can override the IsConcurrent property and return true. The priority system is not used with concurrent abilities.

Life Cycle

API

Abilities can be started/stopped manually from any script by getting a reference to the Ultimate Character Locomotion component and then calling the TryStartAbility or TryStopAbility method on that component. These methods require a reference to the ability that will be started/stopped and that reference can be retrieved with GetAbility.

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

Events

When the ability starts or stops the “OnCharacterAbilityActive” event will be sent from the built-in Event System. A corresponding Unity event will also be sent. The following example will subscribe to this event from a new component:

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

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

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

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

Inspected Fields

Enabled

Can the ability be activated?

Start Type

Specifies how the ability can be started:

  • Automatic: The ability will try to be started every update.
  • Manual: The ability must be started with UltimateCharacterLocomotion.TryStartAbility.
  • Button Down: The ability will start when the specified button is down.
  • Button Down Continuous: The ability will continuously check for a button down to determine if the ability should start.
  • Double Press: The ability will start when the specified button is pressed twice.
  • Long Press: The ability will start when the specified button has been pressed for more than the specified duration.
  • Tap: The ability will start when the specified button is quickly tapped.
  • Axis: The ability will start when the specified axis is a non-zero value.
  • Custom: The ability will start after a user defined starter has indicated that the ability should start.
Stop Type

Specifies how the ability can be stopped:

  • Automatic: The ability will try to be stopped every update.
  • Manual: The ability must be started with UltimateCharacterLocomotion.TryStopAbility.
  • Button Up: The ability will stop when the specified button is up.
  • Button Down: The ability will stop when the specified button is down.
  • Button Toggle: The ability will stop when the same button has been pressed again after the ability has started.
  • Long Press: The ability will stop when the specified button has been pressed for more than the specified duration.
  • Axis: The ability stop when the specified axis is a non-zero value.
Input Names

The button name(s) that can start or stop the ability.

Long Press Duration

Specifies how long the button should be pressed down until the ability starts/stops. Only used when the ability has a start/stop type of LongPress.

Wait For Long Press Release

Should the long press wait to be activated until the button has been released?

Attribute Modifier

Allows you to specify an attribute that the ability should start when active. One use for this is applied to the Speed Change ability to give the character stamina.

State

Specifies the name of the state that the ability should use when active.

Append Item Definition Name

Should the Item Definition name be appended to the name of the state name?

Ability Index Parameter

Specifies the value to set the Ability Index parameter to (-1 will not set the parameter).

Start Audio Clip Set

A set of AudioClips that can be played when the ability is started.

Stop Audio Clip Set

A set of AudioClips that can be played when the ability is stopped.

Use Gravity

Should the character use gravity while the ability is active?

Use Root Motion Position

Can the character use root motion for positioning?

Use Root Motion Rotation

Can the character use root motion for rotation?

Allow Positional Input

Does the ability allow positional input?

Allow Rotational Input

Does the ability allow rotational input?

Detect Horizontal Collisions

Should the character detect horizontal collisions while the ability is active?

Detect Vertical Collisions

Should the character detect vertical collisions while the ability is active?

Animator Motion

A reference to the AnimatorMotion that the ability uses.

Allow Equipped Slots

Specifies which slots can have the item equipped when the ability is active.

Allow Item Definitions

An array of Item Definitions that are allowed to be equipped when the ability starts. Any Item Definition can be equipped if no Item Definitions are specified.

Immediate Unequip

Should the items be unequipped immediately?

Reequip Slots

Should the ability equip the slots that were unequipped when the ability started?

Ability Indicator Text

The text that should be shown by the ability indicator when the ability can start.

Ability Indicator Icon

The sprite that should be drawn by the ability indicator when the ability can start.

Keep Reading

Previous Page

Movement Types

Next Page

Included Abilities