Animator Controller

Export

Use the supplied Animator Controller as a working reference, or build a project-specific controller that keeps Ultimate Character Controller’s parameter, ID, and animation-event contracts.

Before you edit the controller

Confirm the character works with the supplied controller in Play Mode.
Make a project-owned copy of any controller you plan to modify.
Decide whether the model is Humanoid or Generic. Generic rigs need a controller and clips authored for their hierarchy.
Review Animator Parameters and Default Animator Values before changing transition conditions.

The controller does not require the demo’s exact state-machine or layer layout. Animator Monitor updates named parameters; your transitions decide how those values select states. Keeping the demo layout is usually the quickest route when the project uses similar locomotion, abilities, and items.

Assign a controller to the character

Open Tools > Opsive > Ultimate Character Controller > Character Manager.
Select the character and enable Animator.
For each model, choose Model Type and assign the project-owned controller in Animator Controller.
Select Build Character for a new character or Update Character for an existing character. The manager adds the standard Ultimate Character Controller parameters when they are missing.
Select the configured model and confirm that its Animator uses the intended controller and that Animator Monitor is present.
Open Window > Animation > Animator and verify that the Parameters list contains the movement, ability, and item-slot parameters used by the project.

The Version 3 parameter builder adds 22 standard parameters, including two item slots. A project with more item slots can add the corresponding Slot<ID>... parameters; Animator Monitor updates a slot only when that controller contains its Slot Item ID parameter.

Add or change a state-machine flow

Choose the layer by the body region and blend behavior the animation needs. Use the Base Layer for locomotion or a full-body baseline, a masked override layer for a body region, an additive layer for motion added over the current pose, or the Full Body Layer for an action that must replace the whole pose.
Add a state or sub-state machine with a name that identifies the ability, item, or locomotion mode.
Assign clips compatible with the model’s Avatar or generic hierarchy.
Create entry conditions from the relevant values:
- Locomotion commonly uses HorizontalMovement, ForwardMovement, Speed, Moving, Aiming, and MovementSetID.
- Character abilities use AbilityIndex, AbilityChange, and, when needed, AbilityIntData or AbilityFloatData.
- Item actions use the matching Slot<ID>ItemID, Slot<ID>ItemStateIndex, Slot<ID>ItemStateIndexChange, and Slot<ID>ItemSubstateIndex values.
Add a deliberate return path to the layer’s idle or locomotion state. Test both a normal completion and an interrupted action.
Preserve every required Animation Event when replacing or moving a clip. The event must exist on every clip that can drive that action, unless its Animation Event Trigger is deliberately configured to use Duration.
Test the change before modifying another layer.

Understand the supplied 13-layer layout

The table groups the Version 3 demo controller’s 13 layers by purpose; its rows do not represent their stacking order.

Layer group	Supplied layer names	Purpose
Baseline	Base Layer	Provides idle, movement, aiming movement, crouch, and core ability flows such as Fall, Interact, Jump, Quick Turn, and Ride. Ability transitions are selected with the ability parameters.
Hand overrides	Left Hand Layer, Right Hand Layer	Holds hand and finger poses without replacing the rest of the body.
Two-arm overrides	Arms Layer, Upperbody Layer	Applies two-arm item actions. The Arms mask avoids replacing torso motion, while Upperbody includes the torso when the action needs it.
One-side overrides	Left Arm Layer, Right Arm Layer, Left Upperbody Layer, Right Upperbody Layer	Allows one arm, or one arm plus its upper-body contribution, to act independently. This supports dual-wield and secondary-item arrangements.
Additive overlays	Additive Layer, Additive Left Arm Layer, Additive Right Arm Layer	Adds motion such as recoil or a reaction over the pose selected by lower layers. These three layers use additive blending.
Full replacement	Full Body Layer	Overrides the complete pose for actions such as death, revive, or a full-body attack.

The actual stacking order is Base Layer, Left Hand Layer, Arms Layer, Left Arm Layer, Upperbody Layer, Right Arm Layer, Right Hand Layer, Right Upperbody Layer, Left Upperbody Layer, Additive Layer, Additive Left Arm Layer, Additive Right Arm Layer, then Full Body Layer.

Layer order and Avatar Masks matter. A later override layer can replace motion chosen below it, while an additive layer expects a compatible additive clip. Do not copy a state into another layer without also checking its mask, blend mode, transition conditions, and exit path.

Choose a customization approach

Keep the supplied structure

Use this approach when the game needs similar locomotion, abilities, item categories, and body-region layering. Add project-specific states under the existing sub-state machines and keep the supplied parameters and layer masks. This minimizes the number of interacting transitions that must be rebuilt.

Start from a minimal controller

Use a new controller when the game’s animation flow is fundamentally different or it does not need the demo’s item and body-region layers. Begin with the required parameters and one working locomotion flow, then add one ability or item action at a time. You do not need to recreate all 13 demo layers.

Replace clips without redesigning transitions

Use Replacing Animations when the state logic is already correct and only the motions need to change. Replace every occurrence across the relevant masked layers and keep Replace Events enabled when the new clips should receive the supplied animation events.

Verify in Play Mode

Select the active model and keep the Animator window visible.
Move, stop, turn, crouch, and aim. The live parameters should select the intended Base Layer states without rapid unwanted transitions.
Start each changed ability. Confirm the expected AbilityIndex and any data parameter, watch the intended layer enter its state, and verify that it returns cleanly when the ability ends.
Equip and use each changed item while stationary and moving. Confirm that the correct slot parameters select matching states on the hand, arm, and upper-body layers.
Trigger an additive reaction and a full-body action. The additive result should retain the underlying pose; the full-body action should replace it.
Repeat interrupted actions, perspective changes, and rapid inputs. No layer should remain stuck in an action state, and required events should occur once at the intended frame.

Troubleshooting

Symptom	Check	Fix
The Console reports that the Animator is not designed for Ultimate Character Controller.	`HorizontalMovement`, `ForwardMovement`, or `AbilityChange` is missing, and other feature parameters may also be absent.	Run Update Character with the intended controller or add the full set from Animator Parameters.
Parameters change but an ability state never starts.	The transition may use the wrong AbilityIndex, parameter type, or trigger condition.	Compare the live values with Default Animator Values and correct the transition.
An item action works while stationary but not while moving.	The action may exist on Upperbody Layer but not the corresponding Arms Layer, or vice versa.	Add the intended state and transition to every masked layer the action needs.
A one-handed action moves both arms or the torso.	The state may be on a layer with the wrong Avatar Mask.	Move it to the appropriate left/right arm or upper-body layer, or correct that layer’s mask.
An additive action distorts the pose.	The layer or clip may not be configured for compatible additive blending.	Verify the layer’s blending mode and the clip’s additive reference pose.
An action starts but never returns.	The exit condition, animation event, or return transition may be missing.	Add a return path and verify the event expected by the trigger, or intentionally use Duration timing.
A replacement changes only part of the visible result.	Another layer or perspective may still reference the original clip.	Search the full controller and all first-person or item controllers for the old clip, then follow Replacing Animations.

Animator provides the recommended route through Animator setup and customization.
Animator Parameters defines the exact parameter names, types, and meanings.
Default Animator Values lists the supplied ability and item ID mappings.
Replacing Animations covers the Animation Replacer workflow and event preservation.
First Person Arms explains the generic first-person rig and its separate controller needs.

Developer reference

AnimatorMonitor does not search for specific layer or state names. It hashes and writes the standard parameter names, including movement, ability, and item-slot values. AnimatorBuilder.AddParameters adds the Version 3 baseline of 22 parameters: 13 shared character parameters, four parameters each for slots 0 and 1, and LegIndex.

The shipped Demo.controller currently defines 13 layers. Its Base, hand, arm, upper-body, and full-body layers use override blending; the three Additive layers use additive blending. The masked layers use separate Avatar Mask assets, and the Base, Upperbody, and Full Body layers enable IK Pass. These are implementation choices in the supplied demo controller, not mandatory layer names for a custom controller.