Character

The Ultimate Character Controller uses a kinematic, deterministic character controller. This means that the movements can be predicted and they can also be replayed. This is extremely useful in a networked environment where the server needs to ensure the position and rotation are valid on the client. The Character Locomotion component is responsible for the core movement and for the following:

  • Movement
  • Collision Detection
  • Root Motion
  • Wall Bouncing
  • Wall Gliding
  • Slopes
  • Stairs
  • Push Rigidbodies
  • Dynamic Gravity
  • Variable Time Scale
  • Capsule Collider and Sphere Collider support
  • Moving Platforms

The Character Locomotion component isn’t directly added to your character though – the Ultimate Character Locomotion component is instead added. The Ultimate Character Locomotion component inherits Character Locomotion and adds support for the following:

  • Movement Types
  • Abilities
  • Effects
  • Animator Knowledge

New characters should be built using the Character Manager. The Character Manager will add all of the necessary components to your character, including the Ultimate Character Locomotion component.

Stairs

On the Ultimate Character Locomotion component the Max Step Height variable specifies the maximum height that the character can step when moving up stairs. In order to ensure smooth movement this value must be less than the radius of the character’s collider. If the character should be able to step up taller stairs a transparent quad collider should be added to the stairs. This collider should be placed at a slope angle across the top of the stairs. The collider should then be assigned to the TransparentFX layer. With this setup the controller will then use the Slope Limit value to determine if the character can walk up the stairs. When the IK is positioned it will ignore this transparent collider and place the feet on the actual steps.

In Air Movement

By default when the character is in the air it will use the Motor Acceleration and Motor Damping values to determine the speed. You can change between grounded and airborne values by using the state system to set the property values when the “Airborne” state is active.

API

The Ultimate Character Locomotion component works with the Simulation Manager to smoothly move the object. Because of this the standard Transform.SetPosition/Rotation methods should not be used. Equivalent methods have been added to the Ultimate Character Locomotion component and should be used instead.

using UnityEngine;
using Opsive.UltimateCharacterController.Character;

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

    /// <summary>
    /// Set the position and deactivate the character.
    /// </summary>
    private void Start()
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        if (characterLocomotion != null) {
            characterLocomotion.SetPositionAndRotation(Vector3.zero, Quaternion.identity);
        }
    }
}

Forces should also be added to the CharacterLocomotion component instead of the Rigidbody component. You can do so with the AddForce method:

using UnityEngine;
using Opsive.UltimateCharacterController.Character;

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

    /// <summary>
    /// Set the position and deactivate the character.
    /// </summary>
    private void Start()
    {
        var characterLocomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        if (characterLocomotion != null) {
            characterLocomotion.AddForce(Vector3.up * 5);
        }
    }
}

The character can persist between scenes by marking the character GameObject as DontDestroyOnLoad. When the character is marked as DontDestroyOnLoad the camera and UI should also be marked with DontDestroyOnLoad. This will allow all of the references to persist between scene loads.

private void Start()
{
    // Find the character. If the character does not exist then instantiate a new character with DontDestroyOnLoad.
    var character = FindObjectOfType<Character.UltimateCharacterLocomotion>();
    if (character == null) {
        character = Instantiate(m_Character).GetComponent<Character.UltimateCharacterLocomotion>();
        DontDestroyOnLoad(character.gameObject);
    }
    // Find the camera. If the camera does not exist then instantiate a new camera with DontDestroyOnLoad.
    var camera = FindObjectOfType<Camera.CameraController>();
    if (camera == null) {
        camera = Instantiate(m_Camera).GetComponent<Camera.CameraController>();
        // The camera needs to be aware of the instantiated character.
        camera.Character = character.gameObject;
        DontDestroyOnLoad(camera.gameObject);
    }
    // Find the active canvas. If the canvas does not exist then instantiate a new canvas with DontDestroyOnLoad.
    var canvasScaler = FindObjectOfType<UnityEngine.UI.CanvasScaler>();
    if (canvasScaler == null) {
        DontDestroyOnLoad(Instantiate(m_Canvas));
    }
}

Inspected Fields

Movement Type

The Movement Type controls the direction that the character rotates as well as the value of the inputs. Multiple Movement Types can be added to a character but only a single Movement Type is active at a time. The Movement Type can be changed with the state system or by calling SetMovementType on the controller.

First Person Movement Type

The name of the active first person movement type.

Third Person Movement Type

The name of the active third person movement type.

Use Root Motion Position

Should root motion be used to move the character?

Root Motion Speed Multiplier

If using root motion, applies a multiplier to the root motion delta position while on the ground.

Root Motion Air Force Multiplier

If using root motion, applies a multiplier to the root motion delta position while in the air.

Use Root Motion Rotation

Should root motion be used to rotate the character?

Root Motion Rotation Multiplier

If using root motion, applies a multiplier to the root motion delta rotation.

Motor Rotation Speed

The rate at which the character can rotate. Only used by non-root motion characters.

Mass

The mass of the character. The mass is used to determine how much force to apply when colliding with a Rigidbody.

Skin Width

Specifies the width of the characters skin, which is used for ground detection. The larger the value the less distance between the character and ground is required for the character to be considered grounded.

Slope Limit

The maximum slope angle that the character can traverse (in degrees).

Max Step height

The maximum object height that the character can step on top of. This value should be less than the radius of any of the character’s colliders. The reason for this is to ensure your character has a smooth movement when stepping. If the Max Step Height was greater than the radius of the character’s colliders then there would be a large vertical jump as the controller moves the character up in the step in a single frame.

Motor Acceleration

The rate at which the character’s motor force accelerates while on the ground. Only used by non-root motion characters.

Motor Damping

The rate at which the character’s motor force decelerates while on the ground. Only used by non-root motion characters.

Motor Backwards Multiplier

A multiplier which is applied to the motor while moving backwards.

Previous Acceleration Influence

A (0-1) value specifying the amount of influence the previous acceleration direction has on the current velocity.

Adjust Motor Force On Slope

Should the motor force be adjusted while on a slope?

Motor Slope Force Up

If adjusting the motor force on a slope, the force multiplier when on an upward slope.

Motor Slope Force Down

If adjusting the motor force on a slope, the force multiplier when on a downward slope.

External Force Damping

The rate at which the character’s external force decelerates.

External Force Air Damping

The rate at which the character’s external force decelerates while in the air.

Stick To Ground

Should the character stick to the ground?

Stickiness

If the character is sticking to the ground, specifies how sticky the ground is. A higher value means the ground is more sticky.

Time Scale

The local time scale of the character. The time scale of the character can be modified independently of the global time scale.

First Person State Name

The name of the state that should be activated when the character is in a first person perspective.

Third Person State Name

The name of the state that should be activated when the character is in a third person perspective.

Moving State Name

The name of the state that should be activated when the character is moving.

Airborne State Name

The name of the state that should be activated when the character is airborne.

Use Gravity

Should gravity be applied?

Gravity Direction

The normalized direction of the gravity force.

Gravity Magnitude

The amount of gravity force to apply.

Detect Horizontal Collisions

Should the character detect horizontal collisions? Disabling this will reduce the number of casts that need to be performed and increase performance.

Detect Vertical Collisions

Should the character detect vertical collisions? Disabling this will reduce the number of casts that need to be performed and increase performance.

Collider Layer Mask

The layers that can act as colliders for the character.

Max Collision Count

The maximum number of colliders that the character can detect.

Max Soft Force Frames

The maximum number of frames that the soft force can be distributed by.

Rotation Collision Check Count

The maximum number of collision checks that should be performed when rotating.

Max Overlap Iterations

The maximum number of iterations to detect collision overlaps.

Wall Glide Curve

A curve specifying the amount to move when gliding along a wall. The x variable represents the dot product between the character look direction and wall normal. An x value of 0 means the character is looking directly at the wall. An x value of 1 indicates the character is looking parallel to the wall.

Wall Bounce Modifier

A multiplier to apply when hitting a wall. Allows for the character to bounce off of a wall.

Stick To Moving Platform

Should the character stick to the moving platform? If false the character will inherit the moving platform’s momentum when the platform stops quickly.

Moving Platform Separation Velocity

The velocity magnitude required for the character to separate from the moving platform due to a sudden moving platform stop.

Min Horizontal Moving Platform Stick Speed

The maximum speed of the platform that the character should stick when the platform collides with the character from a horizontal position.

Moving Platform Force Damping

The rate at which the character’s moving platform force decelerates when the character is no longer on the platform.

Yaw Multiplier

Specifies how much to multiply the yaw parameter by when turning in place.

Moving Speed Parameter Value

Specifies the value of the Speed Parameter when the character is moving.

Abilities

Abilities allow the controller to be extended without having to change the core controller code. Multiple abilities can be active at the same time and it is strongly recommended that you create new abilities specific to your game as it will add new unique functionality.

Item Abilities

Item Abilities allow the controller to interact with any items that the character is carrying.

Effects

Effects can be considered lightweight abilities and they are used to provide effects that affect the character or camera, such as shaking the camera during an earthquake or playing a one off audio file.

Keep Reading

Previous Page

Component Overview

Next Page

Character Creation