Animator Parameters

Export

Animator parameters connect Ultimate Character Controller’s movement, abilities, and equipped items to transitions and blend trees in a Unity Animator Controller.

Add the Version 3 parameters

  1. Open Tools > Opsive > Ultimate Character Controller > Character Manager.
  2. Select the character, enable Animator, and assign the intended Animator Controller.
  3. Select Build Character for a new character or Update Character for an existing one. Character Manager adds each missing standard parameter to the assigned controller.
  4. Open the controller in Window > Animation > Animator and select the Parameters tab.
  5. Compare every name and type with the tables below. Names are case-sensitive.
  6. Build transition conditions around the values the character actually uses, then verify them in Play Mode before editing another flow.

The Version 3 parameter builder adds 22 parameters: 13 shared character parameters, four parameters for each of slots 0 and 1, plus LegIndex. If a parameter already exists with the correct name but the wrong type, the builder does not replace it; correct that parameter manually.

Movement and look parameters

Name Type Version 3 behavior and common use
HorizontalMovement Float Receives the horizontal component of the locomotion input vector. Use it as the horizontal axis of a locomotion blend tree. Animator Monitor applies Horizontal Movement Damping Time.
ForwardMovement Float Receives the forward component of the locomotion input vector. Use it as the forward axis of a locomotion blend tree. Animator Monitor applies Forward Movement Damping Time.
Pitch Float Receives the active look source’s pitch when a look source is present. Use it for vertical aim or look poses. Animator Monitor applies Pitch Damping Time.
Yaw Float Receives the character’s rotational change multiplied by Animator Monitor’s Yaw Multiplier. Use it for turn-in-place or turning blends rather than as an absolute world rotation. Animator Monitor applies Yaw Damping Time.
Speed Float Normally becomes Moving Speed Parameter Value while the character is moving and 0 while stopped. An ability can temporarily override it, such as Speed Change. It is not a direct world-speed measurement.
Height Float Receives a height value set by an ability. Height Change can set its configured height when active and restore 0 when it stops.
Moving Bool Becomes true or false when the character starts or stops moving. Use it for clear idle-versus-movement decisions.
Aiming Bool Follows the character’s aiming event and is forwarded to equipped item animators. Do not assume it is always true in first person; verify the live value for the project’s Aim setup.
MovementSetID Int Receives Animator Movement Set ID from the dominant equipped Character Item. Use it to select stance families such as default, melee, or bow movement.
LegIndex Float Used by the supplied controller’s transition conditions to choose a leg-compatible entry back into movement. Keep it when retaining those transitions; a custom controller that does not use leg-aware entry conditions does not have to reference it.

HorizontalMovement and ForwardMovement describe controller input, not the character’s measured velocity. Use Speed, Moving, or a project-specific parameter when a transition needs a different meaning.

Ability parameters

Name Type Version 3 behavior and common use
AbilityIndex Int Receives the Ability Index Parameter from the highest-priority active ability that supplies one. 0 represents no selected ability in the standard flow. Use it to select an ability state or sub-state machine.
AbilityChange Trigger Is set when AbilityIndex changes. Use it with the index condition so the Animator can enter or re-enter the correct ability flow when the selection changes.
AbilityIntData Int Carries ability-specific integer detail in addition to AbilityIndex. For example, Interact exposes Ability Int Data Value so different interaction animations can share one ability index.
AbilityFloatData Float Carries ability-specific continuous or variant data. Current abilities use it for values such as fall velocity, steering input, or idle variation. An ability can request damping when updating it.

The first active ability by priority that supplies each value wins. Do not use AbilityIntData or AbilityFloatData without defining what that value means for the selected AbilityIndex.

Item-slot parameters

Version 3 adds this group for slot 0 and slot 1. Replace <ID> with the numeric Slot ID:

Name pattern Type Version 3 behavior and common use
Slot<ID>ItemID Int Receives Animator Item ID from the Character Item equipped in that slot. 0 represents no equipped item in the standard flow. Use it to select the item family.
Slot<ID>ItemStateIndex Int Receives the state index from the highest-priority active item ability for that slot. Use it to select actions such as Use, Reload, Equip, or Unequip.
Slot<ID>ItemStateIndexChange Trigger Is set when the slot’s item or item state changes to a nonzero value. Use it with the ID and state-index conditions to enter or re-enter the intended item action.
Slot<ID>ItemSubstateIndex Int Carries the action’s variation within the selected item state, such as an attack sequence or another Animator Audio State Set choice.

For example, a pistol with Animator Item ID 2 performing the standard Use item ability in slot 0 can expose Slot0ItemID = 2 and Slot0ItemStateIndex = 2; the substate distinguishes the selected use variation.

If the inventory uses slot 2 or above, add all four matching parameters manually. Animator Monitor treats a slot as available in a controller when it finds that slot’s Slot<ID>ItemID; keep the full four-parameter group together.

Choose parameters by use case

  • Directional locomotion: Drive a two-dimensional blend tree with HorizontalMovement and ForwardMovement, then use Moving for clean entry and exit conditions.
  • Turn-in-place: Use Yaw with suitable positive and negative thresholds. Tune Yaw Multiplier and Yaw Damping Time on Animator Monitor before changing many transitions.
  • Ability selection: Pair AbilityChange with the intended AbilityIndex. Add AbilityIntData or AbilityFloatData only when one ability needs multiple animation choices.
  • Equipped stance: Use MovementSetID for a broad stance and Slot<ID>ItemID when the animation is specific to an item family.
  • Item action: Pair Slot<ID>ItemStateIndexChange with the Slot Item ID and Item State Index. Use the substate only for a variation inside that action.
  • Return to movement: Use the live movement values and, when keeping the supplied leg-aware transitions, LegIndex to choose a compatible re-entry pose.

Verify in Play Mode

  1. Select the active character model and open Window > Animation > Animator.
  2. On Animator Monitor, expand Editor and enable Log Ability Parameter Changes and Log Item Parameter Changes.
  3. Enter Play Mode and move in every direction. Watch HorizontalMovement, ForwardMovement, Moving, Speed, Pitch, and Yaw respond.
  4. Start an ability. Confirm that AbilityIndex and AbilityChange select the expected state, and inspect any ability data value used by its transitions.
  5. Equip and use an item in each supported slot. Confirm its Slot Item ID, Item State Index, change trigger, and substate match the intended item and action.
  6. Stop the action, unequip the item, and return to idle. The active indexes should return to their standard neutral values and the Animator should leave the action state.
  7. Disable the logging options after testing.

Troubleshooting

Symptom Check Fix
The Console says the Animator is not designed for Ultimate Character Controller. Version 3 validates HorizontalMovement, ForwardMovement, and AbilityChange during Animator Monitor initialization. Add the missing parameters with the exact names and types, then check the complete table rather than stopping at the three validation names.
Character Manager ran, but a transition still reports a type mismatch. A parameter with that name may already have the wrong type. Delete or rename the incorrect parameter and recreate it with the type in this page; the parameter builder only adds missing names.
The character moves but Speed remains 1. The default Moving Speed Parameter Value is 1; Speed is not measured velocity. Use the directional parameters for blend magnitude, tune Moving Speed Parameter Value, or provide a deliberate ability override.
An ability index changes but its state does not restart. The transition may test only AbilityIndex and ignore AbilityChange. Add the change trigger to the intended entry transition.
An item equips but the item state never changes. The controller may lack the complete slot group, or its transition may omit Slot<ID>ItemStateIndexChange. Add all four parameters for that slot and use the change trigger with the ID and state index.
A slot above 1 never updates. The standard builder creates only slot 0 and slot 1. Add the four correctly named parameters for the additional Slot ID.
Aiming transitions are wrong in first person. The controller may assume Aiming is permanently true. Watch the live value and build transitions around the Aim ability behavior used by the project.
The parameters are correct but the wrong state plays. The configured ability, item, or movement-set ID may not match the transition threshold. Compare the Inspector values with Default Animator Values and correct the ID or transition.
  • Animator Controller explains how to organize layers, states, and transitions around these parameters.
  • Default Animator Values lists the supplied Ability Index, Item State Index, Animator Item ID, and Movement Set ID mappings.
  • Animator provides the full setup and customization route.
  • Abilities explains ability priority and Ability Index Parameter.
  • Item Slots explains the Slot IDs used in item parameter names.

Developer reference

AnimatorBuilder.AddParameters checks each standard name and adds it only when no parameter with that name exists. It creates the 22-parameter Version 3 baseline but does not verify or replace the type of an existing parameter. AnimatorMonitor hashes these exact names and writes values through Unity’s Animator API.

Movement and look values update during the character’s animation update. Ability and item-ability selections are marked dirty and resolved by active-ability priority at the synchronized update point. AbilityChange and each Slot<ID>ItemStateIndexChange are Unity Trigger parameters rather than persistent booleans.

For item slots, Animator Monitor first checks for Slot<ID>ItemID. If that parameter is absent, the controller does not receive the state-index, change-trigger, or substate writes for that slot. The same values are also forwarded to active supported child and item animators.