Actor Controller

The Actor Controller component is the heart of the Actor Controller asset as well as the Motion Controller asset. It’s the low-level input-based character controller that handles gravity, collisions, movement, rotation, etc.

 

Setup

You can add the component to your character from the Unity menu:

Component | ootii | Actor Controller

 

Basic & Advanced Views

One of the best resources for understanding the properties is to simply hover over the property names. I use tool-tips to help describe what the properties do.

The Actor Controller allows you to modify behavior in two ways:

Basic View – This view is used to get up and running when you don’t need to tweak values. To see the Basic View properties, click here.

Advanced View – This view provides access to detailed properties that allow you to fine tune how the Actor Controller behaves. To see the Advanced View properties, click here.

 

Body Shapes

Body shapes are used for collision detection by the Actor Controller. By using spheres and capsules, we can represent the shape of a human as well as other non-simple characters. We also have the ability to change these shapes during run-time in order to match the character’s pose.

The default setup has two shapes:

Body Capsule – This capsule is similar to a traditional character controller, but is raised off the ground. This allows the actor to get right up to the edge of a step… which is great for foot IK.

Foot Sphere – This sphere is only active while in the air. This keeps our feet from entering things as we jump over objects. However, it doesn’t block us when we move close to a ledge or step.

Shapes

Body Shapes can be added as capsules or as spheres. By changing the radius and position of the shapes, you can mimic anything from humans to dogs.

Body Shapes vs. Colliders

It’s important to note that body shapes are NOT colliders. So, external raycasts or rigid-bodies won’t react to them. If you want an external raycasts to hit your character, you can add traditional Unity colliders to your actor as you normally would or check the ‘Use Unity Colliders’ checkbox.

The reason I use body shapes instead of colliders is that the normal Unity capsule collider isn’t very flexible. You can’t rotate it arbitrarily or tie it to different transforms. That means its shape won’t automatically change as your character animates.

For example: Notice how the Unity capsule collider can’t resize automatically to match the head transform. It’s also stuck in the cardinal directions. However, the body shape capsule will resize and rotate with the transforms it’s tied to. So, your character’s shape will change automatically.

 

 

 

 

Unity Colliders

To help compensate for the Unity capsule collider restrictions, there is an option on each body shape that will create and manage Unity colliders using the body shapes.

Simply check the “Use Unity Colliders” checkbox and colliders will be created at run-time to match the body shapes.

Spheres are easy. However, since we can’t really use Unity capsule colliders, spheres are used instead. We use multiple sphere to approximate the body shape capsule’s position, size, and rotation.

Rigidbodies

Adding a Rigidbody component to your character is fine. However, the rigidbody will attempt to control your character. So, that means the rigidbody and AC are competing. To fix this, disable gravity on the rigidbody and check the “Is Kinematic” check box. This will stop the rigidbody from trying to control your character.

Properties

The properties of the depend on the shape (sphere vs. capsule). However, the properties should make sense for either shape.

Name – Friendly name of the body shape.

Radius – Radius of the sphere or capsule.

Use Unity Colliders – Determines if we’ll auto-create Unity sphere colliders to mimic the body shapes.

 

Enabled on ground – Determines if the body shape are active and will collide while the character is on the ground.

Enabled on ramp – Determines if the body shape are active and will collide while the character is on ramps and slopes.

Enabled in air – Determines if the body shape are active and will collide while the character is not on the ground.

Transform – Character transform to tie the body shape to. The body shape will move as the transform moves. If no value is specified, the character’s root transform is used.

Transform Offset – Offset of the body shape relative to the Transform.

 

States

The Actor Controller keeps a history of its previous state each frame. You can use this information to look at what the Actor Controller was doing in the past.

For example, if the character wasn’t grounded last frame, but is this frame you could play a sound.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
using UnityEngine;
using com.ootii.Actors;

public class SampleComponent : MonoBehaviour
{
    public void SomeFunction()
    {
        ActorController lActorController = gameObject.GetComponent<ActorController>();
        if (!lActorController.PrevState.IsGrounded && lActorController.State.IsGrounded)
        {
            // Play sound
        }
    }
}

Code

The Actor Controller knows how to move, collide, and use gravity, but it doesn’t know when to do these things. Typically an Actor Drivers or other logic does that. They direction the Actor Controller through these three functions:

Move(Vector3) – Function that tells the actor to move in world space.


1
2
3
4
5
6
7
8
9
10
11
12
using UnityEngine;
using com.ootii.Actors;

public class SampleComponent : MonoBehaviour
{
    public void SomeFunction(float rSpeed)
    {
        ActorController lActorController = gameObject.GetComponent<ActorController>();
        Vector3 lMove = new Vector3(0f, 0f, rSpeed * Time.deltaTime);
        lActorController.Move(lMove);
    }
}

MoveRelative(Vector3) – Similar to the Move() function, but this function tells the actor to move in actor space. That means the x-component is to the left/right of the character, the y-component is up/down of the character, and the z-component is forward/backwards of the character.


1
lActorController.RelativeMove(lMove);

Rotate(Quaternion) – This tells the character how much to rotate and is relative to the character’s current rotation.


1
2
Quaternion lRotation = Quaternion.Euler(0f, 90f * Time.deltaTime, 0f);
lActorController.Rotate(lRotation);

When the Actor Controller is told to move, it will then process gravity, collisions, etc. In the end, the character will attempt to move as it’s told, but it will may be limited by the environment.

Other useful functions include:


1
2
3
4
5
6
7
8
// Adds an instant force for something like jumping
lActorController.AddImpulse(new Vector3(0f, 10f, 0f));

// Disables gravity
lActorController.IsGravityEnabled = false;

// Stops forcing the character to the ground
lActorController.ForceGrounding = false;